]>
Commit | Line | Data |
---|---|---|
9b4abc69 ED |
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+ --> | |
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</title> | |
11 | <productname>systemd</productname> | |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
15 | <refentrytitle>systemd-pstore</refentrytitle> | |
16 | <manvolnum>8</manvolnum> | |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
20 | <refname>systemd-pstore</refname> | |
21 | <refname>systemd-pstore.service</refname> | |
22 | <refpurpose>Tool to archive contents of the persistent storage filesytem</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 | |
38 | error records when the kernel dies (or reboots or powers-off). These records in | |
39 | turn can be referenced to debug kernel problems (currently the kernel stuffs | |
40 | the tail of the dmesg, which also contains a stack backtrace, into 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 (eg. 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> is read to obtain options, then the /sys/fs/pstore | |
63 | directory contents are processed according to the options. Pstore files are written to the | |
64 | journal, and optionally saved into /var/lib/systemd/pstore.</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 | </refsect1> | |
85 | ||
86 | <refsect1> | |
87 | <title>Usage</title> | |
88 | <para>Data stored in the journal can be viewed with | |
89 | <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
90 | as usual.</para> | |
91 | </refsect1> | |
92 | ||
93 | <refsect1> | |
94 | <title>See Also</title> | |
95 | <para> | |
96 | <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
97 | </para> | |
98 | </refsect1> | |
99 | </refentry> |