system/systemd
system/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd synced 2024-07-21 18:24:38 +00:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Merge pull request #30607 from dtardon/docbook-improvements

Browse source 
Minor improvements to man pages
This commit is contained in:
Yu Watanabe 2023-12-25 19:34:55 +09:00 committed by GitHub
parent 0a0f49556f 8f39acd005
commit c6f7c8acd9
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
9 changed files with 80 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
man/cgroup-sandboxing.xml
View file

@ -12,6 +12,6 @@
in the service unit, as it applies to the whole control group.</para>
<para id="plural">These options cannot be bypassed by prefixing <literal>+</literal> to the executable path
in the service unit, as it applies to the whole control group.</para>
in the service unit, as they apply to the whole control group.</para>
</refsect1>

16
man/crypttab.xml
View file

@ -458,10 +458,12 @@
<citerefentry project='man-pages'><refentrytitle>mkswap</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
This option implies <option>plain</option>.</para>
<para>WARNING: Using the <option>swap</option> option will
destroy the contents of the named partition during every boot,
so make sure the underlying block device is specified
correctly.</para>
<warning>
<para>Using the <option>swap</option> option will
destroy the contents of the named partition during every boot,
so make sure the underlying block device is specified
correctly.</para>
</warning>
<xi:include href="version-info.xml" xpointer="v186"/></listitem>
</varlistentry>
@ -591,8 +593,10 @@
<literal>btrfs</literal>. If no argument is specified defaults to <literal>ext4</literal>. This
option implies <option>plain</option>.</para>
<para>WARNING: Using the <option>tmp</option> option will destroy the contents of the named partition
during every boot, so make sure the underlying block device is specified correctly.</para>
<warning>
<para>Using the <option>tmp</option> option will destroy the contents of the named partition
during every boot, so make sure the underlying block device is specified correctly.</para>
</warning>
<xi:include href="version-info.xml" xpointer="v186"/></listitem>
</varlistentry>

2
man/sd_bus_message_append.xml
View file

@ -95,7 +95,7 @@
<title>Item type specifiers</title>
<tgroup cols='5'>
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers'])//colspec" />
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//colspec)" />
<xi:include href="sd_bus_message_append_basic.xml" xpointer="xpointer(//table[@id='format-specifiers']//thead)" />
<tbody>

14
man/systemctl.xml
View file

@ -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 <option>--force</option> is specified
twice for these operations (with the exception of <command>kexec</command>), they will be executed
immediately, without terminating any processes or unmounting any file systems. Warning: specifying
<option>--force</option> twice with any of these operations might result in data loss. Note that when
<option>--force</option> is specified twice the selected operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
succeed even when the system manager has crashed.</para>
immediately, without terminating any processes or unmounting any file systems.</para>
<warning>
<para>Specifying
<option>--force</option> twice with any of these operations might result in data loss. Note that when
<option>--force</option> is specified twice the selected operation is executed by
<command>systemctl</command> itself, and the system manager is not contacted. This means the command should
succeed even when the system manager has crashed.</para>
</warning>
</listitem>
</varlistentry>

8
man/systemd-storagetm.service.xml
View file

@ -39,9 +39,11 @@
NVMe-TCP mass storage devices. Its primary use-case is to be invoked by the
<filename>storage-target-mode.target</filename> unit that can be booted into.</para>
<para>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.</para>
<warning>
<para>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.</para>
</warning>
<para>Note that to function properly networking must be configured too. The recommended mechanism to boot
into a storage target mode is by adding <literal>rd.systemd.unit=storage-target-mode.target

16
man/systemd.network.xml
View file

@ -1342,13 +1342,15 @@ Table=1234</programlisting></para>
Fallback Peer Labeling</ulink> rules. They will be removed when the interface is
deconfigured. Failures to manage the labels will be ignored.</para>
<para>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 <citerefentry
project='man-pages'><refentrytitle>netlabelctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is needed.</para>
<warning>
<para>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 <citerefentry
project='man-pages'><refentrytitle>netlabelctl</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is needed.</para>
</warning>
<para>Example:
<programlisting>[Address]

24
man/systemd.unit.xml
View file

@ -25,17 +25,19 @@
</refnamediv>
<refsynopsisdiv>
<para><filename><replaceable>service</replaceable>.service</filename>,
<filename><replaceable>socket</replaceable>.socket</filename>,
<filename><replaceable>device</replaceable>.device</filename>,
<filename><replaceable>mount</replaceable>.mount</filename>,
<filename><replaceable>automount</replaceable>.automount</filename>,
<filename><replaceable>swap</replaceable>.swap</filename>,
<filename><replaceable>target</replaceable>.target</filename>,
<filename><replaceable>path</replaceable>.path</filename>,
<filename><replaceable>timer</replaceable>.timer</filename>,
<filename><replaceable>slice</replaceable>.slice</filename>,
<filename><replaceable>scope</replaceable>.scope</filename></para>
<para><simplelist type="inline">
<member><filename><replaceable>service</replaceable>.service</filename></member>
<member><filename><replaceable>socket</replaceable>.socket</filename></member>
<member><filename><replaceable>device</replaceable>.device</filename></member>
<member><filename><replaceable>mount</replaceable>.mount</filename></member>
<member><filename><replaceable>automount</replaceable>.automount</filename></member>
<member><filename><replaceable>swap</replaceable>.swap</filename></member>
<member><filename><replaceable>target</replaceable>.target</filename></member>
<member><filename><replaceable>path</replaceable>.path</filename></member>
<member><filename><replaceable>timer</replaceable>.timer</filename></member>
<member><filename><replaceable>slice</replaceable>.slice</filename></member>
<member><filename><replaceable>scope</replaceable>.scope</filename></member>
</simplelist></para>
<refsect2>
<title>System Unit Search Path</title>

18
man/udevadm.xml
View file

@ -550,14 +550,16 @@
<para>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.</para>
<para>WARNING: <option>--initialized-nomatch</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.
<literal>ATTRS</literal> or <literal>IMPORT{parent}</literal> keys, see
<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details), the final state of the device becomes easily unstable with this option.
</para>
<warning>
<para><option>--initialized-nomatch</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.
<literal>ATTRS</literal> or <literal>IMPORT{parent}</literal> keys, see
<citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>
for more details), the final state of the device becomes easily unstable with this option.
</para>
</warning>
<xi:include href="version-info.xml" xpointer="v251"/>
</listitem>

42
man/veritytab.xml
View file

@ -41,19 +41,19 @@ This is based on crypttab(5).
verity protected block device. Fields are delimited by
white space.</para>
<para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>data-device</replaceable> <replaceable>hash-device</replaceable> <replaceable>roothash</replaceable> <replaceable>options</replaceable></programlisting>
<para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>data-device</replaceable> <replaceable>hash-device</replaceable> <replaceable>roothash</replaceable> <optional><replaceable>options</replaceable></optional></programlisting>
The first four fields are mandatory, the remaining one is optional.</para>
<para>The first field contains the name of the resulting verity volume; its block device is set up
below <filename>/dev/mapper/</filename>.</para>
<para>The second field contains a path to the underlying block data device, or a specification of a block device via
<literal>UUID=</literal> followed by the UUID.</para>
<varname>UUID=</varname> followed by the <replaceable>UUID</replaceable>.</para>
<para>The third field contains a path to the underlying block hash device, or a specification of a block device via
<literal>UUID=</literal> followed by the UUID.</para>
<varname>UUID=</varname> followed by the <replaceable>UUID</replaceable>.</para>
<para>The fourth field is the <literal>roothash</literal> in hexadecimal.</para>
<para>The fourth field is the <replaceable>roothash</replaceable> in hexadecimal.</para>
<para>The fifth field, if present, is a comma-delimited list of options. The following options are
recognized:</para>
@ -71,7 +71,7 @@ This is based on crypttab(5).
<varlistentry>
<term><option>format=<replaceable>NUMBER</replaceable></option></term>
<listitem><para>Specifies the hash version type. Format type 0 is original Chrome OS version. Format type 1 is
<listitem><para>Specifies the hash version type. Format type <literal>0</literal> is original Chrome OS version. Format type <literal>1</literal> is
modern version.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
@ -117,7 +117,7 @@ This is based on crypttab(5).
<term><option>salt=<replaceable>HEX</replaceable></option></term>
<listitem><para>Salt used for format or verification. Format is a hexadecimal string; 256 bytes long maximum;
<literal>-</literal>is the special value for empty.</para>
<literal>-</literal> is the special value for empty.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
@ -125,8 +125,8 @@ This is based on crypttab(5).
<varlistentry>
<term><option>uuid=<replaceable>UUID</replaceable></option></term>
<listitem><para>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.</para>
<listitem><para>Use the provided <replaceable>UUID</replaceable> for format command instead of generating new one. The <replaceable>UUID</replaceable> must be
provided in standard <acronym>UUID</acronym> format, e.g. <literal>12345678-1234-1234-1234-123456789abc</literal>.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
</varlistentry>
@ -137,9 +137,9 @@ This is based on crypttab(5).
<term><option>panic-on-corruption</option></term>
<listitem><para>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 <literal>--ignore-corruption</literal> option the
corruption is only logged. With <literal>--restart-on-corruption</literal> or
<literal>--panic-on-corruption</literal> the kernel is restarted (panicked) immediately.
options kernel fails the <acronym>IO</acronym> operation with <acronym>I/O</acronym> error. With <option>--ignore-corruption</option> option the
corruption is only logged. With <option>--restart-on-corruption</option> or
<option>--panic-on-corruption</option> the kernel is restarted (panicked) immediately.
(You have to provide way how to avoid restart loops.)</para>
@ -150,10 +150,11 @@ This is based on crypttab(5).
<term><option>ignore-zero-blocks</option></term>
<listitem><para>Instruct kernel to not verify blocks that are expected to contain zeroes and always directly
return zeroes instead.
return zeroes instead.</para>
WARNING: Use this option only in very specific cases. This option is available since Linux kernel version 4.5.
</para>
<warning>
<para>Use this option only in very specific cases. This option is available since Linux kernel version 4.5.</para>
</warning>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
@ -162,11 +163,12 @@ This is based on crypttab(5).
<term><option>check-at-most-once</option></term>
<listitem><para>Instruct kernel to verify blocks only the first time they are read from the data device, rather
than every time.
than every time.</para>
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.
</para>
<warning>
<para>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.</para>
</warning>
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
</varlistentry>
@ -183,7 +185,7 @@ This is based on crypttab(5).
<varlistentry>
<term><option>fec-device=<replaceable>PATH</replaceable></option></term>
<listitem><para>Use forward error correction (FEC) to recover from corruption if hash verification fails. Use
<listitem><para>Use forward error correction (<acronym>FEC</acronym>) 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.</para>
@ -194,7 +196,7 @@ This is based on crypttab(5).
<varlistentry>
<term><option>fec-offset=<replaceable>BYTES</replaceable></option></term>
<listitem><para>This is the offset, in bytes, from the start of the FEC device to the beginning of the encoding
<listitem><para>This is the offset, in bytes, from the start of the <acronym>FEC</acronym> device to the beginning of the encoding
data. (Aligned on 512 bytes.)</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>