man/systemd-coredump.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   This file is part of systemd.
   7
   8   Copyright 2014 Zbigniew Jędrzejewski-Szmek
   9
  10   systemd is free software; you can redistribute it and/or modify it
  11   under the terms of the GNU Lesser General Public License as published by
  12   the Free Software Foundation; either version 2.1 of the License, or
  13   (at your option) any later version.
  14
  15   systemd is distributed in the hope that it will be useful, but
  16   WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  18   Lesser General Public License for more details.
  19
  20   You should have received a copy of the GNU Lesser General Public License
  21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  22 -->
  23
  24 <refentry id="systemd-coredump" conditional='ENABLE_COREDUMP'
  25           xmlns:xi="http://www.w3.org/2001/XInclude">
  26
  27   <refentryinfo>
  28     <title>systemd-coredump</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Lennart</firstname>
  35         <surname>Poettering</surname>
  36         <email>lennart@poettering.net</email>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>systemd-coredump</refentrytitle>
  43     <manvolnum>8</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>systemd-coredump</refname>
  48     <refname>systemd-coredump.socket</refname>
  49     <refname>systemd-coredump@.service</refname>
  50     <refpurpose>Log and store core dumps</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <para><filename>/usr/lib/systemd/systemd-coredump</filename></para>
  55     <para><filename>systemd-coredump@.service</filename></para>
  56     <para><filename>systemd-coredump.socket</filename></para>
  57   </refsynopsisdiv>
  58
  59   <refsect1>
  60     <title>Description</title>
  61
  62     <para><command>systemd-coredump</command> can be used as a helper
  63     binary by the kernel when a user space program receives a fatal
  64     signal and dumps core. For it to be used in this capacity, it must
  65     be specified by the
  66     <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  67     setting. The syntax of this setting is explained in
  68     <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  69     Systemd installs <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> which configures
  70     <varname>kernel.core_pattern</varname> to invoke <command>systemd-coredump</command>.
  71     This file may be masked or overridden to use a different setting following normal
  72     <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  73     rules.</para>
  74
  75     <para>The behavior of a specific program upon reception of a
  76     signal is governed by a few factors which are described in detail
  77     in <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  78     In particular, the coredump will only be processed when the
  79     related resource limits are high enough. For programs started by
  80     <command>systemd</command>, those may be set using
  81     <varname>LimitCore=</varname> (see
  82     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
  83     </para>
  84
  85     <para>The behaviour of <command>systemd-coredump</command> is configured through
  86     <filename>/etc/systemd/coredump.conf</filename> and other configuration files. See
  87     <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  88     for details. By default, <command>systemd-coredump</command> will log the coredump including a
  89     backtrace if possible, and store the core (contents of process' memory contents) in an external
  90     file on disk in <filename>/var/lib/systemd/coredump</filename>.</para>
  91
  92     <para>When the kernel invokes <command>systemd-coredump</command> to handle a coredump,
  93     it will connect to the socket created by the <filename>systemd-coredump.socket</filename>
  94     unit, which in turn will spawn a <filename>systemd-coredump@.service</filename> instance
  95     to process the coredump. Hence <filename>systemd-coredump.socket</filename>
  96     and <filename>systemd-coredump@.service</filename> are helper units which do the actual
  97     processing of coredumps and are subject to normal service management.</para>
  98
  99     <para>The log entry and a backtrace are stored in the journal, and can be viewed with
 100     <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 101     <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 102     may be used to list and extract coredumps or load them in
 103     <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
 104     </para>
 105
 106     <para>The coredump helper is invoked anew each time. Therefore, any configuration
 107     changes will take effect on the invocation of <command>systemd-coredump</command>.
 108     If the sysctl configuration is modified, it must be updated in the kernel before
 109     it takes effect, see
 110     <citerefentry><refentrytitle>systemd-sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
 111     and
 112     <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 113     </para>
 114   </refsect1>
 115
 116   <refsect1>
 117     <title>See Also</title>
 118     <para>
 119       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 120       <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 121       <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 122       <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 123       <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 124       <citerefentry><refentrytitle>systemd-sysctl.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
 125     </para>
 126   </refsect1>
 127 </refentry>