Merge pull request #2944 from keszybz/man-coredump-sysctl

Man coredump sysctl

1 files changed, 39 insertions, 17 deletions

diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml
index f1598461ef..51dc27e8d3 100644
--- a/man/systemd-coredump.xml
+++ b/man/systemd-coredump.xml
@@ -45,11 +45,15 @@
 
   <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>
@@ -60,12 +64,13 @@
     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. 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>
+    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
@@ -77,18 +82,35 @@
     <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>).
     </para>
 
-    <para><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>, or directly in
-    the journal. This behavior may be modified using
-    <citerefentry><refentrytitle>coredump.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
-
-    <para>Apart from the
-    <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-    log viewer,
+    <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.</para>
+    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>