shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2025-01-24 06:04:05 +03:00
Code

man: describe systemd-coredump --backtrace

Browse Source
This commit is contained in:
Zbigniew Jędrzejewski-Szmek 2016-11-06 10:48:15 -05:00
parent 5b45a16067
commit f6940bc34a
1 changed files with 34 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
man/systemd-coredump.xml
View File

@ -52,14 +52,26 @@
<refsynopsisdiv>
<para><filename>/usr/lib/systemd/systemd-coredump</filename></para>
<para><filename>/usr/lib/systemd/systemd-coredump</filename> <option>--backtrace</option></para>
<para><filename>systemd-coredump@.service</filename></para>
<para><filename>systemd-coredump.socket</filename></para>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>systemd-coredump</command> is a system service that can acquire core dumps
from the kernel and handle them in various ways.</para>
<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
@ -70,18 +82,20 @@
if possible to the journal and store the core dump itself in an external file in
<filename>/var/lib/systemd/coredump</filename>.</para>
<para>When the kernel invokes <command>systemd-coredump</command> to handle a core dump,
it will connect to the socket created by the <filename>systemd-coredump.socket</filename>
unit, which in turn will spawn a <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>The behavior of a specific program upon reception of a signal is governed by a few
factors which are described in detail in
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
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="http://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>
</refsect1>
<refsect1>
@ -91,7 +105,8 @@
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>In order to be used <command>systemd-coredump</command> must be configured in
<para>In order to be used by the kernel to handle core dumps,
<command>systemd-coredump</command> must be configured in
<citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
parameter <varname>kernel.core_pattern</varname>. The syntax of this parameter is explained in
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
@ -99,14 +114,20 @@
<varname>kernel.core_pattern</varname> accordingly. This file may be masked or overridden to use a different
setting following normal
<citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
rules.
If the sysctl configuration is modified, it must be updated in the kernel before
it takes effect, see
rules. If the sysctl configuration is modified, it must be updated in the kernel before it
takes effect, see
<citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and
<citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>In order to by used in the <option>--backtrace</option> mode, an appropriate backtrace
handler must be installed on the sender side. For example, in case of
<citerefentry><refentrytitle>python</refentrytitle><manvolnum>1</manvolnum></citerefentry>, this
means a <varname>sys.excepthook</varname> must installed, see
<ulink url="https://github.com/keszybz/systemd-coredump-python">systemd-coredump-python</ulink>.
</para>
<para>The behavior of <command>systemd-coredump</command> itself is configured through the configuration file
<filename>/etc/systemd/coredump.conf</filename> and corresponding snippets
<filename>/etc/systemd/coredump.conf.d/*.conf</filename>, see