From 29de35667936a5cd26d7c3fe929342e483c34ea4 Mon Sep 17 00:00:00 2001 From: Yu Watanabe Date: Mon, 10 Aug 2026 05:55:23 +0900 Subject: [PATCH] man: update documentation for systemd-coredump --- man/coredump.conf.xml | 16 ++- man/rules/meson.build | 5 +- man/systemd-coredump.xml | 228 +++++++++++++++++++++++++++++++++++---- tools/command_ignorelist | 3 + 4 files changed, 230 insertions(+), 22 deletions(-) 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-coredump systemd-coredump.socket systemd-coredump@.service + systemd-coredump-register.service + systemd-coredumpd.service Acquire, 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-coredump systemd-coredump.socket + systemd-coredump@.service + systemd-coredump-register.service + systemd-coredumpd.service @@ -64,29 +70,193 @@ Handling. - Invocation of <command>systemd-coredump</command> + 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"]