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       For further details see systemd Coredump Handling[1].
48
49   Invocation of systemd-coredump
50       The systemd-coredump executable does the actual work. It is invoked
51       twice: once as the handler by the kernel, and the second time in the
52       systemd-coredump@.service to actually write the data to the journal and
53       process and save the core file.
54
55       When the kernel invokes systemd-coredump to handle a core dump, it runs
56       in privileged mode, and will connect to the socket created by the
57       systemd-coredump.socket unit, which in turn will spawn an unprivileged
58       systemd-coredump@.service instance to process the core dump. Hence
59       systemd-coredump.socket and systemd-coredump@.service are helper units
60       which do the actual processing of core dumps and are subject to normal
61       service management.
62
63       It is also possible to invoke systemd-coredump with --backtrace option.
64       In this case, systemd-coredump expects a journal entry in the journal
65       Journal Export Format[2] on standard input. The entry should contain a
66       MESSAGE= field and any additional metadata fields the caller deems
67       reasonable.  systemd-coredump will append additional metadata fields in
68       the same way it does for core dumps received from the kernel. In this
69       mode, no core dump is stored in the journal.
70

CONFIGURATION

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

INFORMATION ABOUT THE CRASHED PROCESS

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

SEE ALSO

307       coredump.conf(5), coredumpctl(1), systemd-journald.service(8), systemd-
308       tmpfiles(8), core(5), sysctl.d(5), systemd-sysctl.service(8), systemd
309       Coredump Handling[1]
310

NOTES

312        1. systemd Coredump Handling
313           https://systemd.io/COREDUMP
314
315        2. Journal Export Format
316           https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
317
318        3. systemd-coredump-python
319           https://github.com/systemd/systemd-coredump-python
320
321        4. kill(1) expects signal names without the prefix; kill(2) uses the
322           prefix; all systemd tools accept signal names both with and without
323           the prefix.
324
325        5. the coredump metadata spec
326           https://systemd.io/COREDUMP_PACKAGE_METADATA/
327
328
329
330systemd 254                                                SYSTEMD-COREDUMP(8)
Impressum