diff options
Diffstat (limited to 'man')
| -rw-r--r-- | man/coredump.conf.xml | 17 | ||||
| -rw-r--r-- | man/dnssec-trust-anchors.d.xml | 14 | ||||
| -rw-r--r-- | man/kernel-install.xml | 5 | ||||
| -rw-r--r-- | man/machinectl.xml | 25 | ||||
| -rw-r--r-- | man/nss-resolve.xml | 4 | ||||
| -rw-r--r-- | man/resolved.conf.xml | 2 | ||||
| -rw-r--r-- | man/sd_bus_negotiate_fds.xml | 46 | ||||
| -rw-r--r-- | man/sd_is_fifo.xml | 8 | ||||
| -rw-r--r-- | man/systemctl.xml | 21 | ||||
| -rw-r--r-- | man/systemd-analyze.xml | 17 | ||||
| -rw-r--r-- | man/systemd-nspawn.xml | 4 | ||||
| -rw-r--r-- | man/systemd-resolve.xml | 4 | ||||
| -rw-r--r-- | man/systemd-system.conf.xml | 11 | ||||
| -rw-r--r-- | man/systemd.exec.xml | 349 | ||||
| -rw-r--r-- | man/systemd.netdev.xml | 90 | ||||
| -rw-r--r-- | man/systemd.network.xml | 117 | ||||
| -rw-r--r-- | man/systemd.socket.xml | 8 | ||||
| -rw-r--r-- | man/systemd.unit.xml | 118 |
18 files changed, 475 insertions, 385 deletions
diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index 4f95680a3a..77b4dac51c 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -83,16 +83,13 @@ <varlistentry> <term><varname>Storage=</varname></term> - <listitem><para>Controls where to store cores. One of - <literal>none</literal>, <literal>external</literal>, - <literal>journal</literal>, and <literal>both</literal>. When - <literal>none</literal>, the core dumps will be logged but not - stored permanently. When <literal>external</literal> (the - default), cores will be stored in <filename>/var/lib/systemd/coredump</filename>. - When <literal>journal</literal>, cores will be stored in - the journal and rotated following normal journal - rotation patterns. When <literal>both</literal>, cores - will be stored in both locations.</para> + <listitem><para>Controls where to store cores. One of <literal>none</literal>, + <literal>external</literal>, and <literal>journal</literal>. When + <literal>none</literal>, the core dumps will be logged (included the traceback if + possible), but not stored permanently. When <literal>external</literal> (the + default), cores will be stored in <filename>/var/lib/systemd/coredump/</filename>. + When <literal>journal</literal>, cores will be stored in the journal and rotated + following normal journal rotation patterns.</para> <para>When cores are stored in the journal, they might be compressed following journal compression settings, see diff --git a/man/dnssec-trust-anchors.d.xml b/man/dnssec-trust-anchors.d.xml index 4bdc167f79..9a28862ceb 100644 --- a/man/dnssec-trust-anchors.d.xml +++ b/man/dnssec-trust-anchors.d.xml @@ -160,14 +160,12 @@ <refsect1> <title>Negative Trust Anchors</title> - <para>Negative trust anchors define domains where DNSSEC - validation shall be turned off. Negative trust anchor files are - found at the same location as positive trust anchor files, and - follow the same overriding rules. They are text files with the - <filename>.negative</filename> suffix. Empty lines and lines whose - first character is <literal>;</literal> are ignored. Each line - specifies one domain name where DNSSEC validation shall be - disabled on.</para> + <para>Negative trust anchors define domains where DNSSEC validation shall be turned + off. Negative trust anchor files are found at the same location as positive trust anchor files, + and follow the same overriding rules. They are text files with the + <filename>.negative</filename> suffix. Empty lines and lines whose first character is + <literal>;</literal> are ignored. Each line specifies one domain name which is the root of a DNS + subtree where validation shall be disabled.</para> <para>Negative trust anchors are useful to support private DNS subtrees that are not referenced from the Internet DNS hierarchy, diff --git a/man/kernel-install.xml b/man/kernel-install.xml index d7e27de758..4a8a46cef4 100644 --- a/man/kernel-install.xml +++ b/man/kernel-install.xml @@ -72,9 +72,12 @@ in <filename>/usr/lib/kernel/install.d/</filename>. This can be used to override a system-supplied executables with a local file if needed; a symbolic link in <filename>/etc/kernel/install.d/</filename> with the same name as an executable in <filename>/usr/lib/kernel/install.d/</filename>, - pointing to /dev/null, disables the executable entirely. Executables must have the + pointing to <filename>/dev/null</filename>, disables the executable entirely. Executables must have the extension <literal>.install</literal>; other extensions are ignored.</para> + <para>An executable should return <constant>0</constant> on success. It may also + return <constant>77</constant> to cause the whole operation to terminate + (executables later in lexical order will be skipped).</para> </refsect1> <refsect1> diff --git a/man/machinectl.xml b/man/machinectl.xml index 597a5cc583..eaa247714b 100644 --- a/man/machinectl.xml +++ b/man/machinectl.xml @@ -186,12 +186,11 @@ <varlistentry> <term><option>--uid=</option></term> - <listitem><para>When used with the <command>shell</command> - command, chooses the user ID to open the interactive shell - session as. If this switch is not specified, defaults to - <literal>root</literal>. Note that this switch is not - supported for the <command>login</command> command (see - below).</para></listitem> + <listitem><para>When used with the <command>shell</command> command, chooses the user ID to + open the interactive shell session as. If the argument to the <command>shell</command> + command also specifies an user name, this option is ignored. If the name is not specified + in either way, <literal>root</literal> will be used by default. Note that this switch is + not supported for the <command>login</command> command (see below).</para></listitem> </varlistentry> <varlistentry> @@ -285,6 +284,20 @@ name passed.</para></listitem> </varlistentry> + <varlistentry> + <term><option>--max-addresses=</option></term> + + <listitem><para>When used with the <option>list-machines</option> + command, limits the number of ip addresses output for every machine. + Defaults to 1. All addresses can be requested with <literal>all</literal> + as argument to <option>--max-addresses</option> . If the argument to + <option>--max-addresses</option> is less than the actual number + of addresses,<literal>...</literal>follows the last address. + If multiple addresses are to be written for a given machine, every + address except the first one is on a new line and is followed by + <literal>,</literal> if another address will be output afterwards. </para></listitem> + </varlistentry> + <xi:include href="user-system-options.xml" xpointer="host" /> <xi:include href="user-system-options.xml" xpointer="machine" /> diff --git a/man/nss-resolve.xml b/man/nss-resolve.xml index e6cc1d982a..d66e8ba521 100644 --- a/man/nss-resolve.xml +++ b/man/nss-resolve.xml @@ -85,7 +85,7 @@ group: compat mymachines systemd shadow: compat -hosts: files mymachines <command>resolve</command> myhostname +hosts: files mymachines <command>resolve [!UNAVAIL=return]</command> dns networks: files protocols: db files @@ -95,6 +95,8 @@ rpc: db files netgroup: nis</programlisting> + <para>This keeps the <command>dns</command> module as a fallback for cases where the <command>nss-resolve</command> + module is not installed.</para> </refsect1> <refsect1> diff --git a/man/resolved.conf.xml b/man/resolved.conf.xml index 44df8ffa80..4fc1ef1b33 100644 --- a/man/resolved.conf.xml +++ b/man/resolved.conf.xml @@ -206,7 +206,7 @@ <term><varname>Cache=</varname></term> <listitem><para>Takes a boolean argument. If "yes" (the default), resolving a domain name which already got queried earlier will return the previous result as long as it is still valid, and thus does not result in a new - network request. Be aware that that turning off caching comes at a performance penalty, which is particularly + network request. Be aware that turning off caching comes at a performance penalty, which is particularly high when DNSSEC is used.</para> <para>Note that caching is turned off implicitly if the configured DNS server is on a host-local IP address diff --git a/man/sd_bus_negotiate_fds.xml b/man/sd_bus_negotiate_fds.xml index a538b13cf0..1501e1427d 100644 --- a/man/sd_bus_negotiate_fds.xml +++ b/man/sd_bus_negotiate_fds.xml @@ -99,41 +99,27 @@ setting as negotiated by the program ultimately activated. By default, file descriptor passing is enabled for both.</para> - <para><function>sd_bus_negotiate_timestamps()</function> controls - whether implicit sender timestamps shall be attached automatically - to all incoming messages. Takes a bus object and a boolean, which, - when true, enables timestamping, and, when false, disables it. - Use + <para><function>sd_bus_negotiate_timestamp()</function> controls whether implicit sender + timestamps shall be attached automatically to all incoming messages. Takes a bus object and a + boolean, which, when true, enables timestamping, and, when false, disables it. Use <citerefentry><refentrytitle>sd_bus_message_get_monotonic_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_realtime_usec</refentrytitle><manvolnum>3</manvolnum></citerefentry>, <citerefentry><refentrytitle>sd_bus_message_get_seqnum</refentrytitle><manvolnum>3</manvolnum></citerefentry> - to query the timestamps of incoming messages. If negotiation is - disabled or not supported, these calls will fail with - <constant>-ENODATA</constant>. Note that not all transports - support timestamping of messages. Specifically, timestamping is - only available on the kdbus transport, but not on dbus1. The - timestamping is applied by the kernel and cannot be manipulated by - userspace. By default, message timestamping is not negotiated for + to query the timestamps of incoming messages. If negotiation is disabled or not supported, these + calls will fail with <constant>-ENODATA</constant>. Note that currently no transports support + timestamping of messages. By default, message timestamping is not negotiated for connections.</para> - <para><function>sd_bus_negotiate_creds()</function> controls - whether and which implicit sender credentials shall be attached - automatically to all incoming messages. Takes a bus object and a - boolean indicating whether to enable or disable the credential - parts encoded in the bit mask value argument. Note that not all - transports support attaching sender credentials to messages, or do - not support all types of sender credential parameters, or might - suppress them under certain circumstances for individual - messages. Specifically, implicit sender credentials on messages - are only fully supported on kdbus transports, and dbus1 only - supports <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender - credentials are attached by the kernel and cannot be manipulated - by userspace, and are thus suitable for authorization - decisions. By default, only - <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and - <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In - fact, these two credential fields are always sent along and cannot - be turned off.</para> + <para><function>sd_bus_negotiate_creds()</function> controls whether and which implicit sender + credentials shall be attached automatically to all incoming messages. Takes a bus object and a + boolean indicating whether to enable or disable the credential parts encoded in the bit mask + value argument. Note that not all transports support attaching sender credentials to messages, + or do not support all types of sender credential parameters, or might suppress them under + certain circumstances for individual messages. Specifically, dbus1 only supports + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant>. The sender credentials are suitable for + authorization decisions. By default, only <constant>SD_BUS_CREDS_WELL_KNOWN_NAMES</constant> and + <constant>SD_BUS_CREDS_UNIQUE_NAME</constant> are enabled. In fact, these two credential fields + are always sent along and cannot be turned off.</para> <para>The <function>sd_bus_negotiate_fds()</function> function may be called only before the connection has been started with diff --git a/man/sd_is_fifo.xml b/man/sd_is_fifo.xml index 627cb87aaf..7ff02cbfec 100644 --- a/man/sd_is_fifo.xml +++ b/man/sd_is_fifo.xml @@ -117,10 +117,10 @@ whether the specified file descriptor refers to a socket. If the <parameter>family</parameter> parameter is not <constant>AF_UNSPEC</constant>, it is checked whether the socket - is of the specified family (AF_UNIX, <constant>AF_INET</constant>, - ...). If the <parameter>type</parameter> parameter is not 0, it is - checked whether the socket is of the specified type - (<constant>SOCK_STREAM</constant>, + is of the specified family (<constant>AF_UNIX</constant>, + <constant>AF_INET</constant>, ...). If the <parameter>type</parameter> + parameter is not 0, it is checked whether the socket is of the + specified type (<constant>SOCK_STREAM</constant>, <constant>SOCK_DGRAM</constant>, ...). If the <parameter>listening</parameter> parameter is positive, it is checked whether the socket is in accepting mode, i.e. diff --git a/man/systemctl.xml b/man/systemctl.xml index 7e0ac9613a..e738b5aecd 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -363,7 +363,20 @@ to finish. If this is not specified, the job will be verified, enqueued and <command>systemctl</command> will wait until the unit's start-up is completed. By passing this - argument, it is only verified and enqueued.</para> + argument, it is only verified and enqueued. This option may not be + combined with <option>--wait</option>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>--wait</option></term> + + <listitem> + <para>Synchronously wait for started units to terminate again. + This option may not be combined with <option>--no-block</option>. + Note that this will wait forever if any given unit never terminates + (by itself or by getting stopped explicitly); particularly services + which use <literal>RemainAfterExit=yes</literal>.</para> </listitem> </varlistentry> @@ -613,7 +626,7 @@ <listitem> <para>When used with <command>list-dependencies</command>, - <command>list-units</command> or <command>list-machines</command>, the + <command>list-units</command> or <command>list-machines</command>, the output is printed as a list instead of a tree, and the bullet circles are omitted.</para> </listitem> @@ -1073,8 +1086,8 @@ kobject-uevent 1 systemd-udevd-kernel.socket systemd-udevd.service <listitem> <para>Reenable one or more units, as specified on the command line. This is a combination of <command>disable</command> and <command>enable</command> and is useful to reset the symlinks a unit file is - enabled with to the defaults configured in its <literal>[Install]</literal> section. This commands expects - a unit uname only, it does not accept paths to unit files.</para> + enabled with to the defaults configured in its <literal>[Install]</literal> section. This command expects + a unit name only, it does not accept paths to unit files.</para> </listitem> </varlistentry> diff --git a/man/systemd-analyze.xml b/man/systemd-analyze.xml index bc37765dff..8fa7cd3329 100644 --- a/man/systemd-analyze.xml +++ b/man/systemd-analyze.xml @@ -181,14 +181,15 @@ <option>--log-target=</option>, described in <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>).</para> - <para><command>systemd-analyze verify</command> will load unit - files and print warnings if any errors are detected. Files - specified on the command line will be loaded, but also any other - units referenced by them. This command works by prepending the - directories for all command line arguments at the beginning of the - unit load path, which means that all units files found in those - directories will be used in preference to the unit files found in - the standard locations, even if not listed explicitly.</para> + <para><command>systemd-analyze verify</command> will load unit files and print + warnings if any errors are detected. Files specified on the command line will be + loaded, but also any other units referenced by them. The full unit search path is + formed by combining the directories for all command line arguments, and the usual unit + load paths (variable <varname>$SYSTEMD_UNIT_PATH</varname> is supported, and may be + used to replace or augment the compiled in set of unit load paths; see + <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>). + All units files present in the directories containing the command line arguments will + be used in preference to the other paths.</para> <para>If no command is passed, <command>systemd-analyze time</command> is implied.</para> diff --git a/man/systemd-nspawn.xml b/man/systemd-nspawn.xml index 97b348b565..bf3860604c 100644 --- a/man/systemd-nspawn.xml +++ b/man/systemd-nspawn.xml @@ -1007,8 +1007,8 @@ <example> <title>Download a Fedora image and start a shell in it</title> - <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/21/Cloud/Images/x86_64/Fedora-Cloud-Base-20141203-21.x86_64.raw.xz -# systemd-nspawn -M Fedora-Cloud-Base-20141203-21</programlisting> + <programlisting># machinectl pull-raw --verify=no http://ftp.halifax.rwth-aachen.de/fedora/linux/releases/24/CloudImages/x86_64/images/Fedora-Cloud-Base-24-1.2.x86_64.raw.xz +# systemd-nspawn -M Fedora-Cloud-Base-24-1.2.x86_64.raw</programlisting> <para>This downloads an image using <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry> diff --git a/man/systemd-resolve.xml b/man/systemd-resolve.xml index ca26bb4d49..2bc917ac26 100644 --- a/man/systemd-resolve.xml +++ b/man/systemd-resolve.xml @@ -135,7 +135,7 @@ TXT).</para> <para>The <option>--openpgp</option> switch may be used to query PGP keys stored as - <ulink url="https://tools.ietf.org/html/draft-wouters-dane-openpgp-02">OPENPGPKEY</ulink> resource records. + <ulink url="https://tools.ietf.org/html/rfc7929">OPENPGPKEY</ulink> resource records. When this option is specified one or more e-mail address must be specified.</para> <para>The <option>--tlsa</option> switch maybe be used to query TLS public @@ -339,7 +339,7 @@ www.0pointer.net: 2a01:238:43ed:c300:10c3:bcf3:3266:da74 </example> <example> - <title>Retrieve the MX record of the <literal>0pointer.net</literal> domain</title> + <title>Retrieve the MX record of the <literal>yahoo.com</literal> domain</title> <programlisting>$ systemd-resolve -t MX yahoo.com --legend=no yahoo.com. IN MX 1 mta7.am0.yahoodns.net diff --git a/man/systemd-system.conf.xml b/man/systemd-system.conf.xml index 1bb40fd234..a268397d09 100644 --- a/man/systemd-system.conf.xml +++ b/man/systemd-system.conf.xml @@ -106,6 +106,17 @@ </varlistentry> <varlistentry> + <term><varname>CtrlAltDelBurstAction=</varname></term> + + <listitem><para>Defines what action will be performed + if user presses Ctr-Alt-Delete more than 7 times in 2s. + Can be set to <literal>reboot-force</literal>, <literal>poweroff-force</literal> + or disabled with <literal>ignore</literal>. Defaults to + <literal>reboot-force</literal>. + </para></listitem> + </varlistentry> + + <varlistentry> <term><varname>CPUAffinity=</varname></term> <listitem><para>Configures the initial CPU affinity for the diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index bcedebd5bb..5e6787338d 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -160,14 +160,18 @@ use. However, UID/GIDs are recycled after a unit is terminated. Care should be taken that any processes running as part of a unit for which dynamic users/groups are enabled do not leave files or directories owned by these users/groups around, as a different unit might get the same UID/GID assigned later on, and thus gain access to - these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname> and + these files or directories. If <varname>DynamicUser=</varname> is enabled, <varname>RemoveIPC=</varname>, <varname>PrivateTmp=</varname> are implied. This ensures that the lifetime of IPC objects and temporary files created by the executed processes is bound to the runtime of the service, and hence the lifetime of the dynamic user/group. Since <filename>/tmp</filename> and <filename>/var/tmp</filename> are usually the only world-writable directories on a system this ensures that a unit making use of dynamic user/group allocation - cannot leave files around after unit termination. Use <varname>RuntimeDirectory=</varname> (see below) in order - to assign a writable runtime directory to a service, owned by the dynamic user/group and removed automatically - when the unit is terminated. Defaults to off.</para></listitem> + cannot leave files around after unit termination. 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 whitelisted + using <varname>ReadWritePaths=</varname>, but care must be taken so that UID/GID recycling doesn't + create security issues involving files created by the service. Use <varname>RuntimeDirectory=</varname> (see + below) in order to assign a writable runtime directory to a service, owned by the dynamic user/group and + removed automatically when the unit is terminated. Defaults to off.</para></listitem> </varlistentry> <varlistentry> @@ -817,49 +821,37 @@ <listitem><para>Controls which capabilities to include in the capability bounding set for the executed process. See <citerefentry project='man-pages'><refentrytitle>capabilities</refentrytitle><manvolnum>7</manvolnum></citerefentry> for - details. Takes a whitespace-separated list of capability names as read by <citerefentry - project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be included in the bounding set, all others are - removed. If the list of capabilities is prefixed with <literal>~</literal>, all but the listed capabilities - will be included, the effect of the assignment inverted. Note that this option also affects the respective - capabilities in the effective, permitted and inheritable capability sets. If this option is not used, the - capability bounding set is not modified on process execution, hence no limits on the capabilities of the - process are enforced. This option may appear more than once, in which case the bounding sets are merged. If the - empty string is assigned to this option, the bounding set is reset to the empty capability set, and all prior - settings have no effect. If set to <literal>~</literal> (without any further argument), the bounding set is - reset to the full set of available capabilities, also undoing any previous settings. This does not affect - commands prefixed with <literal>+</literal>.</para></listitem> + details. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. Capabilities listed will be + included in the bounding set, all others are removed. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. Note that this option also affects the respective capabilities in the effective, permitted and + inheritable capability sets. If this option is not used, the capability bounding set is not modified on process + execution, hence no limits on the capabilities of the process are enforced. This option may appear more than + once, in which case the bounding sets are merged. If the empty string is assigned to this option, the bounding + set is reset to the empty capability set, and all prior settings have no effect. If set to + <literal>~</literal> (without any further argument), the bounding set is reset to the full set of available + capabilities, also undoing any previous settings. This does not affect commands prefixed with + <literal>+</literal>.</para></listitem> </varlistentry> <varlistentry> <term><varname>AmbientCapabilities=</varname></term> - <listitem><para>Controls which capabilities to include in the - ambient capability set for the executed process. Takes a - whitespace-separated list of capability names as read by - <citerefentry project='mankier'><refentrytitle>cap_from_name</refentrytitle><manvolnum>3</manvolnum></citerefentry>, - e.g. <constant>CAP_SYS_ADMIN</constant>, - <constant>CAP_DAC_OVERRIDE</constant>, - <constant>CAP_SYS_PTRACE</constant>. This option may appear more than - once in which case the ambient capability sets are merged. - If the list of capabilities is prefixed with <literal>~</literal>, all - but the listed capabilities will be included, the effect of the - assignment inverted. If the empty string is - assigned to this option, the ambient capability set is reset to - the empty capability set, and all prior settings have no effect. - If set to <literal>~</literal> (without any further argument), the - ambient capability set is reset to the full set of available - capabilities, also undoing any previous settings. Note that adding - capabilities to 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> 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></listitem> + <listitem><para>Controls which capabilities to include in the ambient capability set for the executed + process. Takes a whitespace-separated list of capability names, e.g. <constant>CAP_SYS_ADMIN</constant>, + <constant>CAP_DAC_OVERRIDE</constant>, <constant>CAP_SYS_PTRACE</constant>. This option may appear more than + once in which case the ambient capability sets are merged. If the list of capabilities is prefixed with + <literal>~</literal>, all but the listed capabilities will be included, the effect of the assignment + inverted. If the empty string is assigned to this option, the ambient capability set is reset to the empty + capability set, and all prior settings have no effect. If set to <literal>~</literal> (without any further + argument), the ambient capability set is reset to the full set of available capabilities, also undoing any + previous settings. Note that adding capabilities to 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> 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></listitem> </varlistentry> <varlistentry> @@ -885,48 +877,34 @@ <term><varname>ReadOnlyPaths=</varname></term> <term><varname>InaccessiblePaths=</varname></term> - <listitem><para>Sets up a new file system namespace for - executed processes. These options may be used to limit access - a process might have to the main file system hierarchy. Each - setting takes a space-separated list of paths relative to - the host's root directory (i.e. the system running the service manager). - Note that if entries contain symlinks, they are resolved from the host's root directory as well. - Entries (files or directories) listed in - <varname>ReadWritePaths=</varname> are accessible from - within the namespace with the same access rights as from - outside. Entries listed in - <varname>ReadOnlyPaths=</varname> are accessible for - reading only, writing will be refused even if the usual file - access controls would permit this. Entries listed in - <varname>InaccessiblePaths=</varname> will be made - inaccessible for processes inside the namespace, and may not - countain any other mountpoints, including those specified by - <varname>ReadWritePaths=</varname> or - <varname>ReadOnlyPaths=</varname>. - Note that restricting access with these options does not extend - to submounts of a directory that are created later on. - Non-directory paths can be specified as well. These - options may be specified more than once, in which case all - paths listed will have limited access from within the - namespace. If the empty string is assigned to this option, the - specific list is reset, and all prior assignments have no - effect.</para> - <para>Paths in - <varname>ReadOnlyPaths=</varname> - and - <varname>InaccessiblePaths=</varname> - may be prefixed with - <literal>-</literal>, in which case - they will be ignored when they do not - exist. Note that using this - setting will disconnect propagation of - mounts from the service to the host - (propagation in the opposite direction - continues to work). This means that - this setting may not be used for - services which shall be able to - install mount points in the main mount - namespace.</para></listitem> + <listitem><para>Sets up a new file system namespace for executed processes. These options may be used to limit + access a process might have to the file system hierarchy. Each setting takes a space-separated list of paths + relative to the host's root directory (i.e. the system running the service manager). Note that if paths + contain symlinks, they are resolved relative to the root directory set with + <varname>RootDirectory=</varname>.</para> + + <para>Paths listed in <varname>ReadWritePaths=</varname> are accessible from within the namespace with the same + access modes as from outside of it. Paths listed in <varname>ReadOnlyPaths=</varname> are accessible for + reading only, writing will be refused even if the usual file access controls would permit this. Nest + <varname>ReadWritePaths=</varname> inside of <varname>ReadOnlyPaths=</varname> in order to provide writable + subdirectories within read-only directories. Use <varname>ReadWritePaths=</varname> in order to whitelist + specific paths for write access if <varname>ProtectSystem=strict</varname> is used. Paths listed in + <varname>InaccessiblePaths=</varname> will be made inaccessible for processes inside the namespace (along with + everything below them in the file system hierarchy).</para> + + <para>Note that restricting access with these options does not extend to submounts of a directory that are + created later on. Non-directory paths may be specified as well. These options may be specified more than once, + in which case all paths listed will have limited access from within the namespace. If the empty string is + assigned to this option, the specific list is reset, and all prior assignments have no effect.</para> + + <para>Paths in <varname>ReadWritePaths=</varname>, <varname>ReadOnlyPaths=</varname> and + <varname>InaccessiblePaths=</varname> may be prefixed with <literal>-</literal>, in which case they will be ignored + when they do not exist. Note that using this setting will disconnect propagation of mounts from the service to + the host (propagation in the opposite direction continues to work). This means that this setting may not be used + for services which shall be able to install mount points in the main mount namespace. Note that the effect of + these settings may be undone by privileged processes. In order to set up an effective sandboxed environment for + a unit it is thus recommended to combine these settings with either + <varname>CapabilityBoundingSet=~CAP_SYS_ADMIN</varname> or <varname>SystemCallFilter=~@mount</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -941,37 +919,33 @@ private <filename>/tmp</filename> and <filename>/var/tmp</filename> namespace by using the <varname>JoinsNamespaceOf=</varname> directive, see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for - details. Note that using this setting will disconnect propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). This means that this setting may not be used for - services which shall be able to install mount points in the main mount namespace. This setting is implied if - <varname>DynamicUser=</varname> is set.</para></listitem> + details. This setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same + restrictions regarding mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and + related calls, see above.</para></listitem> + </varlistentry> <varlistentry> <term><varname>PrivateDevices=</varname></term> - <listitem><para>Takes a boolean argument. If true, sets up a - new /dev namespace for the executed processes and only adds - API pseudo devices such as <filename>/dev/null</filename>, - <filename>/dev/zero</filename> or - <filename>/dev/random</filename> (as well as the pseudo TTY - subsystem) to it, but no physical devices such as - <filename>/dev/sda</filename>. This is useful to securely turn - off physical device access by the executed process. Defaults - to false. Enabling this option will also remove - <constant>CAP_MKNOD</constant> from the capability bounding - set for the unit (see above), and set + <listitem><para>Takes a boolean argument. If true, sets up a new /dev namespace for the executed processes and + only adds API pseudo devices such as <filename>/dev/null</filename>, <filename>/dev/zero</filename> or + <filename>/dev/random</filename> (as well as the pseudo TTY subsystem) to it, but no physical devices such as + <filename>/dev/sda</filename>, system memory <filename>/dev/mem</filename>, system ports + <filename>/dev/port</filename> and others. This is useful to securely turn off physical device access by the + executed process. Defaults to false. Enabling this option will install a system call filter to block low-level + I/O system calls that are grouped in the <varname>@raw-io</varname> set, will also remove + <constant>CAP_MKNOD</constant> from the capability bounding set for the unit (see above), and set <varname>DevicePolicy=closed</varname> (see <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry> - for details). Note that using this setting will disconnect - propagation of mounts from the service to the host - (propagation in the opposite direction continues to work). - This means that this setting may not be used for services - which shall be able to install mount points in the main mount - namespace. The /dev namespace will be mounted read-only and 'noexec'. - The latter may break old programs which try to set up executable - memory by using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> - of <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>.</para></listitem> + for details). Note that using this setting will disconnect propagation of mounts from the service to the host + (propagation in the opposite direction continues to work). This means that this setting may not be used for + services which shall be able to install mount points in the main mount namespace. The /dev namespace will be + mounted read-only and 'noexec'. The latter may break old programs which try to set up executable memory by + using <citerefentry><refentrytitle>mmap</refentrytitle><manvolnum>2</manvolnum></citerefentry> of + <filename>/dev/zero</filename> instead of using <constant>MAP_ANON</constant>. This setting is implied if + <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding mount propagation and + privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> </varlistentry> <varlistentry> @@ -1020,74 +994,80 @@ <varlistentry> <term><varname>ProtectSystem=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>full</literal>. If true, mounts the - <filename>/usr</filename> and <filename>/boot</filename> - directories read-only for processes invoked by this unit. If - set to <literal>full</literal>, the <filename>/etc</filename> - directory is mounted read-only, too. This setting ensures that - any modification of the vendor-supplied operating system (and - optionally its configuration) is prohibited for the service. - It is recommended to enable this setting for all long-running - services, unless they are involved with system updates or need - to modify the operating system in other ways. Note however - that processes retaining the CAP_SYS_ADMIN capability can undo - the effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or the special values <literal>full</literal> or + <literal>strict</literal>. If true, mounts the <filename>/usr</filename> and <filename>/boot</filename> + directories read-only for processes invoked by this unit. If set to <literal>full</literal>, the + <filename>/etc</filename> directory is mounted read-only, too. If set to <literal>strict</literal> the entire + file system hierarchy is mounted read-only, except for the API file system subtrees <filename>/dev</filename>, + <filename>/proc</filename> and <filename>/sys</filename> (protect these directories using + <varname>PrivateDevices=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>). This setting ensures that any modification of the vendor-supplied + operating system (and optionally its configuration, and local mounts) is prohibited for the service. It is + recommended to enable this setting for all long-running services, unless they are involved with system updates + or need to modify the operating system in other ways. If this option is used, + <varname>ReadWritePaths=</varname> may be used to exclude specific directories from being made read-only. This + setting is implied if <varname>DynamicUser=</varname> is set. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>ProtectHome=</varname></term> - <listitem><para>Takes a boolean argument or - <literal>read-only</literal>. If true, the directories - <filename>/home</filename>, <filename>/root</filename> and - <filename>/run/user</filename> - are made inaccessible and empty for processes invoked by this - unit. If set to <literal>read-only</literal>, the three - directories are made read-only instead. It is recommended to - enable this setting for all long-running services (in - particular network-facing ones), to ensure they cannot get - access to private user data, unless the services actually - require access to the user's private data. Note however that - processes retaining the CAP_SYS_ADMIN capability can undo the - effect of this setting. This setting is hence particularly - useful for daemons which have this capability removed, for - example with <varname>CapabilityBoundingSet=</varname>. - Defaults to off.</para></listitem> + <listitem><para>Takes a boolean argument or <literal>read-only</literal>. If true, the directories + <filename>/home</filename>, <filename>/root</filename> and <filename>/run/user</filename> are made inaccessible + and empty for processes invoked by this unit. If set to <literal>read-only</literal>, the three directories are + made read-only instead. It is recommended to enable this setting for all long-running services (in particular + network-facing ones), to ensure they cannot get access to private user data, unless the services actually + require access to the user's private data. This setting is implied if <varname>DynamicUser=</varname> is + set. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectKernelTunables=</varname></term> + + <listitem><para>Takes a boolean argument. If true, kernel variables accessible through + <filename>/proc/sys</filename>, <filename>/sys</filename>, <filename>/proc/sysrq-trigger</filename>, + <filename>/proc/latency_stats</filename>, <filename>/proc/acpi</filename>, + <filename>/proc/timer_stats</filename>, <filename>/proc/fs</filename> and <filename>/proc/irq</filename> will + be made read-only to all processes of the unit. Usually, tunable kernel variables should only be written at + boot-time, with the <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> + mechanism. Almost no services need to write to these at runtime; it is hence recommended to turn this on for + most services. For this setting the same restrictions regarding mount propagation and privileges apply as for + <varname>ReadOnlyPaths=</varname> and related calls, see above. Defaults to off.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>ProtectControlGroups=</varname></term> + + <listitem><para>Takes a boolean argument. If true, the Linux Control Groups (<citerefentry + project='man-pages'><refentrytitle>cgroups</refentrytitle><manvolnum>7</manvolnum></citerefentry>) hierarchies + accessible through <filename>/sys/fs/cgroup</filename> will be made read-only to all processes of the + unit. Except for container managers no services should require write access to the control groups hierarchies; + it is hence recommended to turn this on for most services. For this setting the same restrictions regarding + mount propagation and privileges apply as for <varname>ReadOnlyPaths=</varname> and related calls, see + above. Defaults to off.</para></listitem> </varlistentry> <varlistentry> <term><varname>MountFlags=</varname></term> - <listitem><para>Takes a mount propagation flag: - <option>shared</option>, <option>slave</option> or - <option>private</option>, which control whether mounts in the - file system namespace set up for this unit's processes will - receive or propagate mounts or unmounts. See - <citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> - for details. Defaults to <option>shared</option>. Use - <option>shared</option> to ensure that mounts and unmounts are - propagated from the host to the container and vice versa. Use - <option>slave</option> to run processes so that none of their - mounts and unmounts will propagate to the host. Use - <option>private</option> to also ensure that no mounts and - unmounts from the host will propagate into the unit processes' - namespace. Note that <option>slave</option> means that file - systems mounted on the host might stay mounted continuously in - the unit's namespace, and thus keep the device busy. Note that - the file system namespace related options - (<varname>PrivateTmp=</varname>, - <varname>PrivateDevices=</varname>, - <varname>ProtectSystem=</varname>, - <varname>ProtectHome=</varname>, - <varname>ReadOnlyPaths=</varname>, - <varname>InaccessiblePaths=</varname> and - <varname>ReadWritePaths=</varname>) require that mount - and unmount propagation from the unit's file system namespace - is disabled, and hence downgrade <option>shared</option> to + <listitem><para>Takes a mount propagation flag: <option>shared</option>, <option>slave</option> or + <option>private</option>, which control whether mounts in the file system namespace set up for this unit's + processes will receive or propagate mounts or unmounts. See <citerefentry + project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>2</manvolnum></citerefentry> for + details. Defaults to <option>shared</option>. Use <option>shared</option> to ensure that mounts and unmounts + are propagated from the host to the container and vice versa. Use <option>slave</option> to run processes so + that none of their mounts and unmounts will propagate to the host. Use <option>private</option> to also ensure + that no mounts and unmounts from the host will propagate into the unit processes' namespace. Note that + <option>slave</option> means that file systems mounted on the host might stay mounted continuously in the + unit's namespace, and thus keep the device busy. Note that the file system namespace related options + (<varname>PrivateTmp=</varname>, <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, + <varname>ProtectHome=</varname>, <varname>ProtectKernelTunables=</varname>, + <varname>ProtectControlGroups=</varname>, <varname>ReadOnlyPaths=</varname>, + <varname>InaccessiblePaths=</varname>, <varname>ReadWritePaths=</varname>) require that mount and unmount + propagation from the unit's file system namespace is disabled, and hence downgrade <option>shared</option> to <option>slave</option>. </para></listitem> </varlistentry> @@ -1322,7 +1302,15 @@ </table> Note, that as new system calls are added to the kernel, additional system calls might be added to the groups - above, so the contents of the sets may change between systemd versions.</para></listitem> + above, so the contents of the sets may change between systemd versions.</para> + + <para>It is recommended to combine the file system namespacing related options with + <varname>SystemCallFilter=~@mount</varname>, in order to prohibit the unit's processes to undo the + mappings. Specifically these are the options <varname>PrivateTmp=</varname>, + <varname>PrivateDevices=</varname>, <varname>ProtectSystem=</varname>, <varname>ProtectHome=</varname>, + <varname>ProtectKernelTunables=</varname>, <varname>ProtectControlGroups=</varname>, + <varname>ReadOnlyPaths=</varname>, <varname>InaccessiblePaths=</varname> and + <varname>ReadWritePaths=</varname>.</para></listitem> </varlistentry> <varlistentry> @@ -1346,7 +1334,8 @@ identifiers to include in the system call filter. The known architecture identifiers are <constant>x86</constant>, <constant>x86-64</constant>, <constant>x32</constant>, - <constant>arm</constant> as well as the special identifier + <constant>arm</constant>, <constant>s390</constant>, + <constant>s390x</constant> as well as the special identifier <constant>native</constant>. Only system calls of the specified architectures will be permitted to processes of this unit. This is an effective way to disable compatibility with @@ -1629,8 +1618,8 @@ <varname>ExecStop=</varname> and <varname>ExecStopPost=</varname> processes, and encodes the service "result". Currently, the following values are defined: <literal>timeout</literal> (in case of an operation timeout), <literal>exit-code</literal> (if a service process exited with a non-zero exit code; see - <varname>$EXIT_STATUS</varname> below for the actual exit status returned), <literal>signal</literal> (if a - service process was terminated abnormally by a signal; see <varname>$EXIT_STATUS</varname> below for the actual + <varname>$EXIT_CODE</varname> below for the actual exit code returned), <literal>signal</literal> (if a + service process was terminated abnormally by a signal; see <varname>$EXIT_CODE</varname> below for the actual signal used for the termination), <literal>core-dump</literal> (if a service process terminated abnormally and dumped core), <literal>watchdog</literal> (if the watchdog keep-alive ping was enabled for the service but it missed the deadline), or <literal>resources</literal> (a catch-all condition in case a system operation @@ -1675,32 +1664,32 @@ <row> <entry morerows="1" valign="top"><literal>timeout</literal></entry> <entry valign="top"><literal>killed</literal></entry> - <entry><literal>TERM</literal><sbr/><literal>KILL</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> </row> <row> <entry valign="top"><literal>exited</literal></entry> - <entry><literal>0</literal><sbr/><literal>1</literal><sbr/><literal>2</literal><sbr/><literal - >3</literal><sbr/>…<sbr/><literal>255</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> </row> <row> <entry valign="top"><literal>exit-code</literal></entry> <entry valign="top"><literal>exited</literal></entry> - <entry><literal>0</literal><sbr/><literal>1</literal><sbr/><literal>2</literal><sbr/><literal - >3</literal><sbr/>…<sbr/><literal>255</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> </row> <row> <entry valign="top"><literal>signal</literal></entry> <entry valign="top"><literal>killed</literal></entry> - <entry><literal>HUP</literal><sbr/><literal>INT</literal><sbr/><literal>KILL</literal><sbr/>…</entry> + <entry><literal>HUP</literal>, <literal>INT</literal>, <literal>KILL</literal>, …</entry> </row> <row> <entry valign="top"><literal>core-dump</literal></entry> <entry valign="top"><literal>dumped</literal></entry> - <entry><literal>ABRT</literal><sbr/><literal>SEGV</literal><sbr/><literal>QUIT</literal><sbr/>…</entry> + <entry><literal>ABRT</literal>, <literal>SEGV</literal>, <literal>QUIT</literal>, …</entry> </row> <row> @@ -1710,12 +1699,12 @@ </row> <row> <entry><literal>killed</literal></entry> - <entry><literal>TERM</literal><sbr/><literal>KILL</literal></entry> + <entry><literal>TERM</literal>, <literal>KILL</literal></entry> </row> <row> <entry><literal>exited</literal></entry> - <entry><literal>0</literal><sbr/><literal>1</literal><sbr/><literal>2</literal><sbr/><literal - >3</literal><sbr/>…<sbr/><literal>255</literal></entry> + <entry><literal>0</literal>, <literal>1</literal>, <literal>2</literal>, <literal + >3</literal>, …, <literal>255</literal></entry> </row> <row> diff --git a/man/systemd.netdev.xml b/man/systemd.netdev.xml index e56708a648..e378e61dd1 100644 --- a/man/systemd.netdev.xml +++ b/man/systemd.netdev.xml @@ -58,31 +58,38 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Virtual Network Device files must have the extension - <filename>.netdev</filename>; other extensions are ignored. - Virtual network devices are created as soon as networkd is - started. If a netdev with the specified name already exists, - networkd will use that as-is rather than create its own. Note that - the settings of the pre-existing netdev will not be changed by + <para>The main Virtual Network Device file must have the extension <filename>.netdev</filename>; + other extensions are ignored. Virtual network devices are created as soon as networkd is + started. If a netdev with the specified name already exists, networkd will use that as-is rather + than create its own. Note that the settings of the pre-existing netdev will not be changed by networkd.</para> - <para>The <filename>.netdev</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> + <para>The <filename>.netdev</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the netdev file <filename>foo.netdev</filename>, a "drop-in" directory + <filename>foo.netdev.d/</filename> may exist. All files with the suffix <literal>.conf</literal> + from this directory will be parsed after the file itself is parsed. This is useful to alter or + add configuration settings, without having to modify the main configuration file. Each drop-in + file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> </refsect1> <refsect1> @@ -163,7 +170,10 @@ <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row> <row><entry><varname>vrf</varname></entry> - <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + <entry>A Virtual Routing and Forwarding (<ulink url="https://www.kernel.org/doc/Documentation/networking/vrf.txt">VRF</ulink>) interface to create separate routing and forwarding domains.</entry></row> + + <row><entry><varname>vcan</varname></entry> + <entry>The virtual CAN driver (vcan). Similar to the network loopback devices, vcan offers a virtual local CAN interface.</entry></row> </tbody> </tgroup> @@ -315,6 +325,26 @@ </listitem> </varlistentry> <varlistentry> + <term><varname>AgeingTimeSec=</varname></term> + <listitem> + <para>This specifies the number of seconds a MAC Address will be kept in + the forwarding database after having a packet received from this MAC Address.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem> + <para>The priority of the bridge. An integer between 0 and 65535. A lower value + means higher priority. The bridge having the lowest priority will be elected as root bridge.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DefaultPVID=</varname></term> + <listitem> + <para>This specifies the default port VLAN ID of a newly attached bridge port.</para> + </listitem> + </varlistentry> + <varlistentry> <term><varname>MulticastQuerier=</varname></term> <listitem> <para>A boolean. This setting controls the IFLA_BR_MCAST_QUERIER option in the kernel. @@ -524,6 +554,18 @@ <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para> </listitem> </varlistentry> + <varlistentry> + <term><varname>RemoteCheckSumTx=</varname></term> + <listitem> + <para>A boolean. When true, remote transmit checksum offload of VXLAN is turned on.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RemoteCheckSumRx=</varname></term> + <listitem> + <para>A boolean. When true, remote receive checksum offload in VXLAN is turned on.</para> + </listitem> + </varlistentry> <varlistentry> <term><varname>GroupPolicyExtension=</varname></term> <listitem> diff --git a/man/systemd.network.xml b/man/systemd.network.xml index c332cd7bdc..0af927db19 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -58,31 +58,40 @@ <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>. </para> - <para>Network files must have the extension - <filename>.network</filename>; other extensions are ignored. - Networks are applied to links whenever the links appear.</para> - - <para>The <filename>.network</filename> files are read from the - files located in the system network directory - <filename>/usr/lib/systemd/network</filename>, the volatile - runtime network directory - <filename>/run/systemd/network</filename> and the local - administration network directory - <filename>/etc/systemd/network</filename>. All configuration files - are collectively sorted and processed in lexical order, regardless - of the directories in which they live. However, files with - identical filenames replace each other. Files in - <filename>/etc</filename> have the highest priority, files in - <filename>/run</filename> take precedence over files with the same - name in <filename>/usr/lib</filename>. This can be used to - override a system-supplied configuration file with a local file if - needed. As a special case, an empty file (file size 0) or symlink - with the same name pointing to <filename>/dev/null</filename> - disables the configuration file entirely (it is "masked").</para> - - <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 nor IPv6LL enabled, - shall be considered to have no IPv6 support. IPv6 will be automatically disabled for that interface by writing "1" - to <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. + <para>The main network file must have the extension <filename>.network</filename>; other + extensions are ignored. Networks are applied to links whenever the links appear.</para> + + <para>The <filename>.network</filename> files are read from the files located in the system + network directory <filename>/usr/lib/systemd/network</filename>, the volatile runtime network + directory <filename>/run/systemd/network</filename> and the local administration network + directory <filename>/etc/systemd/network</filename>. All configuration files are collectively + sorted and processed in lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. Files in <filename>/etc</filename> + have the highest priority, files in <filename>/run</filename> take precedence over files with + the same name in <filename>/usr/lib</filename>. This can be used to override a system-supplied + configuration file with a local file if needed. As a special case, an empty file (file size 0) + or symlink with the same name pointing to <filename>/dev/null</filename> disables the + configuration file entirely (it is "masked").</para> + + <para>Along with the network file <filename>foo.network</filename>, a "drop-in" directory + <filename>foo.network.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings, without having to modify the main + configuration file. Each drop-in file must have appropriate section headers.</para> + + <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal> + directories can be placed in <filename>/usr/lib/systemd/network</filename> or + <filename>/run/systemd/network</filename> directories. Drop-in files in + <filename>/etc</filename> take precedence over those in <filename>/run</filename> which in turn + take precedence over those in <filename>/usr/lib</filename>. Drop-in files under any of these + directories take precedence over the main netdev file wherever located. (Of course, since + <filename>/run</filename> is temporary and <filename>/usr/lib</filename> is for vendors, it is + unlikely drop-ins should be used in either of those places.)</para> + + <para>Note that an interface without any static IPv6 addresses configured, and neither DHCPv6 + nor IPv6LL enabled, shall be considered to have no IPv6 support. IPv6 will be automatically + disabled for that interface by writing "1" to + <filename>/proc/sys/net/ipv6/conf/<replaceable>ifname</replaceable>/disable_ipv6</filename>. </para> </refsect1> @@ -458,24 +467,31 @@ <varlistentry> <term><varname>Domains=</varname></term> <listitem> - <para>The domains used for DNS host name resolution on this link. Takes a list of DNS domain names which - are used as search suffixes for extending single-label host names (host names containing no dots) to become - fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, each of - the specified search domains are appended to it in turn, converting it into a fully qualified domain name, - until one of them may be successfully resolved.</para> - - <para>The specified domains are also used for routing of DNS queries: look-ups for host names ending in the - domains specified here are preferably routed to the DNS servers configured for this interface. If a domain - name is prefixed with <literal>~</literal>, the domain name becomes a pure "routing" domain, is used for - DNS query routing purposes only and is not used in the described domain search logic. By specifying a - routing domain of <literal>~.</literal> (the tilde indicating definition of a routing domain, the dot - referring to the DNS root domain which is the implied suffix of all valid DNS names) it is possible to - route all DNS traffic preferably to the DNS server specified for this interface. The route domain logic is - particularly useful on multi-homed hosts with DNS servers serving particular private DNS zones on each - interface.</para> + <para>A list of domains which should be resolved using the DNS servers on this link. Each item in the list + should be a domain name, optionally prefixed with a tilde (<literal>~</literal>). The domains with the + prefix are called "routing-only domains". The domains without the prefix are called "search domains" and + are first used as search suffixes for extending single-label host names (host names containing no dots) to + become fully qualified domain names (FQDNs). If a single-label host name is resolved on this interface, + each of the specified search domains are appended to it in turn, converting it into a fully qualified + domain name, until one of them may be successfully resolved.</para> + + <para>Both "search" and "routing-only" domains are used for routing of DNS queries: look-ups for host names + ending in those domains (hence also single label names, if any "search domains" are listed), are routed to + the DNS servers configured for this interface. The domain routing logic is particularly useful on + multi-homed hosts with DNS servers serving particular private DNS zones on each interface.</para> + + <para>The "routing-only" domain <literal>~.</literal> (the tilde indicating definition of a routing domain, + the dot referring to the DNS root domain which is the implied suffix of all valid DNS names) has special + effect. It causes all DNS traffic which does not match another configured domain routing entry to be routed + to DNS servers specified for this interface. This setting is useful to prefer a certain set of DNS servers + if a link on which they are connected is available.</para> <para>This setting is read by - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> + <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>. + "Search domains" correspond to the <varname>domain</varname> and <varname>search</varname> entries in + <citerefentry><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Domain name routing has no equivalent in the traditional glibc API, which has no concept of domain + name servers limited to a specific link.</para> </listitem> </varlistentry> <varlistentry> @@ -908,6 +924,15 @@ DHCP server.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for DHCP routes (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> @@ -948,6 +973,16 @@ project='man-pages'><refentrytitle>resolv.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> </listitem> </varlistentry> + + <varlistentry> + <term><varname>RouteTable=<replaceable>num</replaceable></varname></term> + <listitem> + <para>The table identifier for the routes received in the Router Advertisement + (a number between 1 and 4294967295, or 0 to unset). + The table can be retrieved using <command>ip route show table <replaceable>num</replaceable></command>. + </para> + </listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index 26e5d3ce7b..d759e17289 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -294,10 +294,10 @@ <term><varname>ListenUSBFunction=</varname></term> <listitem><para>Specifies a <ulink url="https://www.kernel.org/doc/Documentation/usb/functionfs.txt">USB - FunctionFS</ulink> endpoint location to listen on, for + FunctionFS</ulink> endpoints location to listen on, for implementation of USB gadget functions. This expects an - absolute file system path as the argument. Behavior otherwise - is very similar to the <varname>ListenFIFO=</varname> + absolute file system path of functionfs mount point as the argument. + Behavior otherwise is very similar to the <varname>ListenFIFO=</varname> directive above. Use this to open the FunctionFS endpoint <filename>ep0</filename>. When using this option, the activated service has to have the @@ -445,7 +445,7 @@ <varlistentry> <term><varname>MaxConnectionsPerSource=</varname></term> <listitem><para>The maximum number of connections for a service per source IP address. - This is is very similar to the <varname>MaxConnections=</varname> directive + This is very similar to the <varname>MaxConnections=</varname> directive above. Disabled by default.</para> </listitem> </varlistentry> diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index f818e772a9..9778283fec 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -144,71 +144,71 @@ <option>false</option> and <option>off</option> are equivalent.</para> - <para>Time span values encoded in unit files can be written in various formats. A stand-alone number specifies a - time in seconds. If suffixed with a time unit, the unit is honored. A concatenation of multiple values with units - is supported, in which case the values are added up. Example: <literal>50</literal> refers to 50 seconds; - <literal>2min 200ms</literal> refers to 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units - are understood: <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, + <para>Time span values encoded in unit files can be written in various formats. A stand-alone + number specifies a time in seconds. If suffixed with a time unit, the unit is honored. A + concatenation of multiple values with units is supported, in which case the values are added + up. Example: <literal>50</literal> refers to 50 seconds; <literal>2min 200ms</literal> refers to + 2 minutes and 200 milliseconds, i.e. 120200 ms. The following time units are understood: + <literal>s</literal>, <literal>min</literal>, <literal>h</literal>, <literal>d</literal>, <literal>w</literal>, <literal>ms</literal>, <literal>us</literal>. For details see <citerefentry><refentrytitle>systemd.time</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para> - <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are ignored. This may be - used for commenting. Lines ending in a backslash are concatenated with the following line while reading and the - backslash is replaced by a space character. This may be used to wrap long lines.</para> - - <para>Units can be aliased (have an alternative name), by creating a symlink from the new name to the existing name - in one of the unit search paths. For example, <filename>systemd-networkd.service</filename> has the alias - <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the symlink - <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In addition, unit files may - specify aliases through the <varname>Alias=</varname> directive in the [Install] section; those aliases are only - effective when the unit is enabled. When the unit is enabled, symlinks will be created for those names, and removed - when the unit is disabled. For example, <filename>reboot.target</filename> specifies - <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever CTRL+ALT+DEL is - pressed. Alias names may be used in commands like <command>enable</command>, <command>disable</command>, - <command>start</command>, <command>stop</command>, <command>status</command>, …, and in unit dependency directives - <varname>Wants=</varname>, <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, - with the limitation that aliases specified through <varname>Alias=</varname> are only effective when the unit is - enabled. Aliases cannot be used with the <command>preset</command> command.</para> - - <para>Along with a unit file <filename>foo.service</filename>, the - directory <filename>foo.service.wants/</filename> may exist. All - unit files symlinked from such a directory are implicitly added as - dependencies of type <varname>Wants=</varname> to the unit. This - is useful to hook units into the start-up of other units, without - having to modify their unit files. For details about the semantics - of <varname>Wants=</varname>, see below. The preferred way to - create symlinks in the <filename>.wants/</filename> directory of a - unit file is with the <command>enable</command> command of the + <para>Empty lines and lines starting with <literal>#</literal> or <literal>;</literal> are + ignored. This may be used for commenting. Lines ending in a backslash are concatenated with the + following line while reading and the backslash is replaced by a space character. This may be + used to wrap long lines.</para> + + <para>Units can be aliased (have an alternative name), by creating a symlink from the new name + to the existing name in one of the unit search paths. For example, + <filename>systemd-networkd.service</filename> has the alias + <filename>dbus-org.freedesktop.network1.service</filename>, created during installation as the + symlink <filename>/usr/lib/systemd/system/dbus-org.freedesktop.network1.service</filename>. In + addition, unit files may specify aliases through the <varname>Alias=</varname> directive in the + [Install] section; those aliases are only effective when the unit is enabled. When the unit is + enabled, symlinks will be created for those names, and removed when the unit is disabled. For + example, <filename>reboot.target</filename> specifies + <varname>Alias=ctrl-alt-del.target</varname>, so when enabled it will be invoked whenever + CTRL+ALT+DEL is pressed. Alias names may be used in commands like <command>enable</command>, + <command>disable</command>, <command>start</command>, <command>stop</command>, + <command>status</command>, …, and in unit dependency directives <varname>Wants=</varname>, + <varname>Requires=</varname>, <varname>Before=</varname>, <varname>After=</varname>, …, with the + limitation that aliases specified through <varname>Alias=</varname> are only effective when the + unit is enabled. Aliases cannot be used with the <command>preset</command> command.</para> + + <para>Along with a unit file <filename>foo.service</filename>, the directory + <filename>foo.service.wants/</filename> may exist. All unit files symlinked from such a + directory are implicitly added as dependencies of type <varname>Wants=</varname> to the unit. + This is useful to hook units into the start-up of other units, without having to modify their + unit files. For details about the semantics of <varname>Wants=</varname>, see below. The + preferred way to create symlinks in the <filename>.wants/</filename> directory of a unit file is + with the <command>enable</command> command of the <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> - tool which reads information from the [Install] section of unit - files (see below). A similar functionality exists for - <varname>Requires=</varname> type dependencies as well, the - directory suffix is <filename>.requires/</filename> in this - case.</para> + tool which reads information from the [Install] section of unit files (see below). A similar + functionality exists for <varname>Requires=</varname> type dependencies as well, the directory + suffix is <filename>.requires/</filename> in this case.</para> <para>Along with a unit file <filename>foo.service</filename>, a "drop-in" directory - <filename>foo.service.d/</filename> may exist. All files with the suffix <literal>.conf</literal> from this - directory will be parsed after the file itself is parsed. This is useful to alter or add configuration settings for - a unit, without having to modify unit files. Each drop-in file must have appropriate section headers. Note that for - instantiated units, this logic will first look for the instance <literal>.d/</literal> subdirectory and read its - <literal>.conf</literal> files, followed by the template <literal>.d/</literal> subdirectory and the - <literal>.conf</literal> files there. Also note that settings from the <literal>[Install]</literal> section are not - honoured in drop-in unit files, and have no effect.</para> - - <para>In addition to <filename>/etc/systemd/system</filename>, - the drop-in <literal>.conf</literal> files for system services - can be placed in <filename>/usr/lib/systemd/system</filename> or - <filename>/run/systemd/system</filename> directories. Drop-in - files in <filename>/etc</filename> take precedence over those in - <filename>/run</filename> which in turn take precedence over - those in <filename>/usr/lib</filename>. Drop-in files under any of - these directories take precedence over unit files wherever located. - (Of course, since <filename>/run</filename> is temporary and - <filename>/usr/lib</filename> is for vendors, it is unlikely - drop-ins should be used in either of those places.)</para> - <!-- Note that we do not document .include here, as we - consider it mostly obsolete, and want people to - use .d/ drop-ins instead. --> + <filename>foo.service.d/</filename> may exist. All files with the suffix + <literal>.conf</literal> from this directory will be parsed after the file itself is + parsed. This is useful to alter or add configuration settings for a unit, without having to + modify unit files. Each drop-in file must have appropriate section headers. Note that for + instantiated units, this logic will first look for the instance <literal>.d/</literal> + subdirectory and read its <literal>.conf</literal> files, followed by the template + <literal>.d/</literal> subdirectory and the <literal>.conf</literal> files there. Also note that + settings from the <literal>[Install]</literal> section are not honoured in drop-in unit files, + and have no effect.</para> + + <para>In addition to <filename>/etc/systemd/system</filename>, the drop-in <literal>.d</literal> + directories for system services can be placed in <filename>/usr/lib/systemd/system</filename> or + <filename>/run/systemd/system</filename> directories. Drop-in files in <filename>/etc</filename> + take precedence over those in <filename>/run</filename> which in turn take precedence over those + in <filename>/usr/lib</filename>. Drop-in files under any of these directories take precedence + over unit files wherever located. (Of course, since <filename>/run</filename> is temporary and + <filename>/usr/lib</filename> is for vendors, it is unlikely drop-ins should be used in either + of those places.)</para> + + <!-- Note that we do not document .include here, as we consider it mostly obsolete, and want + people to use .d/ drop-ins instead. --> <para>Some unit names reflect paths existing in the file system namespace. Example: a device unit |