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

Man coredump sysctl

4 files changed, 107 insertions, 29 deletions

diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml
index a0a497b467..2064a96523 100644
--- a/man/coredump.conf.xml
+++ b/man/coredump.conf.xml
@@ -60,7 +60,14 @@
 
     <para>These files configure the behavior of
     <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
-    a handler for core dumps invoked by the kernel.</para>
+    a handler for core dumps invoked by the kernel. Whether <command>systemd-coredump</command> is used
+    is determined by the kernel's
+    <varname>kernel.core_pattern</varname> <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    setting. See
+    <citerefentry><refentrytitle>systemd-coredump</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    and
+    <citerefentry project='man-pages'><refentrytitle>core</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    pages for the details.</para>
   </refsect1>
 
   <xi:include href="standard-conf.xml" xpointer="main-conf" />
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>
diff --git a/man/systemd-sysctl.service.xml b/man/systemd-sysctl.service.xml
index 9027ff0f3f..686b2cdef4 100644
--- a/man/systemd-sysctl.service.xml
+++ b/man/systemd-sysctl.service.xml
@@ -62,24 +62,29 @@
     <para><filename>systemd-sysctl.service</filename> is an early boot
     service that configures
     <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-    kernel parameters.</para>
+    kernel parameters by invoking <command>/usr/lib/systemd/systemd-sysctl</command>.</para>
 
-    <para>If invoked with no arguments, it applies all directives from
-    all configuration files in
-    <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    are searched for a matching file. If one or more filenames are passed on
-    the command line, only the directives in these files are applied.
-    </para>
+    <para>When invoked with no arguments, <command>/usr/lib/systemd/systemd-sysctl</command> applies
+    all directives from configuration files listed in
+    <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    If one or more filenames are passed on the command line, only the directives in these files are
+    applied.</para>
+
+    <para>In addition, <option>--prefix=</option> option may be used to limit which sysctl
+    settings are applied.</para>
 
     <para>See
     <citerefentry project='man-pages'><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-    for information about the configuration of this service.</para>
+    for information about the configuration of sysctl settings. After sysctl configuration is
+    changed on disk, it must be written to the files in <filename>/proc/sys</filename> before it
+    takes effect. It is possible to update specific settings, or simply to reload all configuration,
+    see Examples below.</para>
   </refsect1>
 
   <refsect1><title>Options</title>
     <variablelist>
-      <varlistentry id='path'>
-        <term><option>--path=</option></term>
+      <varlistentry id='prefix'>
+        <term><option>--prefix=</option></term>
         <listitem>
           <para>Only apply rules with the specified prefix.</para>
         </listitem>
@@ -92,6 +97,50 @@
   </refsect1>
 
   <refsect1>
+    <title>Examples</title>
+
+    <example>
+      <title>Reset all sysctl settings</title>
+
+      <programlisting>systemctl restart systemd-sysctl</programlisting>
+    </example>
+
+    <example>
+      <title>View coredump handler configuration</title>
+
+      <programlisting># sysctl kernel.core_pattern
+kernel.core_pattern = |/usr/libexec/abrt-hook-ccpp %s %c %p %u %g %t %P %I
+</programlisting>
+    </example>
+
+    <example>
+      <title>Update coredump handler configuration</title>
+
+      <programlisting># /usr/lib/systemd/systemd-sysctl --prefix kernel.core_pattern</programlisting>
+
+      <para>This searches all the directories listed in
+      <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      for configuration files and writes <filename>/proc/sys/kernel/core_pattern</filename>.</para>
+    </example>
+
+    <example>
+      <title>Update coredump handler configuration according to a specific file</title>
+
+      <programlisting># /usr/lib/systemd/systemd-sysctl 50-coredump.conf</programlisting>
+
+      <para>This applies all the settings found in <filename>50-coredump.conf</filename>.
+      Either <filename>/etc/sysctl.d/50-coredump.conf</filename>, or
+      <filename>/run/sysctl.d/50-coredump.conf</filename>, or
+      <filename>/usr/lib/sysctl.d/50-coredump.conf</filename> will be used, in the order
+      of preference.</para>
+    </example>
+
+    <para>See
+    <citerefentry project='man-pages'><refentrytitle>sysctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
+    for various ways to directly apply sysctl settings.</para>
+  </refsect1>
+
+  <refsect1>
     <title>See Also</title>
     <para>
       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml
index 5ec878512a..ce900a5db1 100644
--- a/man/systemd.nspawn.xml
+++ b/man/systemd.nspawn.xml
@@ -224,7 +224,7 @@
       </varlistentry>
 
       <varlistentry>
-        <term><option>KillSignal=</option></term>
+        <term><varname>KillSignal=</varname></term>
 
         <listitem><para>Specify the process signal to send to the
         container's PID 1 when nspawn itself receives SIGTERM, in