]>
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"> | |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
9b4abc69 ED |
5 | |
6 | <refentry id="systemd-pstore" conditional='ENABLE_PSTORE' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | ||
9 | <refentryinfo> | |
aa07dc70 | 10 | <title>systemd-pstore.service</title> |
9b4abc69 ED |
11 | <productname>systemd</productname> |
12 | </refentryinfo> | |
13 | ||
14 | <refmeta> | |
aa07dc70 | 15 | <refentrytitle>systemd-pstore.service</refentrytitle> |
9b4abc69 ED |
16 | <manvolnum>8</manvolnum> |
17 | </refmeta> | |
18 | ||
19 | <refnamediv> | |
9b4abc69 | 20 | <refname>systemd-pstore.service</refname> |
aa07dc70 ZJS |
21 | <refname>systemd-pstore</refname> |
22 | <refpurpose>A service to archive contents of pstore</refpurpose> | |
9b4abc69 ED |
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 | |
e3b19262 ZJS |
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 | |
9b4abc69 ED |
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, | |
e3b19262 | 62 | the <filename>pstore.conf</filename> file is read and the <filename>/sys/fs/pstore</filename> |
9b4abc69 | 63 | directory contents are processed according to the options. Pstore files are written to the |
e3b19262 | 64 | journal, and optionally saved into <filename>/var/lib/systemd/pstore</filename>.</para> |
9b4abc69 ED |
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> | |
f00c3664 ED |
84 | |
85 | <refsect2> | |
86 | <title>Controlling 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>, | |
91 | that control writes into pstore. | |
92 | The crash_kexec_post_notifiers parameter enables the kernel to write | |
93 | dmesg (including stack trace) into pstore upon a panic or crash, and | |
94 | printk.always_kmsg_dump parameter enables the kernel to write dmesg | |
95 | upon a normal shutdown (shutdown, reboot, halt). These kernel | |
96 | parameters are managed via the | |
97 | <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
98 | mechanism, specifically the file <filename>/usr/lib/tmpfiles/systemd-pstore.conf</filename>. | |
99 | </para> | |
100 | </refsect2> | |
101 | ||
9b4abc69 ED |
102 | </refsect1> |
103 | ||
104 | <refsect1> | |
105 | <title>Usage</title> | |
106 | <para>Data stored in the journal can be viewed with | |
107 | <citerefentry><refentrytitle>journalctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> | |
108 | as usual.</para> | |
109 | </refsect1> | |
110 | ||
111 | <refsect1> | |
112 | <title>See Also</title> | |
113 | <para> | |
114 | <citerefentry><refentrytitle>pstore.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> | |
115 | </para> | |
116 | </refsect1> | |
117 | </refentry> |