Adding upstream version 247.3.upstream/247.3upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 117 insertions, 0 deletions

diff --git a/man/systemd-pstore.service.xml b/man/systemd-pstore.service.xml
new file mode 100644
index 0000000..306f109
--- /dev/null
+++ b/man/systemd-pstore.service.xml
@@ -0,0 +1,117 @@
+<?xml version='1.0'?>
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
+
+<refentry id="systemd-pstore" conditional='ENABLE_PSTORE'
+          xmlns:xi="http://www.w3.org/2001/XInclude">
+
+  <refentryinfo>
+    <title>systemd-pstore.service</title>
+    <productname>systemd</productname>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>systemd-pstore.service</refentrytitle>
+    <manvolnum>8</manvolnum>
+  </refmeta>
+
+  <refnamediv>
+    <refname>systemd-pstore.service</refname>
+    <refname>systemd-pstore</refname>
+    <refpurpose>A service to archive contents of pstore</refpurpose>
+  </refnamediv>
+
+  <refsynopsisdiv>
+    <para><filename>/usr/lib/systemd/systemd-pstore</filename></para>
+    <para><filename>systemd-pstore.service</filename></para>
+  </refsynopsisdiv>
+
+  <refsect1>
+    <title>Description</title>
+    <para><filename>systemd-pstore.service</filename> is a system service that archives the
+    contents of the Linux persistent storage filesystem, pstore, to other storage,
+    thus preserving the existing information contained in the pstore, and clearing
+    pstore storage for future error events.</para>
+
+    <para>Linux provides a persistent storage file system, pstore, that can store
+    error records when the kernel dies (or reboots or powers-off). These records in
+    turn can be referenced to debug kernel problems (currently the kernel stuffs
+    the tail of the dmesg, which also contains a stack backtrace, into pstore).</para>
+
+    <para>The pstore file system supports a variety of backends that map onto persistent
+    storage, such as the ACPI ERST and UEFI variables. The pstore backends
+    typically offer a relatively small amount of persistent storage, e.g. 64KiB,
+    which can quickly fill up and thus prevent subsequent kernel crashes from
+    recording errors. Thus there is a need to monitor and extract the pstore
+    contents so that future kernel problems can also record information in the
+    pstore.</para>
+
+    <para>The pstore service is independent of the kdump service. In cloud environments
+    specifically, host and guest filesystems are on remote filesystems (eg. iSCSI
+    or NFS), thus kdump relies (implicitly and/or explicitly) upon proper operation
+    of networking software *and* hardware *and* infrastructure. Thus it may not be
+    possible to capture a kernel coredump to a file since writes over the network
+    may not be possible.</para>
+
+    <para>The pstore backend, on the other hand, is completely local and provides a path
+    to store error records which will survive a reboot and aid in post-mortem
+    debugging.</para>
+
+    <para>The <command>systemd-pstore</command> executable does the actual work. Upon starting,
+    the <filename>pstore.conf</filename> file is read and the <filename>/sys/fs/pstore</filename>
+    directory contents are processed according to the options. Pstore files are written to the
+    journal, and optionally saved into <filename>/var/lib/systemd/pstore</filename>.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>Configuration</title>
+
+    <para>The behavior of <command>systemd-pstore</command> is configured through the configuration file
+    <filename>/etc/systemd/pstore.conf</filename> and corresponding snippets
+    <filename>/etc/systemd/pstore.conf.d/*.conf</filename>, see
+    <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+    </para>
+
+    <refsect2>
+      <title>Disabling pstore processing</title>
+
+      <para>To disable pstore processing by <command>systemd-pstore</command>,
+      set <programlisting>Storage=none</programlisting> in
+      <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+      </para>
+    </refsect2>
+
+    <refsect2>
+      <title>Controlling kernel parameters</title>
+
+      <para> The kernel has two parameters,
+      <filename>/sys/module/kernel/parameters/crash_kexec_post_notifiers</filename> and
+      <filename>/sys/module/printk/parameters/always_kmsg_dump</filename>,
+      that control writes into pstore.
+      The crash_kexec_post_notifiers parameter enables the kernel to write
+      dmesg (including stack trace) into pstore upon a panic or crash, and
+      printk.always_kmsg_dump parameter enables the kernel to write dmesg
+      upon a normal shutdown (shutdown, reboot, halt). These kernel
+      parameters are managed via the
+      <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+      mechanism, specifically the file <filename>/usr/lib/tmpfiles/systemd-pstore.conf</filename>.
+      </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.</para>
+  </refsect1>
+
+  <refsect1>
+    <title>See Also</title>
+    <para>
+      <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
+    </para>
+  </refsect1>
+</refentry>