FreeBSD Manual Pages
UCORED(8) System Manager's Manual UCORED(8) NAME ucored -- process and filter userland coredump files SYNOPSIS ucored [-dLv] [-p pidfile] DESCRIPTION The ucored daemon listens for coredump notifications from the kernel via devd(8) and applies a policy to each generated coredump. The default pol- icy moves all coredumps to /var/ucrash, though this is subject to change. The options are as follows: -d Run in the foreground instead of detaching from the controlling terminal. This is intended to be used in debugging ucored itself. All messages are redirected to either stdout or stderr. The -d op- tion does not imply any extra verbosity. -L Do not load ucoredev(4) if it is not already loaded at startup. ucored will otherwise try to load it and take over coredumps for the entire system. This option implies a fallback to using devd(8) notfications to hoover up coredumps if the module was not previ- ously loaded. The -L option has no effect if ucoredev(4) does not exist. -p pidfile Write the ucored daemon pid to the specified pidfile. If the pidfile already exists and contains a valid pid, then ucored will refuse to start. -v Run with verbosity. The -v option may be specified multiple times to increase verbosity. At this time, specifying more verbosity than -vv will have no effect. Note that ucored can run either standalone or initiated via inetd(8) con- figured to handle its UNIX socket at /var/run/ucored.sock. If ucored is invoked via some socket-initiation launcher like inetd(8), then the kern.coredump_devctl sysctl(8) will need to be manually enabled. During standalone operation, ucored will enable and disable it as needed. Policies The ucored daemon offers some flexibility in the policies it will apply to a coredump. The following policy actions are supported: discard Discards the coredump completely. ucored will promptly unlink(2) the coredump if necessary, but cores produced by ucoredev(4) do not exist on disk and do not need to be unlinked. This is a final rule, and must be the last rule specified in a chain. execute Executes a command. The command must be an absolute path, as the working directory of ucored is undefined. The command may either be a string that will be word-split based on standard shell rules, or an array of arguments. The process will be run with /dev/null hooked up to standard input, standard output, and standard error. The environment it will run in is a subset of the environment that ucored runs in. By default, only the LANG and PATH variables are inherited. An env table may be supplied to augment the inherited environment. Values of env may use shell-style "$VAR" substitu- tion, as well as any of the substitutions described below in "Path Substitutions". Shell-style variables will only be resolved from the running environment, and will not be affected by other assign- ments specified in env. ignore Ignores the coredump. For coredumps produced by ucoredev(4), this is the same as the discard policy. It does not make sense to combine an ignore rule with any other rule, and attempts to do so will raise an error. move Moves the core file to some other destination on disk. If the specified destination does not have any path separators, then the operation is considered to be a rename. If the destination is a relative path, then it is considered to be relative to the original location of the coredump. If the destination does not end with a trailing slash, then the last component is assumed to be a filename unless the specified path already exists and is a directory. See "Path Substitutions" below for more details on how ucored may augment paths. pipe Pipes the core file to another command. The command will be inter- preted as it is specified for the execute action above, and the same constraints apply. The core file will be opened, if neces- sary, and passed to the standard input of the specified command in- stead of /dev/null. The notes for the execute action about the en- vironment and env also apply to the pipe action. script Specifies a script that will process the coredump. The file speci- fied should be a lua script that returns a function that will han- dle an internal ucore object. See "ucore Objects" below for more details on what ucored provides in a ucore object. This is a final rule, and must be the last rule specified in a chain. Path Substitutions The ucored daemon will process paths that are supplied as a destination to move to and apply requested substitutions for data from the coredump noti- fication. These substitutions are applied to all parts of the path, not just the filename component. The following substitutions may be requested: "%d" The domainname of the jail that the process belonged to, or the host if the process was unjailed. If unset, this will expand to the empty string. "%f" The current path to the corefile. "%h" The hostname of the jail that the process belonged to, or the host if the process was unjailed. If unset, this will expand to the empty string. "%I" An index to uniquify a corefile. Indices must be placed in the filename portion of a path. It will not be replaced in any other position, and only the first occurrence will be replaced. ucored will replace the "%I" token with an index from 0 up to the max_cores specified on the action, or 5 if unspecified, until it finds a file that does not exist. If all of the allowed corefiles under this scheme exist, then the oldest one will be replaced. Note that ucored does not currently handle potential races well, so hopefully the process isn't repeatedly crashing and every single dump needs to be captured. "%j" The jid of the jail that the process belonged to. This will be 0 for unjailed processes. "%n" The name of the process. "%P" The pid of the process' parent. "%p" The pid of the process. "%s" The signal that triggered the coredump. "%u" The uid of the process credentials. ucore Objects When information about a coredump has been received, ucored constructs a "ucore" object with the relevant information. The following methods are available on the ucore object: ucore:attributes() Returns a table of attributes received. The following attributes are recorded: compression A string describing the compression of the core. The fol- lowing values are valid: "" No compression. This is kern.compress_user_cores=0. "gzip" Compressed with gzip. This is kern.compress_user_cores=1. "zstd" Compressed with zstd. This is kern.compress_user_cores=2. "???" Unknown compression state. This shouldn't really happen in practice. jid The jid of the jail that the process belonged to. This will be 0 for unjailed processes. gid The gid of the process credentials. ppid The pid of the process' parent. pid The pid of the process. tainted True if the process is running a setuid/setgid binary, or if the process had changed credentials since execve(2) time. The uid and gid are overridden to root/wheel when a file is moved if the process has been tainted, for security reasons. signal The signal that triggered the coredump. uid The uid of the process credentials. ucore:comm() The command that was running. Note that the "comm" field in FreeBSD is limited to 19 bytes. ucore:jail() The name of the jail the process was running in. ucore:filename() The filename component of the core's path. ucore:move(path) Move the core to the specified path. For file moves, ucored will attempt to use rename(2) first. If the rename(2) operation fails because it's a cross-filesystem rename, then ucored will fallback to using copy_file_range(2) to try and be more performant. The owner, mode, and some file flags from the original coredump are preserved in the move. Specifically, the nouchg and nodump flags are preserved in case some other system policy would have set them. Note that ucored may fail the move for security reasons in some circumstances. If the coredump path provided by the kernel is now a symlink instead of a regular file, then ucored will refuse to move it. If the destination exists and is not owned by the same user as the original coredump, then ucored will refuse to move it. If the destination exists and is a symlink, then ucored will also refuse to move it. ucore:path() The full path to the coredump. Configuration ucored is configured with UCL using libucl(3). Its configuration, by de- fault, is located at /usr/local/etc/ucored.conf. The top-level object in the configuration is expected to have a "filters" key whose value is one or more filter objects. Either a single object or an array of object(s) is accepted. Each filter object may have three keys: name Optional. A name to be used for reference in errors related to the filter. If a name is not specified, then the index into hte fil- ters array will be used instead. match Required. An object whose keys describe fields to match on, and whose values contain POSIX Extended Regular Expressions to match against. All fields that are specified are tested, and a rule is only selected if all of the specified expressions match. The first rule to match will handle the corefile. The following fields are valid for matching against: comm The command that was executed. The comm field is the full path to the command when it's available. domainname The domainname from the process' jail or the host, as ap- plicable. hostname The hostname from the process' jail or the host, as applic- able. jail The jail name from the process' jail if it was jailed, or the empty string if it was not. path The original path of the corefile. For cores that were dumped through ucoredev(4), the path will be empty. execute Required. One or more actions to execute against the core. Either a single object or an array of object(s) is accepted. Each action object has a required key, type, to name the action to execute. The valid action types and the required arguments are de- scribed above in "Policies". The named arguments are expected to be provided as a key in the same object. FILES /usr/local/etc/ucored.conf, /var/run/ucored.sock, /var/ucrash EXIT STATUS The ucored utility exits 1 if an error occurs in startup. SEE ALSO chflags(1), copy_file_range(2), rename(2), unlink(2), pidfile(3), sig- nal(3), ucoredev(4), devd(8), inetd(8), sysctl(8) FreeBSD ports 15.quarterly August 20, 2025 UCORED(8)
NAME | SYNOPSIS | DESCRIPTION | FILES | EXIT STATUS | SEE ALSO
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=ucored&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>