systemd-coredump@.service(8)

1SYSTEMD-COREDUMP(8)            systemd-coredump            SYSTEMD-COREDUMP(8)
2
3
4

NAME

6       systemd-coredump, systemd-coredump.socket, systemd-coredump@.service -
7       Acquire, save and process core dumps
8

SYNOPSIS

10       /usr/lib/systemd/systemd-coredump
11
12       /usr/lib/systemd/systemd-coredump --backtrace
13
14       systemd-coredump@.service
15
16       systemd-coredump.socket
17

DESCRIPTION

19       systemd-coredump@.service is a system service to process core dumps. It
20       will log a summary of the event to systemd-journald.service(8),
21       including information about the process identifier, owner, the signal
22       that killed the process, and the stack trace if possible. It may also
23       save the core dump for later processing. See the "Information about the
24       crashed process" section below.
25
26       The behavior of a specific program upon reception of a signal is
27       governed by a few factors which are described in detail in core(5). In
28       particular, the core dump will only be processed when the related
29       resource limits are sufficient.
30
31       Core dumps can be written to the journal or saved as a file. In both
32       cases, they can be retrieved for further processing, for example in
33       gdb(1). See coredumpctl(1), in particular the list and debug verbs.
34
35       By default, systemd-coredump will log the core dump to the journal,
36       including a backtrace if possible, and store the core dump (an image of
37       the memory contents of the process) itself in an external file in
38       /var/lib/systemd/coredump. These core dumps are deleted after a few
39       days by default; see /usr/lib/tmpfiles.d/systemd.conf for details. Note
40       that the removal of core files from the file system and the purging of
41       journal entries are independent, and the core file may be present
42       without the journal entry, and journal entries may point to
43       since-removed core files. Some metadata is attached to core files in
44       the form of extended attributes, so the core files are useful for some
45       purposes even without the full metadata available in the journal entry.
46
47   Invocation of systemd-coredump
48       The systemd-coredump executable does the actual work. It is invoked
49       twice: once as the handler by the kernel, and the second time in the
50       systemd-coredump@.service to actually write the data to the journal and
51       process and save the core file.
52
53       When the kernel invokes systemd-coredump to handle a core dump, it runs
54       in privileged mode, and will connect to the socket created by the
55       systemd-coredump.socket unit, which in turn will spawn an unprivileged
56       systemd-coredump@.service instance to process the core dump. Hence
57       systemd-coredump.socket and systemd-coredump@.service are helper units
58       which do the actual processing of core dumps and are subject to normal
59       service management.
60
61       It is also possible to invoke systemd-coredump with --backtrace option.
62       In this case, systemd-coredump expects a journal entry in the journal
63       Journal Export Format[1] on standard input. The entry should contain a
64       MESSAGE= field and any additional metadata fields the caller deems
65       reasonable.  systemd-coredump will append additional metadata fields in
66       the same way it does for core dumps received from the kernel. In this
67       mode, no core dump is stored in the journal.
68

CONFIGURATION

70       For programs started by systemd, process resource limits can be set by
71       directive LimitCORE=, see systemd.exec(5).
72
73       In order to be used by the kernel to handle core dumps,
74       systemd-coredump must be configured in sysctl(8) parameter
75       kernel.core_pattern. The syntax of this parameter is explained in
76       core(5). systemd installs the file /usr/lib/sysctl.d/50-coredump.conf
77       which configures kernel.core_pattern accordingly. This file may be
78       masked or overridden to use a different setting following normal
79       sysctl.d(5) rules. If the sysctl configuration is modified, it must be
80       updated in the kernel before it takes effect, see sysctl(8) and
81       systemd-sysctl(8).
82
83       In order to be used in the --backtrace mode, an appropriate backtrace
84       handler must be installed on the sender side. For example, in case of
85       python(1), this means a sys.excepthook must be installed, see
86       systemd-coredump-python[2].
87
88       The behavior of systemd-coredump itself is configured through the
89       configuration file /etc/systemd/coredump.conf and corresponding
90       snippets /etc/systemd/coredump.conf.d/*.conf, see coredump.conf(5). A
91       new instance of systemd-coredump is invoked upon receiving every core
92       dump. Therefore, changes in these files will take effect the next time
93       a core dump is received.
94
95       Resources used by core dump files are restricted in two ways.
96       Parameters like maximum size of acquired core dumps and files can be
97       set in files /etc/systemd/coredump.conf and snippets mentioned above.
98       In addition the storage time of core dump files is restricted by
99       systemd-tmpfiles, corresponding settings are by default in
100       /usr/lib/tmpfiles.d/systemd.conf. The default is to delete core dumps
101       after a few days; see the above file for details.
102
103   Disabling coredump processing
104       To disable potentially resource-intensive processing by
105       systemd-coredump, set
106
107           Storage=none ProcessSizeMax=0
108
109       in coredump.conf(5).
110

INFORMATION ABOUT THE CRASHED PROCESS

112       coredumpctl(1) can be used to retrieve saved core dumps independently
113       of their location, to display information, and to process them e.g. by
114       passing to the GNU debugger (gdb).
115
116       Data stored in the journal can be also viewed with journalctl(1) as
117       usual (or from any other process, using the sd-journal(3) API). The
118       relevant messages have MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1:
119
120           $ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 -o verbose
121           ...
122           MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
123           COREDUMP_PID=552351
124           COREDUMP_UID=1000
125           COREDUMP_GID=1000
126           COREDUMP_SIGNAL_NAME=SIGSEGV
127           COREDUMP_SIGNAL=11
128           COREDUMP_TIMESTAMP=1614342930000000
129           COREDUMP_COMM=Web Content
130           COREDUMP_EXE=/usr/lib64/firefox/firefox
131           COREDUMP_USER_UNIT=app-gnome-firefox-552136.scope
132           COREDUMP_CMDLINE=/usr/lib64/firefox/firefox -contentproc -childID 5 -isForBrowser ...
133           COREDUMP_CGROUP=/user.slice/user-1000.slice/user@1000.service/app.slice/app-....scope
134           COREDUMP_FILENAME=/var/lib/systemd/coredump/core.Web....552351.....zst
135           ...
136
137
138       The following fields are saved (if known) with the journal entry
139
140       COREDUMP_UID=, COREDUMP_PID=, COREDUMP_GID=
141           The process number (PID), owner user number (UID), and group number
142           (GID) of the crashed process.
143
144           When the crashed process was part of a container (or in a process
145           or user namespace in general), those are the values as seen
146           outside, in the namespace where systemd-coredump is running.
147
148       COREDUMP_TIMESTAMP=
149           The time of the crash as reported by the kernel (in µs since the
150           epoch).
151
152       COREDUMP_RLIMIT=
153           The core file size soft resource limit, see getrlimit(2).
154
155       COREDUMP_UNIT=, COREDUMP_SLICE=
156           The system unit and slice names.
157
158           When the crashed process was in container, those are the units
159           names outside, in the main system manager.
160
161       COREDUMP_CGROUP=
162           Control group information in the format used in /proc/self/cgroup.
163           On systems with the unified cgroup hierarchy, this is a single path
164           prefixed with "0::", and multiple paths prefixed with controller
165           numbers on legacy systems.
166
167           When the crashed process was in a container, this is the full path,
168           as seen outside of the container.
169
170       COREDUMP_OWNER_UID=, COREDUMP_USER_UNIT=
171           The numerical UID of the user owning the login session or systemd
172           user unit of the crashed process, and the user manager unit. Both
173           fields are only present for user processes.
174
175           When the crashed process was in container, those are the values
176           outside, in the main system.
177
178       COREDUMP_SIGNAL_NAME=, COREDUMP_SIGNAL=
179           The terminating signal name (with the "SIG" prefix [3]) and
180           numerical value. (Both are included because signal numbers vary by
181           architecture.)
182
183       COREDUMP_CWD=, COREDUMP_ROOT=
184           The current working directory and root directory of the crashed
185           process.
186
187           When the crashed process is in a container, those paths are
188           relative to the root of the container's mount namespace.
189
190       COREDUMP_OPEN_FDS=
191           Information about open file descriptors, in the following format:
192
193               fd:/path/to/file
194               pos:     ...
195               flags:   ...
196               ...
197
198               fd:/path/to/file
199               pos:     ...
200               flags:   ...
201               ...
202
203
204           The first line contains the file descriptor number fd and the path,
205           while subsequent lines show the contents of /proc/pid/fdinfo/fd.
206
207       COREDUMP_EXE=
208           The destination of the /proc/pid/exe symlink.
209
210           When the crashed process is in a container, that path is relative
211           to the root of the container's mount namespace.
212
213       COREDUMP_COMM=, COREDUMP_PROC_STATUS=, COREDUMP_PROC_MAPS=,
214       COREDUMP_PROC_LIMITS=, COREDUMP_PROC_MOUNTINFO=, COREDUMP_ENVIRON=
215           Fields that map the per-process entries in the /proc/ filesystem:
216           /proc/pid/comm (the command name associated with the process),
217           /proc/pid/exe (the filename of the executed command),
218           /proc/pid/status (various metadata about the process),
219           /proc/pid/maps (memory regions visible to the process and their
220           access permissions), /proc/pid/limits (the soft and hard resource
221           limits), /proc/pid/mountinfo (mount points in the process's mount
222           namespace), /proc/pid/environ (the environment block of the crashed
223           process).
224
225           See proc(5) for more information.
226
227       COREDUMP_HOSTNAME=
228           The system hostname.
229
230           When the crashed process was in container, this is the container
231           hostname.
232
233       COREDUMP_CONTAINER_CMDLINE=
234           For processes running in a container, the commandline of the
235           process spawning the container (the first parent process with a
236           different mount namespace).
237
238       COREDUMP=
239           When the core is stored in the journal, the core image itself.
240
241       COREDUMP_FILENAME=
242           When the core is stored externally, the path to the core file.
243
244       COREDUMP_TRUNCATED=
245           Set to "1" when the saved coredump was truncated. (A partial core
246           image may still be processed by some tools, though obviously not
247           all information is available.)
248
249       COREDUMP_PACKAGE_NAME=, COREDUMP_PACKAGE_VERSION=,
250       COREDUMP_PACKAGE_JSON=
251           If the executable contained .package metadata ELF notes, they will
252           be parsed and attached. The package and packageVersion of the
253           'main' ELF module (ie: the executable) will be appended
254           individually. The JSON-formatted content of all modules will be
255           appended as a single JSON object, each with the module name as the
256           key. For more information about this metadata format and content,
257           see the coredump metadata spec[4].
258
259       MESSAGE=
260           The message generated by systemd-coredump that includes the
261           backtrace if it was successfully generated. When systemd-coredump
262           is invoked with --backtrace, this field is provided by the caller.
263
264       Various other fields exist in the journal entry, but pertain to the
265       logging process, i.e.  systemd-coredump, not the crashed process. See
266       systemd.journal-fields(7).
267
268       The following fields are saved (if known) with the external file listed
269       in COREDUMP_FILENAME= as extended attributes:
270
271       user.coredump.pid, user.coredump.uid, user.coredump.gid,
272       user.coredump.signal, user.coredump.timestamp, user.coredump.rlimit,
273       user.coredump.hostname, user.coredump.comm, user.coredump.exe
274           Those are the same as COREDUMP_PID=, COREDUMP_UID=, COREDUMP_GID=,
275           COREDUMP_SIGNAL=, COREDUMP_TIMESTAMP=, COREDUMP_RLIMIT=,
276           COREDUMP_HOSTNAME=, COREDUMP_COMM=, and COREDUMP_EXE=, described
277           above.
278
279       Those can be viewed using getfattr(1). For the core file described in
280       the journal entry shown above:
281
282           $ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web....552351.....zst
283           # file: /var/lib/systemd/coredump/core.Web....552351.....zst
284           user.coredump.pid="552351"
285           user.coredump.uid="1000"
286           user.coredump.gid="1000"
287           user.coredump.signal="11"
288           user.coredump.timestamp="1614342930000000"
289           user.coredump.comm="Web Content"
290           user.coredump.exe="/usr/lib64/firefox/firefox"
291           ...
292
293

NOTES

299        1. Journal Export Format
300           https://www.freedesktop.org/wiki/Software/systemd/export
301
302        2. systemd-coredump-python
303           https://github.com/systemd/systemd-coredump-python
304
305        3. kill(1) expects signal names without the prefix; kill(2) uses the
306           prefix; all systemd tools accept signal names both with and without
307           the prefix.
308
309        4. the coredump metadata spec
310           https://systemd.io/COREDUMP_PACKAGE_METADATA/
311
312
313
314systemd 249                                                SYSTEMD-COREDUMP(8)

NAME

SYNOPSIS

DESCRIPTION

CONFIGURATION

INFORMATION ABOUT THE CRASHED PROCESS

SEE ALSO

NOTES