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 the 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       MESSAGE=
250           The message generated by systemd-coredump that includes the
251           backtrace if it was successfully generated. When systemd-coredump
252           is invoked with --backtrace, this field is provided by the caller.
253
254       Various other fields exist in the journal entry, but pertain to the
255       logging process, i.e.  systemd-coredump, not the crashed process. See
256       systemd.journal-fields(7).
257
258       The following fields are saved (if known) with the external file listed
259       in COREDUMP_FILENAME= as extended attributes:
260
261       user.coredump.pid, user.coredump.uid, user.coredump.gid,
262       user.coredump.signal, user.coredump.timestamp, user.coredump.rlimit,
263       user.coredump.hostname, user.coredump.comm, user.coredump.exe
264           Those are the same as COREDUMP_PID=, COREDUMP_UID=, COREDUMP_GID=,
265           COREDUMP_SIGNAL=, COREDUMP_TIMESTAMP=, COREDUMP_RLIMIT=,
266           COREDUMP_HOSTNAME=, COREDUMP_COMM=, and COREDUMP_EXE=, described
267           above.
268
269       Those can be viewed using getfattr(1). For the core file described in
270       the journal entry shown above:
271
272           $ getfattr --absolute-names -d /var/lib/systemd/coredump/core.Web....552351.....zst
273           # file: /var/lib/systemd/coredump/core.Web....552351.....zst
274           user.coredump.pid="552351"
275           user.coredump.uid="1000"
276           user.coredump.gid="1000"
277           user.coredump.signal="11"
278           user.coredump.timestamp="1614342930000000"
279           user.coredump.comm="Web Content"
280           user.coredump.exe="/usr/lib64/firefox/firefox"
281           ...
282
283

SEE ALSO

285       coredump.conf(5), coredumpctl(1), systemd-journald.service(8), systemd-
286       tmpfiles(8), core(5), sysctl.d(5), systemd-sysctl.service(8).
287

NOTES

289        1. Journal Export Format
290           https://www.freedesktop.org/wiki/Software/systemd/export
291
292        2. systemd-coredump-python
293           https://github.com/systemd/systemd-coredump-python
294
295        3. kill(1) expects signal names without the prefix; kill(2) uses the
296           prefix; all systemd tools accept signal names both with and without
297           the prefix.
298
299
300
301
302systemd 248                                                SYSTEMD-COREDUMP(8)
Impressum