1SYSTEMD-COREDUMP(8) systemd-coredump SYSTEMD-COREDUMP(8)
2
6 systemd-coredump, systemd-coredump.socket, systemd-coredump@.service -
7 Acquire, save and process core dumps
8
10 /usr/lib/systemd/systemd-coredump
11 /usr/lib/systemd/systemd-coredump --backtrace
13 systemd-coredump@.service
15 systemd-coredump.socket
17
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 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 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 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 For further details see systemd Coredump Handling[1].
48 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 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 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
72 For programs started by systemd, process resource limits can be set by
73 directive LimitCORE=, see systemd.exec(5).
74 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 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 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 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 Disabling coredump processing
106 To disable potentially resource-intensive processing by
107 systemd-coredump, set
108 Storage=none
110 ProcessSizeMax=0
111 in coredump.conf(5).
113
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 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 $ 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 The following fields are saved (if known) with the journal entry
142 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 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 COREDUMP_TIMESTAMP=
152 The time of the crash as reported by the kernel (in µs since the
153 epoch).
154 COREDUMP_RLIMIT=
156 The core file size soft resource limit, see getrlimit(2).
157 COREDUMP_UNIT=, COREDUMP_SLICE=
159 The system unit and slice names.
160 When the crashed process was in container, those are the units
162 names outside, in the main system manager.
163 COREDUMP_CGROUP=
165 The primary cgroup of the unit of the crashed process.
166 When the crashed process was in a container, this is the full path,
168 as seen outside of the container.
169 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 When the crashed process was in a container, this is the full path,
177 as seen outside of the container.
178 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 When the crashed process was in container, those are the values
186 outside, in the main system.
187 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 COREDUMP_CWD=, COREDUMP_ROOT=
194 The current working directory and root directory of the crashed
195 process.
196 When the crashed process is in a container, those paths are
198 relative to the root of the container's mount namespace.
199 COREDUMP_OPEN_FDS=
201 Information about open file descriptors, in the following format:
202 fd:/path/to/file
204 pos: ...
205 flags: ...
206 ...
207 fd:/path/to/file
209 pos: ...
210 flags: ...
211 ...
212 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 COREDUMP_EXE=
218 The destination of the /proc/pid/exe symlink.
219 When the crashed process is in a container, that path is relative
221 to the root of the container's mount namespace.
222 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 See proc(5) for more information.
238 COREDUMP_HOSTNAME=
240 The system hostname.
241 When the crashed process was in container, this is the container
243 hostname.
244 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 COREDUMP=
251 When the core is stored in the journal, the core image itself.
252 COREDUMP_FILENAME=
254 When the core is stored externally, the path to the core file.
255 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 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 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 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 The following fields are saved (if known) with the external file listed
281 in COREDUMP_FILENAME= as extended attributes:
282 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 Those can be viewed using getfattr(1). For the core file described in
292 the journal entry shown above:
293 $ 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
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
312 1. systemd Coredump Handling
313 https://systemd.io/COREDUMP
314 2. Journal Export Format
316 https://systemd.io/JOURNAL_EXPORT_FORMATS#journal-export-format
317 3. systemd-coredump-python
319 https://github.com/systemd/systemd-coredump-python
320 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 5. the coredump metadata spec
326 https://systemd.io/COREDUMP_PACKAGE_METADATA/
327systemd 253 SYSTEMD-COREDUMP(8)