Merge pull request #16678 from poettering/loop-configure

[thirdparty/systemd.git] / man / systemd-pstore.service.xml

<?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+ -->

<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>