From afc7ad8cd5ac87dfe72b47fd64b6d9088a905034 Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 09:59:23 +0100 Subject: [PATCH 1/7] man: fix plural --- man/cgroup-sandboxing.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/cgroup-sandboxing.xml b/man/cgroup-sandboxing.xml index c9e068f8879..6aa62df5367 100644 --- a/man/cgroup-sandboxing.xml +++ b/man/cgroup-sandboxing.xml @@ -12,6 +12,6 @@ in the service unit, as it applies to the whole control group. These options cannot be bypassed by prefixing + to the executable path - in the service unit, as it applies to the whole control group. + in the service unit, as they apply to the whole control group. From 2dfeb64bcd6425100dbf399e563ba6bc63d57a98 Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 16:54:07 +0100 Subject: [PATCH 2/7] man: use at one more place --- man/systemd.unit.xml | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 41f1a0af4ac..11154bdc76f 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -25,17 +25,19 @@ - service.service, - socket.socket, - device.device, - mount.mount, - automount.automount, - swap.swap, - target.target, - path.path, - timer.timer, - slice.slice, - scope.scope + + service.service + socket.socket + device.device + mount.mount + automount.automount + swap.swap + target.target + path.path + timer.timer + slice.slice + scope.scope + System Unit Search Path From 28ed1ba9bd54cfc564a6356f577040faae252325 Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 18:26:34 +0100 Subject: [PATCH 3/7] man: use better-fitting markup --- man/veritytab.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/man/veritytab.xml b/man/veritytab.xml index e58edf1a506..bdeaebe02c0 100644 --- a/man/veritytab.xml +++ b/man/veritytab.xml @@ -48,12 +48,12 @@ This is based on crypttab(5). below /dev/mapper/. The second field contains a path to the underlying block data device, or a specification of a block device via - UUID= followed by the UUID. + UUID= followed by the UUID. The third field contains a path to the underlying block hash device, or a specification of a block device via - UUID= followed by the UUID. + UUID= followed by the UUID. - The fourth field is the roothash in hexadecimal. + The fourth field is the roothash in hexadecimal. The fifth field, if present, is a comma-delimited list of options. The following options are recognized: @@ -137,9 +137,9 @@ This is based on crypttab(5). Defines what to do if a data verity problem is detected (data corruption). Without these - options kernel fails the IO operation with I/O error. With --ignore-corruption option the - corruption is only logged. With --restart-on-corruption or - --panic-on-corruption the kernel is restarted (panicked) immediately. + options kernel fails the IO operation with I/O error. With option the + corruption is only logged. With or + the kernel is restarted (panicked) immediately. (You have to provide way how to avoid restart loops.) From ee5bf48f7df5b307c9803ad396df3ce2b491a84e Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 18:33:12 +0100 Subject: [PATCH 4/7] man: sprinkle some more markup around --- man/veritytab.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/man/veritytab.xml b/man/veritytab.xml index bdeaebe02c0..317daec8aed 100644 --- a/man/veritytab.xml +++ b/man/veritytab.xml @@ -41,17 +41,17 @@ This is based on crypttab(5). verity protected block device. Fields are delimited by white space. - Each line is in the formvolume-name data-device hash-device roothash options + Each line is in the formvolume-name data-device hash-device roothash options The first four fields are mandatory, the remaining one is optional. The first field contains the name of the resulting verity volume; its block device is set up below /dev/mapper/. The second field contains a path to the underlying block data device, or a specification of a block device via - UUID= followed by the UUID. + UUID= followed by the UUID. The third field contains a path to the underlying block hash device, or a specification of a block device via - UUID= followed by the UUID. + UUID= followed by the UUID. The fourth field is the roothash in hexadecimal. @@ -71,7 +71,7 @@ This is based on crypttab(5). - Specifies the hash version type. Format type 0 is original Chrome OS version. Format type 1 is + Specifies the hash version type. Format type 0 is original Chrome OS version. Format type 1 is modern version. @@ -125,8 +125,8 @@ This is based on crypttab(5). - Use the provided UUID for format command instead of generating new one. The UUID must be - provided in standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc. + Use the provided UUID for format command instead of generating new one. The UUID must be + provided in standard UUID format, e.g. 12345678-1234-1234-1234-123456789abc. @@ -137,7 +137,7 @@ This is based on crypttab(5). Defines what to do if a data verity problem is detected (data corruption). Without these - options kernel fails the IO operation with I/O error. With option the + options kernel fails the IO operation with I/O error. With option the corruption is only logged. With or the kernel is restarted (panicked) immediately. @@ -183,7 +183,7 @@ This is based on crypttab(5). - Use forward error correction (FEC) to recover from corruption if hash verification fails. Use + Use forward error correction (FEC) to recover from corruption if hash verification fails. Use encoding data from the specified device. The fec device argument can be block device or file image. For format, if fec device path doesn't exist, it will be created as file. Note: block sizes for data and hash devices must match. Also, if the verity data_device is encrypted the fec_device should be too. @@ -194,7 +194,7 @@ This is based on crypttab(5). - This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding + This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding data. (Aligned on 512 bytes.) From f37841c0b7254f011a904e86dfc86275967148fb Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 18:33:36 +0100 Subject: [PATCH 5/7] man: add a missing space --- man/veritytab.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/veritytab.xml b/man/veritytab.xml index 317daec8aed..5e444878bc8 100644 --- a/man/veritytab.xml +++ b/man/veritytab.xml @@ -117,7 +117,7 @@ This is based on crypttab(5). Salt used for format or verification. Format is a hexadecimal string; 256 bytes long maximum; - -is the special value for empty. + - is the special value for empty. From 617b85d10e66cd1f572a02bb7ee8093bc45e22b9 Mon Sep 17 00:00:00 2001 From: David Tardon Date: Sat, 23 Dec 2023 18:40:15 +0100 Subject: [PATCH 6/7] man: use for warnings --- man/crypttab.xml | 16 ++++++++++------ man/systemctl.xml | 14 +++++++++----- man/systemd-storagetm.service.xml | 8 +++++--- man/systemd.network.xml | 16 +++++++++------- man/udevadm.xml | 18 ++++++++++-------- man/veritytab.xml | 16 +++++++++------- 6 files changed, 52 insertions(+), 36 deletions(-) diff --git a/man/crypttab.xml b/man/crypttab.xml index 5e67d44cb3a..175e169fbc7 100644 --- a/man/crypttab.xml +++ b/man/crypttab.xml @@ -458,10 +458,12 @@ mkswap8. This option implies . - WARNING: Using the option will - destroy the contents of the named partition during every boot, - so make sure the underlying block device is specified - correctly. + + Using the option will + destroy the contents of the named partition during every boot, + so make sure the underlying block device is specified + correctly. + @@ -591,8 +593,10 @@ btrfs. If no argument is specified defaults to ext4. This option implies . - WARNING: Using the option will destroy the contents of the named partition - during every boot, so make sure the underlying block device is specified correctly. + + Using the option will destroy the contents of the named partition + during every boot, so make sure the underlying block device is specified correctly. + diff --git a/man/systemctl.xml b/man/systemctl.xml index e0267df7783..b22c1b19541 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -2478,11 +2478,15 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err processes will be killed forcibly and all file systems are unmounted or remounted read-only. This is hence a drastic but relatively safe option to request an immediate reboot. If is specified twice for these operations (with the exception of kexec), they will be executed - immediately, without terminating any processes or unmounting any file systems. Warning: specifying - twice with any of these operations might result in data loss. Note that when - is specified twice the selected operation is executed by - systemctl itself, and the system manager is not contacted. This means the command should - succeed even when the system manager has crashed. + immediately, without terminating any processes or unmounting any file systems. + + + Specifying + twice with any of these operations might result in data loss. Note that when + is specified twice the selected operation is executed by + systemctl itself, and the system manager is not contacted. This means the command should + succeed even when the system manager has crashed. + diff --git a/man/systemd-storagetm.service.xml b/man/systemd-storagetm.service.xml index 0ca1cbd8a5c..728b3ae37a0 100644 --- a/man/systemd-storagetm.service.xml +++ b/man/systemd-storagetm.service.xml @@ -39,9 +39,11 @@ NVMe-TCP mass storage devices. Its primary use-case is to be invoked by the storage-target-mode.target unit that can be booted into. - Warning: the NVMe disks are currently exposed without authentication or encryption, in read/write - mode. This means network peers may read from and write to the device without any restrictions. This - functionality should hence only be used in a local setup. + + The NVMe disks are currently exposed without authentication or encryption, in read/write + mode. This means network peers may read from and write to the device without any restrictions. This + functionality should hence only be used in a local setup. + Note that to function properly networking must be configured too. The recommended mechanism to boot into a storage target mode is by adding rd.systemd.unit=storage-target-mode.target diff --git a/man/systemd.network.xml b/man/systemd.network.xml index ea558c4b4ef..1f30cc13b30 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1342,13 +1342,15 @@ Table=1234 Fallback Peer Labeling rules. They will be removed when the interface is deconfigured. Failures to manage the labels will be ignored. - Warning: Once labeling is enabled for network traffic, a lot of LSM access control points in - Linux networking stack go from dormant to active. Care should be taken to avoid getting into a - situation where for example remote connectivity is broken, when the security policy hasn't been - updated to consider LSM per-packet access controls and no rules would allow any network - traffic. Also note that additional configuration with netlabelctl8 - is needed. + + Once labeling is enabled for network traffic, a lot of LSM access control points in + Linux networking stack go from dormant to active. Care should be taken to avoid getting into a + situation where for example remote connectivity is broken, when the security policy hasn't been + updated to consider LSM per-packet access controls and no rules would allow any network + traffic. Also note that additional configuration with netlabelctl8 + is needed. + Example: [Address] diff --git a/man/udevadm.xml b/man/udevadm.xml index a9a4a4c3749..34f7f5c3874 100644 --- a/man/udevadm.xml +++ b/man/udevadm.xml @@ -550,14 +550,16 @@ Typically, it is essential that applications which intend to use such a match, make sure a suitable udev rule is installed that sets at least one property on devices that shall be matched. See also Initialized Devices section below for more details. - WARNING: can potentially save a significant - amount of time compared to re-triggering all devices in the system and e.g. can be used to - optimize boot time. However, this is not safe to be used in a boot sequence in general. - Especially, when udev rules for a device depend on its parent devices (e.g. - ATTRS or IMPORT{parent} keys, see - udev7 - for more details), the final state of the device becomes easily unstable with this option. - + + can potentially save a significant + amount of time compared to re-triggering all devices in the system and e.g. can be used to + optimize boot time. However, this is not safe to be used in a boot sequence in general. + Especially, when udev rules for a device depend on its parent devices (e.g. + ATTRS or IMPORT{parent} keys, see + udev7 + for more details), the final state of the device becomes easily unstable with this option. + + diff --git a/man/veritytab.xml b/man/veritytab.xml index 5e444878bc8..ee88528775a 100644 --- a/man/veritytab.xml +++ b/man/veritytab.xml @@ -150,10 +150,11 @@ This is based on crypttab(5). Instruct kernel to not verify blocks that are expected to contain zeroes and always directly - return zeroes instead. + return zeroes instead. - WARNING: Use this option only in very specific cases. This option is available since Linux kernel version 4.5. - + + Use this option only in very specific cases. This option is available since Linux kernel version 4.5. + @@ -162,11 +163,12 @@ This is based on crypttab(5). Instruct kernel to verify blocks only the first time they are read from the data device, rather - than every time. + than every time. - WARNING: It provides a reduced level of security because only offline tampering of the data device's content - will be detected, not online tampering. This option is available since Linux kernel version 4.17. - + + It provides a reduced level of security because only offline tampering of the data device's content + will be detected, not online tampering. This option is available since Linux kernel version 4.17. + From 8f39acd005226dbd880edcb08780911afd7d310d Mon Sep 17 00:00:00 2001 From: David Tardon Date: Mon, 25 Dec 2023 09:17:17 +0100 Subject: [PATCH 7/7] man: fix xpointer expression --- man/sd_bus_message_append.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/man/sd_bus_message_append.xml b/man/sd_bus_message_append.xml index 3ed70b453eb..a029edd1b89 100644 --- a/man/sd_bus_message_append.xml +++ b/man/sd_bus_message_append.xml @@ -95,7 +95,7 @@ Item type specifiers - +