<varlistentry>
<term><option>--random-seed=yes|no</option></term>
- <listitem><para>By default the <command>install</command> command initializes a random seed file in
+ <listitem><para>By default, the <command>install</command> command initializes a random seed file in
the ESP. When creating an image it may be desirable to disable that in order to avoid having the
same seed in all instances.</para>
<filename>os-release</filename> (e.g. <literal>vendorx-cashier-system</literal>).</para>
<para>If set to <option>auto</option> (the default), the <filename>/etc/kernel/entry-token</filename>
- file will be read if it exists, and the stored value used. Otherwise if the local machine ID is
- initialized it is used. Otherwise <varname>IMAGE_ID=</varname> from <filename>os-release</filename>
+ file will be read if it exists, and the stored value used. Otherwise, if the local machine ID is
+ initialized it is used. Otherwise, <varname>IMAGE_ID=</varname> from <filename>os-release</filename>
will be used, if set. Otherwise, <varname>ID=</varname> from <filename>os-release</filename> will be
used, if set.</para>
<para>Using the default entry name <literal>Linux Boot Manager</literal> is generally preferable as only
one bootloader installed to a single ESP partition should be used to boot any number of OS installations
found on the various disks installed in the system. Specifically distributions should not use this flag
- to install a branded entry in the boot option list. However in situations with multiple disks, each with
+ to install a branded entry in the boot option list. However, in situations with multiple disks, each with
their own ESP partition, it can be beneficial to make it easier to identify the bootloader being used in
the firmware's boot option menu.</para>
see above and below.</para></listitem>
<listitem><para>The key may be acquired via a PKCS#11 compatible hardware security token or
- smartcard. In this case a saved key used in unlock process is stored on disk/removable media, acquired via
+ smartcard. In this case, a saved key used in unlock process is stored on disk/removable media, acquired via
<constant>AF_UNIX</constant>, or stored in the LUKS2 JSON token metadata header. For RSA, the saved key
is an encrypted volume key. The encrypted volume key is then decrypted by the PKCS#11 token with an RSA
private key stored on it, and used to unlock the encrypted volume. For elliptic-curve (EC) cryptography,
</para></listitem>
<listitem><para>Similarly, the key may be acquired via a FIDO2 compatible hardware security token
- (which must implement the "hmac-secret" extension). In this case a key generated randomly during
+ (which must implement the "hmac-secret" extension). In this case, a key generated randomly during
enrollment is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in
the LUKS2 JSON token metadata header. The random key is hashed via a keyed hash function (HMAC) on the
FIDO2 token, using a secret key stored on the token that never leaves it. The resulting hash value is
then used as key to unlock the encrypted volume. Use the <option>fido2-device=</option> option
described below to use this mechanism.</para></listitem>
- <listitem><para>Similarly, the key may be acquired via a TPM2 security chip. In this case a (during
+ <listitem><para>Similarly, the key may be acquired via a TPM2 security chip. In this case, a (during
enrollment) randomly generated key — encrypted by an asymmetric key derived from the TPM2 chip's seed
key — is stored on disk/removable media, acquired via <constant>AF_UNIX</constant>, or stored in the
LUKS2 JSON token metadata header. Use the <option>tpm2-device=</option> option described below to use
<para>The specified URI can refer directly to a private key stored on a token or alternatively
just to a slot or token, in which case a search for a suitable private key will be performed. In
- this case if multiple suitable objects are found the token is refused. The keyfile configured
+ this case, if multiple suitable objects are found, the token is refused. The keyfile configured
in the third column of the line is used as is (i.e. in binary form, unprocessed). The resulting
decrypted key (for RSA) or derived shared secret (for ECC) is then Base64 encoded before it is used
to unlock the LUKS volume.</para>
<term><option>fido2-rp=</option></term>
<listitem><para>Takes a string, configuring the FIDO2 Relying Party (rp) for the FIDO2 unlock
- operation. If not specified <literal>io.systemd.cryptsetup</literal> is used, except if the LUKS2
+ operation. If not specified, <literal>io.systemd.cryptsetup</literal> is used, except if the LUKS2
JSON token header contains a different value. It should normally not be necessary to override
this.</para>
public key specified at key enrollment time can be provided. See
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for details on enrolling TPM2 PCR public keys. If this option is not specified but it is attempted to
- unlock a LUKS2 volume with a signed TPM2 PCR enrollment a suitable signature file
+ unlock a LUKS2 volume with a signed TPM2 PCR enrollment, a suitable signature file
<filename>tpm2-pcr-signature.json</filename> is searched for in <filename>/etc/systemd/</filename>,
<filename>/run/systemd/</filename>, <filename>/usr/lib/systemd/</filename> (in this
order).</para>
variants. See
<citerefentry><refentrytitle>systemd-cryptenroll</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for details on enrolling TPM2 pcrlock policies. If this option is not specified but it is attempted
- to unlock a LUKS2 volume with a TPM2 pcrlock enrollment a suitable signature file
+ to unlock a LUKS2 volume with a TPM2 pcrlock enrollment, a suitable signature file
<filename>pcrlock.json</filename> is searched for in <filename>/run/systemd/</filename> and
<filename>/var/lib/systemd/</filename> (in this order).</para>
<listitem><para>Selects one or more TPM2 PCR banks to measure the volume key into, as configured with
<option>tpm2-measure-pcr=</option> above. Multiple banks may be specified, separated by a colon
- character. If not specified automatically determines available and used banks. Expects a message
+ character. If not specified, automatically determines available and used banks. Expects a message
digest name (e.g. <literal>sha1</literal>, <literal>sha256</literal>, …) as argument, to identify the
bank.</para>
<listitem><para>Takes a path to use as home directory for the user. Note that this is the directory
the user's home directory is mounted to while the user is logged in. This is not where the user's
- data is actually stored, see <option>--image-path=</option> for that. If not specified defaults to
+ data is actually stored, see <option>--image-path=</option> for that. If not specified, defaults to
<filename>/home/$USER</filename>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<listitem><para>Takes a file system path to a directory. Specifies the skeleton directory to
initialize the home directory with. All files and directories in the specified path are copied into
- any newly create home directory. If not specified defaults to <filename>/etc/skel/</filename>.
+ any newly create home directory. If not specified, defaults to <filename>/etc/skel/</filename>.
</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<term><option>--shell=<replaceable>SHELL</replaceable></option></term>
<listitem><para>Takes a file system path. Specifies the shell binary to execute on terminal
- logins. If not specified defaults to <filename>/bin/bash</filename>.</para>
+ logins. If not specified, defaults to <filename>/bin/bash</filename>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
After this time passes logging in may only proceed after the password is changed.
<option>--password-change-warn=</option> specifies how much earlier than then the time configured
with <option>--password-change-max=</option> the user is warned at login to change their password as
- it will expire soon. Finally <option>--password-change-inactive=</option> configures the time which
+ it will expire soon. Finally, <option>--password-change-inactive=</option> configures the time which
has to pass after the password as expired until the user is not permitted to log in or change the
password anymore. Note that these options only apply to password authentication, and do not apply to
other forms of authentication, for example PKCS#11-based security token
loopback file system instead of immediately from a common pool like the other backends do it). In
regular intervals free disk space in the active home areas and their backing storage is redistributed
among them, taking the weight value configured here into account. Expects an integer in the range
- 1…10000, or the special string <literal>off</literal>. If not specified defaults to 100. The weight
+ 1…10000, or the special string <literal>off</literal>. If not specified, defaults to 100. The weight
is used to scale free space made available to the home areas: a home area with a weight of 200 will
get twice the free space as one with a weight of 100; a home area with a weight of 50 will get half
of that. The backing file system will be assigned space for a weight of 20. If set to
<term><option>--noexec=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Configures the <literal>nosuid</literal>, <literal>nodev</literal> and
- <literal>noexec</literal> mount options for the home directories. By default <literal>nodev</literal>
+ <literal>noexec</literal> mount options for the home directories. By default, <literal>nodev</literal>
and <literal>nosuid</literal> are on, while <literal>noexec</literal> is off. For details about these
mount options see <citerefentry
project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
directory/user account, as well as the file share ("service") to mount as directory. The latter is
used when <literal>cifs</literal> storage is selected. The file share should be specified in format
<literal>//<replaceable>host</replaceable>/<replaceable>share</replaceable>/<replaceable>directory/…</replaceable></literal>. The
- directory part is optional — if not specified the home directory will be placed in the top-level
+ directory part is optional — if not specified, the home directory will be placed in the top-level
directory of the share. The <option>--cifs-extra-mount-options=</option> setting allows specifying
additional mount options when mounting the share, see <citerefentry
project='man-pages'><refentrytitle>mount.cifs</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<citerefentry><refentrytitle>homectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>. If not
configured or assigned the empty string, the default storage is automatically determined: if not
running in a container environment and <filename>/home/</filename> is not itself encrypted, defaults
- to <literal>luks</literal>. Otherwise defaults to <literal>subvolume</literal> if
+ to <literal>luks</literal>. Otherwise, defaults to <literal>subvolume</literal> if
<filename>/home/</filename> is on a btrfs file system, and <literal>directory</literal>
otherwise. Note that the storage selected on the <command>homectl</command> command line always takes
precedence.</para>
<term><varname>DefaultFileSystemType=</varname></term>
<listitem><para>When using <literal>luks</literal> as storage (see above), selects the default file
system to use inside the user's LUKS volume. Takes one of <literal>btrfs</literal>,
- <literal>ext4</literal> or <literal>xfs</literal>. If not specified defaults to
+ <literal>ext4</literal> or <literal>xfs</literal>. If not specified, defaults to
<literal>btrfs</literal>. This setting has no effect if a different storage mechanism is used. The
file system type selected on the <command>homectl</command> command line always takes
precedence.</para>
<varlistentry>
<term><option>--namespace=<replaceable>NAMESPACE</replaceable></option></term>
- <listitem><para>Takes a journal namespace identifier string as argument. If not specified the data
- collected by the default namespace is shown. If specified shows the log data of the specified
+ <listitem><para>Takes a journal namespace identifier string as argument. If not specified, the data
+ collected by the default namespace is shown. If specified, shows the log data of the specified
namespace instead. If the namespace is specified as <literal>*</literal> data from all namespaces is
shown, interleaved. If the namespace identifier is prefixed with <literal>+</literal> data from the
specified namespace and the default namespace is shown, interleaved, but no other. For details about
<term><option>--cursor-file=<replaceable>FILE</replaceable></option></term>
<listitem><para>If <replaceable>FILE</replaceable> exists and contains a cursor, start showing
- entries <emphasis>after</emphasis> this location. Otherwise show entries according to the other
+ entries <emphasis>after</emphasis> this location. Otherwise, show entries according to the other
given options. At the end, write the cursor of the last entry to
<replaceable>FILE</replaceable>. Use this option to continually read the journal by sequentially
calling <command>journalctl</command>.</para>
<para>Note that this option does not control whether <command>systemd-journald</command> collects
generated audit records, it just controls whether it tells the kernel to generate them. If you need
to prevent <command>systemd-journald</command> from collecting the generated messages, the socket
- unit <literal>systemd-journald-audit.socket</literal> can be disabled and in this case this setting
+ unit <literal>systemd-journald-audit.socket</literal> can be disabled and, in this case, this setting
is without effect.</para>
<xi:include href="version-info.xml" xpointer="v246"/>
the special value <literal>state</literal>. If false (the default), normal boot mode is selected, the root
directory and <filename>/var/</filename> are mounted as specified on the kernel command line or
<filename>/etc/fstab</filename>, or otherwise configured. If true, full state-less boot mode is selected. In
- this case the root directory is mounted as volatile memory file system (<literal>tmpfs</literal>), and only
+ this case, the root directory is mounted as volatile memory file system (<literal>tmpfs</literal>), and only
<filename>/usr/</filename> is mounted from the file system configured as root device, in read-only mode. This
enables fully state-less boots were the vendor-supplied OS is used as shipped, with only default
configuration and no stored state in effect, as <filename>/etc/</filename> and <filename>/var/</filename> (as
<para>If <varname>root=</varname> is not set (or set to <literal>gpt-auto</literal>) the automatic
root partition discovery implemented by
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
- will be in effect. In this case <varname>rootfstype=</varname>, <varname>rootflags=</varname>,
+ will be in effect. In this case, <varname>rootfstype=</varname>, <varname>rootflags=</varname>,
<varname>ro</varname>, <varname>rw</varname> will be interpreted by
<command>systemd-gpt-auto-generator</command>.</para>
<para>If set to <option>auto</option> (the default), the
<filename>/etc/kernel/entry-token</filename> (or
<filename>$KERNEL_INSTALL_CONF_ROOT/entry-token</filename>) file will be read if it exists, and the
- stored value used. Otherwise if the local machine ID is initialized it is used. Otherwise
+ stored value used. Otherwise, if the local machine ID is initialized, it is used. Otherwise,
<varname>IMAGE_ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise,
- <varname>ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise a
+ <varname>ID=</varname> from <filename>os-release</filename> will be used, if set. Otherwise, a
randomly generated machine ID is used.</para>
<para>Using the machine ID for naming the entries is generally preferable, however there are cases
<para>Note that while <varname>$KERNEL_INSTALL_ENTRY_TOKEN</varname> and
<varname>$KERNEL_INSTALL_MACHINE_ID</varname> are often set to the same value, the latter is guaranteed
to be a valid 32 character ID in lowercase hexadecimals while the former can be any short string. The
- entry token to use is read from <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise a
+ entry token to use is read from <filename>/etc/kernel/entry-token</filename>, if it exists. Otherwise, a
few possible candidates below <varname>$BOOT</varname> are checked for Boot Loader Specification Type 1
entry directories, and if found the entry token is derived from that. If that is not successful,
<varname>$KERNEL_INSTALL_MACHINE_ID</varname> is used as fallback.</para>
if (r < 0)
return log_error(o.log_level, r, "sd_bus_add_object_vtable()");
- /* By default the service is assigned an ephemeral name. Also add a fixed
+ /* By default, the service is assigned an ephemeral name. Also add a fixed
* one, so that clients know whom to call.
* https://www.freedesktop.org/software/systemd/man/sd_bus_request_name.html
*/
<listitem>
<para>Show discovered LLDP (Link Layer Discovery Protocol) neighbors. If one or more
<replaceable>PATTERN</replaceable>s are specified only neighbors on those interfaces are shown.
- Otherwise shows discovered neighbors on all interfaces. Note that for this feature to work,
+ Otherwise, shows discovered neighbors on all interfaces. Note that for this feature to work,
<varname>LLDP=</varname> must be turned on for the specific interface, see
<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
details.</para>
drop-in directories are created and populated in one go.</para>
<para>Multiple drop-ins may be "edited" in this mode with <option>--drop-in=</option>, and
- the same contents will be written to all of them. Otherwise exactly one main configuration file
+ the same contents will be written to all of them. Otherwise, exactly one main configuration file
is expected.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
hence where the data was found.</para>
<para>The primary use cases for these five flags are follow-up look-ups based on DNS data retrieved
- earlier. In this case it is often a good idea to limit the follow-up look-up to the protocol that was
+ earlier. In this case, it is often a good idea to limit the follow-up look-up to the protocol that was
used to discover the first DNS result.</para>
<para>The NO_CNAME flag controls whether CNAME/DNAME resource records shall be followed during the
each non-existence proof. The secure counter is increased for each operation that successfully verified
a signed reply, the insecure counter is increased for each operation that successfully verified that an
unsigned reply is rightfully unsigned. The bogus counter is increased for each operation where the
- validation did not check out and the data is likely to have been tempered with. Finally the
+ validation did not check out and the data is likely to have been tempered with. Finally, the
indeterminate counter is increased for each operation which did not complete because the necessary keys
could not be acquired or the cryptographic algorithms were unknown.</para>
for details on the capabilities concept. If not specified, the default bounding set is left as is
(i.e. usually contains the full set of capabilities). The default ambient set is set to
<constant>CAP_WAKE_ALARM</constant> for regular users if the PAM session is associated with a local
- seat or if it is invoked for the <literal>systemd-user</literal> service. Otherwise defaults to the
+ seat or if it is invoked for the <literal>systemd-user</literal> service. Otherwise, defaults to the
empty set.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
<filename>/run/portables/</filename>, to make sure it is included in it.</para></listitem>
</orderedlist>
- <para>By default all unit files whose names start with a prefix generated from the image's file name are copied
+ <para>By default, all unit files whose names start with a prefix generated from the image's file name are copied
out. Specifically, the prefix is determined from the image file name with any suffix such as
<filename>.raw</filename> removed, truncated at the first occurrence of an underscore character
(<literal>_</literal>), if there is one. The underscore logic is supposed to be used to versioning so that the
<listitem><para>Extracts various metadata from a portable service image and presents it to the
caller. Specifically, the
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file of the
- image is retrieved as well as all matching unit files. By default a short summary showing the most relevant
+ image is retrieved as well as all matching unit files. By default, a short summary showing the most relevant
metadata in combination with a list of matching unit files is shown (that is the unit files
<command>attach</command> would install to the host system). If combined with <option>--cat</option> (see
above), the <filename>os-release</filename> data and the units files' contents is displayed unprocessed. This
<term><option>-p</option> <replaceable>PROFILE</replaceable></term>
<term><option>--profile=<replaceable>PROFILE</replaceable></option></term>
- <listitem><para>When attaching an image, select the profile to use. By default the <literal>default</literal>
+ <listitem><para>When attaching an image, select the profile to use. By default, the <literal>default</literal>
profile is used. For details about profiles, see below.</para>
<xi:include href="version-info.xml" xpointer="v239"/></listitem>
no matching partition file are left as they are.</para>
<para>Note that these definitions may only be used to create and initialize new partitions or to grow
- existing ones. In the latter case it will not grow the contained files systems however; separate
+ existing ones. In the latter case, it will not grow the contained files systems however; separate
mechanisms, such as
<citerefentry><refentrytitle>systemd-growfs</refentrytitle><manvolnum>8</manvolnum></citerefentry> may be
used to grow the file systems inside of these partitions. Partitions may also be marked for automatic
<listitem><para>The textual label to assign to the partition if none is assigned yet. Note that this
setting is not used for matching. It is also not used when a label is already set for an existing
partition. It is thus only used when a partition is newly created or when an existing one had a no
- label set (that is: an empty label). If not specified a label derived from the partition type is
+ label set (that is: an empty label). If not specified, a label derived from the partition type is
automatically used. Simple specifier expansion is supported, see below.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<varname>SizeMaxBytes=</varname>) otherwise. If the backing device does not provide enough space to
fulfill the constraints placing the partition will fail. For partitions that shall be created,
depending on the setting of <varname>Priority=</varname> (see above) the partition might be dropped
- and the placing algorithm restarted. By default a minimum size constraint of 10M and no maximum size
+ and the placing algorithm restarted. By default, a minimum size constraint of 10M and no maximum size
constraint is set.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<listitem><para>Specifies minimum and maximum size constraints in bytes for the free space after the
partition (the "padding"). Semantics are similar to <varname>SizeMinBytes=</varname> and
<varname>SizeMaxBytes=</varname>, except that unlike partition sizes free space can be shrunk and can
- be as small as zero. By default no size constraints on padding are set, so that only
+ be as small as zero. By default, no size constraints on padding are set, so that only
<varname>PaddingWeight=</varname> determines the size of the padding applied.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<term><varname>Flags=</varname></term>
<listitem><para>Configures the 64-bit GPT partition flags field to set for the partition when creating
- it. This option has no effect if the partition already exists. If not specified the flags values is
+ it. This option has no effect if the partition already exists. If not specified, the flags value is
set to all zeroes, except for the three bits that can also be configured via
<varname>NoAuto=</varname>, <varname>ReadOnly=</varname> and <varname>GrowFileSystem=</varname>; see
below for details on the defaults for these three flags. Specify the flags value in hexadecimal (by
<para>The program's output contains information about the protocol used for the look-up and on which network
interface the data was discovered. It also contains information on whether the information could be
- authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover all data
+ authenticated. All data for which local DNSSEC validation succeeds is considered authenticated. Moreover, all data
originating from local, trusted sources is also reported authenticated, including resolution of the local host
name, the <literal>localhost</literal> hostname or all data from <filename>/etc/hosts</filename>.</para>
</refsect1>
<ulink url="https://tools.ietf.org/html/rfc2782">RFC 2782 SRV</ulink> services, depending on the
specified list of parameters. If three parameters are passed the first is assumed to be the DNS-SD
service name, the second the <constant class='dns'>SRV</constant> service type, and the third the
- domain to search in. In this case a full DNS-SD style <constant class='dns'>SRV</constant> and
+ domain to search in. In this case, a full DNS-SD style <constant class='dns'>SRV</constant> and
<constant class='dns'>TXT</constant> lookup is executed. If only two parameters are specified, the
first is assumed to be the <constant class='dns'>SRV</constant> service type, and the second the
- domain to look in. In this case no <constant class='dns'>TXT</constant> resource record is requested.
+ domain to look in. In this case, no <constant class='dns'>TXT</constant> resource record is requested.
Finally, if only one parameter is specified, it is assumed to be a domain name, that is already
prefixed with an <constant class='dns'>SRV</constant> type, and an <constant
class='dns'>SRV</constant> lookup is done (no <constant class='dns'>TXT</constant>).</para>
<literal>llmnr-ipv4</literal>, <literal>llmnr-ipv6</literal> (LLMNR via the indicated underlying IP
protocols), <literal>mdns</literal> (<ulink url="https://www.ietf.org/rfc/rfc6762.txt">Multicast DNS</ulink>),
<literal>mdns-ipv4</literal>, <literal>mdns-ipv6</literal> (MDNS via the indicated underlying IP protocols).
- By default the lookup is done via all protocols suitable for the lookup. If used, limits the set of
+ By default, the lookup is done via all protocols suitable for the lookup. If used, limits the set of
protocols that may be used. Use this option multiple times to enable resolving via multiple protocols at the
same time. The setting <literal>llmnr</literal> is identical to specifying this switch once with
<literal>llmnr-ipv4</literal> and once via <literal>llmnr-ipv6</literal>. Note that this option does not force
returned data could not be verified (either because the data
was found unsigned in the DNS, or the DNS server did not
support DNSSEC or no appropriate trust anchors were known). In
- the latter case it is assumed that client programs employ a
+ the latter case, it is assumed that client programs employ a
secondary scheme to validate the returned DNS data, should
this be required.</para>
<listitem><para>Set a shell prompt prefix string. This ultimately controls the
<varname>$SHELL_PROMPT_PREFIX</varname> environment variable for the invoked program, which is
- typically imported into the shell prompt. By default – if emojis are supported – a superhero emoji is
+ typically imported into the shell prompt. By default – if emojis are supported –, a superhero emoji is
shown (🦸). This default may also be changed (or turned off) by passing the
<varname>$SYSTEMD_RUN_SHELL_PROMPT_PREFIX</varname> environment variable to <varname>run0</varname>,
see below. Set to an empty string to disable shell prompt prefixing.</para>
<varlistentry>
<term><varname>$SHELL_PROMPT_PREFIX</varname></term>
- <listitem><para>By default set to the superhero emoji (if supported), but may be overridden with the
+ <listitem><para>By default, set to the superhero emoji (if supported), but may be overridden with the
<varname>$SYSTEMD_RUN_SHELL_PROMPT_PREFIX</varname> environment variable (see below), or the
<option>--shell-prompt-prefix=</option> switch (see above).</para>
<para>If an error occurs during the callback invocation, the callback should return a negative error number
(optionally, a more precise error may be returned in <parameter>ret_error</parameter>, as well). If it wants other
- callbacks that match the same rule to be called, it should return 0. Otherwise it should return a positive integer.
+ callbacks that match the same rule to be called, it should return 0. Otherwise, it should return a positive integer.
</para>
<para>If the <parameter>bus</parameter> refers to a direct connection (i.e. not a bus connection, as set with
will be automatically read and processed, and outgoing messages written, whenever the event loop is run. When the
event loop is about to terminate, the bus connection is automatically flushed and closed (see
<citerefentry><refentrytitle>sd_bus_set_close_on_exit</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
- details on this). By default bus connection objects are not attached to any event loop. When a bus connection
+ details on this). By default, bus connection objects are not attached to any event loop. When a bus connection
object is attached to one it is not necessary to invoke
<citerefentry><refentrytitle>sd_bus_wait</refentrytitle><manvolnum>3</manvolnum></citerefentry> or
<citerefentry><refentrytitle>sd_bus_process</refentrytitle><manvolnum>3</manvolnum></citerefentry> as this
o);
if (r < 0)
return log_error(r, "sd_bus_add_object_vtable()");
- /* By default the service is only assigned an ephemeral name. Also add a
+ /* By default, the service is only assigned an ephemeral name. Also add a
* well-known one, so that clients know whom to call. This needs to be
* asynchronous, as D-Bus might not be yet available. The callback will check
* whether the error is expected or not, in case it fails.
if (r < 0)
return log_error(r, "sd_event_default()");
- /* By default the event loop will terminate when all sources have disappeared,
+ /* By default, the event loop will terminate when all sources have disappeared,
* so we have to keep it 'occupied'. Register signal handling to do so.
* https://www.freedesktop.org/software/systemd/man/sd_event_add_signal.html
*/
<citerefentry><refentrytitle>sd-event</refentrytitle><manvolnum>3</manvolnum></citerefentry>
event loop, see
<citerefentry><refentrytitle>sd_bus_attach_event</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
- By default this mechanism is enabled and makes sure that any pending messages that have not been
+ By default, this mechanism is enabled and makes sure that any pending messages that have not been
written to the bus connection are written out when the event loop is shutting down. In some
cases this behaviour is not desirable, for example when the bus connection shall remain usable
until after the event loop exited. If <parameter>b</parameter> is true, the feature is enabled
that are sent on the connection and have no sender set yet, for example through
<citerefentry><refentrytitle>sd_bus_message_set_sender</refentrytitle><manvolnum>3</manvolnum></citerefentry>. Note
that this function is only supported on direct connections, i.e. not on connections to a bus broker as the broker
- will fill in the sender service name automatically anyway. By default no sender name is configured, and hence
+ will fill in the sender service name automatically anyway. By default, no sender name is configured, and hence
messages are sent without sender field set. If the <parameter>name</parameter> parameter is specified as
<constant>NULL</constant> the default sender service name is cleared, returning to the default state if a default
sender service name was set before. If passed as non-<constant>NULL</constant> the specified name must be a valid
irrelevant and the tracking of the specific peer is immediately
removed. <function>sd_bus_track_get_recursive()</function> may be used to determine whether the bus peer tracking
object is operating in recursive mode. <function>sd_bus_track_set_recursive()</function> may be used to enable or
- disable recursive mode. By default a bus peer tracking object operates in non-recursive mode, and
+ disable recursive mode. By default, a bus peer tracking object operates in non-recursive mode, and
<function>sd_bus_track_get_recursive()</function> for a newly allocated object hence returns a value equal to
zero. Use <function>sd_bus_track_set_recursive()</function> to enable recursive mode, right after allocation. It
takes a boolean argument to enable or disable recursive mode. Note that tracking objects for which
project='man-pages'><refentrytitle>pthread_sigmask</refentrytitle><manvolnum>3</manvolnum></citerefentry>).</para>
<para>If the second parameter of <function>sd_event_add_child()</function> is passed as
- <constant>NULL</constant> no reference to the event source object is returned. In this case the event
+ <constant>NULL</constant> no reference to the event source object is returned. In this case, the event
source is considered "floating", and will be destroyed implicitly when the event loop itself is
destroyed.</para>
<para><function>sd_event_source_get_child_pidfd_own()</function> may be used to query whether the pidfd
the event source encapsulates shall be closed when the event source is freed. This function returns zero
- if the pidfd shall be left open, and positive if it shall be closed automatically. By default this
+ if the pidfd shall be left open, and positive if it shall be closed automatically. By default, this
setting defaults to on if the event source was allocated via <function>sd_event_add_child()</function>
and off if it was allocated via <function>sd_event_add_child_pidfd()</function>. The
<function>sd_event_source_set_child_pidfd_own()</function> function may be used to change the setting and
<para><function>sd_event_source_get_child_process_own()</function> may be used to query whether the
process the event source watches shall be killed (with <constant>SIGKILL</constant>) and reaped when the
event source is freed. This function returns zero if the process shell be left running, and positive if
- it shall be killed and reaped automatically. By default this setting defaults to off. The
+ it shall be killed and reaped automatically. By default, this setting defaults to off. The
<function>sd_event_source_set_child_process_own()</function> function may be used to change the setting
and takes a boolean parameter with the new setting. Note that currently if the calling process is
terminated abnormally the watched process might survive even thought the event source ceases to
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the second parameter of these functions is passed as <constant>NULL</constant> no reference to
- the event source object is returned. In this case the event source is considered "floating", and will be
+ the event source object is returned. In this case, the event source is considered "floating", and will be
destroyed implicitly when the event loop itself is destroyed.</para>
<para>If the <parameter>handler</parameter> parameter to <function>sd_event_add_defer()</function> or
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para>
<para>If the second parameter of <function>sd_event_add_inotify()</function> is passed as
- <constant>NULL</constant> no reference to the event source object is returned. In this case the event
+ <constant>NULL</constant> no reference to the event source object is returned. In this case, the event
source is considered "floating", and will be destroyed implicitly when the event loop itself is
destroyed.</para>
<para>If the second parameter of
<function>sd_event_add_io()</function> is
<constant>NULL</constant> no reference to the event source object
- is returned. In this case the event source is considered
+ is returned. In this case, the event source is considered
"floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
event source shall take ownership of the file descriptor. Takes a boolean parameter
<parameter>b</parameter>. When true (nonzero), the file descriptor will be closed automatically when the
event source is freed or when the file descriptor is replaced by
- <function>sd_event_source_set_io_fd()</function>. By default the descriptor is not owned by the event
+ <function>sd_event_source_set_io_fd()</function>. By default, the descriptor is not owned by the event
source, and the application has to do close it on its own if needed.</para>
<para><function>sd_event_source_get_io_fd_own()</function> may be used to query the current setting of the file
with <constant>SD_EVENT_OFF</constant>.</para>
<para>If the second parameter of <function>sd_event_add_memory_pressure()</function> is
- <constant>NULL</constant> no reference to the event source object is returned. In this case the event
+ <constant>NULL</constant> no reference to the event source object is returned. In this case, the event
source is considered "floating", and will be destroyed implicitly when the event loop itself is
destroyed.</para>
<para>If the second parameter of
<function>sd_event_add_signal()</function> is
<constant>NULL</constant> no reference to the event source object
- is returned. In this case the event source is considered
+ is returned. In this case, the event source is considered
"floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
<para>If the second parameter of
<function>sd_event_add_time()</function> is
<constant>NULL</constant> no reference to the event source object
- is returned. In this case the event source is considered
+ is returned. In this case, the event source is considered
"floating", and will be destroyed implicitly when the event loop
itself is destroyed.</para>
base the <parameter>usec</parameter> parameter passed to the timer
callback, or the timestamp returned by
<function>sd_event_now()</function>. In the former case timer
- events will be regular, while in the latter case the scheduling
+ events will be regular, while in the latter case, the scheduling
latency will keep accumulating on the timer.</para>
<para><function>sd_event_source_get_time()</function> retrieves the configured time value of an event
<para>If the parameter <parameter>b</parameter> is specified as true, the event loop will terminate on
<constant>SIGINT</constant> and <constant>SIGTERM</constant>. If specified as false, it will no
longer. When this functionality is turned off the calling thread's signal mask is restored to match the
- state before it was turned on, for the two signals. By default the two signals are not handled by the
+ state before it was turned on, for the two signals. By default, the two signals are not handled by the
event loop, and Linux' default signal handling for them is in effect.</para>
<para>It is customary for UNIX programs to exit on either of these two signals, hence it is typically a
dispatched more often than the specified burst within the specified interval it is placed in a mode
similar to being disabled with
<citerefentry><refentrytitle>sd_event_source_set_enabled</refentrytitle><manvolnum>3</manvolnum></citerefentry>
- and the <constant>SD_EVENT_OFF</constant> parameter. However it is disabled only temporarily – once the
+ and the <constant>SD_EVENT_OFF</constant> parameter. However, it is disabled only temporarily – once the
specified interval is over regular operation resumes. It is again disabled temporarily once the specified rate
limiting is hit the next time. If either the interval or the burst value are specified as zero, rate
- limiting is turned off. By default event sources do not have rate limiting enabled. Note that rate
+ limiting is turned off. By default, event sources do not have rate limiting enabled. Note that rate
limiting and disabling via <function>sd_event_source_set_enabled()</function> are independent of each
other, and an event source will only effect event loop wake-ups and is dispatched while it both is
enabled and rate limiting is not in effect.</para>
invocation.</para></listitem>
<listitem><para>If <constant>SD_JOURNAL_APPEND</constant> is returned, new entries have been appended to the end
- of the journal. In this case it is sufficient to simply continue reading at the previous end location of the
+ of the journal. In this case, it is sufficient to simply continue reading at the previous end location of the
journal, to read the newly added entries.</para></listitem>
<listitem><para>If <constant>SD_JOURNAL_INVALIDATE</constant>, journal files were added to or removed from the
<para><function>sd_journal_has_runtime_files()</function> returns a positive value
if runtime journal files (present in /run/systemd/journal/) have been found.
- Otherwise returns 0.</para>
+ Otherwise, returns 0.</para>
<para><function>sd_journal_has_persistent_files()</function> returns a positive value
if persistent journal files (present in /var/log/journal/) have been found.
- Otherwise returns 0.</para>
+ Otherwise, returns 0.</para>
</refsect1>
<refsect1>
<listitem><para>Takes an image policy string as argument, as per
<citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
policy is enforced when operating on the disk image specified via <option>--image=</option>, see
- above. If not specified defaults to the <literal>*</literal> policy, i.e. all recognized file systems
+ above. If not specified, defaults to the <literal>*</literal> policy, i.e. all recognized file systems
in the image are used.</para></listitem>
</varlistentry>
<listitem>
<para>List units that <command>systemd</command> currently has in memory. This includes units that are
either referenced directly or through a dependency, units that are pinned by applications programmatically,
- or units that were active in the past and have failed. By default only units which are active, have pending
+ or units that were active in the past and have failed. By default, only units which are active, have pending
jobs, or have failed are shown; this can be changed with option <option>--all</option>. If one or more
<replaceable>PATTERN</replaceable>s are specified, only units matching one of them are shown. The units
that are shown are additionally filtered by <option>--type=</option> and <option>--state=</option> if those
</row>
<row>
<entry><literal>bad</literal></entry>
- <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However the unit file listing printed by <command>list-unit-files</command> might show it.</entry>
+ <entry>The unit file is invalid or another error occurred. Note that <command>is-enabled</command> will not actually return this state, but print an error message instead. However, the unit file listing printed by <command>list-unit-files</command> might show it.</entry>
<entry>> 0</entry>
</row>
<row>
<title>Description</title>
<para><command>systemd-ac-power</command> may be used to check whether the system
- is running on AC power or not. By default it will simply return success (if we
+ is running on AC power or not. By default, it will simply return success (if we
can detect that we are running on AC power) or failure, with no output.
This can be useful for example to debug <varname>ConditionACPower=</varname> (see
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>).</para>
<varlistentry>
<term><option>--low</option></term>
- <listitem><para>Instead of showing AC power state, show low battery state. In this case will return
+ <listitem><para>Instead of showing AC power state, show low battery state. In this case, will return
zero if all batteries are currently discharging and below 5% of maximum charge. Returns non-zero
otherwise.</para>
<command>blame</command> command, this only takes into account the time units spent in
<literal>activating</literal> state, and hence does not cover units that never went through an
<literal>activating</literal> state (such as device units that transition directly from
- <literal>inactive</literal> to <literal>active</literal>). Moreover it does not show information on
+ <literal>inactive</literal> to <literal>active</literal>). Moreover, it does not show information on
jobs (and in particular not jobs that timed out).</para>
<example>
<para>This command has two distinct modes of operation, depending on whether the operator
<replaceable>OP</replaceable> is specified.</para>
- <para>In the first mode — when <replaceable>OP</replaceable> is not specified — it will compare the two
+ <para>In the first mode — when <replaceable>OP</replaceable> is not specified —, it will compare the two
version strings and print either <literal><replaceable>VERSION1</replaceable> <
<replaceable>VERSION2</replaceable></literal>, or <literal><replaceable>VERSION1</replaceable> ==
<replaceable>VERSION2</replaceable></literal>, or <literal><replaceable>VERSION1</replaceable> >
<para>Reports whether the system is equipped with a usable TPM2 device. If a TPM2 device has been
discovered, is supported, and is being used by firmware, by the OS kernel drivers and by userspace
(i.e. systemd) this prints <literal>yes</literal> and exits with exit status zero. If no such device is
- discovered/supported/used, prints <literal>no</literal>. Otherwise prints
+ discovered/supported/used, prints <literal>no</literal>. Otherwise, prints
<literal>partial</literal>. In either of these two cases exits with non-zero exit status. It also shows
five lines indicating separately whether firmware, drivers, the system, the kernel and libraries
discovered/support/use TPM2. Currently, required libraries are <filename>libtss2-esys.so.0</filename>,
<term><option>--base-time=<replaceable>TIMESTAMP</replaceable></option></term>
<listitem><para>When used with the <command>calendar</command> command, show next iterations relative
- to the specified point in time. If not specified defaults to the current time.</para>
+ to the specified point in time. If not specified, defaults to the current time.</para>
<xi:include href="version-info.xml" xpointer="v244"/></listitem>
</varlistentry>
<constant>0</constant> or <constant>1</constant> if the condition is respectively true or false.</para>
<para>In case of the <command>has-tpm2</command> command returns 0 if a TPM2 device is discovered,
- supported and used by firmware, driver, and userspace (i.e. systemd). Otherwise returns the OR
+ supported and used by firmware, driver, and userspace (i.e. systemd). Otherwise, returns the OR
combination of the value 1 (in case firmware support is missing), 2 (in case driver support is missing)
and 4 (in case userspace support is missing). If no TPM2 support is available at all, value 7 is hence
returned.</para>
<varlistentry>
<term><option>--tty=<replaceable></replaceable></option></term>
- <listitem><para>Specify the TTY to output to. By default <command>systemd-bsod</command> will
+ <listitem><para>Specify the TTY to output to. By default, <command>systemd-bsod</command> will
automatically find a free VT to display the message on. If this option is specified a TTY may be
selected explicitly. Use <option>--tty=/dev/tty</option> to direct output to the terminal the command
is invoked on.</para>
<term><option>--name=<replaceable>name</replaceable></option></term>
<listitem><para>When specified with the <command>encrypt</command> command controls the credential
- name to embed in the encrypted credential data. If not specified the name is chosen automatically
+ name to embed in the encrypted credential data. If not specified, the name is chosen automatically
from the filename component of the specified output path. If specified as empty string no
credential name is embedded in the encrypted credential, and no verification of credential name is
done when the credential is decrypted.</para>
<para>When specified with the <command>decrypt</command> command control the credential name to
- validate the credential name embedded in the encrypted credential with. If not specified the name is
+ validate the credential name embedded in the encrypted credential with. If not specified, the name is
chosen automatically from the filename component of the specified input path. If no credential name
is embedded in the encrypted credential file (i.e. the <option>--name=</option> with an empty string
was used when encrypted) the specified name has no effect as no credential name validation is
<para>When specified with the <command>decrypt</command> command controls the timestamp to use to
validate the "not-after" timestamp that was configured with <option>--not-after=</option> during
- encryption. If not specified defaults to the current system time.</para>
+ encryption. If not specified, defaults to the current system time.</para>
<xi:include href="version-info.xml" xpointer="v250"/></listitem>
</varlistentry>
<listitem><para>When specified with the <command>encrypt</command> command controls the time when the
credential shall not be used anymore. This embeds the specified timestamp in the encrypted
credential. During decryption the timestamp is checked against the current system clock, and if the
- timestamp is in the past the decryption will fail. By default no such timestamp is set. Takes a
+ timestamp is in the past the decryption will fail. By default, no such timestamp is set. Takes a
timestamp specification in the format described in
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
<filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>,
<filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The
<option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same
- syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this
+ syntax as <option>--tpm2-pcrs=</option> described above). If not specified, defaults to 11 (i.e. this
binds the policy to any unified kernel image for which a PCR signature can be provided).</para>
<para>Note the difference between <option>--tpm2-pcrs=</option> and
<filename>/etc/systemd/</filename>, <filename>/run/systemd/</filename>,
<filename>/usr/lib/systemd/</filename> (searched in this order), it is automatically used. The
<option>--tpm2-public-key-pcrs=</option> option takes a list of TPM2 PCR indexes to bind to (same
- syntax as <option>--tpm2-pcrs=</option> described above). If not specified defaults to 11 (i.e. this
+ syntax as <option>--tpm2-pcrs=</option> described above). If not specified, defaults to 11 (i.e. this
binds the policy to any unified kernel image for which a PCR signature can be provided).</para>
<para>Note the difference between <option>--tpm2-pcrs=</option> and
unmounted.</para>
<para>The OS image may either be specified as path to an OS image stored in a regular file or may
- refer to block device node (in the latter case the block device must be the "whole" device, i.e. not
+ refer to block device node (in the latter case, the block device must be the "whole" device, i.e. not
a partition device). (The other supported commands described here support this, too.)</para>
<para>All mounted file systems are checked with the appropriate <citerefentry
<listitem><para>Detach the specified disk image from a loopback block device. This undoes the effect
of <option>--attach</option> above. This expects either a path to a loopback block device as an
- argument, or the path to the backing image file. In the latter case it will automatically determine
+ argument, or the path to the backing image file. In the latter case, it will automatically determine
the right device to detach.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
the current working directory, or an absolute path, both outside of the image). If the destination
path is omitted or specified as dash (<literal>-</literal>), the specified file is written to
standard output. If the source path in the image file system refers to a regular file it is copied to
- the destination path. In this case access mode, extended attributes and timestamps are copied as
+ the destination path. In this case, access mode, extended attributes and timestamps are copied as
well, but file ownership is not. If the source path in the image refers to a directory, it is copied
- to the destination path, recursively with all containing files and directories. In this case the file
+ to the destination path, recursively with all containing files and directories. In this case, the file
ownership is copied too.</para>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
image) and a destination path (relative to the image's root directory). If the source path is omitted
or specified as dash (<literal>-</literal>), the data to write is read from standard input. If the
source path in the host file system refers to a regular file, it is copied to the destination path.
- In this case access mode, extended attributes and timestamps are copied as well, but file ownership
+ In this case, access mode, extended attributes and timestamps are copied as well, but file ownership
is not. If the source path in the host file system refers to a directory it is copied to the
- destination path, recursively with all containing files and directories. In this case the file
+ destination path, recursively with all containing files and directories. In this case, the file
ownership is copied too.</para>
<para>As with <option>--mount</option> file system checks are implicitly run before the copy
dissection policy into account. Since this operation does not mount file systems, this command –
unlike all other commands implemented by this tool – requires no privileges other than the ability to
access the specified file. Prints "OK" and returns zero if the image appears to be in order and
- matches the specified image dissection policy. Otherwise prints an error message and returns
+ matches the specified image dissection policy. Otherwise, prints an error message and returns
non-zero.</para>
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
<term><option>--read-only</option></term>
<term><option>-r</option></term>
- <listitem><para>Operate in read-only mode. By default <option>--mount</option> will establish
+ <listitem><para>Operate in read-only mode. By default, <option>--mount</option> will establish
writable mount points. If this option is specified they are established in read-only mode
instead.</para>
<varlistentry>
<term><option>--fsck=no</option></term>
- <listitem><para>Turn off automatic file system checking. By default when an image is accessed for
+ <listitem><para>Turn off automatic file system checking. By default, when an image is accessed for
writing (by <option>--mount</option> or <option>--copy-to</option>) the file systems contained in the
OS image are automatically checked using the appropriate <citerefentry
project='man-pages'><refentrytitle>fsck</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<term><option>--growfs=no</option></term>
<listitem><para>Turn off automatic growing of accessed file systems to their partition size, if
- marked for that in the GPT partition table. By default when an image is accessed for writing (by
+ marked for that in the GPT partition table. By default, when an image is accessed for writing (by
<option>--mount</option> or <option>--copy-to</option>) the file systems contained in the OS image
are automatically grown to their partition sizes, if bit 59 in the GPT partition flags is set for
partition types that are defined by the <ulink
<varlistentry>
<term><option>--welcome=</option></term>
- <listitem><para>Takes a boolean argument. By default when prompting the user for configuration
+ <listitem><para>Takes a boolean argument. By default, when prompting the user for configuration
options a brief welcome text is shown before the first question is asked. Pass false to this option
to turn off the welcome text.</para>
completing the download successfully, or unsuccessfully. See
<varname>SuccessAction=</varname>/<varname>FailureAction=</varname> on
<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
- details about the available actions. If not specified no action is taken, and the system will
+ details about the available actions. If not specified, no action is taken, and the system will
continue to boot normally.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
<para><filename>systemd-journal-remote.service</filename> is a system service that uses
<command>systemd-journal-remote</command> to listen for connections.
<filename>systemd-journal-remote.socket</filename> configures the network address that
- <filename>systemd-journal-remote.service</filename> listens on. By default this is port 19532.
+ <filename>systemd-journal-remote.service</filename> listens on. By default, this is port 19532.
What connections are accepted and how the received data is stored can be configured through the
<citerefentry><refentrytitle>journal-remote.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
configuration file.</para>
necessary. Individual fields making up a log record stored in the journal may be up to 2⁶⁴-1 bytes in size.</para>
<para>The journal service stores log data either persistently below <filename>/var/log/journal</filename> or in a
- volatile way below <filename>/run/log/journal/</filename> (in the latter case it is lost at reboot). By default, log
+ volatile way below <filename>/run/log/journal/</filename> (in the latter case, it is lost at reboot). By default, log
data is stored persistently if <filename>/var/log/journal/</filename> exists during boot, with an implicit fallback
to volatile storage otherwise. Use <varname>Storage=</varname> in
<citerefentry><refentrytitle>journald.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> to configure
<para>If <filename>systemd-journald.service</filename> is stopped, the stream connections associated with all
services are terminated. Further writes to those streams by the service will result in <constant>EPIPE</constant>
- errors. In order to react gracefully in this case it is recommended that programs logging to standard output/error
+ errors. In order to react gracefully in this case, it is recommended that programs logging to standard output/error
ignore such errors. If the <constant>SIGPIPE</constant> UNIX signal handler is not blocked or turned off, such
write attempts will also result in such process signals being generated, see
<citerefentry project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
consisting of one or more services from the rest of the system and a mechanism for improving
performance. Multiple journal namespaces may exist simultaneously, each defining its own, independent log
stream managed by its own instance of <command>systemd-journald</command>. Namespaces are independent of
- each other, both in the data store and in the IPC interface. By default only a single 'default' namespace
+ each other, both in the data store and in the IPC interface. By default, only a single "default namespace
exists, managed by <filename>systemd-journald.service</filename> (and its associated socket
units). Additional namespaces are created by starting an instance of the
<filename>systemd-journald@.service</filename> service template. The instance name is the namespace
the native logging protocol of the journal and via stdout/stderr; the logging from all three transports
is associated with the namespace.</para>
- <para>By default only the default namespace will collect kernel and audit log messages.</para>
+ <para>By default, only the default namespace will collect kernel and audit log messages.</para>
<para>The <command>systemd-journald</command> instance of the default namespace is configured through
<filename>/etc/systemd/journald.conf</filename> (see below), while the other instances are configured
same PEM key should be supplied in both cases.</para>
<para>If the <option>--public-key=</option> is not specified but <option>--private-key=</option> is
- specified the public key is automatically derived from the private key.</para>
+ specified, the public key is automatically derived from the private key.</para>
<para><option>--certificate=</option> can be used to specify an X.509 certificate as an alternative
to <option>--public-key=</option> since v256.</para>
<listitem><para>Enable probing of the mount source. This switch is implied if a single argument is specified on
the command line. If passed, additional metadata is read from the device to enhance the unit to create. For
example, a descriptive string for the transient units is generated from the file system label and device
- model. Moreover if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular
+ model. Moreover, if a removable block device (e.g. USB stick) is detected an automount unit instead of a regular
mount unit is created, with a short idle timeout, in order to ensure the file-system is placed in a clean
state quickly after each access.</para>
accessed. In automount mode the <option>--timeout-idle-sec=</option> switch (see below) may be used to ensure
the mount point is unmounted automatically after the last access and an idle period passed.</para>
- <para>If this switch is not specified it defaults to false. If not specified and <option>--discover</option> is
+ <para>If this switch is not specified, it defaults to false. If not specified and <option>--discover</option> is
used (or only a single argument passed, which implies <option>--discover</option>, see above), and the file
system block device is detected to be removable, it is set to true, in order to increase the chance that the
file system is in a fully clean state if the device is unplugged abruptly.</para>
<term><option>--timeout-idle-sec=</option></term>
<listitem><para>Takes a time value that controls the idle timeout in automount mode. If set to
- <literal>infinity</literal> (the default) no automatic unmounts are done. Otherwise the file system backing the
+ <literal>infinity</literal> (the default) no automatic unmounts are done. Otherwise, the file system backing the
automount point is detached after the last access and the idle timeout passed. See
<citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry> for details on
the time syntax supported. This option has no effect if only a regular mount is established, and automounting
<listitem><para>This option only has an effect in automount mode,
and controls whether the automount unit shall be bound to the backing device's lifetime. If set, the
- automount unit will be stopped automatically when the backing device vanishes. By default the automount unit
+ automount unit will be stopped automatically when the backing device vanishes. By default, the automount unit
stays around, and subsequent accesses will block until backing device is replugged. This option has no effect
in case of non-device mounts, such as network or virtual file system mounts.</para>
<listitem><para>Takes an image policy string as argument, as per
<citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
policy is enforced when operating on the disk image specified via <option>--image=</option>, see
- above. If not specified defaults to
+ above. If not specified, defaults to
<literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent:home=encrypted+unprotected+absent:srv=encrypted+unprotected+absent:esp=unprotected+absent:xbootldr=unprotected+absent:tmp=encrypted+unprotected+absent:var=encrypted+unprotected+absent</literal>,
i.e. all recognized file systems in the image are used, but not the swap partition.</para>
<listitem><para>Takes the path to an OCI runtime bundle to invoke, as specified in the <ulink
url="https://github.com/opencontainers/runtime-spec/blob/master/spec.md">OCI Runtime Specification</ulink>. In
- this case no <filename>.nspawn</filename> file is loaded, and the root directory and various settings are read
+ this case, no <filename>.nspawn</filename> file is loaded, and the root directory and various settings are read
from the OCI runtime JSON data (but data passed on the command line takes precedence).</para>
<xi:include href="version-info.xml" xpointer="v242"/></listitem>
<listitem><para>Mount the container's root file system (and any other file systems contained in the container
image) read-only. This has no effect on additional mounts made with <option>--bind=</option>,
<option>--tmpfs=</option> and similar options. This mode is implied if the container image file or directory is
- marked read-only itself. It is also implied if <option>--volatile=</option> is used. In this case the container
+ marked read-only itself. It is also implied if <option>--volatile=</option> is used. In this case, the container
image on disk is strictly read-only, while changes are permitted but kept non-persistently in memory only. For
further details, see below.</para></listitem>
</varlistentry>
<constant>SIGTERM</constant>, in order to trigger an orderly shutdown of the container. Defaults to
<constant>SIGRTMIN+3</constant> if <option>--boot</option> is used (on systemd-compatible init systems
<constant>SIGRTMIN+3</constant> triggers an orderly shutdown). If <option>--boot</option> is not used and this
- option is not specified the container's processes are terminated abruptly via <constant>SIGKILL</constant>. For
+ option is not specified, the container's processes are terminated abruptly via <constant>SIGKILL</constant>. For
a list of valid signals, see <citerefentry
project='man-pages'><refentrytitle>signal</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
<para>It's recommended to use <literal>copy-…</literal> or <literal>replace-…</literal> if the
container shall be able to make changes to the DNS configuration on its own, deviating from the
- host's settings. Otherwise <literal>bind</literal> is preferable, as it means direct changes to
+ host's settings. Otherwise, <literal>bind</literal> is preferable, as it means direct changes to
<filename>/etc/resolv.conf</filename> in the container are not allowed, as it is a read-only bind
mount (but note that if the container has enough privileges, it might simply go ahead and unmount the
bind mount anyway). Note that both if the file is bind mounted and if it is copied no further
<term><option>--nv-index=</option></term>
<listitem><para>Specifies the NV index to store the policy in. Honoured by
- <command>make-policy</command>. If not specified the command will automatically pick a free NV
+ <command>make-policy</command>. If not specified, the command will automatically pick a free NV
index.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
<listitem><para>Takes a path to read <filename>*.pcrlock</filename> and
<filename>*.pcrlock.d/*.pcrlock</filename> files from. May be used more than once to specify multiple
- such directories. If not specified defaults to <filename>/etc/pcrlock.d/</filename>,
+ such directories. If not specified, defaults to <filename>/etc/pcrlock.d/</filename>,
<filename>/run/pcrlock.d/</filename>, <filename>/var/lib/pcrlock.d/</filename>,
<filename>/usr/local/pcrlock.d/</filename>, <filename>/usr/lib/pcrlock.d/</filename>.</para>
<term><option>--policy=</option></term>
<listitem><para>Takes a file system path as argument. If specified, configures where to write pcrlock
- policy metadata to. If not specified defaults to
+ policy metadata to. If not specified, defaults to
<filename>/var/lib/systemd/pcrlock.json</filename>.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
<varlistentry>
<term><option>--bank=</option></term>
- <listitem><para>Takes the PCR banks to extend the specified word into. If not specified the tool
+ <listitem><para>Takes the PCR banks to extend the specified word into. If not specified, the tool
automatically determines all enabled PCR banks and measures the word into all of
them.</para>
<term><option>--graceful</option></term>
<listitem><para>If no TPM2 firmware, kernel subsystem, kernel driver or device support is found, exit
- with exit status 0 (i.e. indicate success). If this is not specified any attempt to measure without a
+ with exit status 0 (i.e. indicate success). If this is not specified, any attempt to measure without a
TPM2 device will cause the invocation to fail.</para>
<xi:include href="version-info.xml" xpointer="v253"/></listitem>
<varlistentry>
<term><option>--dry-run=</option></term>
- <listitem><para>Takes a boolean. If this switch is not specified <option>--dry-run=yes</option> is
+ <listitem><para>Takes a boolean. If this switch is not specified, <option>--dry-run=yes</option> is
the implied default. Controls whether <filename>systemd-repart</filename> executes the requested
re-partition operations or whether it should only show what it would do. Unless
<option>--dry-run=no</option> is specified <filename>systemd-repart</filename> will not actually
<listitem><para>Takes one of <literal>refuse</literal>, <literal>allow</literal>,
<literal>require</literal>, <literal>force</literal> or <literal>create</literal>. Controls how to
operate on block devices that are entirely empty, i.e. carry no partition table/disk label yet. If
- this switch is not specified the implied default is <literal>refuse</literal>.</para>
+ this switch is not specified, the implied default is <literal>refuse</literal>.</para>
<para>If <literal>refuse</literal> <command>systemd-repart</command> requires that the block device
it shall operate on already carries a partition table and refuses operation if none is found. If
<varlistentry>
<term><option>--discard=</option></term>
- <listitem><para>Takes a boolean. If this switch is not specified <option>--discard=yes</option> is
+ <listitem><para>Takes a boolean. If this switch is not specified ,<option>--discard=yes</option> is
the implied default. Controls whether to issue the <constant>BLKDISCARD</constant> I/O control
command on the space taken up by any added partitions or on the space in between them. Usually, it is
a good idea to issue this request since it tells the underlying hardware that the covered blocks
<varlistentry>
<term><option>--factory-reset=</option></term>
- <listitem><para>Takes boolean. If this switch is not specified <option>--factory=reset=no</option> is
+ <listitem><para>Takes boolean. If this switch is not specified, <option>--factory=reset=no</option> is
the implied default. Controls whether to operate in "factory reset" mode, see above. If set to true
this will remove all existing partitions marked with <varname>FactoryReset=</varname> set to yes
early while executing the re-partitioning algorithm. Use with care, this is a great way to lose all
<listitem><para>Takes a UUID as argument or the special value <constant>random</constant>. If a UUID
is specified the UUIDs to assign to partitions and the partition table itself are derived via
- cryptographic hashing from it. If not specified it is attempted to read the machine ID from the host
+ cryptographic hashing from it. If not specified, it is attempted to read the machine ID from the host
(or more precisely, the root directory configured via <option>--root=</option>) and use it as seed
instead, falling back to a randomized seed otherwise. Use <option>--seed=random</option> to force a
randomized seed. Explicitly specifying the seed may be used to generated strictly reproducible
<listitem><para>Takes a file system path. Configures the encryption key to use when setting up LUKS2
volumes configured with the <varname>Encrypt=key-file</varname> setting in partition files. Should
refer to a regular file containing the key, or an <constant>AF_UNIX</constant> stream socket in the
- file system. In the latter case a connection is made to it and the key read from it. If this switch
- is not specified the empty key (i.e. zero length key) is used. This behaviour is useful for setting
+ file system. In the latter case, a connection is made to it and the key read from it. If this switch
+ is not specified, the empty key (i.e. zero length key) is used. This behaviour is useful for setting
up encrypted partitions during early first boot that receive their user-supplied password only in a
later setup step.</para>
and no global DNS server configured, one of the compiled-in fallback DNS servers is used.</para>
</listitem>
- <listitem><para>Otherwise the unicast DNS query fails, as no suitable DNS servers can be determined.
+ <listitem><para>Otherwise, the unicast DNS query fails, as no suitable DNS servers can be determined.
</para></listitem>
</itemizedlist>
<citerefentry project='man-pages'><refentrytitle>bash</refentrytitle><manvolnum>1</manvolnum></citerefentry>
shell which is started by the service unit. The shell expands <literal>$SHELL</literal> to the path of
the shell, and <literal>$$</literal> to its process number, and then those strings are passed to the
- <command>echo</command> built-in and printed to standard output (which in this case is connected to the
+ <command>echo</command> built-in and printed to standard output (which, in this case, is connected to the
calling terminal).</para>
</example>
<listitem><para>Signs the given PE binary for EFI Secure Boot. Takes a path to a PE binary as its
argument. If the PE binary already has a certificate table, the new signature will be added to it.
- Otherwise a new certificate table will be created. The signed PE binary will be written to the path
+ Otherwise, a new certificate table will be created. The signed PE binary will be written to the path
specified with <option>--output=</option>.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
<term><varname>AllowHybridSleep=</varname></term>
<term><varname>AllowSuspendThenHibernate=</varname></term>
- <listitem><para>By default any power-saving mode is advertised if possible (i.e.
+ <listitem><para>By default, any power-saving mode is advertised if possible (i.e.
the kernel supports that mode, the necessary resources are available). Those
switches can be used to disable specific modes.</para>
<listitem><para>The initrd initialization.</para></listitem>
</itemizedlist>
- <para>However this form of reboot comes with drawbacks as well:</para>
+ <para>However, this form of reboot comes with drawbacks as well:</para>
<itemizedlist>
<listitem><para>The OS update remains incomplete, as the kernel is not reset and continues
<ulink url="https://github.com/cloud-hypervisor/cloud-hypervisor/blob/main/docs/vsock.md">cloud-hypervisor VSOCK support</ulink>
and <ulink url="https://github.com/firecracker-microvm/firecracker/blob/main/docs/vsock.md">Using the Firecracker Virtio-vsock Device</ulink>.</para>
- <para>Moreover connecting to <literal>.host</literal> will connect to the local host via SSH, without
+ <para>Moreover, connecting to <literal>.host</literal> will connect to the local host via SSH, without
involving networking.</para>
<para>This tool is supposed to be used together with
url="https://nvmexpress.org/wp-content/uploads/NVM-Express-Base-Specification-2.0c-2022.10.04-Ratified.pdf">NVM
Express Base Specification 2.0c</ulink>, section 4.5 "NVMe Qualified Names". Note that the NQN
specified here will be suffixed with a dot and the block device name before it is exposed on the
- NVMe target. If not specified defaults to
+ NVMe target. If not specified, defaults to
<literal>nqn.2023-10.io.systemd:storagetm.<replaceable>ID</replaceable></literal>, where ID is
replaced by a 128bit ID derived from
<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<listitem><para>Takes an image policy string as argument, as per
<citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
- policy is enforced when operating on system extension disk images. If not specified defaults to
+ policy is enforced when operating on system extension disk images. If not specified, defaults to
<literal>root=verity+signed+encrypted+unprotected+absent:usr=verity+signed+encrypted+unprotected+absent</literal>
for system extensions, i.e. only the root and <filename>/usr/</filename> file systems in the image
are used. For configuration extensions defaults to
running and hence <varname>RuntimeWatchdogSec=</varname> is still honoured. In order to define a
timeout on this first phase of system shutdown, configure <varname>JobTimeoutSec=</varname> and
<varname>JobTimeoutAction=</varname> in the [Unit] section of the
- <filename>shutdown.target</filename> unit. By default <varname>RuntimeWatchdogSec=</varname> defaults
+ <filename>shutdown.target</filename> unit. By default, <varname>RuntimeWatchdogSec=</varname> defaults
to 0 (off), and <varname>RebootWatchdogSec=</varname> to 10min.</para>
<para><varname>KExecWatchdogSec=</varname> may be used to additionally enable the watchdog when kexec
<varlistentry>
<term><option>--kvm=<replaceable>BOOL</replaceable></option></term>
- <listitem><para>If <option>--kvm=</option> is not specified KVM support will be
+ <listitem><para>If <option>--kvm=</option> is not specified, KVM support will be
detected automatically. If true, KVM is always used, and if false, KVM is never used.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
<varlistentry>
<term><option>--vsock=<replaceable>BOOL</replaceable></option></term>
- <listitem><para>If <option>--vsock=</option> is not specified VSOCK networking support will be
+ <listitem><para>If <option>--vsock=</option> is not specified, VSOCK networking support will be
detected automatically. If true, VSOCK networking is always used, and if false, VSOCK networking is never used.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
<listitem>
<para>Sets the specific CID to use for the guest.
Valid CIDs are in the range <constant>3</constant> to <constant>4294967294</constant> (<constant>0xFFFF_FFFE</constant>).
- CIDs outside of this range are reserved. By default vmspawn will attempt to derive a CID for the guest derived from the machine name,
+ CIDs outside of this range are reserved. By default, vmspawn will attempt to derive a CID for the guest derived from the machine name,
falling back to a random CID if this CID is taken.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
<term><option>--tpm=<replaceable>BOOL</replaceable></option></term>
<listitem>
- <para>If <option>--tpm=</option> is not specified vmspawn will detect the presence of <citerefentry project='debian'>
+ <para>If <option>--tpm=</option> is not specified, vmspawn will detect the presence of <citerefentry project='debian'>
<refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry> and use it if available.
If yes is specified <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is always used, and if no is set <citerefentry project='debian'><refentrytitle>swtpm</refentrytitle>
<listitem><para>Takes an absolute path, or a relative path beginning with
<filename>./</filename>. Specifies a JSON firmware definition file, which allows selecting the
- firmware to boot in the VM. If not specified a suitable firmware is automatically discovered. If the
+ firmware to boot in the VM. If not specified, a suitable firmware is automatically discovered. If the
special string <literal>list</literal> is specified lists all discovered firmwares.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
<listitem><para>Configure whether to search for firmware which supports Secure Boot.</para>
- <para>If the option is not specified the first firmware which is detected will be used.
- If the option is set to yes then the first firmware with Secure Boot support will be selected.
- If no is specified then the first firmware without Secure Boot will be selected.</para>
+ <para>If the option is not specified, the first firmware which is detected will be used.
+ If the option is set to yes, then the first firmware with Secure Boot support will be selected.
+ If no is specified, then the first firmware without Secure Boot will be selected.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--pass-ssh-key=<replaceable>BOOL</replaceable></option></term>
- <listitem><para>By default an SSH key is generated to allow <command>systemd-vmspawn</command> to open
+ <listitem><para>By default, an SSH key is generated to allow <command>systemd-vmspawn</command> to open
a D-Bus connection to the VM's systemd bus. Setting this to "no" will disable SSH key generation.</para>
<para>The generated keys are ephemeral. That is they are valid only for the current invocation of <command>systemd-vmspawn</command>,
<citerefentry project="man-pages"><refentrytitle>ssh-keygen</refentrytitle><manvolnum>1</manvolnum></citerefentry>
for more information.</para>
- <para>By default <literal>ed25519</literal> keys are generated, however <literal>rsa</literal> keys
+ <para>By default, <literal>ed25519</literal> keys are generated, however <literal>rsa</literal> keys
may also be useful if the VM has a particularly old version of
<citerefentry project='man-pages'><refentrytitle>sshd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
<para>If an error occurred the value errno is propagated to the return code.
If EXIT_STATUS is supplied by the running image that is returned.
- Otherwise EXIT_SUCCESS is returned.</para>
+ Otherwise, EXIT_SUCCESS is returned.</para>
</refsect1>
<refsect1>
<term><option>-A</option></term>
<listitem><para>Explicitly configures the architecture to select. If specified, a filename with the
- specified architecture identifier will be looked for. If not specified only filenames with a locally
+ specified architecture identifier will be looked for. If not specified, only filenames with a locally
supported architecture are considered, or those without any architecture identifier.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
<term><option>--print=</option></term>
<term><option>-p</option></term>
- <listitem><para>Configures what precisely to write to standard output. If not specified prints the
+ <listitem><para>Configures what precisely to write to standard output. If not specified, prints the
full, resolved path of the newest matching file in the <literal>.v/</literal> directory. This switch can be set to one of the following:</para>
<itemizedlist>
is already marked read-only), while <varname>BindReadOnlyPaths=</varname> creates read-only bind mounts. These
settings may be used more than once, each usage appends to the unit's list of bind mounts. If the empty string
is assigned to either of these two options the entire list of bind mounts defined prior to this is reset. Note
- that in this case both read-only and regular bind mounts are reset, regardless which of the two settings is
+ that, in this case, both read-only and regular bind mounts are reset, regardless which of the two settings is
used.</para>
<para>Using this option implies that a mount namespace is allocated for the unit, i.e. it implies the
effect of <varname>PrivateMounts=</varname> (see below).</para>
<para>This option is particularly useful when <varname>RootDirectory=</varname>/<varname>RootImage=</varname>
- is used. In this case the source path refers to a path on the host file system, while the destination path
+ is used. In this case, the source path refers to a path on the host file system, while the destination path
refers to a path below the root directory of the unit.</para>
<para>Note that the destination directory must exist or systemd must be able to create it. Thus, it
leave files around after unit termination. Furthermore
<varname>NoNewPrivileges=</varname> and <varname>RestrictSUIDSGID=</varname> are implicitly enabled
(and cannot be disabled), to ensure that processes invoked cannot take benefit or create SUID/SGID
- files or directories. Moreover <varname>ProtectSystem=strict</varname> and
+ files or directories. Moreover, <varname>ProtectSystem=strict</varname> and
<varname>ProtectHome=read-only</varname> are implied, thus prohibiting the service to write to
arbitrary file system locations. In order to allow the service to write to certain directories, they
have to be allow-listed using <varname>ReadWritePaths=</varname>, but care must be taken so that
capabilities to the ambient capability set adds them to the process's inherited capability set.</para>
<para>Ambient capability sets are useful if you want to execute a process as a non-privileged user but
- still want to give it some capabilities. Note that in this case option <constant>keep-caps</constant>
+ still want to give it some capabilities. Note that, in this case, option <constant>keep-caps</constant>
is automatically added to <varname>SecureBits=</varname> to retain the capabilities over the user
change. <varname>AmbientCapabilities=</varname> does not affect commands prefixed with
<literal>+</literal>.</para>
executed processes. Takes an integer between -1000 (to disable OOM killing of processes of this unit)
and 1000 (to make killing of processes of this unit under memory pressure very likely). See <ulink
url="https://docs.kernel.org/filesystems/proc.html">The /proc Filesystem</ulink> for
- details. If not specified defaults to the OOM score adjustment level of the service manager itself,
+ details. If not specified, defaults to the OOM score adjustment level of the service manager itself,
which is normally at 0.</para>
<para>Use the <varname>OOMPolicy=</varname> setting of service units to configure how the service
<varname>ReadOnlyPaths=</varname> and related calls, see above. If set to <literal>true</literal>
(as opposed to <literal>disconnected</literal>), this has the side effect of adding
<varname>Requires=</varname> and <varname>After=</varname> dependencies on all mount units necessary
- to access <filename>/tmp/</filename> and <filename>/var/tmp/</filename> on the host. Moreover an
+ to access <filename>/tmp/</filename> and <filename>/var/tmp/</filename> on the host. Moreover, an
implicitly <varname>After=</varname> ordering on
<citerefentry><refentrytitle>systemd-tmpfiles-setup.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is added.</para>
<para>If the standard output (or error output, see below) of a unit is connected to the journal or
the kernel log buffer, the unit will implicitly gain a dependency of type <varname>After=</varname>
on <filename>systemd-journald.socket</filename> (also see the "Implicit Dependencies" section
- above). Also note that in this case stdout (or stderr, see below) will be an
+ above). Also note that, in this case, stdout (or stderr, see below) will be an
<constant>AF_UNIX</constant> stream socket, and not a pipe or FIFO that can be reopened. This means
when executing shell scripts the construct <command>echo "hello" > /dev/stderr</command> for
writing text to stderr will not work. To mitigate this use the construct <command>echo "hello"
<option>notice</option>, <option>info</option>, <option>debug</option> (highest log level, also lowest priority
messages). See <citerefentry
project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry> for
- details. By default no filtering is applied (i.e. the default maximum log level is <option>debug</option>). Use
+ details. By default, no filtering is applied (i.e. the default maximum log level is <option>debug</option>). Use
this option to configure the logging system to drop log messages of a specific service above the specified
level. For example, set <varname>LogLevelMax=</varname><option>info</option> in order to turn off debug logging
of a particularly chatty unit. Note that the configured level is applied to any log messages written by any
url="https://www.dmtf.org/standards/smbios">DMI/SMBIOS</ulink> OEM string table entries (field type
11) with a prefix of <literal>io.systemd.credential:</literal> or
<literal>io.systemd.credential.binary:</literal>. In both cases a key/value pair separated by
- <literal>=</literal> is expected, in the latter case the right-hand side is Base64 decoded when
+ <literal>=</literal> is expected. In the latter case, the right-hand side is Base64 decoded when
parsed (thus permitting binary data to be passed in). Example <ulink
url="https://www.qemu.org/docs/master/system/index.html">qemu</ulink> switch: <literal>-smbios
type=11,value=io.systemd.credential:xx=yy</literal>, or <literal>-smbios
<varname>LoadCredential=</varname>, <varname>LoadCredentialEncrypted=</varname> and
<varname>ImportCredential=</varname> take priority over credentials found by
<varname>SetCredential=</varname>. As such, <varname>SetCredential=</varname> will act as default if
- no credentials are found by any of the former. In this case not being able to retrieve the credential
+ no credentials are found by any of the former. In this case, not being able to retrieve the credential
from the path specified in <varname>LoadCredential=</varname> or
<varname>LoadCredentialEncrypted=</varname> is not considered fatal.</para>
<title>Output directories</title>
<para>Generators are invoked with three arguments: paths to directories where generators can place their
- generated unit files or symlinks. By default those paths are runtime directories that are included in the
+ generated unit files or symlinks. By default, those paths are runtime directories that are included in the
search path of <command>systemd</command>, but a generator may be called with different paths for
debugging purposes. If only one argument is provided, the generator should use the same directory as the
three output paths.</para>
</tgroup>
</table>
- By default this is unset, i.e. all possible modes will be advertised.
+ By default, this is unset, i.e. all possible modes will be advertised.
This option may be specified more than once, in which case all specified speeds and modes are advertised.
If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect.
</para>
<term><option>nofail</option></term>
<listitem><para>With <option>nofail</option>, this mount will be only wanted, not required, by
- <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. Moreover the mount unit is not
+ <filename>local-fs.target</filename> or <filename>remote-fs.target</filename>. Moreover, the mount unit is not
ordered before these target units. This means that the boot will continue without waiting for the mount unit
and regardless whether the mount point can be mounted successfully.</para>
to provide protocol typing, OAM, and versioning capabilities. For details about the VXLAN GPE
Header, see the <ulink url="https://tools.ietf.org/html/draft-ietf-nvo3-vxlan-gpe-07">
Generic Protocol Extension for VXLAN </ulink> document. If destination port is not specified and
- Generic Protocol Extension is set then default port of 4790 is used. Defaults to false.</para>
+ Generic Protocol Extension is set, the default port of 4790 is used. Defaults to false.</para>
<xi:include href="version-info.xml" xpointer="v243"/>
</listitem>
<varlistentry>
<term><varname>DestinationPort=</varname></term>
<listitem>
- <para>Configures the default destination UDP port. If the destination port is not specified then
+ <para>Configures the default destination UDP port. If the destination port is not specified, the
Linux kernel default will be used. Set to 4789 to get the IANA assigned value.</para>
<xi:include href="version-info.xml" xpointer="v229"/>
resolving domain names that do not match any link's configured <varname>Domains=</varname>
setting. If false, this link's configured DNS servers are never used for such domains, and
are exclusively used for resolving names that match at least one of the domains configured on
- this link. If not specified defaults to an automatic mode: queries not matching any link's
+ this link. If not specified, defaults to an automatic mode: queries not matching any link's
configured domains will be routed to this link if it has no routing-only domains configured.
</para>
route to the source on that interface, the machine will drop the packet. Takes one of
<literal>no</literal>, <literal>strict</literal>, or <literal>loose</literal>. When <literal>no</literal>,
no source validation will be done. When <literal>strict</literal>, each incoming packet is tested against the FIB and
- if the incoming interface is not the best reverse path, the packet check will fail. By default failed packets are discarded.
+ if the incoming interface is not the best reverse path, the packet check will fail. By default, failed packets are discarded.
When <literal>loose</literal>, each incoming packet's source address is tested against the FIB. The packet is dropped
only if the source address is not reachable via any interface on that router.
See <ulink url="https://tools.ietf.org/html/rfc1027">RFC 3704</ulink>.
<listitem>
<para>Takes a boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery Protocol)
is a technique for IPv6 to allow routing of addresses to a different destination when peers
- expect them to be present on a certain physical link. In this case a router answers Neighbour
+ expect them to be present on a certain physical link. In this case, a router answers Neighbour
Advertisement messages intended for another machine by offering its own MAC address as
destination. Unlike proxy ARP for IPv4, it is not enabled globally, but will only send
Neighbour Advertisement messages for addresses in the IPv6 neighbor proxy table, which can
added to the routing table with a metric of 1024, and a scope of <option>global</option>,
<option>link</option> or <option>host</option>, depending on the route's destination and
gateway. If the destination is on the local host, e.g., 127.x.x.x, or the same as the link's
- own address, the scope will be set to <option>host</option>. Otherwise if the gateway is null
+ own address, the scope will be set to <option>host</option>. Otherwise, if the gateway is null
(a direct route), a <option>link</option> scope will be used. For anything else, scope
defaults to <option>global</option>.</para>
triggered automatically in case of a bus-off condition after the specified delay time. Subsecond delays can
be specified using decimals (e.g. <literal>0.1s</literal>) or a <literal>ms</literal> or
<literal>us</literal> postfix. Using <literal>infinity</literal> or <literal>0</literal> will turn the
- automatic restart off. By default automatic restart is disabled.</para>
+ automatic restart off. By default, automatic restart is disabled.</para>
<xi:include href="version-info.xml" xpointer="v239"/>
</listitem>
<para>The access lists configured with this option are applied to all sockets created by processes
of this unit (or in the case of socket units, associated with it). The lists are implicitly
combined with any lists configured for any of the parent slice units this unit might be a member
- of. By default both access lists are empty. Both ingress and egress traffic is filtered by these
+ of. By default, both access lists are empty. Both ingress and egress traffic is filtered by these
settings. In case of ingress traffic the source IP address is checked against these access lists,
in case of egress traffic the destination IP address is checked. The following rules are applied in
turn:</para>
<listitem>
<para>Takes a list of space-separated network interface names. This option restricts the network
- interfaces that processes of this unit can use. By default processes can only use the network interfaces
+ interfaces that processes of this unit can use. By default, processes can only use the network interfaces
listed (allow-list). If the first character of the rule is <literal>~</literal>, the effect is inverted:
the processes can only use network interfaces not listed (deny-list).
</para>
of this unit (or in the case of socket units, associated with it). The filters are loaded in addition
to filters any of the parent slice units this unit might be a member of as well as any
<varname>IPAddressAllow=</varname> and <varname>IPAddressDeny=</varname> filters in any of these units.
- By default there are no filters specified.</para>
+ By default, there are no filters specified.</para>
<para>If these settings are used multiple times in the same unit all the specified programs are attached. If an
empty string is assigned to these settings the program list is reset and all previous specified programs ignored.</para>
<listitem><para>Sets the memory pressure threshold time for memory pressure monitor as configured via
<varname>MemoryPressureWatch=</varname>. Specifies the maximum allocation latency before a memory
- pressure event is signalled to the service, per 2s window. If not specified defaults to the
+ pressure event is signalled to the service, per 2s window. If not specified, defaults to the
<varname>DefaultMemoryPressureThresholdSec=</varname> setting in
<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
(which in turn defaults to 200ms). The specified value expects a time unit such as
<listitem>
<para>A special target unit that sets up all slice units (see
<citerefentry><refentrytitle>systemd.slice</refentrytitle><manvolnum>5</manvolnum></citerefentry>
- for details) that shall always be active after boot. By default the generic
+ for details) that shall always be active after boot. By default, the generic
<filename>system.slice</filename> slice unit as well as the root slice unit
<filename>-.slice</filename> are pulled in and ordered before this unit (see
below).</para>
<para>In some cases timestamps are shown in the UTC timezone instead of the local timezone, which is indicated via
the <literal>UTC</literal> timezone specifier in the output.</para>
- <para>In some cases timestamps are shown with microsecond granularity. In this case the sub-second remainder is
+ <para>In some cases timestamps are shown with microsecond granularity. In this case, the sub-second remainder is
separated by a full stop from the seconds component.</para>
</refsect1>
it is subject to the <varname>AccuracySec=</varname> setting below.</para>
<para>May be specified more than once, in which case the timer unit will trigger whenever any of the
- specified expressions elapse. Moreover calendar timers and monotonic timers (see above) may be
+ specified expressions elapse. Moreover, calendar timers and monotonic timers (see above) may be
combined within the same timer unit.</para>
<para>If the empty string is assigned to any of these options, the list of timers is reset (both
section headers. For instantiated units, this logic will first look for the instance
<literal>.d/</literal> subdirectory (e.g. <literal>foo@bar.service.d/</literal>) and read its
<literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory (e.g.
- <literal>foo@.service.d/</literal>) and the <literal>.conf</literal> files there. Moreover for unit
+ <literal>foo@.service.d/</literal>) and the <literal>.conf</literal> files there. Moreover, for unit
names containing dashes (<literal>-</literal>), the set of directories generated by repeatedly
truncating the unit name after all dashes is searched too. Specifically, for a unit name
<filename>foo-bar-baz.service</filename> not only the regular drop-in directory
signals, resource consumption and other statistics are lost, except for what is stored in the log subsystem.</para>
<para>Use <command>systemctl daemon-reload</command> or an equivalent command to reload unit configuration while
- the unit is already loaded. In this case all configuration settings are flushed out and replaced with the new
+ the unit is already loaded. In this case, all configuration settings are flushed out and replaced with the new
configuration (which however might not be in effect immediately), however all runtime state is
saved/restored.</para>
</refsect1>
is not unloaded if it is in the <constant>failed</constant> state. In <option>failed</option> mode, failed
units are not unloaded until the user invoked <command>systemctl reset-failed</command> on them to reset the
<constant>failed</constant> state, or an equivalent command. This behaviour is altered if this option is set to
- <option>inactive-or-failed</option>: in this case the unit is unloaded even if the unit is in a
+ <option>inactive-or-failed</option>: in this case, the unit is unloaded even if the unit is in a
<constant>failed</constant> state, and thus an explicitly resetting of the <constant>failed</constant> state is
not necessary. Note that if this mode is used unit results (such as exit codes, exit signals, consumed
resources, …) are flushed out immediately after the unit completed, except for what is stored in the logging
<listitem><para>Controls the exit status to propagate back to an invoking container manager (in case of a
system service) or service manager (in case of a user manager) when the
<varname>FailureAction=</varname>/<varname>SuccessAction=</varname> are set to <option>exit</option> or
- <option>exit-force</option> and the action is triggered. By default the exit status of the main process of the
+ <option>exit-force</option> and the action is triggered. By default, the exit status of the main process of the
triggering unit (if this applies) is propagated. Takes a value in the range 0…255 or the empty string to
request default behaviour.</para>
for use on the system or whether the legacy v1 cgroup or the modern v2 cgroup hierarchy is used.
</para>
- <para>Multiple controllers may be passed with a space separating them; in this case the condition
+ <para>Multiple controllers may be passed with a space separating them; in this case, the condition
will only pass if all listed controllers are available for use. Controllers unknown to systemd are
ignored. Valid controllers are <literal>cpu</literal>, <literal>io</literal>,
<literal>memory</literal>, and <literal>pids</literal>. Even if available in the kernel, a
implicitly along with their reverses and cannot be specified directly.</para>
<para>Note: <varname>Triggers=</varname> is created implicitly between a socket,
- path unit, or an automount unit, and the unit they activate. By default a unit
+ path unit, or an automount unit, and the unit they activate. By default, a unit
with the same name is triggered, but this can be overridden using
<varname>Sockets=</varname>, <varname>Service=</varname>, and <varname>Unit=</varname>
settings. See
<filename>/var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw</filename>. Explanation: even
though <filename>mymachine_7.7.0_x86-64+0-5.raw</filename> has the newest version, it is not preferred
because its tries left counter is zero. And even though <filename>mymachine_7.6.0_arm64.raw</filename>
- has the second newest version it is also not considered, in this case because we operate on an x86_64
+ has the second newest version it is also not considered in this case, because we operate on an x86_64
system and the image is intended for arm64 CPUs. Finally, the <filename>mymachine_7.5.13.raw</filename>
image is not considered because it is older than <filename>mymachine_7.5.14_x86-64.raw</filename>.</para>
</refsect1>
optional.</para>
<para>If the source type is <constant>regular-file</constant> or <constant>directory</constant>, the
- pattern may contain slash characters. In this case it will match the file or directory in
+ pattern may contain slash characters. In this case, it will match the file or directory in
corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
<literal>bar.efi</literal> in directory <literal>foo_1</literal>. </para>
naming newly installed versions.</para>
<para>If the target type is <constant>regular-file</constant> or <constant>directory</constant>, the
- pattern may contain slash characters. In this case it will match the file or directory in
+ pattern may contain slash characters. In this case, it will match the file or directory in
corresponding subdirectory. For example <literal>MatchPattern=foo_@v/bar.efi</literal> will match
<literal>bar.efi</literal> in directory <literal>foo_1</literal>. Directories in the path will be
created when file is installed. Empty directories will be removed when file is removed.</para>
removed unless applied to a directory. This functionality is particularly useful in conjunction with
<varname>Z</varname>.</para>
- <para>By default the access mode of listed inodes is set to the specified mode regardless of whether it is
+ <para>By default, the access mode of listed inodes is set to the specified mode regardless of whether it is
created anew, or already existed. Optionally, if prefixed with <literal>:</literal>, the configured
access mode is only applied when creating new inodes, and if the inode the line refers to
already exists, its access mode is left in place unmodified.</para>
Resolvability of User and Group Names</ulink> for more information on requirements on system user/group
definitions.</para>
- <para>By default the ownership of listed inodes is set to the specified user/group regardless of whether it is
+ <para>By default, the ownership of listed inodes is set to the specified user/group regardless of whether it is
created anew, or already existed. Optionally, if prefixed with <literal>:</literal>, the configured
user/group information is only applied when creating new inodes, and if the inode the line refers to
already exists, its user/group is left in place unmodified.</para>
<listitem><para>Controls which services to query for users/groups. Takes a list of one or more
service names, separated by <literal>:</literal>. See below for a list of well-known service
- names. If not specified all available services are queried at once.</para>
+ names. If not specified, all available services are queried at once.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
</varlistentry>
<term><option>--synthesize=<replaceable>BOOL</replaceable></option></term>
<listitem><para>Controls whether to synthesize records for the root and nobody users/groups if they
- are not defined otherwise. By default (or <literal>yes</literal>) such records are implicitly
+ are not defined otherwise. By default (or <literal>yes</literal>), such records are implicitly
synthesized if otherwise missing since they have special significance to the OS. When
<literal>no</literal> this synthesizing is turned off.</para>
<term><command>groups-of-user</command> <optional><replaceable>USER</replaceable>…</optional></term>
<listitem><para>List groups that the specified users are members of. If no users are specified list
- all user/group memberships defined (in this case <command>groups-of-user</command> and
+ all user/group memberships defined (in this case, <command>groups-of-user</command> and
<command>users-in-group</command> are equivalent). Use <option>--output=</option> to tweak output
mode.</para>
<itemizedlist>
<listitem><para>A Varlink service reference starting with the <literal>unix:</literal> string, followed
by an absolute <constant>AF_UNIX</constant> socket path, or by <literal>@</literal> and an arbitrary
- string (the latter for referencing sockets in the abstract namespace). In this case a stream socket
+ string (the latter for referencing sockets in the abstract namespace). In this case, a stream socket
connection is made to the specified socket.</para></listitem>
<listitem><para>A Varlink service reference starting with the <literal>exec:</literal> string, followed
- by an absolute path of a binary to execute. In this case the specified process is forked off locally,
+ by an absolute path of a binary to execute. In this case, the specified process is forked off locally,
with a connected stream socket passed in.</para></listitem>
<listitem><para>A Varlink service reference starting with the <literal>ssh-unix:</literal> string, followed
<listitem><para>A Varlink service reference starting with the <literal>ssh-exec:</literal> string,
followed by an SSH host specification, followed by <literal>:</literal>, followed by a command line. In
- this case the command is invoked and the Varlink protocol is spoken on the standard input and output of
+ this case, the command is invoked and the Varlink protocol is spoken on the standard input and output of
the invoked command.</para></listitem>
</itemizedlist>
- <para>For convenience these two simpler (redundant) service address syntaxes are also supported:</para>
+ <para>For convenience, these two simpler (redundant) service address syntaxes are also supported:</para>
<itemizedlist>
<listitem><para>A file system path to an <constant>AF_UNIX</constant> socket, either absolute
<listitem><para>Reads a Varlink interface definition file, parses and validates it, then outputs it
with syntax highlighting. This checks for syntax and internal consistency of the interface. Expects a
- file name to read the interface definition from. If omitted reads the interface definition from
+ file name to read the interface definition from. If omitted, reads the interface definition from
STDIN.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
<term><option>--timeout=</option></term>
<listitem>
- <para>Expects a timeout in seconds as parameter. By default a timeout of 45s is enforced. To turn
+ <para>Expects a timeout in seconds as parameter. By default, a timeout of 45s is enforced. To turn
off the timeout specify <literal>infinity</literal> or an empty string.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
projects / thirdparty / systemd.git / commitdiff
