1<?xml version='1.0'?>
2<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
3  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
5
6<refentry id="systemd-pstore" conditional='ENABLE_PSTORE'
7          xmlns:xi="http://www.w3.org/2001/XInclude">
8
9  <refentryinfo>
10    <title>systemd-pstore.service</title>
11    <productname>systemd</productname>
12  </refentryinfo>
13
14  <refmeta>
15    <refentrytitle>systemd-pstore.service</refentrytitle>
16    <manvolnum>8</manvolnum>
17  </refmeta>
18
19  <refnamediv>
20    <refname>systemd-pstore.service</refname>
21    <refname>systemd-pstore</refname>
22    <refpurpose>A service to archive contents of pstore</refpurpose>
23  </refnamediv>
24
25  <refsynopsisdiv>
26    <para><filename>/usr/lib/systemd/systemd-pstore</filename></para>
27    <para><filename>systemd-pstore.service</filename></para>
28  </refsynopsisdiv>
29
30  <refsect1>
31    <title>Description</title>
32    <para><filename>systemd-pstore.service</filename> is a system service that archives the
33    contents of the Linux persistent storage filesystem, pstore, to other storage,
34    thus preserving the existing information contained in the pstore, and clearing
35    pstore storage for future error events.</para>
36
37    <para>Linux provides a persistent storage file system, pstore, that can store error records when the
38    kernel dies (or reboots or powers-off). These records in turn can be referenced to debug kernel problems
39    (currently the kernel stores the tail of the kernel log, which also contains a stack backtrace, into
40    pstore).</para>
41
42    <para>The pstore file system supports a variety of backends that map onto persistent
43    storage, such as the ACPI ERST and UEFI variables. The pstore backends
44    typically offer a relatively small amount of persistent storage, e.g. 64KiB,
45    which can quickly fill up and thus prevent subsequent kernel crashes from
46    recording errors. Thus there is a need to monitor and extract the pstore
47    contents so that future kernel problems can also record information in the
48    pstore.</para>
49
50    <para>The pstore service is independent of the kdump service. In cloud environments
51    specifically, host and guest filesystems are on remote filesystems (e.g. iSCSI
52    or NFS), thus kdump relies (implicitly and/or explicitly) upon proper operation
53    of networking software *and* hardware *and* infrastructure. Thus it may not be
54    possible to capture a kernel coredump to a file since writes over the network
55    may not be possible.</para>
56
57    <para>The pstore backend, on the other hand, is completely local and provides a path
58    to store error records which will survive a reboot and aid in post-mortem
59    debugging.</para>
60
61    <para>The <command>systemd-pstore</command> executable does the actual work. Upon starting,
62    the <filename>pstore.conf</filename> file is read and the <filename>/sys/fs/pstore/</filename>
63    directory contents are processed according to the options. Pstore files are written to the
64    journal, and optionally saved into <filename>/var/lib/systemd/pstore/</filename>.</para>
65  </refsect1>
66
67  <refsect1>
68    <title>Configuration</title>
69
70    <para>The behavior of <command>systemd-pstore</command> is configured through the configuration file
71    <filename>/etc/systemd/pstore.conf</filename> and corresponding snippets
72    <filename>/etc/systemd/pstore.conf.d/*.conf</filename>, see
73    <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
74    </para>
75
76    <refsect2>
77      <title>Disabling pstore processing</title>
78
79      <para>To disable pstore processing by <command>systemd-pstore</command>,
80      set <programlisting>Storage=none</programlisting> in
81      <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
82      </para>
83    </refsect2>
84
85    <refsect2>
86      <title>Kernel parameters</title>
87
88      <para> The kernel has two parameters,
89      <filename>/sys/module/kernel/parameters/crash_kexec_post_notifiers</filename> and
90      <filename>/sys/module/printk/parameters/always_kmsg_dump</filename>, that control writes into pstore.
91      The first enables storing of the kernel log (including stack trace) into pstore upon a panic or crash,
92      and the second enables storing of the kernel log upon a normal shutdown (shutdown, reboot, halt). These
93      parameters can be managed via the
94      <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
95      mechanism, specifically the file <filename>/usr/lib/tmpfiles/systemd-pstore.conf</filename>.
96      </para>
97    </refsect2>
98
99  </refsect1>
100
101  <refsect1>
102    <title>Usage</title>
103    <para>Data stored in the journal can be viewed with
104    <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>
105    as usual.</para>
106  </refsect1>
107
108  <refsect1>
109    <title>See Also</title>
110    <para>
111      <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
112    </para>
113  </refsect1>
114</refentry>
115