diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml
index 74b025636e..f59c0dacd1 100644
--- a/man/coredump.conf.xml
+++ b/man/coredump.conf.xml
@@ -47,6 +47,18 @@
and
core5
pages for the details.
+
+ On systems where core dumps are processed by the long-running
+ systemd-coredumpd.service (rather than a fresh
+ systemd-coredump@.service instance started for every crash, see
+ systemd-coredump8 for
+ details on when each applies), these configuration files are only read once, when the service starts.
+ If systemd-coredumpd.service is running, changes to
+ coredump.conf or its drop-ins will not take effect until the
+ service is reloaded:
+ systemctl reload systemd-coredumpd.service
+ This causes the running service to reparse its configuration without restarting or interrupting any core
+ dump currently being processed.
@@ -168,9 +180,9 @@
makes
sure that old core dumps are removed as soon as the total disk
space taken up by core dumps grows beyond this limit (defaults
- to 10% of the total disk size, capped at 4GiB, minimum 1MiB).
+ to 10% of the total disk size, capped at 4GiB, minimum 1MiB).
controls how much disk space to keep
- free at least (defaults to 15% of the total disk size, limited
+ free at least (defaults to 15% of the total disk size, limited
to a maximum of 4GiB). Note that the disk space used
by core dumps might temporarily exceed these limits while
core dumps are processed. takes precedence.
diff --git a/man/rules/meson.build b/man/rules/meson.build
index 35b025c89e..12dc58c6da 100644
--- a/man/rules/meson.build
+++ b/man/rules/meson.build
@@ -1041,7 +1041,10 @@ manpages = [
['systemd-clonesetup', '8', ['systemd-clonesetup@.service'], ''],
['systemd-coredump',
'8',
- ['systemd-coredump.socket', 'systemd-coredump@.service'],
+ ['systemd-coredump-register.service',
+ 'systemd-coredump.socket',
+ 'systemd-coredump@.service',
+ 'systemd-coredumpd.service'],
'ENABLE_COREDUMP'],
['systemd-creds', '1', [], ''],
['systemd-cryptenroll', '1', [], 'HAVE_LIBCRYPTSETUP'],
diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml
index 4741d25408..6e96a6953f 100644
--- a/man/systemd-coredump.xml
+++ b/man/systemd-coredump.xml
@@ -20,14 +20,20 @@
systemd-coredumpsystemd-coredump.socketsystemd-coredump@.service
+ systemd-coredump-register.service
+ systemd-coredumpd.serviceAcquire, save and process core dumps/usr/lib/systemd/systemd-coredump/usr/lib/systemd/systemd-coredump
- systemd-coredump@.service
+ /usr/lib/systemd/systemd-coredump
+ /usr/lib/systemd/systemd-coredumpsystemd-coredump.socket
+ systemd-coredump@.service
+ systemd-coredump-register.service
+ systemd-coredumpd.service
@@ -64,29 +70,193 @@
Handling.
- Invocation of systemd-coredump
+ Overview
- The systemd-coredump executable does the actual work. It is invoked twice:
- once as the handler by the kernel, and the second time in the
- systemd-coredump@.service to actually write the data to the journal and process
- and save the core file.
+ The systemd-coredump executable does the actual work, but is invoked
+ differently depending on the capabilities of the running kernel.
- When the kernel invokes systemd-coredump to handle a core dump, it runs in
- privileged mode, and will connect to the socket created by the
+ When the kernel supports the kernel coredump socket protocol (see "Kernel Requirements" below,
+ generally kernel v6.19 or newer), systemd-coredumpd.service creates and listens on
+ a Unix socket, and systemd-coredump-register.service writes the socket path to
+ /proc/sys/kernel/core_pattern. When a process crashes, the kernel connects to the
+ socket, and sends the core dump of the process through the socket. Then,
+ systemd-coredumpd.service transfers the core to the corresponding container if the
+ crashed process is in a container environment, otherwise saves the core in the local storage and writes
+ information about the crashed process to journal.
+
+ When the running kernel does not meet those requirements, the executable
+ systemd-coredump is invoked twice: once as the handler by the kernel, and the second
+ time in the systemd-coredump@.service to actually write the data to the journal and
+ process and save the core file.
+
+ When the kernel invokes systemd-coredump to handle a core dump this way, it
+ runs in privileged mode, and will connect to the socket created by the
systemd-coredump.socket unit, which in turn will spawn an unprivileged
systemd-coredump@.service instance to process the core dump. Hence
systemd-coredump.socket and systemd-coredump@.service are
helper units which do the actual processing of core dumps and are subject to normal service
management.
- It is also possible to invoke systemd-coredump with
- option. In this case, systemd-coredump expects a
- journal entry in the journal
- Journal Export Format
- on standard input. The entry should contain a MESSAGE= field and any additional
- metadata fields the caller deems reasonable. systemd-coredump will append additional
- metadata fields in the same way it does for core dumps received from the kernel. In this mode, no core
- dump is stored in the journal.
+ See "Units" below for details on the individual units involved in either mode.
+
+
+
+ Command-line Options
+
+ systemd-coredump is normally not invoked directly by the user, but by the
+ kernel, or by the units described below. It supports the following modes of invocation:
+
+
+
+ (no option)
+
+ Handles a single core dump. This is the mode the kernel uses to invoke
+ systemd-coredump directly (via kernel.core_pattern) on
+ kernels that do not support the kernel coredump socket protocol, as well as the mode used by
+ systemd-coredump@.service to actually process and save a core dump that was
+ handed to it via systemd-coredump.socket.
+
+
+
+
+
+ systemd-coredump expects a journal entry in the
+ Journal Export
+ Format on standard input. The entry should contain a MESSAGE= field and
+ any additional metadata fields the caller deems reasonable.
+ systemd-coredump will append additional metadata fields in the same way it does
+ for core dumps received from the kernel. In this mode, no core dump is stored in the
+ journal.
+
+
+
+
+
+ Runs systemd-coredump as the long-running manager process that
+ listens on the kernel coredump socket, accepts connections from the kernel, and forks off worker
+ processes to process each individual core dump. This is the mode used internally by
+ systemd-coredumpd.service and is not intended to be invoked interactively.
+ See "Units" below for details.
+
+
+
+
+
+
+
+ Checks whether the running kernel and execution environment fulfil the
+ requirements for the kernel coredump socket protocol (see "Kernel Requirements" below), and exits
+ with a non-zero status if they are not met. This is used internally as the
+ ExecCondition= of systemd-coredumpd.service and
+ systemd-coredump-register.service, so that those units are skipped, without
+ being marked as failed, on systems where the feature is unavailable. It is not intended to be
+ invoked interactively.
+
+
+
+
+
+
+
+ Kernel Requirements for the Coredump Socket
+
+ The kernel coredump socket protocol, used by systemd-coredumpd.service and
+ systemd-coredump-register.service, requires:
+
+
+ A kernel that supports the PIDFD_INFO_COREDUMP (since kernel
+ v6.16) and PIDFD_INFO_COREDUMP_SIGNAL (since kernel v6.19) flags for the
+ PIDFD_GET_INFO
+ ioctl2
+ operation on a PID file descriptor (see
+ pidfd_open2).
+ Support for these flags is used as an indicator that the kernel is also new enough to support the
+ request-mode (@@-prefixed) kernel coredump socket
+ kernel.core_pattern, which was introduced in kernel v6.17.
+
+ systemd-coredump must be running in the initial PID, USER, and
+ TIME namespaces, i.e. on the host, not inside a container.
+
+
+ These conditions are checked with systemd-coredump
+ before systemd-coredumpd.service and
+ systemd-coredump-register.service are started. If the requirements are not met,
+ systemd-coredump instead falls back to the legacy invocation via
+ systemd-coredump.socket and systemd-coredump@.service.
+
+
+
+ Units
+
+ The following units are involved in processing core dumps. Which of them are active depends on
+ whether the kernel coredump socket protocol is available, see "Kernel Requirements" above.
+
+
+
+ systemd-coredumpd.service
+
+ A long-running manager service, started early at boot on kernels that support the
+ kernel coredump socket protocol. It creates and listens on the AF_UNIX socket
+ /run/systemd/coredumpd/kernel (this path is also passed to the kernel via
+ kernel.core_pattern by systemd-coredump-register.service,
+ see below). When the kernel connects to this socket to submit a core dump,
+ systemd-coredumpd.service accepts the connection and forks off a worker
+ process to receive and process that specific core dump, up to a limit of 8 concurrently running
+ workers (once this limit is reached, no further connections are accepted until a worker finishes).
+ Workers that run for longer than 5 minutes are killed automatically.
+
+ The configuration in
+ coredump.conf5
+ is read once when systemd-coredumpd.service starts. Since the service keeps
+ running afterwards (rather than being invoked anew for every core dump, as
+ systemd-coredump@.service is), changes to
+ coredump.conf and its drop-ins are not picked up
+ automatically. Reload the service to apply configuration changes, see
+ coredump.conf5
+ for details.
+
+
+
+
+
+ systemd-coredump-register.service
+
+ A oneshot unit, automatically pulled in and bound to the lifetime of
+ systemd-coredumpd.service (it is not meant to be started or stopped manually).
+ Once systemd-coredumpd.service is up, this unit points the kernel at it by
+ setting kernel.core_pattern to the request-mode (@@-prefixed)
+ socket path /run/systemd/coredumpd/kernel, and persists this setting to
+ /run/sysctl.d/60-coredump.conf via
+ systemd-sysctl8.
+ When systemd-coredumpd.service is stopped,
+ systemd-coredump-register.service is stopped along with it and reverts
+ kernel.core_pattern to its previous value.
+
+ Because /run/sysctl.d/60-coredump.conf takes precedence, per the usual
+ sysctl.d5
+ ordering rules, over the /usr/lib/sysctl.d/50-coredump.conf file described in
+ "Configuration" below, masking or overriding 50-coredump.conf alone is
+ not sufficient to install a custom kernel.core_pattern on a
+ system where systemd-coredumpd.service is active. See "Configuration" below
+ for how to prevent this.
+
+
+
+
+
+ systemd-coredump.socket
+ systemd-coredump@.service
+
+ Legacy handler units, used on kernels that do not support the kernel coredump
+ socket protocol (see "Kernel Requirements" above). The kernel invokes
+ systemd-coredump directly and in privileged mode for each crash; that instance
+ connects to systemd-coredump.socket, which in turn spawns an unprivileged
+ systemd-coredump@.service instance to actually process and save the core
+ dump. Unlike systemd-coredumpd.service, a fresh
+ systemd-coredump@.service instance is started for every core dump, so it
+ always reads the current coredump.conf configuration.
+
+
@@ -150,6 +320,21 @@
systemd-sysctl8.
+ On systems where systemd-coredumpd.service is active (see "Kernel
+ Requirements" and "Units" above), systemd-coredump-register.service writes its own
+ kernel.core_pattern setting to /run/sysctl.d/60-coredump.conf
+ whenever systemd-coredumpd.service is running, and this file takes precedence over
+ /usr/lib/sysctl.d/50-coredump.conf. As a result, masking or overriding
+ 50-coredump.conf alone does not override the default
+ kernel.core_pattern on such systems, since 60-coredump.conf will
+ still take effect. To set a custom kernel.core_pattern of your own on a system where
+ systemd-coredumpd.service is available, you must additionally stop (if currently
+ running) and mask systemd-coredumpd.service:
+ systemctl mask --now systemd-coredumpd.service
+ Masking systemd-coredumpd.service also prevents
+ systemd-coredump-register.service, which is bound to it, from running and writing
+ 60-coredump.conf.
+
In order to be used in the mode, an appropriate backtrace
handler must be installed on the sender side. For example, in case of
python1, this
@@ -160,9 +345,14 @@
The behavior of systemd-coredump itself is configured through the configuration file
/etc/systemd/coredump.conf and corresponding snippets
/etc/systemd/coredump.conf.d/*.conf, see
- coredump.conf5. A new
- instance of systemd-coredump is invoked upon receiving every core dump. Therefore, changes
- in these files will take effect the next time a core dump is received.
+ coredump.conf5. When
+ core dumps are processed via systemd-coredump@.service (see "Units" above), a new
+ instance of systemd-coredump is invoked upon receiving every core dump, and changes in
+ these files will take effect the next time a core dump is received. When core dumps are instead processed
+ by the long-running systemd-coredumpd.service, configuration changes require an
+ explicit reload of that service to take effect; see
+ coredump.conf5 for
+ details.Resources used by core dump files are restricted in two ways. Parameters like maximum size of acquired
core dumps and files can be set in files /etc/systemd/coredump.conf and snippets mentioned
diff --git a/tools/command_ignorelist b/tools/command_ignorelist
index cb256d6647..69aaccb96c 100644
--- a/tools/command_ignorelist
+++ b/tools/command_ignorelist
@@ -157,6 +157,9 @@ systemd-cgtop.xml ./refsect1[title="Keys"]/variablelist/varlistentry[term="h"]
systemd-cgtop.xml ./refsect1[title="Keys"]/variablelist/varlistentry[term="q"]
systemd-cgtop.xml ./refsect1[title="Keys"]/variablelist/varlistentry[term="p"]
systemd-cgtop.xml ./refsect1[title="Keys"]/variablelist/varlistentry[term="+"]
+systemd-coredump.xml ./refsect1[title="Description"]/refsect2[title="Command-line Options"]/variablelist/varlistentry[term="(no option)"]
+systemd-coredump.xml ./refsect1[title="Description"]/refsect2[title="Command-line Options"]/variablelist/varlistentry[term="--backtrace"]
+systemd-coredump.xml ./refsect1[title="Description"]/refsect2[title="Units"]/variablelist/varlistentry[term="systemd-coredump.socket"]
systemd-delta.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="-t"]
systemd-delta.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="--diff="]
systemd-delta.xml ./refsect1[title="Options"]/variablelist/varlistentry[term="-t"]/listitem/para/variablelist/varlistentry[term="masked"]