Debian Codegraph @

upstream/debian-trixie/man8/systemd-coredump.8

raw
1 '\" t
2 .TH "SYSTEMD\-COREDUMP" "8" "" "systemd 257.13" "systemd-coredump"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-coredump, systemd-coredump.socket, [email protected] \- Acquire, save and process core dumps
24 .SH "SYNOPSIS"
25 .PP
26 /usr/lib/systemd/systemd\-coredump
27 .PP
28 /usr/lib/systemd/systemd\-coredump
29 \fB\-\-backtrace\fR
30 .PP
31 systemd\-coredump@\&.service
32 .PP
33 systemd\-coredump\&.socket
34 .SH "DESCRIPTION"
35 .PP
36 systemd\-coredump@\&.service
37 is a system service to process core dumps\&. It will log a summary of the event to
38 \fBsystemd-journald.service\fR(8), including information about the process identifier, owner, the signal that killed the process, and the stack trace if possible\&. It may also save the core dump for later processing\&. See the "Information about the crashed process" section below\&.
39 .PP
40 The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in
41 \fBcore\fR(5)\&. In particular, the core dump will only be processed when the related process resource limits (\fBRLIMIT_CORE\fR) are sufficient\&.
42 .PP
43 Core dumps can be written to the journal or saved as a file\&. In both cases, they can be retrieved for further processing, for example in
44 \fBgdb\fR(1)\&. See
45 \fBcoredumpctl\fR(1), in particular the
46 \fBlist\fR
47 and
48 \fBdebug\fR
49 verbs\&.
50 .PP
51 By default,
52 \fBsystemd\-coredump\fR
53 will log the core dump to the journal, including a backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in an external file in
54 /var/lib/systemd/coredump/\&. These core dumps are deleted after a few days by default; see
55 /usr/lib/tmpfiles\&.d/systemd\&.conf
56 for details\&. Note that the removal of core files from the file system and the purging of journal entries are independent, and the core file may be present without the journal entry, and journal entries may point to since\-removed core files\&. Some metadata is attached to core files in the form of extended attributes, so the core files are useful for some purposes even without the full metadata available in the journal entry\&.
57 .PP
58 For further details see
59 \m[blue]\fBsystemd Coredump Handling\fR\m[]\&\s-2\u[1]\d\s+2\&.
60 .SS "Invocation of systemd\-coredump"
61 .PP
62 The
63 \fBsystemd\-coredump\fR
64 executable does the actual work\&. It is invoked twice: once as the handler by the kernel, and the second time in the
65 systemd\-coredump@\&.service
66 to actually write the data to the journal and process and save the core file\&.
67 .PP
68 When the kernel invokes
69 \fBsystemd\-coredump\fR
70 to handle a core dump, it runs in privileged mode, and will connect to the socket created by the
71 systemd\-coredump\&.socket
72 unit, which in turn will spawn an unprivileged
73 systemd\-coredump@\&.service
74 instance to process the core dump\&. Hence
75 systemd\-coredump\&.socket
76 and
77 systemd\-coredump@\&.service
78 are helper units which do the actual processing of core dumps and are subject to normal service management\&.
79 .PP
80 It is also possible to invoke
81 \fBsystemd\-coredump\fR
82 with
83 \fB\-\-backtrace\fR
84 option\&. In this case,
85 \fBsystemd\-coredump\fR
86 expects a journal entry in the journal
87 \m[blue]\fBJournal Export Format\fR\m[]\&\s-2\u[2]\d\s+2
88 on standard input\&. The entry should contain a
89 \fIMESSAGE=\fR
90 field and any additional metadata fields the caller deems reasonable\&.
91 \fBsystemd\-coredump\fR
92 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\&.
93 .SS "Core dumps in Containers/Namespaces"
94 .PP
95 The
96 systemd\-coredump@\&.service
97 service will automatically attempt to extract a stacktrace from a process as it crashes\&. For this stacktrace symbols will be resolved based on debug information embedded in the crashing ELF image, or equivalent debug information separately available on the host OS\&. For processes that crash inside of local containers or other mount namespace\-based sandboxes, this auxiliary debug information is typically not available on the host (simply because containers typically run different software versions than the host)\&.
98 systemd\-coredump
99 provides two mechanisms to address this:
100 .sp
101 .RS 4
102 .ie n \{\
103 \h'-04' 1.\h'+01'\c
104 .\}
105 .el \{\
106 .sp -1
107 .IP " 1." 4.2
108 .\}
109 For full\-OS containers running systemd inside it is a good idea to enable
110 \fICoredumpReceive=\fR
111 on the unit (see
112 \fBsystemd.resource-control\fR(5)), which ensures that coredumps of a container are attempted to be forwarded to
113 systemd\-coredump@\&.service
114 running inside the container, i\&.e the container gets to process and store its own core dumps\&. Note that
115 \fBsystemd-nspawn\fR(8)
116 defaults to this mode if invoked with the
117 \fB\-\-boot\fR
118 switch\&. This mode of operation is generally recommended for security reasons: the security\-sensitive processing of the core dump is done within the confinements of the container itself, by the container\*(Aqs own code, backed by the container\*(Aqs own storage\&.
119 .RE
120 .sp
121 .RS 4
122 .ie n \{\
123 \h'-04' 2.\h'+01'\c
124 .\}
125 .el \{\
126 .sp -1
127 .IP " 2." 4.2
128 .\}
129 Alternatively, for more restricted containers (that do not run a proper
130 init
131 system as PID 1) it is possible to enable processing of the core dump on the host, with access to the debug information data from the container itself\&. This mode of operation must be enabled via
132 \fIEnterNamespace=\fR
133 in
134 \fBcoredump.conf\fR(5), and defaults to off, for security reasons\&.
135 .RE
136 .PP
137 If both
138 \fICoredumpReceive=\fR
139 is enabled on the unit of the container the core dump belongs to, and
140 \fIEnterNamespace=\fR
141 is enabled in the
142 coredump\&.conf
143 configuration file, the former takes precedence\&.
144 .SH "CONFIGURATION"
145 .PP
146 For programs started by
147 \fBsystemd\fR, process resource limits can be set by directive
148 \fILimitCORE=\fR, see
149 \fBsystemd.exec\fR(5)\&.
150 .PP
151 In order to be used by the kernel to handle core dumps,
152 \fBsystemd\-coredump\fR
153 must be configured in
154 \fBsysctl\fR(8)
155 parameter
156 \fIkernel\&.core_pattern\fR\&. The syntax of this parameter is explained in
157 \fBcore\fR(5)\&. systemd installs the file
158 /usr/lib/sysctl\&.d/50\-coredump\&.conf
159 which configures
160 \fIkernel\&.core_pattern\fR
161 accordingly\&. This file may be masked or overridden to use a different setting following normal
162 \fBsysctl.d\fR(5)
163 rules\&. If the sysctl configuration is modified, it must be updated in the kernel before it takes effect, see
164 \fBsysctl\fR(8)
165 and
166 \fBsystemd-sysctl\fR(8)\&.
167 .PP
168 In order to be used in the
169 \fB\-\-backtrace\fR
170 mode, an appropriate backtrace handler must be installed on the sender side\&. For example, in case of
171 \fBpython\fR(1), this means a
172 \fIsys\&.excepthook\fR
173 must be installed, see
174 \m[blue]\fBsystemd\-coredump\-python\fR\m[]\&\s-2\u[3]\d\s+2\&.
175 .PP
176 The behavior of
177 \fBsystemd\-coredump\fR
178 itself is configured through the configuration file
179 /etc/systemd/coredump\&.conf
180 and corresponding snippets
181 /etc/systemd/coredump\&.conf\&.d/*\&.conf, see
182 \fBcoredump.conf\fR(5)\&. A new instance of
183 \fBsystemd\-coredump\fR
184 is invoked upon receiving every core dump\&. Therefore, changes in these files will take effect the next time a core dump is received\&.
185 .PP
186 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
187 /etc/systemd/coredump\&.conf
188 and snippets mentioned above\&. In addition the storage time of core dump files is restricted by
189 \fBsystemd\-tmpfiles\fR, corresponding settings are by default in
190 /usr/lib/tmpfiles\&.d/systemd\&.conf\&. The default is to delete core dumps after a few days; see the above file for details\&.
191 .SS "Disabling coredump processing"
192 .PP
193 To disable potentially resource\-intensive processing by
194 \fBsystemd\-coredump\fR, set
195 .sp
196 .if n \{\
197 .RS 4
198 .\}
199 .nf
200 Storage=none
201 ProcessSizeMax=0
202 .fi
203 .if n \{\
204 .RE
205 .\}
206 .sp
207 in
208 \fBcoredump.conf\fR(5)\&.
209 .SH "INFORMATION ABOUT THE CRASHED PROCESS"
210 .PP
211 \fBcoredumpctl\fR(1)
212 can be used to retrieve saved core dumps independently of their location, to display information, and to process them e\&.g\&. by passing to the GNU debugger (gdb)\&.
213 .PP
214 Data stored in the journal can be also viewed with
215 \fBjournalctl\fR(1)
216 as usual (or from any other process, using the
217 \fBsd-journal\fR(3)
218 API)\&. The relevant messages have
219 \fBMESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1\fR:
220 .sp
221 .if n \{\
222 .RS 4
223 .\}
224 .nf
225 $ journalctl MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1 \-o verbose
226 \&...
227 MESSAGE_ID=fc2e22bc6ee647b6b90729ab34a250b1
228 COREDUMP_PID=552351
229 COREDUMP_UID=1000
230 COREDUMP_GID=1000
231 COREDUMP_SIGNAL_NAME=SIGSEGV
232 COREDUMP_SIGNAL=11
233 COREDUMP_TIMESTAMP=1614342930000000
234 COREDUMP_COMM=Web Content
235 COREDUMP_EXE=/usr/lib64/firefox/firefox
236 COREDUMP_USER_UNIT=app\-gnome\-firefox\-552136\&.scope
237 COREDUMP_CMDLINE=/usr/lib64/firefox/firefox \-contentproc \-childID 5 \-isForBrowser \&...
238 COREDUMP_CGROUP=/user\&.slice/user\-1000\&.slice/user@1000\&.service/app\&.slice/app\-\&...\&.scope
239 COREDUMP_FILENAME=/var/lib/systemd/coredump/core\&.Web\&...\&.552351\&.\&...\&.zst
240 \&...
241 .fi
242 .if n \{\
243 .RE
244 .\}
245 .PP
246 The following fields are saved (if known) with the journal entry
247 .PP
248 \fICOREDUMP_UID=\fR, \fICOREDUMP_PID=\fR, \fICOREDUMP_GID=\fR
249 .RS 4
250 The process number (PID), owner user number (UID), and group number (GID) of the crashed process\&.
251 .sp
252 When the crashed process was part of a container (or in a process or user namespace in general), those are the values as seen
253 \fIoutside\fR, in the namespace where
254 systemd\-coredump
255 is running\&.
256 .sp
257 Added in version 248\&.
258 .RE
259 .PP
260 \fICOREDUMP_BY_PIDFD=\fR
261 .RS 4
262 If the crashed process was analyzed using a PIDFD provided by the kernel (requires kernel v6\&.16) then this field will be present and set to
263 "1"\&. If this field is not set, then the crashed process was analyzed via a PID, which is known to be subject to race conditions\&.
264 .sp
265 Added in version 258\&.
266 .RE
267 .PP
268 \fICOREDUMP_TIMESTAMP=\fR
269 .RS 4
270 The time of the crash as reported by the kernel (in μs since the epoch)\&.
271 .sp
272 Added in version 248\&.
273 .RE
274 .PP
275 \fICOREDUMP_RLIMIT=\fR
276 .RS 4
277 The core file size soft resource limit, see
278 \fBgetrlimit\fR(2)\&.
279 .sp
280 Added in version 248\&.
281 .RE
282 .PP
283 \fICOREDUMP_UNIT=\fR, \fICOREDUMP_SLICE=\fR
284 .RS 4
285 The system unit and slice names\&.
286 .sp
287 When the crashed process was in container, those are the units names
288 \fIoutside\fR, in the main system manager\&.
289 .sp
290 Added in version 248\&.
291 .RE
292 .PP
293 \fICOREDUMP_CGROUP=\fR
294 .RS 4
295 The primary cgroup of the unit of the crashed process\&.
296 .sp
297 When the crashed process was in a container, this is the full path, as seen outside of the container\&.
298 .sp
299 Added in version 248\&.
300 .RE
301 .PP
302 \fICOREDUMP_PROC_CGROUP=\fR
303 .RS 4
304 Control group information in the format used in
305 /proc/self/cgroup\&. On systems with the unified cgroup hierarchy, this is a single path prefixed with
306 "0::", and multiple paths prefixed with controller numbers on legacy systems\&.
307 .sp
308 When the crashed process was in a container, this is the full path, as seen outside of the container\&.
309 .sp
310 Added in version 248\&.
311 .RE
312 .PP
313 \fICOREDUMP_OWNER_UID=\fR, \fICOREDUMP_USER_UNIT=\fR, \fICOREDUMP_SESSION=\fR
314 .RS 4
315 The numerical UID of the user owning the login session or systemd user unit of the crashed process, the user manager unit, and the session identifier\&. All three fields are only present for user processes\&.
316 .sp
317 When the crashed process was in container, those are the values
318 \fIoutside\fR, in the main system\&.
319 .sp
320 Added in version 248\&.
321 .RE
322 .PP
323 \fICOREDUMP_SIGNAL_NAME=\fR, \fICOREDUMP_SIGNAL=\fR
324 .RS 4
325 The terminating signal name (with the
326 "SIG"
327 prefix
328 \&\s-2\u[4]\d\s+2) and numerical value\&. (Both are included because signal numbers vary by architecture\&.)
329 .sp
330 Added in version 248\&.
331 .RE
332 .PP
333 \fICOREDUMP_CWD=\fR, \fICOREDUMP_ROOT=\fR
334 .RS 4
335 The current working directory and root directory of the crashed process\&.
336 .sp
337 When the crashed process is in a container, those paths are relative to the root of the container\*(Aqs mount namespace\&.
338 .sp
339 Added in version 248\&.
340 .RE
341 .PP
342 \fICOREDUMP_DUMPABLE=\fR
343 .RS 4
344 The
345 \fBPR_GET_DUMPABLE\fR
346 field as reported by the kernel, see
347 \fBprctl\fR(2)\&.
348 .sp
349 Added in version 258\&.
350 .RE
351 .PP
352 \fICOREDUMP_OPEN_FDS=\fR
353 .RS 4
354 Information about open file descriptors, in the following format:
355 .sp
356 .if n \{\
357 .RS 4
358 .\}
359 .nf
360 \fIfd\fR:\fI/path/to/file\fR
361 pos: \&.\&.\&.
362 flags: \&.\&.\&.
363 \&.\&.\&.
364
365 \fIfd\fR:\fI/path/to/file\fR
366 pos: \&.\&.\&.
367 flags: \&.\&.\&.
368 \&.\&.\&.
369 .fi
370 .if n \{\
371 .RE
372 .\}
373 .sp
374 The first line contains the file descriptor number
375 \fIfd\fR
376 and the path, while subsequent lines show the contents of
377 /proc/\fIpid\fR/fdinfo/\fIfd\fR\&.
378 .sp
379 Added in version 248\&.
380 .RE
381 .PP
382 \fICOREDUMP_EXE=\fR
383 .RS 4
384 The destination of the
385 /proc/\fIpid\fR/exe
386 symlink\&.
387 .sp
388 When the crashed process is in a container, that path is relative to the root of the container\*(Aqs mount namespace\&.
389 .sp
390 Added in version 248\&.
391 .RE
392 .PP
393 \fICOREDUMP_CMDLINE=\fR, \fICOREDUMP_COMM=\fR, \fICOREDUMP_ENVIRON=\fR, \fICOREDUMP_PROC_AUXV=\fR, \fICOREDUMP_PROC_LIMITS=\fR, \fICOREDUMP_PROC_MAPS=\fR, \fICOREDUMP_PROC_MOUNTINFO=\fR, \fICOREDUMP_PROC_STATUS=\fR
394 .RS 4
395 Fields that map the per\-process entries in the
396 /proc/
397 filesystem:
398 /proc/\fIpid\fR/cmdline
399 (the command line of the crashed process),
400 /proc/\fIpid\fR/comm
401 (the command name associated with the process),
402 /proc/\fIpid\fR/environ
403 (the environment block of the crashed process),
404 /proc/\fIpid\fR/auxv
405 (the auxiliary vector of the crashed process, see
406 \fBgetauxval\fR(3)),
407 /proc/\fIpid\fR/limits
408 (the soft and hard resource limits),
409 /proc/\fIpid\fR/maps
410 (memory regions visible to the process and their access permissions),
411 /proc/\fIpid\fR/mountinfo
412 (mount points in the process\*(Aqs mount namespace),
413 /proc/\fIpid\fR/status
414 (various metadata about the process)\&.
415 .sp
416 See
417 \fBproc\fR(5)
418 for more information\&.
419 .sp
420 Added in version 248\&.
421 .RE
422 .PP
423 \fICOREDUMP_HOSTNAME=\fR
424 .RS 4
425 The system hostname\&.
426 .sp
427 When the crashed process was in container, this is the container hostname\&.
428 .sp
429 Added in version 248\&.
430 .RE
431 .PP
432 \fICOREDUMP_CONTAINER_CMDLINE=\fR
433 .RS 4
434 For processes running in a container, the command line of the process spawning the container (the first parent process with a different mount namespace)\&.
435 .sp
436 Added in version 248\&.
437 .RE
438 .PP
439 \fICOREDUMP=\fR
440 .RS 4
441 When the core is stored in the journal, the core image itself\&.
442 .sp
443 Added in version 248\&.
444 .RE
445 .PP
446 \fICOREDUMP_FILENAME=\fR
447 .RS 4
448 When the core is stored externally, the path to the core file\&.
449 .sp
450 Added in version 248\&.
451 .RE
452 .PP
453 \fICOREDUMP_TRUNCATED=\fR
454 .RS 4
455 Set to
456 "1"
457 when the saved coredump was truncated\&. (A partial core image may still be processed by some tools, though obviously not all information is available\&.)
458 .sp
459 Added in version 248\&.
460 .RE
461 .PP
462 \fICOREDUMP_PACKAGE_NAME=\fR, \fICOREDUMP_PACKAGE_VERSION=\fR, \fICOREDUMP_PACKAGE_JSON=\fR
463 .RS 4
464 If the executable contained \&.package metadata ELF notes, they will be parsed and attached\&. The
465 \fIpackage\fR
466 and
467 \fIpackageVersion\fR
468 of the \*(Aqmain\*(Aq ELF module (ie: the executable) will be appended individually\&. The JSON\-formatted content of all modules will be appended as a single JSON object, each with the module name as the key\&. For more information about this metadata format and content, see
469 \m[blue]\fBthe coredump metadata spec\fR\m[]\&\s-2\u[5]\d\s+2\&.
470 .sp
471 Added in version 249\&.
472 .RE
473 .PP
474 \fIMESSAGE=\fR
475 .RS 4
476 The message generated by
477 \fBsystemd\-coredump\fR
478 that includes the backtrace if it was successfully generated\&. When
479 \fBsystemd\-coredump\fR
480 is invoked with
481 \fB\-\-backtrace\fR, this field is provided by the caller\&.
482 .sp
483 Added in version 248\&.
484 .RE
485 .PP
486 Various other fields exist in the journal entry, but pertain to the logging process, i\&.e\&.
487 \fBsystemd\-coredump\fR, not the crashed process\&. See
488 \fBsystemd.journal-fields\fR(7)\&.
489 .PP
490 The following fields are saved (if known) with the external file listed in
491 \fICOREDUMP_FILENAME=\fR
492 as extended attributes:
493 .PP
494 \fIuser\&.coredump\&.pid\fR, \fIuser\&.coredump\&.uid\fR, \fIuser\&.coredump\&.gid\fR, \fIuser\&.coredump\&.signal\fR, \fIuser\&.coredump\&.timestamp\fR, \fIuser\&.coredump\&.rlimit\fR, \fIuser\&.coredump\&.hostname\fR, \fIuser\&.coredump\&.comm\fR, \fIuser\&.coredump\&.exe\fR
495 .RS 4
496 Those are the same as
497 \fICOREDUMP_PID=\fR,
498 \fICOREDUMP_UID=\fR,
499 \fICOREDUMP_GID=\fR,
500 \fICOREDUMP_SIGNAL=\fR,
501 \fICOREDUMP_TIMESTAMP=\fR,
502 \fICOREDUMP_RLIMIT=\fR,
503 \fICOREDUMP_HOSTNAME=\fR,
504 \fICOREDUMP_COMM=\fR, and
505 \fICOREDUMP_EXE=\fR, described above\&.
506 .sp
507 Added in version 248\&.
508 .RE
509 .PP
510 Those can be viewed using
511 \fBgetfattr\fR(1)\&. For the core file described in the journal entry shown above:
512 .sp
513 .if n \{\
514 .RS 4
515 .\}
516 .nf
517 $ getfattr \-\-absolute\-names \-d /var/lib/systemd/coredump/core\&.Web\&...\&.552351\&.\&...\&.zst
518 # file: /var/lib/systemd/coredump/core\&.Web\&...\&.552351\&.\&...\&.zst
519 user\&.coredump\&.pid="552351"
520 user\&.coredump\&.uid="1000"
521 user\&.coredump\&.gid="1000"
522 user\&.coredump\&.signal="11"
523 user\&.coredump\&.timestamp="1614342930000000"
524 user\&.coredump\&.comm="Web Content"
525 user\&.coredump\&.exe="/usr/lib64/firefox/firefox"
526 \&...
527 .fi
528 .if n \{\
529 .RE
530 .\}
531 .sp
532 .SH "SEE ALSO"
533 .PP
534 \fBcoredump.conf\fR(5), \fBcoredumpctl\fR(1), \fBsystemd-journald.service\fR(8), \fBsystemd-tmpfiles\fR(8), \fBcore\fR(5), \fBsysctl.d\fR(5), \fBsystemd-sysctl.service\fR(8), \m[blue]\fBsystemd Coredump Handling\fR\m[]\&\s-2\u[1]\d\s+2
535 .SH "NOTES"
536 .IP " 1." 4
537 systemd Coredump Handling
538 .RS 4
539 \%https://systemd.io/COREDUMP
540 .RE
541 .IP " 2." 4
542 Journal Export Format
543 .RS 4
544 \%https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
545 .RE
546 .IP " 3." 4
547 systemd-coredump-python
548 .RS 4
549 \%https://github.com/systemd/systemd-coredump-python
550 .RE
551 .IP " 4." 4
552 \fBkill\fR(1)
553 expects signal names
554 \fIwithout\fR
555 the prefix;
556 \fBkill\fR(2)
557 uses the prefix; all systemd tools accept signal names both with and without the prefix.
558 .IP " 5." 4
559 the coredump metadata spec
560 .RS 4
561 \%https://systemd.io/COREDUMP_PACKAGE_METADATA/
562 .RE