From be0d27ee0c2a2cce39490b8cfc0e7d995fbd7644 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 27 Jul 2021 09:37:29 +0200 Subject: [PATCH 1/4] man: fix assorted issues reported by the manpage-l10n project Fixes #20297. --- man/bootctl.xml | 4 ++-- man/coredump.conf.xml | 19 ++++++---------- man/coredumpctl.xml | 2 +- man/os-release.xml | 2 +- man/repart.d.xml | 14 ++++++------ man/systemd-cryptenroll.xml | 2 +- man/systemd-firstboot.xml | 2 +- man/systemd-machine-id-setup.xml | 2 +- man/systemd-nspawn.xml | 18 +++++++-------- man/systemd-resolved.service.xml | 2 +- man/systemd-sysext.xml | 18 ++++++++------- man/systemd-system.conf.xml | 2 +- man/systemd-userdbd.service.xml | 2 +- man/systemd.exec.xml | 15 +++++++------ man/systemd.link.xml | 10 ++++----- man/systemd.netdev.xml | 38 ++++++++++++++++---------------- man/systemd.network.xml | 32 +++++++++++++-------------- man/systemd.nspawn.xml | 2 +- man/systemd.preset.xml | 2 +- man/systemd.service.xml | 2 +- man/systemd.unit.xml | 2 +- man/userdbctl.xml | 6 ++--- 22 files changed, 98 insertions(+), 100 deletions(-) diff --git a/man/bootctl.xml b/man/bootctl.xml index 81033158f6..d05c3f34d0 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -240,8 +240,8 @@ Control creation and deletion of the top-level machine ID directory on the file - system containing boot loader entries (i.e. beneath the file system returned by - above) during and + system containing boot loader entries (i.e. beneath the file system returned by the + option, see above) during and , respectively. auto is equivalent to yes if /etc/machine-id resides on a filesystem other than tmpfs and no otherwise (in the latter case the machine ID is likely transient and diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index 28e6017c7d..1751191ec0 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -83,12 +83,9 @@ ProcessSizeMax= - The maximum size in bytes of a core - which will be processed. Core dumps exceeding this size - may be stored, but the backtrace will not be generated. - Like other sizes in this same config file, the usual - suffixes to the base of 1024 are allowed (B, K, M, - G, T, P, and E.) + The maximum size in bytes of a core which will be processed. Core dumps exceeding + this size may be stored, but the backtrace will not be generated. Like other sizes in this same + config file, the usual suffixes to the base of 1024 are allowed (B, K, M, G, T, P, and E). Setting Storage=none and ProcessSizeMax=0 disables all coredump handling except for a log entry. @@ -99,9 +96,8 @@ ExternalSizeMax= JournalSizeMax= - The maximum (compressed or uncompressed) size in bytes of a - core to be saved. Unit suffixes are allowed just as in - . + The maximum (compressed or uncompressed) size in bytes of a core to be saved. Unit + suffixes are allowed just as in . @@ -120,9 +116,8 @@ by core dumps might temporarily exceed these limits while core dumps are processed. Note that old core dumps are also removed based on time via - systemd-tmpfiles8. Set - either value to 0 to turn off size-based - clean-up. + systemd-tmpfiles8. + Set either value to 0 to turn off size-based cleanup. diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 6ceed41b05..d45ed753b2 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -162,7 +162,7 @@ Show information of the most recent core dump only, instead of listing all known core - dumps. (Equivalent to + dumps. Equivalent to . diff --git a/man/os-release.xml b/man/os-release.xml index fb24eda182..a7c60183ae 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -373,7 +373,7 @@ A lower-case string (mostly numeric, no spaces or other characters outside of 0–9, a–z, ".", "_" and "-") identifying the operating system extensions support level, to indicate which - extension images are supported. See: + extension images are supported. See systemd-sysext8) for more information. diff --git a/man/repart.d.xml b/man/repart.d.xml index 0305e255c7..d3059e9ec6 100644 --- a/man/repart.d.xml +++ b/man/repart.d.xml @@ -452,8 +452,8 @@ If the special value auto is specified, the source to copy from is automatically picked up from the running system (or the image specified with — if used). A partition that matches both the configured partition type (as - declared with Type= above), and the currently mounted directory appropriate for - that partition type is determined. For example, if the partition type is set to + declared with Type= described above), and the currently mounted directory + appropriate for that partition type is determined. For example, if the partition type is set to root the partition backing the root directory (/) is used as source to copy from — if its partition type is set to root as well. If the declared type is usr the partition backing /usr/ is used as @@ -529,7 +529,7 @@ MakeDirectories= - akes one or more absolute paths, separated by whitespace, each declaring a directory + Takes one or more absolute paths, separated by whitespace, each declaring a directory to create within the new file system. Behaviour is similar to CopyFiles=, but instead of copying in a set of files this just creates the specified directories with the default mode of 0755 owned by the root user and group, plus all their parent directories (with the same @@ -564,10 +564,10 @@ are copied in or the file system configured with Format= is created. The LUKS2 UUID is automatically derived from the partition UUID in a stable fashion. If - key-file or key-file+tpm2 is used a key is added to the LUKS2 - superblock, configurable with the switch to + key-file or key-file+tpm2 is used, a key is added to the LUKS2 + superblock, configurable with the option to systemd-repart. If tpm2 or key-file+tpm2 is - used a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured + used, a key is added to the LUKS2 superblock that is enrolled to the local TPM2 chip, as configured with the and options to systemd-repart. @@ -623,7 +623,7 @@ has no effect on explicit mounts, such as those done via mount8 or fstab5 + project='man-pages'>fstab5. If both bit 50 and 59 are set for a partition (i.e. the partition is marked both read-only and marked for file system growing) the latter is typically without effect: the read-only flag takes diff --git a/man/systemd-cryptenroll.xml b/man/systemd-cryptenroll.xml index d5719bc463..c6d6c5bd6c 100644 --- a/man/systemd-cryptenroll.xml +++ b/man/systemd-cryptenroll.xml @@ -84,7 +84,7 @@ URI Enroll a PKCS#11 security token or smartcard (e.g. a YubiKey). Expects a PKCS#11 - smart card URI referring to the token. Alternatively the special value auto may + smartcard URI referring to the token. Alternatively the special value auto may be specified, in order to automatically determine the URI of a currently plugged in security token (of which there must be exactly one). The special value list may be used to enumerate all suitable PKCS#11 tokens currently plugged in. The security token must contain an RSA diff --git a/man/systemd-firstboot.xml b/man/systemd-firstboot.xml index 87cf98c31a..66d829941b 100644 --- a/man/systemd-firstboot.xml +++ b/man/systemd-firstboot.xml @@ -307,7 +307,7 @@ passwd.shell.root - Specifies the shell binary to use for the specified account when creating it. + Specifies the shell binary to use for the specified account. Equivalent to the credential of the same name defined for the systemd-sysusers.service8 service. diff --git a/man/systemd-machine-id-setup.xml b/man/systemd-machine-id-setup.xml index a9c52d842c..177fe892a6 100644 --- a/man/systemd-machine-id-setup.xml +++ b/man/systemd-machine-id-setup.xml @@ -90,7 +90,7 @@ - Takes a path to a device node or refular file as argument. This is similar to + Takes a path to a device node or regular file as argument. This is similar to as described above, but operates on a disk image instead of a directory tree. diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index e929d32f62..3623ef015a 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1375,12 +1375,12 @@ After=sys-subsystem-net-devices-ens1.device The combination of the three operations above ensures that it is possible to log into the - host's user account inside the container as if it was local to the container. The user is only mapped - transiently, while the container is running and the mapping itself does not result in persistent - changes to the container (except maybe for generated log messages at login time, and similar). Note - that in particular the UID/GID assignment in the container is not made persistently. If the user is - mapped transiently, it is best to not allow the user to make persistent changes to the container. If - the user leaves files or directories owned by the user, and those UIDs/GIDs are recycled during later + container using the same account information as on the host. The user is only mapped transiently, + while the container is running, and the mapping itself does not result in persistent changes to the + container (except maybe for log messages generated at login time, and similar). Note that in + particular the UID/GID assignment in the container is not made persistently. If the user is mapped + transiently, it is best to not allow the user to make persistent changes to the container. If the + user leaves files or directories owned by the user, and those UIDs/GIDs are reused during later container invocations (possibly with a different mapping), those files and directories will be accessible to the "new" user. @@ -1581,9 +1581,9 @@ After=sys-subsystem-net-devices-ens1.device -b The above command line will invoke the specified image file image.raw in - volatile mode, i.e with an empty /etc/ and /var/, so that - the container's payload recognizes this as first boot condition, and will invoke - systemd-firstboot.service, which then read the two passed credentials to + volatile mode, i.e. with empty /etc/ and /var/. The + container payload will recognize this as a first boot, and will invoke + systemd-firstboot.service, which then reads the two passed credentials to configure the system's initial locale and root password. diff --git a/man/systemd-resolved.service.xml b/man/systemd-resolved.service.xml index 7dbbfa0001..34c1257ab0 100644 --- a/man/systemd-resolved.service.xml +++ b/man/systemd-resolved.service.xml @@ -275,7 +275,7 @@ search foobar.com barbar.com fragility in both directions: a valid global name could be obscured by a local name, and resolution of a relative local name could suddenly break when a new top-level domain is created, or when a new subdomain of a top-level domain in registered. Resolving any given name as either relative or absolute - avoids this ambiguity.) + avoids this ambiguity. This resolver has a notion of the special .local domain used for MulticastDNS, and will not route queries with that suffix to unicast DNS servers unless explicitly diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index ad6a401c7a..9d368f7958 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -46,7 +46,7 @@ operating system tree. When one or more system extension images are activated, their /usr/ and /opt/ hierarchies are combined via overlayfs with the same hierarchies of the host OS, and the host - /usr/ and /opt overmounted with it ("merging"). When they are + /usr/ and /opt/ overmounted with it ("merging"). When they are deactivated, the mount point is disassembled — again revealing the unmodified original host version of the hierarchy ("unmerging"). Merging thus makes the extension's resources suddenly appear below the /usr/ and /opt/ hierarchies as if they were included in the @@ -127,13 +127,15 @@ Uses The primary use case for system images are immutable environments where debugging and development - tools shall optionally be made available, but not included in the immutable base OS image itself - (e.g. strace and gdb shall be an optionally installable - addition in order to make debugging/development easier). System extension images should not be - misunderstood as a generic software packaging framework, as no dependency scheme is available: system - extensions should carry all files they need themselves, except for those already shipped in the - underlying host system image. Typically, system extension images are built at the same time as the base - OS image — within the same build system. + tools shall optionally be made available, but not included in the immutable base OS image itself (e.g. + strace1 + and + gdb1 + shall be an optionally installable addition in order to make debugging/development easier). System + extension images should not be misunderstood as a generic software packaging framework, as no dependency + scheme is available: system extensions should carry all files they need themselves, except for those + already shipped in the underlying host system image. Typically, system extension images are built at the + same time as the base OS image — within the same build system. Another use case for the system extension concept is temporarily overriding OS supplied resources with newer ones, for example to install a locally compiled development version of some low-level diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index c11dd46143..5824e01e0c 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -262,7 +262,7 @@ names in status messages (e.g. systemd-journald.service), instead of the longer and more informative descriptions set with Description= (e.g. Journal Logging Service). If , the system manager will use both unit names - and descriptions in status messages (e.g. systemdmd-jouranld.service - Journal Logging + and descriptions in status messages (e.g. systemd-journald.service - Journal Logging Service). See diff --git a/man/systemd-userdbd.service.xml b/man/systemd-userdbd.service.xml index fbbc740040..84a3fc0452 100644 --- a/man/systemd-userdbd.service.xml +++ b/man/systemd-userdbd.service.xml @@ -34,7 +34,7 @@ JSON user/group records from classic UNIX/glibc NSS user/group records in order to provide full backwards compatibility. It may also pick up statically defined JSON user/group records from drop-in files in /etc/userdb/, /run/userdb/, - /run/host/userdb/ and /use/lib/userdb/. + /run/host/userdb/ and /usr/lib/userdb/. Most of systemd-userdbd's functionality is accessible through the userdbctl1 diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index ccb1567900..38f1cc59ee 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -402,14 +402,15 @@ ExtensionImages= This setting is similar to MountImages= in that it mounts a file - system hierarchy from a block device node or loopback file, but instead of providing a destination path, - an overlay will be set up. This option expects a whitespace separated list of mount definitions. Each - definition consists of a source path, optionally followed by a colon and a list of mount options. + system hierarchy from a block device node or loopback file, but instead of providing a destination + path, an overlay will be set up. This option expects a whitespace separated list of mount + definitions. Each definition consists of a source path, optionally followed by a colon and a list of + mount options. A read-only OverlayFS will be set up on top of /usr/ and - /opt/ hierarchies from the root. The order in which the images are listed - will determine the order in which the overlay is laid down: images specified first to last will result - in overlayfs layers bottom to top. + /opt/ hierarchies. The order in which the images are listed will determine the + order in which the overlay is laid down: images specified first to last will result in overlayfs + layers bottom to top. Mount options may be defined as a single comma-separated list of options, in which case they will be implicitly applied to the root partition on the image, or a series of colon-separated tuples @@ -2304,7 +2305,7 @@ SystemCallErrorNumber=EPERM Sets environment variables for executed processes. Each line is unquoted using the rules described in "Quoting" section in - systemd.syntax5 + systemd.syntax7 and becomes a list of variable assignments. If you need to assign a value containing spaces or the equals sign to a variable, put quotes around the whole assignment. Variable expansion is not performed inside the strings and the $ character has no special meaning. Specifier diff --git a/man/systemd.link.xml b/man/systemd.link.xml index 1093e2e0b8..ee4356ac3d 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -457,7 +457,7 @@ MTUBytes= The maximum transmission unit in bytes to set for the - device. The usual suffixes K, M, G, are supported and are + device. The usual suffixes K, M, G are supported and are understood to the base of 1024. @@ -465,7 +465,7 @@ BitsPerSecond= The speed to set for the device, the value is rounded - down to the nearest Mbps. The usual suffixes K, M, G, are + down to the nearest Mbps. The usual suffixes K, M, G are supported and are understood to the base of 1000. @@ -788,7 +788,7 @@ GenericSegmentOffloadMaxBytes= Specifies the maximum size of a Generic Segment Offload (GSO) packet the - device should accept. The usual suffixes K, M, G, are supported and are + device should accept. The usual suffixes K, M, G are supported and are understood to the base of 1024. An unsigned integer in the range 1…65536. Defaults to unset. @@ -796,8 +796,8 @@ GenericSegmentOffloadMaxSegments= - Specifies the maximum number of a Generic Segment Offload (GSO) segments the device should - accept. An unsigned integer in the range 1…65535. Defaults to unset. + Specifies the maximum number of Generic Segment Offload (GSO) segments the device should + accept. An unsigned integer in the range 1…65535. Defaults to unset. diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index 1d1d71786f..f62b4cb400 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -390,7 +390,7 @@ DefaultPVID= This specifies the default port VLAN ID of a newly attached bridge port. - Set this to an integer in the range 1–4094 or none to disable the PVID. + Set this to an integer in the range 1…4094 or none to disable the PVID. @@ -460,7 +460,7 @@ Id= - The VLAN ID to use. An integer in the range 0–4094. + The VLAN ID to use. An integer in the range 0…4094. This setting is compulsory. @@ -654,7 +654,7 @@ TTL= A fixed Time To Live N on Virtual eXtensible Local Area Network packets. - Takes inherit or a number in the range 0–255. 0 is a special + Takes inherit or a number in the range 0…255. 0 is a special value meaning inherit the inner protocol's TTL value. inherit means that it will inherit the outer protocol's TTL value. @@ -913,7 +913,7 @@ TunnelId= - Specifies the tunnel identifier. Takes an number in the range 1–4294967295. The value used + Specifies the tunnel identifier. Takes an number in the range 1…4294967295. The value used must match the PeerTunnelId= value being used at the peer. This setting is compulsory. @@ -1002,7 +1002,7 @@ SessionId= - Specifies the session identifier. Takes an number in the range 1–4294967295. The value used + Specifies the session identifier. Takes an number in the range 1…4294967295. The value used must match the SessionId= value being used at the peer. This setting is compulsory. @@ -1010,7 +1010,7 @@ PeerSessionId= - Specifies the peer session identifier. Takes an number in the range 1–4294967295. + Specifies the peer session identifier. Takes an number in the range 1…4294967295. The value used must match the PeerSessionId= value being used at the peer. This setting is compulsory. @@ -1234,7 +1234,7 @@ TTL= A fixed Time To Live N on tunneled packets. N is a - number in the range 1–255. 0 is a special value meaning that + number in the range 1…255. 0 is a special value meaning that packets inherit the TTL value. The default value for IPv4 tunnels is 0 (inherit). The default value for IPv6 tunnels is 64. @@ -1256,7 +1256,7 @@ It is only used for IPv6 tunnels. A flow label of zero is used to indicate packets that have not been labeled. - It can be configured to a value in the range 0–0xFFFFF, or be + It can be configured to a value in the range 0…0xFFFFF, or be set to inherit, in which case the original flowlabel is used. @@ -1673,15 +1673,15 @@ Sets a comma-separated list of IP (v4 or v6) addresses with CIDR masks from which this peer is allowed to send incoming traffic and to which outgoing traffic for this peer is directed. + The catch-all 0.0.0.0/0 may be specified for matching all IPv4 addresses, and ::/0 may be specified for matching all IPv6 addresses. - Note that this only affects "routing inside the network interface itself", - as in, which wireguard peer packets with a specific destination address are sent to, - and what source addresses are accepted from which peer. - To cause packets to be sent via wireguard in first place, a route needs - to be added, as well - either in the [Routes] section on the - .network matching the wireguard interface, or outside of networkd. - + + Note that this only affects routing inside the network interface itself, + i.e. the packets that pass through the tunnel itself. To cause packets to be sent via the tunnel in + the first place, an appropriate route needs to be added as well — either in the + [Routes] section on the .network matching the wireguard + interface, or externally to systemd-networkd. @@ -1823,7 +1823,7 @@ AdUserPortKey= Specifies the 802.3ad user defined portion of the port key. Takes a number in the range - 0–1023. + 0…1023. @@ -2036,9 +2036,9 @@ [BatmanAdvanced] Section Options - The [BatmanAdvanced] section only applies for - netdevs of kind batadv and accepts the - following keys: + + The [BatmanAdvanced] section only applies for netdevs of kind batadv and accepts + the following keys: diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 242d4ea066..b8bb8aedf4 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1423,7 +1423,7 @@ IPv6Token=prefixstable:2002:da8:1:: Metric= The metric of the route. Takes an unsigned integer in the range 0…4294967295. - Defaluts to unset, and the kernel's default will be used. + Defaults to unset, and the kernel's default will be used. @@ -1615,9 +1615,10 @@ IPv6Token=prefixstable:2002:da8:1:: SendHostname= When true (the default), the machine's hostname (or the value specified with - Hostname= below) will be sent to the DHCP server. Note that the hostname must - consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be formatted as a - valid DNS domain name. Otherwise, the hostname is not sent even if this option is true. + Hostname=, described below) will be sent to the DHCP server. Note that the + hostname must consist only of 7-bit ASCII lower-case characters and no spaces or dots, and be + formatted as a valid DNS domain name. Otherwise, the hostname is not sent even if this option is + true. @@ -1911,8 +1912,8 @@ IPv6Token=prefixstable:2002:da8:1:: FallbackLeaseLifetimeSec= Allows to set DHCPv4 lease lifetime when DHCPv4 server does not send the lease lifetime. - Takes one of forever or infinity means that the address - never expires. Defaults to unset. + Takes one of forever or infinity. The latter means that the + address never expires. Defaults to unset. @@ -2339,9 +2340,9 @@ IPv6Token=prefixstable:2002:da8:1:: ServerAddress= Specifies server address for the DHCP server. Takes an IPv4 address with prefix - length, e.g., 192.168.0.1/24. This setting may be useful when the link which - DHCP server running on has multiple static addresses. When unset, one of static addresses in - the link will be automatically selected. Defaults to unset. + length, for example 192.168.0.1/24. This setting may be useful when the link on + which the DHCP server is running has multiple static addresses. When unset, one of static addresses + in the link will be automatically selected. Defaults to unset. @@ -2521,23 +2522,22 @@ IPv6Token=prefixstable:2002:da8:1:: [DHCPServerStaticLease] Section Options - The [DHCPServerStaticLease] section configures a static DHCP lease to - assign a pre-set IPv4 address to a specific device based on its MAC address. This section can be - specified multiple times. + The [DHCPServerStaticLease] section configures a static DHCP lease to assign a + fixed IPv4 address to a specific device based on its MAC address. This section can be specified multiple + times. MACAddress= - The hardware address of a device which should be assigned IPv4 address - specified in Address=. This key is mandatory. + The hardware address of a device to match. This key is mandatory. Address= - IPv4 address that should be assigned to a device with a hardware address - specified in MACAddress=. This key is mandatory. + The IPv4 address that should be assigned to the device that was matched with + MACAddress=. This key is mandatory. diff --git a/man/systemd.nspawn.xml b/man/systemd.nspawn.xml index 7ba8e361b4..dc0e2f9fd2 100644 --- a/man/systemd.nspawn.xml +++ b/man/systemd.nspawn.xml @@ -202,7 +202,7 @@ capabilities (see capabilities7 for details). The AmbientCapability= setting - specifies capability which will be passed to to started program + specifies capability which will be passed to the started program in the inheritable and ambient capability sets. This will grant these capabilities to this process. This setting correspond to the command line switch. diff --git a/man/systemd.preset.xml b/man/systemd.preset.xml index 64333a3216..9e6db28536 100644 --- a/man/systemd.preset.xml +++ b/man/systemd.preset.xml @@ -207,7 +207,7 @@ disable * systemd-delta1 - daemon8 + daemon7 has a discussion of packaging scriptlets. Fedora page introducing the use of presets: diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 350bc5f8e5..884260a215 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -1134,7 +1134,7 @@ \;. Each command line is unquoted using the rules described in "Quoting" section in - systemd.syntax5. The + systemd.syntax7. The first item becomes the command to execute, and the subsequent items the arguments. This syntax is inspired by shell syntax, but only the meta-characters and expansions diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 9a4010c452..b6e4a2233c 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1535,7 +1535,7 @@ ConditionControlGroupController= - Check whether given cgroup controllers (eg. cpu) are available + Check whether given cgroup controllers (e.g. cpu) are available for use on the system or whether the legacy v1 cgroup or the modern v2 cgroup hierarchy is used. diff --git a/man/userdbctl.xml b/man/userdbctl.xml index 0871306b20..611c425b79 100644 --- a/man/userdbctl.xml +++ b/man/userdbctl.xml @@ -42,7 +42,7 @@ url="https://systemd.io/USER_GROUP_API">User/Group Record Lookup API via Varlink, and may also pick up drop-in JSON user and group records from /etc/userdb/, /run/userdb/, /run/host/userdb/, - /use/lib/userdb/. + /usr/lib/userdb/. @@ -104,7 +104,7 @@ Controls whether to include user/group lookups in the output that are defined using drop-in files in /etc/userdb/, /run/userdb/, - /run/host/userdb/, /use/lib/userdb/. If + /run/host/userdb/, /usr/lib/userdb/. If is used these records are suppressed. If is specified such users/groups are included in the output (which is the default). @@ -260,7 +260,7 @@ systemd-userdbd.service8 and picks up JSON user/group records from /etc/userdb/, /run/userdb/, /run/host/userdb/, - /use/lib/userdb/. + /usr/lib/userdb/. From d6029680df7c4991e37662467668816a83c0b806 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 27 Jul 2021 09:39:19 +0200 Subject: [PATCH 2/4] man: use title of docs/ pages when referring to them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There is some inconsistency, partially caused by the awkward naming of the docs/ pages. But let's be consistent and use the "official" title. If we ever change plural↔singular, we should use the same form everywhere. --- man/nss-systemd.xml | 2 +- man/pam_systemd.xml | 2 +- man/systemd-portabled.service.xml | 4 ++-- man/systemd-sysext.xml | 2 +- man/systemd-userdbd.service.xml | 2 +- man/systemd.exec.xml | 2 +- 6 files changed, 7 insertions(+), 7 deletions(-) diff --git a/man/nss-systemd.xml b/man/nss-systemd.xml index 734a9a4a07..b7b453825e 100644 --- a/man/nss-systemd.xml +++ b/man/nss-systemd.xml @@ -67,7 +67,7 @@ This is a simple mechanism to provide static user and group records via JSON drop-in files. Such user records should be defined in the format described by the JSON User Record specification and be placed in one of the + url="https://systemd.io/USER_RECORD">JSON User Records specification and be placed in one of the aforementioned directories under a file name composed of the user name suffixed with .user, with a world-readable access mode. A symlink named after the user record's UID formatted in decimal and suffixed with .user pointing to the primary record file diff --git a/man/pam_systemd.xml b/man/pam_systemd.xml index 24174213e2..5e3761ac50 100644 --- a/man/pam_systemd.xml +++ b/man/pam_systemd.xml @@ -33,7 +33,7 @@ and hence the systemd control group hierarchy. The module also applies various resource management and runtime parameters to the new session, as - configured in the JSON User Record of the user, when + configured in the JSON User Records of the user, when one is defined. On login, this module — in conjunction with systemd-logind.service — ensures the diff --git a/man/systemd-portabled.service.xml b/man/systemd-portabled.service.xml index 23906f2663..61f2c5ca9e 100644 --- a/man/systemd-portabled.service.xml +++ b/man/systemd-portabled.service.xml @@ -35,8 +35,8 @@ Most of systemd-portabled's functionality is accessible through the portablectl1 command. - See the Portable - Services Documentation for details about the concepts this service implements. + See Portable Services for details about + the concepts this service implements. diff --git a/man/systemd-sysext.xml b/man/systemd-sysext.xml index 9d368f7958..f8a9f47539 100644 --- a/man/systemd-sysext.xml +++ b/man/systemd-sysext.xml @@ -71,7 +71,7 @@ Plain directories or btrfs subvolumes containing the OS tree Disk images with a GPT disk label, following the Discoverable Partition Specification + url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification Disk images lacking a partition table, with a naked Linux file system (e.g. squashfs or ext4) diff --git a/man/systemd-userdbd.service.xml b/man/systemd-userdbd.service.xml index 84a3fc0452..9d8b62c452 100644 --- a/man/systemd-userdbd.service.xml +++ b/man/systemd-userdbd.service.xml @@ -41,7 +41,7 @@ command. The user and group records this service provides access to follow the JSON User Record and JSON User Records and JSON Group Record definitions. This service implements the User/Group Record Lookup API via Varlink, and multiplexes access other services implementing this API, too. It is thus both server and client of this diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index 38f1cc59ee..008cbe9af1 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -241,7 +241,7 @@ This option is supported only for disk images that contain a single file system, without an enveloping partition table. Images that contain a GPT partition table should instead include both root file system and matching Verity data in the same image, implementing the Discoverable Partition Specification. + url="https://systemd.io/DISCOVERABLE_PARTITIONS">Discoverable Partitions Specification. From dab1fe1a8e4d47784b6bf7b440d4b3ba6e70940d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 27 Jul 2021 09:39:39 +0200 Subject: [PATCH 3/4] man/tmpfiles.d: rewrite the description of age-by --- man/tmpfiles.d.xml | 49 +++++++++++++++++++++------------------------- 1 file changed, 22 insertions(+), 27 deletions(-) diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 261de5902d..305033b672 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -550,6 +550,7 @@ w- /proc/sys/vm/swappiness - - - - 10 Age + The date field, when set, is used to decide what files to delete when cleaning. If a file or directory is older than the current time minus the age field, it is deleted. The field @@ -582,10 +583,9 @@ w- /proc/sys/vm/swappiness - - - - 10 and X. If omitted or set to -, no automatic clean-up is done. - If the age field starts with a tilde character - ~, the clean-up is only applied to files and - directories one level inside the directory specified, but not - the files and directories immediately inside it. + If the age field starts with a tilde character ~, clean-up is only applied to + files and directories one level inside the directory specified, but not the files and directories + immediately inside it. The age of a file system entry is determined from its last modification timestamp (mtime), its last access timestamp (atime), @@ -595,30 +595,25 @@ w- /proc/sys/vm/swappiness - - - - 10 the age field. To restrict the deletion based on particular type of file timestamps, the age-by argument can be used. - The age-by argument, when (optionally) specified along - with age will check if the file system entry has aged by the - type of file timestamp(s) provided. It can be specified by - prefixing the age argument with a set of file timestamp types - followed by a colon character :, i.e., - age-by:cleanup-age. - The argument can be a set of: - a (A for directories), - b (B for directories), - c (C for directories; ignored by default), or - m (M for directories), - indicating access, creation, last status change, and last - modification times of a file system entry respectively. See - statx2 - file timestamp fields for more details. + The age-by argument overrides the timestamp types to be used for the age check. It can be + specified by prefixing the age argument with a sequence of characters to specify the timestamp types + and a colon (:): + age-by...:cleanup-age. The + argument can consist of a (A for directories), + b (B for directories), c + (C for directories), or m (M for + directories). Those respectively indicate access, creation, last status change, and last modification + time of a file system entry. The lower-case letter signifies that the given timestamp type should be + considered for files, while the upper-case letter signifies that the given timestamp type should be + considered for directories. See statx2 file + timestamp fields for more details about timestamp types. - If unspecified, the age-by field defaults to - abcmABM, - i.e., by default all file timestamps are taken into consideration, - with the exception of the last status change timestamp (ctime) for - directories. This is because the aging logic itself will alter the - ctime whenever it deletes a file inside it. To ensure that running - the aging logic does not feed back into the next iteration of it, - ctime for directories is ignored by default. + If not specified, the age-by field defaults to abcmABM, i.e. by default all + file timestamps are taken into consideration, with the exception of the last status change timestamp + (ctime) for directories. This is because the aging logic itself will alter the ctime whenever it + deletes a file inside it. To ensure that running the aging logic does not feed back into the next + iteration of itself, ctime for directories is ignored by default. For example: # Files created and modified, and directories accessed more than From e04eae5e1c43c050e0707d3fcfdc16691b761d61 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Tue, 27 Jul 2021 09:42:09 +0200 Subject: [PATCH 4/4] man/systemctl: rework descriptions of bind and mount-image The text used "unit's view" to mean mount namespace. But we talk about mount namespaces in the later part of the paragraph anyway, so trying to use an "approachable term" only makes the whole thing harder to understand. Let's use the precise term. Some paragraph-breaking and re-indentation is done too. --- man/systemctl.xml | 103 ++++++++++++++++++++++++++++------------------ 1 file changed, 64 insertions(+), 39 deletions(-) diff --git a/man/systemctl.xml b/man/systemctl.xml index 8402b9508a..5a133dea75 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -552,38 +552,62 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - bind UNIT PATH [PATH] + + bind + UNIT + PATH + [PATH] + - Bind mounts a file or directory from the host into the specified unit's view. The first path - argument is the source file or directory on the host, the second path argument is the destination file or - directory in the unit's view. When the latter is omitted, the destination path in the unit's view is the same as - the source path on the host. When combined with the switch, a ready-only bind - mount is created. When combined with the switch, the destination path is first created - before the mount is applied. Note that this option is currently only supported for units that run within a mount - namespace (e.g.: with , , etc.). This command supports bind - mounting directories, regular files, device nodes, AF_UNIX socket nodes, as well as FIFOs. - The bind mount is ephemeral, and it is undone as soon as the current unit process exists. - Note that the namespace mentioned here, where the bind mount will be added to, is the one where the main service - process runs, as other processes run in distinct namespaces (e.g.: , - , etc.) + Bind-mounts a file or directory from the host into the specified unit's mount + namespace. The first path argument is the source file or directory on the host, the second path + argument is the destination file or directory in the unit's mount namespace. When the latter is + omitted, the destination path in the unit's mount namespace is the same as the source path on the + host. When combined with the switch, a ready-only bind mount is + created. When combined with the switch, the destination path is first + created before the mount is applied. + + Note that this option is currently only supported for units that run within a mount namespace + (e.g.: with , , etc.). This command + supports bind-mounting directories, regular files, device nodes, AF_UNIX + socket nodes, as well as FIFOs. The bind mount is ephemeral, and it is undone as soon as the + current unit process exists. Note that the namespace mentioned here, where the bind mount will be + added to, is the one where the main service process runs. Other processes (those exececuted by + , , etc.) run in distinct namespaces. + - mount-image UNIT IMAGE [PATH [PARTITION_NAME:MOUNT_OPTIONS]] + + mount-image + UNIT + IMAGE + [PATH + [PARTITION_NAME:MOUNT_OPTIONS]] + - Mounts an image from the host into the specified unit's view. The first path argument is the source - image on the host, the second path argument is the destination directory in the unit's view (ie: inside - /). Any following argument is interpreted as a - colon-separated tuple of partition name and comma-separated list of mount options for that partition. The format is the - same as the service setting. When combined with the switch, a - ready-only mount is created. When combined with the switch, the destination path is first - created before the mount is applied. Note that this option is currently only supported for units that run within a mount - namespace (e.g.: with , , etc.). - Note that the namespace mentioned here, where the image mount will be added to, is the one where the main service - process runs, as other processes run in distinct namespaces (e.g.: , - , etc.). Example: + Mounts an image from the host into the specified unit's mount namespace. The first + path argument is the source image on the host, the second path argument is the destination + directory in the unit's mount namespace (i.e. inside + /). The following argument, if any, is + interpreted as a colon-separated tuple of partition name and comma-separated list of mount options + for that partition. The format is the same as the service + setting. When combined with the switch, a ready-only mount is + created. When combined with the switch, the destination path is first + created before the mount is applied. + + Note that this option is currently only supported for units that run within a mount namespace + (i.e. with , , etc.). Note that the + namespace mentioned here where the image mount will be added to, is the one where the main service + process runs. Note that the namespace mentioned here, where the bind mount will be + added to, is the one where the main service process runs. Other processes (those exececuted by + , , etc.) run in distinct namespaces. + + + Example: systemctl mount-image foo.service /tmp/img.raw /var/lib/image root:ro,nosuid - systemctl mount-image --mkdir bar.service /tmp/img.raw /var/lib/baz/img + systemctl mount-image --mkdir bar.service /tmp/img.raw /var/lib/baz/img + @@ -2185,9 +2209,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - When used with status, controls the number of journal lines to show, counting from - the most recent ones. Takes a positive integer argument, or 0 to disable journal output. Defaults to - 10. + When used with status, controls the number of journal lines to show, + counting from the most recent ones. Takes a positive integer argument, or 0 to disable journal + output. Defaults to 10. @@ -2208,8 +2232,9 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - When used with the reboot command, indicate to the system's firmware to reboot into - the firmware setup interface. Note that this functionality is not available on all systems. + When used with the reboot command, indicate to the system's firmware to + reboot into the firmware setup interface. Note that this functionality is not available on all + systems. @@ -2217,10 +2242,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - When used with the reboot command, indicate to the system's boot loader to show the - boot loader menu on the following boot. Takes a time value as parameter — indicating the menu timeout. Pass - zero in order to disable the menu timeout. Note that not all boot loaders support this - functionality. + When used with the reboot command, indicate to the system's boot loader to + show the boot loader menu on the following boot. Takes a time value as parameter — indicating the + menu timeout. Pass zero in order to disable the menu timeout. Note that not all boot loaders + support this functionality. @@ -2228,10 +2253,10 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - When used with the reboot command, indicate to the system's boot loader to boot into - a specific boot loader entry on the following boot. Takes a boot loader entry identifier as argument, or - help in order to list available entries. Note that not all boot loaders support this - functionality. + When used with the reboot command, indicate to the system's boot loader to + boot into a specific boot loader entry on the following boot. Takes a boot loader entry identifier + as argument, or help in order to list available entries. Note that not all boot + loaders support this functionality.