mirror of
https://github.com/systemd/systemd-stable.git
synced 2024-12-22 13:33:56 +03:00
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.
This commit is contained in:
Zbigniew Jędrzejewski-Szmek
parent
34507fa9e9
commit
4f57f77267
@ -324,35 +324,47 @@
|
||||
<title>Examples</title>
|
||||
|
||||
<example>
|
||||
<title>List all the core dumps of a program named foo</title>
|
||||
<title>List all the core dumps of a program</title>
|
||||
|
||||
<programlisting># coredumpctl list foo</programlisting>
|
||||
<programlisting>$ 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
|
||||
</programlisting>
|
||||
|
||||
<para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
|
||||
only the last entry still has an available core file (in external storage on disk).</para>
|
||||
|
||||
<para>Note that <filename>coredumpctl</filename> 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.</para>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Invoke gdb on the last core dump</title>
|
||||
<title>Invoke <command>gdb</command> on the last core dump</title>
|
||||
|
||||
<programlisting># coredumpctl debug</programlisting>
|
||||
<programlisting>$ coredumpctl debug</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Use gdb to display full register info from the last core dump</title>
|
||||
<title>Use <command>gdb</command> to display full register info from the last core dump</title>
|
||||
|
||||
<programlisting># coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
|
||||
<programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Show information about a process that dumped core,
|
||||
matching by its PID 6654</title>
|
||||
|
||||
<programlisting># coredumpctl info 6654</programlisting>
|
||||
<programlisting>$ coredumpctl info 6654</programlisting>
|
||||
</example>
|
||||
|
||||
<example>
|
||||
<title>Extract the last core dump of /usr/bin/bar to a file named
|
||||
<filename index="false">bar.coredump</filename></title>
|
||||
|
||||
<programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
|
||||
<programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
|
||||
</example>
|
||||
</refsect1>
|
||||
|
||||
|
||||
@ -32,29 +32,11 @@
|
||||
|
||||
<refsect1>
|
||||
<title>Description</title>
|
||||
<para><filename>systemd-coredump@.service</filename> is a system service that can acquire core
|
||||
dumps from the kernel and handle them in various ways. The <command>systemd-coredump</command>
|
||||
executable does the actual work. It is invoked twice: once as the handler by the kernel, and the
|
||||
second time in the <filename>systemd-coredump@.service</filename> to actually write the data to
|
||||
the journal.</para>
|
||||
|
||||
<para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, it runs
|
||||
in privileged mode, and will connect to the socket created by the
|
||||
<filename>systemd-coredump.socket</filename> unit, which in turn will spawn an unprivileged
|
||||
<filename>systemd-coredump@.service</filename> instance to process the core dump. Hence
|
||||
<filename>systemd-coredump.socket</filename> and <filename>systemd-coredump@.service</filename>
|
||||
are helper units which do the actual processing of core dumps and are subject to normal service
|
||||
management.</para>
|
||||
|
||||
<para>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
|
||||
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
||||
</para>
|
||||
|
||||
<para>By default, <command>systemd-coredump</command> will log the core dump including a backtrace
|
||||
if possible to the journal and store the core dump itself in an external file in
|
||||
<filename>/var/lib/systemd/coredump</filename>. These core dumps are deleted after a few days by
|
||||
default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> for details.</para>
|
||||
<para><filename>systemd-coredump@.service</filename> is a system service to process core dumps. It will
|
||||
log a summary of the event to
|
||||
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
|
||||
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.</para>
|
||||
|
||||
<para>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.
|
||||
</para>
|
||||
|
||||
<para>It is also possible to invoke <command>systemd-coredump</command> with
|
||||
<option>--backtrace</option> option. In this case, <command>systemd-coredump</command> expects
|
||||
a journal entry in the journal
|
||||
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>
|
||||
on standard input. The entry should contain a <varname>MESSAGE=</varname> field and any additional
|
||||
metadata fields the caller deems reasonable. <command>systemd-coredump</command> 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.</para>
|
||||
<para>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
|
||||
<citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
|
||||
See <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
||||
in particular the <command>list</command> and <command>debug</command> verbs.</para>
|
||||
|
||||
<para>By default, <command>systemd-coredump</command> 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 <filename>/var/lib/systemd/coredump</filename>. These core dumps are deleted after a
|
||||
few days by default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> 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.
|
||||
</para>
|
||||
|
||||
<refsect2>
|
||||
<title>Invocation of <command>systemd-coredump</command></title>
|
||||
|
||||
<para>The <command>systemd-coredump</command> executable does the actual work. It is invoked twice:
|
||||
once as the handler by the kernel, and the second time in the
|
||||
<filename>systemd-coredump@.service</filename> to actually write the data to the journal and process
|
||||
and save the core file.</para>
|
||||
|
||||
<para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump, it runs in
|
||||
privileged mode, and will connect to the socket created by the
|
||||
<filename>systemd-coredump.socket</filename> unit, which in turn will spawn an unprivileged
|
||||
<filename>systemd-coredump@.service</filename> instance to process the core dump. Hence
|
||||
<filename>systemd-coredump.socket</filename> and <filename>systemd-coredump@.service</filename> are
|
||||
helper units which do the actual processing of core dumps and are subject to normal service
|
||||
management.</para>
|
||||
|
||||
<para>It is also possible to invoke <command>systemd-coredump</command> with
|
||||
<option>--backtrace</option> option. In this case, <command>systemd-coredump</command> expects a
|
||||
journal entry in the journal
|
||||
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/export">Journal Export Format</ulink>
|
||||
on standard input. The entry should contain a <varname>MESSAGE=</varname> field and any additional
|
||||
metadata fields the caller deems reasonable. <command>systemd-coredump</command> 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.</para>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
|
||||
<refsect1>
|
||||
@ -118,9 +133,8 @@
|
||||
<refsect2>
|
||||
<title>Disabling coredump processing</title>
|
||||
|
||||
<para>To disable potentially resource-intensive processing by <command>systemd-coredump</command>,
|
||||
set <programlisting>Storage=none
|
||||
ProcessSizeMax=0</programlisting> in
|
||||
<para>To disable potentially resource-intensive processing by <command>systemd-coredump</command>, set
|
||||
<programlisting>Storage=none ProcessSizeMax=0</programlisting> in
|
||||
<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
|
||||
</para>
|
||||
</refsect2>
|
||||
@ -129,10 +143,9 @@ ProcessSizeMax=0</programlisting> in
|
||||
<refsect1>
|
||||
<title>Usage</title>
|
||||
<para>Data stored in the journal can be viewed with
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
as usual.
|
||||
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
|
||||
can be used to retrieve saved core dumps independent of their location, to display information and to process
|
||||
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> as usual.
|
||||
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> 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).</para>
|
||||
</refsect1>
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user