man: make systemd-coredump and coredumpctl descriptions more accessible

Fixes #17910: we didn't clearly explain that coredumps may exist without
journal entries, and vice versa.

Also, make the examples more concrete, and use '$' instead of '#' to avoid
suggesting that running as root is required. The text is extended a bit in
various places. In the description of systemd-coredump, the details of executor
separation are split out to a separate subsection, since they are rather
detailed and not necessary to understand for normal use.

diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml
index f69f26dc6688f5b88b86d4029afb561d668a8c2a..2b602b71fa078ee8c3b7c7d97f9dd2bdbcbd25e3 100644 (file)
--- a/man/coredumpctl.xml
+++ b/man/coredumpctl.xml
@@ -324,35 +324,47 @@
     <title>Examples</title>
 
     <example>
-      <title>List all the core dumps of a program named foo</title>
+      <title>List all the core dumps of a program</title>
 
-      <programlisting># coredumpctl list foo</programlisting>
+      <programlisting>$ coredumpctl list /usr/lib64/firefox/firefox
+TIME     PID  UID  GID SIG     COREFILE EXE                         SIZE
+Tue …   8018 1000 1000 SIGSEGV missing  /usr/lib64/firefox/firefox   n/a
+Wed … 251609 1000 1000 SIGTRAP missing  /usr/lib64/firefox/firefox   n/a
+Fri … 552351 1000 1000 SIGSEGV present  /usr/lib64/firefox/firefox 28.7M
+</programlisting>
+
+       <para>The journal has three entries pertaining to <filename>/usr/lib64/firefox/firefox</filename>, and
+       only the last entry still has an available core file (in external storage on disk).</para>
+
+       <para>Note that <filename>coredumpctl</filename> needs access to the journal files to retrieve the
+       relevant entries from the journal. Thus, an unprivileged user will normally only see information about
+       crashing programs of this user.</para>
     </example>
 
     <example>
-      <title>Invoke gdb on the last core dump</title>
+      <title>Invoke <command>gdb</command> on the last core dump</title>
 
-      <programlisting># coredumpctl debug</programlisting>
+      <programlisting>$ coredumpctl debug</programlisting>
     </example>
 
     <example>
-      <title>Use gdb to display full register info from the last core dump</title>
+      <title>Use <command>gdb</command> to display full register info from the last core dump</title>
 
-      <programlisting># coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
+      <programlisting>$ coredumpctl debug --debugger-arguments="-batch -ex 'info all-registers'"</programlisting>
     </example>
 
     <example>
       <title>Show information about a process that dumped core,
       matching by its PID 6654</title>
 
-      <programlisting># coredumpctl info 6654</programlisting>
+      <programlisting>$ coredumpctl info 6654</programlisting>
     </example>
 
     <example>
       <title>Extract the last core dump of /usr/bin/bar to a file named
       <filename index="false">bar.coredump</filename></title>
 
-      <programlisting># coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
+      <programlisting>$ coredumpctl -o bar.coredump dump /usr/bin/bar</programlisting>
     </example>
   </refsect1>
 

diff --git a/man/systemd-coredump.xml b/man/systemd-coredump.xml
index f92cfd55ea7b51e55c664a85c79792b571948885..2d53a7a8feb0279ade1cedf99c2db0160aed5544 100644 (file)
--- a/man/systemd-coredump.xml
+++ b/man/systemd-coredump.xml
@@ -32,29 +32,11 @@
 
   <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>. These core dumps are deleted after a few days by
-    default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> for details.</para>
+    <para><filename>systemd-coredump@.service</filename> is a system service to process core dumps. It will
+    log a summary of the event to
+    <citerefentry><refentrytitle>systemd-journald.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+    including information about the process identifier, owner, the signal that killed the process, and the
+    stack trace if possible. It may also save the core dump for later processing.</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
@@ -62,14 +44,47 @@
     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>
+    <para>Core dumps can be written to the journal or saved as a file. In both cases, they can be retrieved
+    for further processing, for example in
+    <citerefentry project='man-pages'><refentrytitle>gdb</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
+    See <citerefentry><refentrytitle>coredumpctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+    in particular the <command>list</command> and <command>debug</command> verbs.</para>
+
+    <para>By default, <command>systemd-coredump</command> will log the core dump to the journal, including a
+    backtrace if possible, and store the core dump (an image of the memory contents of the process) itself in
+    an external file in <filename>/var/lib/systemd/coredump</filename>. These core dumps are deleted after a
+    few days by default; see <filename>/usr/lib/tmpfiles.d/systemd.conf</filename> for details. Note that the
+    removal of core files from the file system and the purging of journal entries are independent, and the
+    core file may be present without the journal entry, and journal entries may point to since-removed core
+    files. Metadata is attached to core files in the form of extended attributes, so the core files may be
+    useful even without the full metadata available in the journal entry.
+    </para>
+
+    <refsect2>
+      <title>Invocation of <command>systemd-coredump</command></title>
+
+      <para>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 and process
+      and save the core file.</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>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>
+    </refsect2>
   </refsect1>
 
   <refsect1>
@@ -118,9 +133,8 @@
     <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
+      <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>
@@ -129,10 +143,9 @@ ProcessSizeMax=0</programlisting> in
   <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
+    <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>