systemd/man/systemd-coredump.xml
2016-04-05 21:00:10 -04:00

128 lines
6.2 KiB
XML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<!--
This file is part of systemd.
Copyright 2014 Zbigniew Jędrzejewski-Szmek
systemd is free software; you can redistribute it and/or modify it
under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or
(at your option) any later version.
systemd is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public License
along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
<refentry id="systemd-coredump" conditional='ENABLE_COREDUMP'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-coredump</title>
<productname>systemd</productname>
<authorgroup>
<author>
<contrib>Developer</contrib>
<firstname>Lennart</firstname>
<surname>Poettering</surname>
<email>lennart@poettering.net</email>
</author>
</authorgroup>
</refentryinfo>
<refmeta>
<refentrytitle>systemd-coredump</refentrytitle>
<manvolnum>8</manvolnum>
</refmeta>
<refnamediv>
<refname>systemd-coredump</refname>
<refname>systemd-coredump.socket</refname>
<refname>systemd-coredump@.service</refname>
<refpurpose>Log and store core dumps</refpurpose>
</refnamediv>
<refsynopsisdiv>
<para><filename>/usr/lib/systemd/systemd-coredump</filename></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> 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
<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>.
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>
and
<citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<para>
<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 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>.
</para>
</refsect1>
</refentry>