From: Zbigniew Jędrzejewski-Szmek Date: Sat, 27 Feb 2021 18:00:51 +0000 (+0100) Subject: man: make systemd-coredump and coredumpctl descriptions more accessible X-Git-Tag: v248-rc3~92^2~17 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4f57f77267610388139272d9ab9ee64dd78e9720;p=thirdparty%2Fsystemd.git man: make systemd-coredump and coredumpctl descriptions more accessible Fixes #17910: we didn't clearly explain that coredumps may exist without journal entries, and vice versa. Also, make the examples more concrete, and use '$' instead of '#' to avoid suggesting that running as root is required. The text is extended a bit in various places. In the description of systemd-coredump, the details of executor separation are split out to a separate subsection, since they are rather detailed and not necessary to understand for normal use. --- diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index f69f26dc668..2b602b71fa0 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -324,35 +324,47 @@ Examples - List all the core dumps of a program named foo + List all the core dumps of a program - # coredumpctl list foo + $ coredumpctl list /usr/lib64/firefox/firefox +TIME PID UID GID SIG COREFILE EXE SIZE +Tue … 8018 1000 1000 SIGSEGV missing /usr/lib64/firefox/firefox n/a +Wed … 251609 1000 1000 SIGTRAP missing /usr/lib64/firefox/firefox n/a +Fri … 552351 1000 1000 SIGSEGV present /usr/lib64/firefox/firefox 28.7M + + + The journal has three entries pertaining to /usr/lib64/firefox/firefox, and + only the last entry still has an available core file (in external storage on disk). + + Note that coredumpctl needs access to the journal files to retrieve the + relevant entries from the journal. Thus, an unprivileged user will normally only see information about + crashing programs of this user. - Invoke gdb on the last core dump + Invoke <command>gdb</command> on the last core dump - # coredumpctl debug + $ coredumpctl debug - Use gdb to display full register info from the last core dump + Use <command>gdb</command> to display full register info from the last core dump - # coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'" + $ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'" Show information about a process that dumped core, matching by its PID 6654 - # coredumpctl info 6654 + $ coredumpctl info 6654 Extract the last core dump of /usr/bin/bar to a file named <filename index="false">bar.coredump</filename> - # coredumpctl -o bar.coredump dump /usr/bin/bar + $ coredumpctl -o bar.coredump dump /usr/bin/bar diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml index f92cfd55ea7..2d53a7a8feb 100644 --- a/man/systemd-coredump.xml +++ b/man/systemd-coredump.xml @@ -32,29 +32,11 @@ Description - systemd-coredump@.service is a system service that can acquire core - dumps from the kernel and handle them in various ways. The systemd-coredump - executable does the actual work. It is invoked twice: once as the handler by the kernel, and the - second time in the systemd-coredump@.service to actually write the data to - the journal. - - When the kernel invokes systemd-coredump to handle a core dump, it runs - in privileged mode, and will connect to the socket created by the - systemd-coredump.socket unit, which in turn will spawn an unprivileged - systemd-coredump@.service instance to process the core dump. Hence - systemd-coredump.socket and systemd-coredump@.service - are helper units which do the actual processing of core dumps and are subject to normal service - management. - - Core dumps can be written to the journal or saved as a file. Once saved they can be retrieved - for further processing, for example in - gdb1. - - - By default, systemd-coredump will log the core dump including a backtrace - if possible to the journal and store the core dump itself in an external file in - /var/lib/systemd/coredump. These core dumps are deleted after a few days by - default; see /usr/lib/tmpfiles.d/systemd.conf for details. + systemd-coredump@.service is a system service to process core dumps. It will + log a summary of the event to + systemd-journald.service8, + 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. The behavior of a specific program upon reception of a signal is governed by a few factors which are described in detail in @@ -62,14 +44,47 @@ In particular, the core dump will only be processed when the related resource limits are sufficient. - It is also possible to invoke systemd-coredump with - option. In this case, systemd-coredump expects - a journal entry in the journal - Journal Export Format - on standard input. The entry should contain a MESSAGE= field and any additional - metadata fields the caller deems reasonable. systemd-coredump 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. + 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 + gdb1. + See coredumpctl1, + in particular the list and debug verbs. + + By default, systemd-coredump 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 /var/lib/systemd/coredump. These core dumps are deleted after a + few days by default; see /usr/lib/tmpfiles.d/systemd.conf 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. Metadata is attached to core files in the form of extended attributes, so the core files may be + useful even without the full metadata available in the journal entry. + + + + Invocation of <command>systemd-coredump</command> + + The systemd-coredump executable does the actual work. It is invoked twice: + once as the handler by the kernel, and the second time in the + systemd-coredump@.service to actually write the data to the journal and process + and save the core file. + + When the kernel invokes systemd-coredump to handle a core dump, it runs in + privileged mode, and will connect to the socket created by the + systemd-coredump.socket unit, which in turn will spawn an unprivileged + systemd-coredump@.service instance to process the core dump. Hence + systemd-coredump.socket and systemd-coredump@.service are + helper units which do the actual processing of core dumps and are subject to normal service + management. + + It is also possible to invoke systemd-coredump with + option. In this case, systemd-coredump expects a + journal entry in the journal + Journal Export Format + on standard input. The entry should contain a MESSAGE= field and any additional + metadata fields the caller deems reasonable. systemd-coredump 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. + @@ -118,9 +133,8 @@ Disabling coredump processing - To disable potentially resource-intensive processing by systemd-coredump, - set Storage=none -ProcessSizeMax=0 in + To disable potentially resource-intensive processing by systemd-coredump, set + Storage=none ProcessSizeMax=0 in coredump.conf5. @@ -129,10 +143,9 @@ ProcessSizeMax=0 in Usage Data stored in the journal can be viewed with - journalctl1 - as usual. - coredumpctl1 - can be used to retrieve saved core dumps independent of their location, to display information and to process + journalctl1 as usual. + coredumpctl1 can be + used to retrieve saved core dumps independent of their location, to display information and to process them e.g. by passing to the GNU debugger (gdb).