1
1
mirror of https://github.com/systemd/systemd-stable.git synced 2025-07-24 00:59:29 +03:00
Commit Graph

240 Commits

Author SHA1 Message Date
ea7a19e95d man: add homectl(1) man page 2020-01-28 22:37:00 +01:00
917cc8082b man: document systemd-repart 2020-01-20 17:42:03 +01:00
7d9ad0e5e5 man: document systemd-userdbd.service 2020-01-15 15:30:40 +01:00
3b2db6f110 man: document userdbctl(1) 2020-01-15 15:30:20 +01:00
ac6431dad9 man: add man page for sd_bus_message_sensitive() 2019-12-18 09:10:34 +01:00
8089643328 man: document the new sd-event pidfd magic 2019-12-04 10:36:10 +01:00
0bca283127 man: document sd_event_source_set_floating()
Let's make sure we get back to 100% man page documentation coverage of
our sd-event APIs. We are bad enough at the others, let's get these ones
right at least.
2019-11-29 02:48:41 +09:00
88eb051972 man: use mkswap@ instead of makeswap@
That is what is linked from systemd.swap(5) and also what the systemd.generator produces.
2019-11-28 15:46:21 +01:00
20bae8b94d meson: correct man page deps 2019-10-31 09:04:19 +09:00
39867bb9fb man: document the systemd-random-seed rework 2019-07-25 18:31:20 +02:00
9b4abc69b2 pstore: Tool to archive contents of pstore
This patch introduces the systemd pstore service which will archive 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.

Linux provides a persistent storage file system, pstore[1], 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).

The pstore file system supports a variety of backends that map onto persistent
storage, such as the ACPI ERST[2, Section 18.5 Error Serialization] and UEFI
variables[3 Appendix N Common Platform Error Record]. 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.

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.

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.

Usage Notes:
This tool moves files from /sys/fs/pstore into /var/lib/systemd/pstore.

To enable kernel recording of error records into pstore, one must either pass
crash_kexec_post_notifiers[4] to the kernel command line or enable via 'echo Y
 > /sys/module/kernel/parameters/crash_kexec_post_notifiers'. This option
invokes the recording of errors into pstore *before* an attempt to kexec/kdump
on a kernel crash.

Optionally, to record reboots and shutdowns in the pstore, one can either pass
the printk.always_kmsg_dump[4] to the kernel command line or enable via 'echo Y >
/sys/module/printk/parameters/always_kmsg_dump'. This option enables code on the
shutdown path to record information via pstore.

This pstore service is a oneshot service. When run, the service invokes
systemd-pstore which is a tool that performs the following:
 - reads the pstore.conf configuration file
 - collects the lists of files in the pstore (eg. /sys/fs/pstore)
 - for certain file types (eg. dmesg) a handler is invoked
 - for all other files, the file is moved from pstore

 - In the case of dmesg handler, final processing occurs as such:
   - files processed in reverse lexigraphical order to faciliate
     reconstruction of original dmesg
   - the filename is examined to determine which dmesg it is a part
   - the file is appended to the reconstructed dmesg

For example, the following pstore contents:

 root@vm356:~# ls -al /sys/fs/pstore
 total 0
 drwxr-x--- 2 root root    0 May  9 09:50 .
 drwxr-xr-x 7 root root    0 May  9 09:50 ..
 -r--r--r-- 1 root root 1610 May  9 09:49 dmesg-efi-155741337601001
 -r--r--r-- 1 root root 1778 May  9 09:49 dmesg-efi-155741337602001
 -r--r--r-- 1 root root 1726 May  9 09:49 dmesg-efi-155741337603001
 -r--r--r-- 1 root root 1746 May  9 09:49 dmesg-efi-155741337604001
 -r--r--r-- 1 root root 1686 May  9 09:49 dmesg-efi-155741337605001
 -r--r--r-- 1 root root 1690 May  9 09:49 dmesg-efi-155741337606001
 -r--r--r-- 1 root root 1775 May  9 09:49 dmesg-efi-155741337607001
 -r--r--r-- 1 root root 1811 May  9 09:49 dmesg-efi-155741337608001
 -r--r--r-- 1 root root 1817 May  9 09:49 dmesg-efi-155741337609001
 -r--r--r-- 1 root root 1795 May  9 09:49 dmesg-efi-155741337710001
 -r--r--r-- 1 root root 1770 May  9 09:49 dmesg-efi-155741337711001
 -r--r--r-- 1 root root 1796 May  9 09:49 dmesg-efi-155741337712001
 -r--r--r-- 1 root root 1787 May  9 09:49 dmesg-efi-155741337713001
 -r--r--r-- 1 root root 1808 May  9 09:49 dmesg-efi-155741337714001
 -r--r--r-- 1 root root 1754 May  9 09:49 dmesg-efi-155741337715001

results in the following:

 root@vm356:~# ls -al /var/lib/systemd/pstore/155741337/
 total 92
 drwxr-xr-x 2 root root  4096 May  9 09:50 .
 drwxr-xr-x 4 root root    40 May  9 09:50 ..
 -rw-r--r-- 1 root root  1610 May  9 09:50 dmesg-efi-155741337601001
 -rw-r--r-- 1 root root  1778 May  9 09:50 dmesg-efi-155741337602001
 -rw-r--r-- 1 root root  1726 May  9 09:50 dmesg-efi-155741337603001
 -rw-r--r-- 1 root root  1746 May  9 09:50 dmesg-efi-155741337604001
 -rw-r--r-- 1 root root  1686 May  9 09:50 dmesg-efi-155741337605001
 -rw-r--r-- 1 root root  1690 May  9 09:50 dmesg-efi-155741337606001
 -rw-r--r-- 1 root root  1775 May  9 09:50 dmesg-efi-155741337607001
 -rw-r--r-- 1 root root  1811 May  9 09:50 dmesg-efi-155741337608001
 -rw-r--r-- 1 root root  1817 May  9 09:50 dmesg-efi-155741337609001
 -rw-r--r-- 1 root root  1795 May  9 09:50 dmesg-efi-155741337710001
 -rw-r--r-- 1 root root  1770 May  9 09:50 dmesg-efi-155741337711001
 -rw-r--r-- 1 root root  1796 May  9 09:50 dmesg-efi-155741337712001
 -rw-r--r-- 1 root root  1787 May  9 09:50 dmesg-efi-155741337713001
 -rw-r--r-- 1 root root  1808 May  9 09:50 dmesg-efi-155741337714001
 -rw-r--r-- 1 root root  1754 May  9 09:50 dmesg-efi-155741337715001
 -rw-r--r-- 1 root root 26754 May  9 09:50 dmesg.txt

where dmesg.txt is reconstructed from the group of related
dmesg-efi-155741337* files.

Configuration file:
The pstore.conf configuration file has four settings, described below.
 - Storage : one of "none", "external", or "journal". With "none", this
   tool leaves the contents of pstore untouched. With "external", the
   contents of the pstore are moved into the /var/lib/systemd/pstore,
   as well as logged into the journal.  With "journal", the contents of
   the pstore are recorded only in the systemd journal. The default is
   "external".
 - Unlink : is a boolean. When "true", the default, then files in the
   pstore are removed once processed. When "false", processing of the
   pstore occurs normally, but the pstore files remain.

References:
[1] "Persistent storage for a kernel's dying breath",
    March 23, 2011.
    https://lwn.net/Articles/434821/

[2] "Advanced Configuration and Power Interface Specification",
    version 6.2, May 2017.
    https://www.uefi.org/sites/default/files/resources/ACPI_6_2.pdf

[3] "Unified Extensible Firmware Interface Specification",
    version 2.8, March 2019.
    https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_final.pdf

[4] "The kernel’s command-line parameters",
    https://static.lwn.net/kerneldoc/admin-guide/kernel-parameters.html
2019-07-19 21:46:07 +02:00
34d2f9204c meson: update hint in man/rules/ 2019-07-19 07:09:34 +09:00
cb367b1785 Merge pull request #12518 from keszybz/naming-scheme
Document our naming schemes properly
2019-05-10 15:14:59 -04:00
aa7585fd8e sd-event: add sd_event_source_disable_unrefp() too
I do not have any immediate use for it, but let's add it for completeness.
2019-05-10 16:55:37 +02:00
afd15bbb4b sd-event: add sd_event_source_disable_unref() helper 2019-05-10 16:55:35 +02:00
0b1e5b6ed8 man: describe naming schemes in a new man page
I decided to make this a separate man page because it is freakin' long.
This content could equally well go in systemd-udevd.service(8), systemd.link(5),
or a new man page for the net_id builtin.

v2:
- rename to systemd.net-naming-scheme
- add udevadm test-builtin net_id example
2019-05-10 10:24:03 +02:00
afb9c0c958 man: document sd_bus_add_{object,fallback}_vtable
The interface provided by those two functions is huge, so this text could
probably be made two or three times as long if all details were described.
But I think it's a good start.
2019-04-23 22:58:51 +02:00
03abeb0baf Merge pull request #12267 from keszybz/udev-settle-warning
Udev settle warning
2019-04-11 19:01:03 +02:00
18a3882250 man: add a page for systemd-udev-settle.service 2019-04-10 10:12:43 +02:00
38df8d3f52 sd-id128: expose ID128_UUID_FORMAT_STR
It is generally useful, and can be made public in the same manner that
SD_ID128_FORMAT_STR is.
2019-04-05 13:47:54 +02:00
2dfdf9c4b2 man: create .so links for sd_bus_close_{unref,unrefp}
Follow-up for bd62b74486.
2019-02-28 13:10:08 +01:00
ffd1a3f688 man: substantially update the docs regarding hooking sd-bus objects up with external event loops
Prompted by https://lists.freedesktop.org/archives/systemd-devel/2018-December/041817.html

This also drops all references to select() from our manpages. It's 2018
after all, people should use poll(), or ppoll() or epoll().
2018-12-13 22:33:47 +01:00
565f3d91a2 man: document systemd-run-generator 2018-11-27 09:44:40 +01:00
15e9a42074 Merge pull request #10306 from poettering/nspawn-ref-unref
nspawn scope lifecycle fixes
2018-11-09 20:49:31 +01:00
48c3512269 man: document sd_bus_attach_event() 2018-11-09 17:09:52 +01:00
eda0d9a13b man: document sd_bus_flush_close_unref() 2018-11-09 17:09:52 +01:00
576af73f4a man: document sd_bus_close() + sd_bus_flush() 2018-11-09 17:09:52 +01:00
c4e48030cf sd-bus: make "close+flush-on-exit" optional when using sd-event with sd-bus
This adds a new pair of API calls sd_bus_set_close_on_exit() and
sd_bus_get_close_on_exit(). They control whether an sd_bus object
attached to a an sd-event loop shall automatically be flushed/closed
when the event loop goes down. Usually that's a good thing, except for
very few cases where the bus connection is longer living than the event
loop it is attached on. Specifically, this is the case for nspawn, where
we run the event loop only while the container is up, but afterwards
still want to be able to use the bus connection.
2018-11-09 17:08:59 +01:00
223ce56fa1 man: document systemd-bless-boot-generator 2018-10-19 22:34:50 +02:00
04431cd1f8 man: document systemd-boot-check-no-failures.service 2018-10-19 22:34:50 +02:00
ab3fc7b193 man: document systemd-bless-boot 2018-10-19 22:34:50 +02:00
190128e407 sd-bus: add new API call sd_bus_error_move()
This new call move an sd_bus_error into another one.
2018-10-13 12:59:29 +02:00
adda90b03e man: add man page for systemd-id128 2018-10-02 15:15:10 +02:00
65d410c7ca sd-id128: add sd_id128_get_boot_app_specific() 2018-10-02 15:15:10 +02:00
d7338be4f0 man: add sd_bus_message_get_signature(3) 2018-08-23 16:57:55 +02:00
7f9f55e1b3 man: add sd_bus_message_read_array(3) 2018-08-11 12:25:54 +02:00
58df2afbbf man: add sd_bus_message_skip(3) 2018-08-11 12:25:54 +02:00
46fdbae32e man: add sd_bus_message_rewind(3) 2018-08-02 15:49:45 +02:00
e7015301fb man: document sd_bus_slot_get_bus in sd_bus_slot_ref(3)
Similar reasoning as for sd_bus_message_get_bus().
2018-08-02 15:49:45 +02:00
dee0fccca3 man: add sd_bus_slot_set_description(3) 2018-08-02 15:49:45 +02:00
6d4a51820e man: add sd_bus_slot_set_userdata(3) 2018-08-02 15:49:45 +02:00
d65044e812 man: add sd_bus_message_set_expect_reply(3) 2018-08-02 15:49:45 +02:00
9905256523 man: document sd_bus_message_get_bus() in sd_bus_message_new(3)
It's not a particularly obvious place, but it's a trivial function that isn't
worth a man page of its own, and it doesn't fit anywhere else either.
2018-08-02 15:49:45 +02:00
2c48865bd0 man: add sd_bus_message_verify_type(3) 2018-08-02 15:49:45 +02:00
9c9207912e man: add sd_bus_message_get_type(3)
sd_bus_message{get_type,is_signal,is_method_call,is_method_error} get one man
page.

sd_bus_message_{set,get}_{destination,path,interface,member,sender} are put in
the second one.
2018-08-02 15:49:45 +02:00
f16a506418 man: add sd_bus_slot_ref(3) 2018-08-02 15:49:45 +02:00
7ddee21716 man: document sd_bus_message_new_method_return 2018-08-02 15:49:45 +02:00
f00ded93e0 man: document *_with_description functions 2018-08-02 15:49:45 +02:00
206ed9c1f6 man: add sd_bus_message_new(3) 2018-08-02 15:48:46 +02:00
cfe8ee463d man: add sd_bus_message_new_call(3) 2018-08-02 15:45:20 +02:00