man/systemd-coredump.xml - systemd-stable - Rivoreo Source Code Repositories

 <?xml version='1.0'?>
 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

 <!--
   SPDX-License-Identifier: LGPL-2.1+
 -->

 <refentry id="systemd-coredump" conditional='ENABLE_COREDUMP'
           xmlns:xi="http://www.w3.org/2001/XInclude">

   <refentryinfo>
     <title>systemd-coredump</title>
     <productname>systemd</productname>
   </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>Acquire, save and process core dumps</refpurpose>
   </refnamediv>

   <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><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>.</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="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>
   </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 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>.
     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 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 project='die-net'><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
     <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>

     <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
       <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
       </para>
     </refsect2>
   </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>
     <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><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>.
     </para>
   </refsect1>
 </refentry>
	<?xml version='1.0'?>
	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

	<!--
	SPDX-License-Identifier: LGPL-2.1+
	-->

	<refentry id="systemd-coredump" conditional='ENABLE_COREDUMP'
	xmlns:xi="http://www.w3.org/2001/XInclude">

	<refentryinfo>
	<title>systemd-coredump</title>
	<productname>systemd</productname>
	</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>Acquire, save and process core dumps</refpurpose>
	</refnamediv>

	<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><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>.</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="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>
	</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 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>.
	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 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 project='die-net'><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
	<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>

	<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
	<citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
	</para>
	</refsect2>
	</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>
	<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><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>.
	</para>
	</refsect1>
	</refentry>