picnoir
/
Systemd
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

coredump: Improve man pages

This commit is contained in:
Peter Mattern 2016-05-16 11:56:04 +02:00 committed by Zbigniew Jędrzejewski-Szmek
parent 77ff6022fa
commit 246ba4aaa9
3 changed files with 109 additions and 77 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
man/coredump.conf.xml
View File

@ -45,7 +45,7 @@
<refnamediv>
<refname>coredump.conf</refname>
<refname>coredump.conf.d</refname>
<refpurpose>Coredump storage configuration files</refpurpose>
<refpurpose>Core dump storage configuration files</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -86,7 +86,7 @@
<listitem><para>Controls where to store cores. One of
<literal>none</literal>, <literal>external</literal>,
<literal>journal</literal>, and <literal>both</literal>. When
<literal>none</literal>, the coredumps will be logged but not
<literal>none</literal>, the core dumps will be logged but not
stored permanently. When <literal>external</literal> (the
default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>.
When <literal>journal</literal>, cores will be stored in
@ -114,7 +114,7 @@
<term><varname>ProcessSizeMax=</varname></term>
<listitem><para>The maximum size in bytes of a core
which will be processed. Coredumps exceeding this size
which will be processed. Core dumps exceeding this size
will be logged, but the backtrace will not be generated
and the core will not be stored.</para></listitem>
</varlistentry>
@ -132,14 +132,14 @@
<term><varname>KeepFree=</varname></term>
<listitem><para>Enforce limits on the disk space taken up by
externally stored coredumps. <option>MaxUse=</option> makes
sure that old coredumps are removed as soon as the total disk
space taken up by coredumps grows beyond this limit (defaults
externally stored core dumps. <option>MaxUse=</option> makes
sure that old core dumps are removed as soon as the total disk
space taken up by core dumps grows beyond this limit (defaults
to 10% of the total disk size). <option>KeepFree=</option>
controls how much disk space to keep free at least (defaults
to 15% of the total disk size). Note that the disk space used
by coredumps might temporarily exceed these limits while
coredumps are processed. Note that old coredumps are also
by core dumps might temporarily exceed these limits while
core dumps are processed. Note that old core dumps are also
removed based on time via
<citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>. Set
either value to 0 to turn off size-based

60
man/coredumpctl.xml
View File

@ -45,7 +45,7 @@
<refnamediv>
<refname>coredumpctl</refname>
<refpurpose>Retrieve coredumps from the journal</refpurpose>
<refpurpose>Retrieve and process saved core dumps and metadata</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -60,9 +60,10 @@
<refsect1>
<title>Description</title>
<para><command>coredumpctl</command> may be used to
retrieve coredumps from
<citerefentry><refentrytitle>systemd-journald</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<para><command>coredumpctl</command> is a tool that can be used to retrieve and process core
dumps and metadata which were saved by
<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
@ -71,18 +72,23 @@
<para>The following options are understood:</para>
<variablelist>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<varlistentry>
<term><option>--no-legend</option></term>
<listitem><para>Do not print column headers.
</para></listitem>
<listitem><para>Do not print column headers.</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<varlistentry>
<term><option>-1</option></term>
<listitem><para>Show information of a single coredump only,
instead of listing all known coredumps. </para></listitem>
<listitem><para>Show information of a single core dump only, instead of listing
all known core dumps.</para></listitem>
</varlistentry>
<varlistentry>
@ -90,7 +96,7 @@
<term><option>--field=</option><replaceable>FIELD</replaceable></term>
<listitem><para>Print all possible data values the specified
field takes in matching coredump entries of the
field takes in matching core dump entries of the
journal.</para></listitem>
</varlistentry>
@ -110,11 +116,11 @@
</para></listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
<xi:include href="standard-options.xml" xpointer="no-pager" />
</variablelist>
</refsect1>
<refsect1>
<title>Commands</title>
<para>The following commands are understood:</para>
@ -122,23 +128,31 @@
<varlistentry>
<term><command>list</command></term>
<listitem><para>List coredumps captured in the journal
<listitem><para>List core dumps captured in the journal
matching specified characteristics. If no command is
specified, this is the implied default.</para></listitem>
specified, this is the implied default.</para>
<para>It's worth noting that different restrictions apply to
data saved in the journal and core dump files saved in
<filename>/var/lib/systemd/coredump</filename>, see overview in
<citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
Thus it may very well happen that a particular core dump is still listed
in the journal while its corresponding core dump file has already been
removed.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>info</command></term>
<listitem><para>Show detailed information about coredumps
<listitem><para>Show detailed information about core dumps
captured in the journal.</para></listitem>
</varlistentry>
<varlistentry>
<term><command>dump</command></term>
<listitem><para>Extract the last coredump matching specified
characteristics. The coredump will be written on standard
<listitem><para>Extract the last core dump matching specified
characteristics. The core dump will be written on standard
output, unless an output file is specified with
<option>--output=</option>. </para></listitem>
</varlistentry>
@ -146,7 +160,7 @@
<varlistentry>
<term><command>gdb</command></term>
<listitem><para>Invoke the GNU debugger on the last coredump
<listitem><para>Invoke the GNU debugger on the last core dump
matching specified characteristics. </para></listitem>
</varlistentry>
@ -197,7 +211,7 @@
<refsect1>
<title>Exit status</title>
<para>On success, 0 is returned; otherwise, a non-zero failure
code is returned. Not finding any matching coredumps is treated as
code is returned. Not finding any matching core dumps is treated as
failure.
</para>
</refsect1>
@ -206,13 +220,13 @@
<title>Examples</title>
<example>
<title>List all the coredumps of a program named foo</title>
<title>List all the core dumps of a program named foo</title>
<programlisting># coredumpctl list foo</programlisting>
</example>
<example>
<title>Invoke gdb on the last coredump</title>
<title>Invoke gdb on the last core dump</title>
<programlisting># coredumpctl gdb</programlisting>
</example>
@ -225,7 +239,7 @@
</example>
<example>
<title>Extract the last coredump of /usr/bin/bar to a file named
<title>Extract the last core dump of /usr/bin/bar to a file named
<filename noindex="true">bar.coredump</filename></title>
<programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>

110
man/systemd-coredump.xml
View File

@ -47,7 +47,7 @@
<refname>systemd-coredump</refname>
<refname>systemd-coredump.socket</refname>
<refname>systemd-coredump@.service</refname>
<refpurpose>Log and store core dumps</refpurpose>
<refpurpose>Acquire, save and process core dumps</refpurpose>
</refnamediv>
<refsynopsisdiv>
@ -58,59 +58,76 @@
<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><command>systemd-coredump</command> can be used as a helper
binary by the kernel when a user space program receives a fatal
signal and dumps core. For it to be used in this capacity, it must
be specified by the
<varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
setting. The syntax of this setting is explained in
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
Systemd installs <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures
<varname>kernel.core_pattern</varname> to invoke <command>systemd-coredump</command>.
This file may be masked or overridden to use a different setting following normal
<citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
rules.</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 coredump will only be processed when the
related resource limits are high enough. For programs started by
<command>systemd</command>, those may be set using
<varname>LimitCore=</varname> (see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
</para>
<para>The behaviour of <command>systemd-coredump</command> is configured through
<filename>/etc/systemd/coredump.conf</filename> and other configuration files. See
<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
for details. By default, <command>systemd-coredump</command> will log the coredump including a
backtrace if possible, and store the core (contents of process' memory contents) in an external
file on disk in <filename>/var/lib/systemd/coredump</filename>.</para>
<para>When the kernel invokes <command>systemd-coredump</command> to handle a coredump,
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 coredump. Hence <filename>systemd-coredump.socket</filename>
and <filename>systemd-coredump@.service</filename> are helper units which do the actual
processing of coredumps and are subject to normal service management.</para>
<para>The log entry and a backtrace are stored in the journal, and can be viewed with
<citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
may be used to list and extract coredumps or load them in
<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>The coredump helper is invoked anew each time. Therefore, any configuration
changes will take effect on the invocation of <command>systemd-coredump</command>.
<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>.</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>
</refsect1>
<refsect1>
<title>Configuration</title>
<para>For programs started by <command>systemd</command> process resource limits can be set by directive
<varname>LimitCore=</varname>, see
<citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
</para>
<para>In order to be used <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>.
Systemd installs the file <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures
<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
<citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
and
<citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
<citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
<para>The behaviour 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
<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A new
instance of <command>systemd-coredump</command> is invoked upon receiving every core dump. Therefore, changes
in these files will take effect the next time a core dump is received.</para>
<para>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 <filename>/etc/systemd/coredump.conf</filename> and snippets mentioned
above. In addition the storage time of core dump files is restricted by <command>systemd-tmpfiles</command>,
corresponding settings are by default in <filename>/usr/lib/tmpfiles.d/systemd.conf</filename>.</para>
</refsect1>
<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
them e.g. by passing to the GNU debugger (gdb).</para>
</refsect1>
<refsect1>
@ -119,6 +136,7 @@
<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-tmpfiles</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
<citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
<citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.