diff options
Diffstat (limited to 'man/systemd.network.xml')
| -rw-r--r-- | man/systemd.network.xml | 1317 |
1 files changed, 764 insertions, 553 deletions
diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 5f0a703..b0efd62 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -1,6 +1,6 @@ <?xml version='1.0'?> <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> <refentry id="systemd.network" conditional='ENABLE_NETWORKD' @@ -39,13 +39,14 @@ <para>The <filename>.network</filename> files are read from the files located in the system network directories <filename>/usr/lib/systemd/network</filename> and - <filename>/usr/local/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 alphanumeric order, regardless of the directories in which they live. However, files - with identical filenames replace each other. It is recommended that each filename is prefixed with - a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>). Otherwise, the - default <filename>.network</filename> files or those generated by + <filename>/usr/local/lib/systemd/network</filename> + <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />, + 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 alphanumeric order, regardless of the directories in which they + live. However, files with identical filenames replace each other. It is recommended that each filename is + prefixed with a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.network</filename>). + Otherwise, the default <filename>.network</filename> files or those generated by <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> may take precedence over user configured files. Files in <filename>/etc/</filename> have the highest priority, files in <filename>/run/</filename> take precedence over files with the same name under @@ -259,16 +260,16 @@ <varlistentry> <term><varname>RequiredForOnline=</varname></term> <listitem> - <para>Takes a boolean or a minimum operational state and an optional maximum operational - state. Please see + <para>Takes a boolean, a minimum operational state (e.g., <literal>carrier</literal>), or a range + of operational state separated with a colon (e.g., <literal>degraded:routable</literal>). + Please see <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for possible operational states. When <literal>yes</literal>, the network is deemed required when determining whether the system is online (including when running <command>systemd-networkd-wait-online</command>). When <literal>no</literal>, the network is ignored when determining the online state. When a minimum operational state and an optional - maximum operational state are set, <literal>yes</literal> is implied, and this controls the - minimum and maximum operational state required for the network interface to be considered - online.</para> + maximum operational state are set, <command>systemd-networkd-wait-online</command> deems that the + interface is online when the operational state is in the specified range.</para> <para>Defaults to <literal>yes</literal> when <varname>ActivationPolicy=</varname> is not set, or set to <literal>up</literal>, <literal>always-up</literal>, or @@ -283,6 +284,44 @@ skipped automatically by <command>systemd-networkd-wait-online</command> if <literal>RequiredForOnline=no</literal>.</para> + <para>The boolean value <literal>yes</literal> is translated as follows; + <variablelist> + <varlistentry> + <term><option>CAN devices</option></term> + <listitem> + <para><literal>carrier</literal>,</para> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + <varlistentry> + <term><option>Master devices, e.g. bond or bridge</option></term> + <listitem> + <para><literal>degraded-carrier</literal> with <varname>RequiredFamilyForOnline=any</varname>,</para> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + <varlistentry> + <term><option>Bonding port interfaces</option></term> + <listitem> + <para><literal>enslaved</literal>,</para> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + <varlistentry> + <term><option>Other interfaces</option></term> + <listitem> + <para><literal>degraded</literal>.</para> + <xi:include href="version-info.xml" xpointer="v236"/> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para>This setting can be overridden by the command line option for + <command>systemd-networkd-wait-online</command>. See + <citerefentry><refentrytitle>systemd-networkd-wait-online.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for more details.</para> + <xi:include href="version-info.xml" xpointer="v236"/> </listitem> </varlistentry> @@ -390,20 +429,28 @@ Defaults to <literal>no</literal>. Further settings for the DHCP server may be set in the [DHCPServer] section described below.</para> - <xi:include href="version-info.xml" xpointer="v215"/> + <para>Even if this is enabled, the DHCP server will not be started automatically and wait for the + persistent storage being ready to load/save leases in the storage, unless + <varname>RelayTarget=</varname> or <varname>PersistLeases=no</varname> are specified in the + [DHCPServer] section. It will be started after + <filename>systemd-networkd-persistent-storage.service</filename> is started, which calls + <command>networkctl persistent-storage yes</command>. See + <citerefentry><refentrytitle>networkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + for more details.</para> + + <xi:include href="version-info.xml" xpointer="v215"/> </listitem> </varlistentry> <varlistentry> <term><varname>LinkLocalAddressing=</varname></term> <listitem> - <para>Enables link-local address autoconfiguration. Accepts <option>yes</option>, - <option>no</option>, <option>ipv4</option>, and <option>ipv6</option>. An IPv6 link-local - address is configured when <option>yes</option> or <option>ipv6</option>. An IPv4 link-local - address is configured when <option>yes</option> or <option>ipv4</option> and when DHCPv4 - autoconfiguration has been unsuccessful for some time. (IPv4 link-local address - autoconfiguration will usually happen in parallel with repeated attempts to acquire a DHCPv4 - lease).</para> + <para>Enables link-local address autoconfiguration. Accepts a boolean, <option>ipv4</option>, + and <option>ipv6</option>. An IPv6 link-local address is configured when <option>yes</option> + or <option>ipv6</option>. An IPv4 link-local address is configured when <option>yes</option> + or <option>ipv4</option> and when DHCPv4 autoconfiguration has been unsuccessful for some time. + (IPv4 link-local address autoconfiguration will usually happen in parallel with repeated attempts + to acquire a DHCPv4 lease).</para> <para>Defaults to <option>no</option> when <varname>KeepMaster=</varname> or <varname>Bridge=</varname> is set or when the specified @@ -661,6 +708,9 @@ Table=1234</programlisting></para> number of dynamically created network interfaces with the same network configuration and automatic address range assignment.</para> + <para>If an empty string is specified, then the all previous assignments in both [Network] and + [Address] sections are cleared.</para> + <xi:include href="version-info.xml" xpointer="v211"/> </listitem> </varlistentry> @@ -698,6 +748,17 @@ Table=1234</programlisting></para> </varlistentry> <varlistentry> + <term><varname>UseDomains=</varname></term> + <listitem> + <para>Specifies the protocol-independent default value for the same settings in + [IPv6AcceptRA], [DHCPv4], and [DHCPv6] sections below. Takes a boolean, or the special value + <option>route</option>. See also the same setting in [DHCPv4] below. Defaults to unset.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>Domains=</varname></term> <listitem> <para>A whitespace-separated list of domains which should be resolved using the DNS servers @@ -762,26 +823,43 @@ Table=1234</programlisting></para> </varlistentry> <varlistentry> - <term><varname>IPForward=</varname></term> + <term><varname>IPv4Forwarding=</varname></term> <listitem> - <para>Configures IP packet forwarding for the system. If enabled, incoming packets on any - network interface will be forwarded to any other interfaces according to the routing table. - Takes a boolean, or the values <literal>ipv4</literal> or <literal>ipv6</literal>, which only - enable IP packet forwarding for the specified address family. This controls the - <filename>net.ipv4.ip_forward</filename> and <filename>net.ipv6.conf.all.forwarding</filename> - sysctl options of the network interface (see + <para>Configures IPv4 packet forwarding for the interface. Takes a boolean value. This controls the + <filename>net.ipv4.conf.<replaceable>INTERFACE</replaceable>.forwarding</filename> sysctl option of + the network interface. See <ulink url="https://docs.kernel.org/networking/ip-sysctl.html">IP Sysctl</ulink> - for details about sysctl options). Defaults to <literal>no</literal>.</para> + for more details about the sysctl option. Defaults to true if <varname>IPMasquerade=</varname> is + enabled for IPv4, otherwise the value specified to the same setting in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + will be used. If none of them are specified, the sysctl option will not be changed.</para> + + <para>To control the global setting, use the same setting in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> - <para>Note: this setting controls a global kernel option, and does so one way only: if a - network that has this setting enabled is set up the global setting is turned on. However, - it is never turned off again, even after all networks with this setting enabled are shut - down again.</para> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> - <para>To allow IP packet forwarding only between specific network interfaces use a firewall. + <varlistentry> + <term><varname>IPv6Forwarding=</varname></term> + <listitem> + <para>Configures IPv6 packet forwarding for the interface. Takes a boolean value. This controls the + <filename>net.ipv6.conf.<replaceable>INTERFACE</replaceable>.forwarding</filename> sysctl option of + the network interface. See + <ulink url="https://docs.kernel.org/networking/ip-sysctl.html">IP Sysctl</ulink> + for more details about the sysctl option. Defaults to true if <varname>IPMasquerade=</varname> is + enabled for IPv6 or <varname>IPv6SendRA=</varname> is enabled, otherwise the value specified to the + same setting in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + will be used. If none of them are specified, the sysctl option will not be changed.</para> + + <para>To control the global setting, use the same setting in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. </para> - <xi:include href="version-info.xml" xpointer="v219"/> + <xi:include href="version-info.xml" xpointer="v256"/> </listitem> </varlistentry> @@ -789,13 +867,20 @@ Table=1234</programlisting></para> <term><varname>IPMasquerade=</varname></term> <listitem> <para>Configures IP masquerading for the network interface. If enabled, packets forwarded - from the network interface will be appear as coming from the local host. Takes one of - <literal>ipv4</literal>, <literal>ipv6</literal>, <literal>both</literal>, or - <literal>no</literal>. Defaults to <literal>no</literal>. If enabled, this automatically sets - <varname>IPForward=</varname> to one of <literal>ipv4</literal>, <literal>ipv6</literal> or - <literal>yes</literal>.</para> - <para>Note. Any positive boolean values such as <literal>yes</literal> or - <literal>true</literal> are now deprecated. Please use one of the values above.</para> + from the network interface will be appear as coming from the local host. Typically, this should be + enabled on the downstream interface of routers. Takes one of <literal>ipv4</literal>, + <literal>ipv6</literal>, <literal>both</literal>, or <literal>no</literal>. Defaults to + <literal>no</literal>. Note. Any positive boolean values such as <literal>yes</literal> or + <literal>true</literal> are now deprecated. Please use one of the values above. Specifying + <literal>ipv4</literal> or <literal>both</literal> implies <varname>IPv4Forwarding=</varname>, + unless it is explicitly specified. Similarly for <varname>IPv6Forwarding=</varname> when + <literal>ipv6</literal> or <literal>both</literal> is specified. These implications are only on + this interface. Hence, to make the IP packet forwarding works, + <varname>IPv4Forwarding=</varname>/<varname>IPv6Forwarding=</varname> need to be enabled on an + upstream interface, or globally enabled by specifying them in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + See <varname>IPv4Forwarding=</varname>/<varname>IPv6Forwarding=</varname> in the above for more + details.</para> <xi:include href="version-info.xml" xpointer="v219"/> </listitem> @@ -823,12 +908,13 @@ Table=1234</programlisting></para> <varlistentry> <term><varname>IPv6AcceptRA=</varname></term> <listitem> - <para>Takes a boolean. Controls IPv6 Router Advertisement (RA) reception support for the - interface. If true, RAs are accepted; if false, RAs are ignored. When RAs are accepted, they - may trigger the start of the DHCPv6 client if the relevant flags are set in the RA data, or - if no routers are found on the link. The default is to disable RA reception for bridge - devices or when IP forwarding is enabled, and to enable it otherwise. Cannot be enabled on - devices aggregated in a bond device or when link-local addressing is disabled.</para> + <para>Takes a boolean. Controls IPv6 Router Advertisement (RA) reception support for the interface. + If true, RAs are accepted; if false, RAs are ignored. When RAs are accepted, they may trigger the + start of the DHCPv6 client if the relevant flags are set in the RA data, or if no routers are found + on the link. Defaults to false for bridge devices, when IP forwarding is enabled, + <varname>IPv6SendRA=</varname> or <varname>KeepMaster=</varname> is enabled. Otherwise, enabled by + default. Cannot be enabled on devices aggregated in a bond device or when link-local addressing is + disabled.</para> <para>Further settings for the IPv6 RA support may be configured in the [IPv6AcceptRA] section, see below.</para> @@ -872,6 +958,18 @@ Table=1234</programlisting></para> </varlistentry> <varlistentry> + <term><varname>IPv6RetransmissionTimeSec=</varname></term> + <listitem> + <para>Configures IPv6 Retransmission Time. The time between retransmitted Neighbor + Solicitation messages. Used by address resolution and the Neighbor Unreachability + Detection algorithm. A value of zero is ignored and the kernel's current value + will be used. Defaults to unset, and the kernel's current value will be used.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>IPv4ReversePathFilter=</varname></term> <listitem> <para>Configure IPv4 Reverse Path Filtering. If enabled, when an IPv4 packet is received, the machine will first check @@ -925,6 +1023,21 @@ Table=1234</programlisting></para> </varlistentry> <varlistentry> + <term><varname>IPv4ProxyARPPrivateVLAN=</varname></term> + <listitem> + <para>Takes a boolean. Configures proxy ARP private VLAN for IPv4, also known as VLAN aggregation, + private VLAN, source-port filtering, port-isolation, or MAC-forced forwarding.</para> + + <para>This variant of the ARP proxy technique will allow the ARP proxy to reply back to the same + interface.</para> + + <para>See <ulink url="https://tools.ietf.org/html/rfc3069">RFC 3069</ulink>. When unset, + the kernel's default will be used.</para> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>IPv6ProxyNDP=</varname></term> <listitem> <para>Takes a boolean. Configures proxy NDP for IPv6. Proxy NDP (Neighbor Discovery Protocol) @@ -965,6 +1078,9 @@ Table=1234</programlisting></para> distributed. See <varname>DHCPPrefixDelegation=</varname> setting and the [IPv6SendRA], [IPv6Prefix], [IPv6RoutePrefix], and [DHCPPrefixDelegation] sections for more configuration options.</para> + <para>If enabled, <varname>IPv6Forwarding=</varname> on this interface is also enabled, unless + the setting is explicitly specified. See <varname>IPv6Forwarding=</varname> in the above for more + details.</para> <xi:include href="version-info.xml" xpointer="v247"/> </listitem> @@ -1323,13 +1439,15 @@ Table=1234</programlisting></para> Fallback Peer Labeling</ulink> rules. They will be removed when the interface is deconfigured. Failures to manage the labels will be ignored.</para> - <para>Warning: Once labeling is enabled for network traffic, a lot of LSM access control points in - Linux networking stack go from dormant to active. Care should be taken to avoid getting into a - situation where for example remote connectivity is broken, when the security policy hasn't been - updated to consider LSM per-packet access controls and no rules would allow any network - traffic. Also note that additional configuration with <citerefentry - project='man-pages'><refentrytitle>netlabelctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> - is needed.</para> + <warning> + <para>Once labeling is enabled for network traffic, a lot of LSM access control points in + Linux networking stack go from dormant to active. Care should be taken to avoid getting into a + situation where for example remote connectivity is broken, when the security policy hasn't been + updated to consider LSM per-packet access controls and no rules would allow any network + traffic. Also note that additional configuration with <citerefentry + project='man-pages'><refentrytitle>netlabelctl</refentrytitle><manvolnum>8</manvolnum></citerefentry> + is needed.</para> + </warning> <para>Example: <programlisting>[Address] @@ -1602,6 +1720,18 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> </varlistentry> <varlistentry> + <term><varname>L3MasterDevice=</varname></term> + <listitem> + <para>A boolean. Specifies whether the rule is to direct lookups to the tables associated with + level 3 master devices (also known as Virtual Routing and Forwarding or VRF devices). + For further details see <ulink url="https://docs.kernel.org/networking/vrf.html"> + Virtual Routing and Forwarding (VRF)</ulink>. Defaults to false.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>SourcePort=</varname></term> <listitem> <para>Specifies the source IP port or IP port range match in forwarding information base @@ -1714,8 +1844,10 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> <varlistentry> <term><varname>Id=</varname></term> <listitem> - <para>The id of the next hop. Takes an integer in the range 1…4294967295. If unspecified, - then automatically chosen by kernel.</para> + <para>The id of the next hop. Takes an integer in the range 1…4294967295. + This is mandatory if <varname>ManageForeignNextHops=no</varname> is specified in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + Otherwise, if unspecified, an unused ID will be automatically picked.</para> <xi:include href="version-info.xml" xpointer="v244"/> </listitem> @@ -1921,7 +2053,7 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> <command>ip route show table <replaceable>num</replaceable></command>. If unset and <varname>Type=</varname> is <literal>local</literal>, <literal>broadcast</literal>, <literal>anycast</literal>, or <literal>nat</literal>, then <literal>local</literal> is used. - In other cases, defaults to <literal>main</literal>.</para> + In other cases, defaults to <literal>main</literal>. Ignored if <varname>L3MasterDevice=</varname> is true.</para> <xi:include href="version-info.xml" xpointer="v230"/> </listitem> @@ -2018,16 +2150,6 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> </varlistentry> <varlistentry> - <term><varname>TTLPropagate=</varname></term> - <listitem> - <para>Takes a boolean. When true enables TTL propagation at Label Switched Path (LSP) egress. - When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - - <varlistentry> <term><varname>MTUBytes=</varname></term> <listitem> <para>The maximum transmission unit in bytes to set for the route. The usual suffixes K, M, @@ -2267,7 +2389,7 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> are implied and these settings in the .network file are silently ignored. Also, <varname>Hostname=</varname>, <varname>MUDURL=</varname>, - <varname>RequestAddress</varname>, + <varname>RequestAddress=</varname>, <varname>RequestOptions=</varname>, <varname>SendOption=</varname>, <varname>SendVendorOption=</varname>, @@ -2472,7 +2594,15 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> effect of the <option>Domains=</option> setting. If set to <option>route</option>, the domain name received from the DHCP server will be used for routing DNS queries only, but not for searching, similarly to the effect of the <option>Domains=</option> setting when the argument is prefixed with - <literal>~</literal>. Defaults to false.</para> + <literal>~</literal>.</para> + + <para>When unspecified, the value specified in the same setting in the [Network] section will be + used. When it is unspecified, the value specified in the same setting in the [DHCPv4] section in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + will be used. When it is unspecified, the value specified in the same setting in the [Network] + section in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry> + will be used. When none of them are specified, defaults to <literal>no</literal>.</para> <para>It is recommended to enable this option only on trusted networks, as setting this affects resolution of all hostnames, in particular of single-label names. It is generally @@ -2663,13 +2793,22 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> </varlistentry> <varlistentry> + <term><varname>ServerPort=</varname></term> + <listitem> + <para>Set the port on which the DHCP server is listening.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>DenyList=</varname></term> <listitem> <para>A whitespace-separated list of IPv4 addresses. Each address can optionally take a prefix length after <literal>/</literal>. DHCP offers from servers in the list are rejected. Note that if <varname>AllowList=</varname> is configured then <varname>DenyList=</varname> is ignored.</para> - <para>Note that this filters only DHCP offers, so the filtering may not work when + <para>Note that this filters only DHCP offers, so the filtering might not work when <varname>RapidCommit=</varname> is enabled. See also <varname>RapidCommit=</varname> in the above. </para> @@ -2683,7 +2822,7 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> <para>A whitespace-separated list of IPv4 addresses. Each address can optionally take a prefix length after <literal>/</literal>. DHCP offers from servers in the list are accepted. </para> - <para>Note that this filters only DHCP offers, so the filtering may not work when + <para>Note that this filters only DHCP offers, so the filtering might not work when <varname>RapidCommit=</varname> is enabled. See also <varname>RapidCommit=</varname> in the above. </para> @@ -3085,6 +3224,16 @@ NFTSet=prefix:netdev:filter:eth_ipv4_prefix</programlisting> <variablelist class='network-directives'> <varlistentry> + <term><varname>UseRedirect=</varname></term> + <listitem> + <para>When true (the default), Redirect message sent by the current first-hop router will be + accepted, and configures routes to redirected nodes will be configured.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>Token=</varname></term> <listitem> <para>Specifies an optional address generation mode for the Stateless Address @@ -3274,12 +3423,25 @@ Token=prefixstable:2002:da8:1::</programlisting></para> </varlistentry> <varlistentry> - <term><varname>UseICMP6RateLimit=</varname></term> + <term><varname>UseReachableTime=</varname></term> <listitem> - <para>Takes a boolean. When true, the ICMP6 rate limit received in the Router Advertisement will be set to ICMP6 - rate limit based on the advertisement. Defaults to true.</para> + <para>Takes a boolean. When true, the reachable time received in the Router Advertisement will be + set on the interface receiving the advertisement. It is used as the base timespan of the validity + of a neighbor entry. Defaults to true.</para> - <xi:include href="version-info.xml" xpointer="v255"/> + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> + <term><varname>UseRetransmissionTime=</varname></term> + <listitem> + <para>Takes a boolean. When true, the retransmission time received in the Router Advertisement will be set + on the interface receiving the advertisement. It is used as the time between retransmissions of Neighbor + Solicitation messages to a neighbor when resolving the address or when probing the reachability of a neighbor. + Defaults to true.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> </listitem> </varlistentry> @@ -3786,6 +3948,22 @@ ServerAddress=192.168.0.1/24</programlisting> </listitem> </varlistentry> + <varlistentry> + <term><varname>PersistLeases=</varname></term> + <listitem> + <para>Takes a boolean. When true, the DHCP server will load and save leases in the persistent + storage. When false, the DHCP server will neither load nor save leases in the persistent storage. + Hence, bound leases will be lost when the interface is reconfigured e.g. by + <command>networkctl reconfigure</command>, or <filename>systemd-networkd.service</filename> + is restarted. That may cause address conflict on the network. So, please take an extra care when + disable this setting. When unspecified, the value specified in the same setting in + <citerefentry><refentrytitle>networkd.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, + which defaults to <literal>yes</literal>, will be used.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + </variablelist> </refsect1> @@ -3852,13 +4030,28 @@ ServerAddress=192.168.0.1/24</programlisting> </varlistentry> <varlistentry> + <term><varname>ReachableTimeSec=</varname></term> + + <listitem> + <para>Configures the time, used in the Neighbor Unreachability Detection algorithm, for which + clients can assume a neighbor is reachable after having received a reachability confirmation. Takes + a time span in the range 0…4294967295 ms. When 0, clients will handle it as if the value wasn't + specified. Defaults to 0.</para> + + <xi:include href="version-info.xml" xpointer="v256"/> + </listitem> + </varlistentry> + + <varlistentry> <term><varname>RetransmitSec=</varname></term> - <listitem><para>Takes a timespan. Configures the retransmit time, used by clients to retransmit Neighbor - Solicitation messages on address resolution and the Neighbor Unreachability Detection algorithm. - An integer, the default unit is seconds, in the range 0…4294967295 msec. Defaults to 0.</para> + <listitem> + <para>Configures the time, used in the Neighbor Unreachability Detection algorithm, for which + clients can use as retransmit time on address resolution and the Neighbor Unreachability Detection + algorithm. Takes a time span in the range 0…4294967295 ms. When 0, clients will handle it as if + the value wasn't specified. Defaults to 0.</para> - <xi:include href="version-info.xml" xpointer="v255"/> + <xi:include href="version-info.xml" xpointer="v255"/> </listitem> </varlistentry> @@ -3974,9 +4167,9 @@ ServerAddress=192.168.0.1/24</programlisting> </varlistentry> </variablelist> - </refsect1> + </refsect1> - <refsect1> + <refsect1> <title>[IPv6Prefix] Section Options</title> <para>One or more [IPv6Prefix] sections contain the IPv6 prefixes that are announced via Router Advertisements. See <ulink url="https://tools.ietf.org/html/rfc4861">RFC 4861</ulink> for further @@ -4051,9 +4244,9 @@ ServerAddress=192.168.0.1/24</programlisting> </listitem> </varlistentry> </variablelist> - </refsect1> + </refsect1> - <refsect1> + <refsect1> <title>[IPv6RoutePrefix] Section Options</title> <para>One or more [IPv6RoutePrefix] sections contain the IPv6 prefix routes that are announced via Router Advertisements. See @@ -4083,9 +4276,9 @@ ServerAddress=192.168.0.1/24</programlisting> </varlistentry> </variablelist> - </refsect1> + </refsect1> - <refsect1> + <refsect1> <title>[IPv6PREF64Prefix] Section Options</title> <para>One or more [IPv6PREF64Prefix] sections contain the IPv6 PREF64 (or NAT64) prefixes that are announced via Router Advertisements. See <ulink url="https://tools.ietf.org/html/rfc8781">RFC 8781</ulink> for further @@ -4112,480 +4305,486 @@ ServerAddress=192.168.0.1/24</programlisting> <xi:include href="version-info.xml" xpointer="v255"/></listitem> </varlistentry> </variablelist> - </refsect1> + </refsect1> - <refsect1> + <refsect1> <title>[Bridge] Section Options</title> - <para>The [Bridge] section accepts the following keys:</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>UnicastFlood=</varname></term> - <listitem> - <para>Takes a boolean. Controls whether the bridge should flood - traffic for which an FDB entry is missing and the destination - is unknown through this port. When unset, the kernel's default will be used. - </para> - - <xi:include href="version-info.xml" xpointer="v223"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastFlood=</varname></term> - <listitem> - <para>Takes a boolean. Controls whether the bridge should flood - traffic for which an MDB entry is missing and the destination - is unknown through this port. When unset, the kernel's default will be used. - </para> - - <xi:include href="version-info.xml" xpointer="v242"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastToUnicast=</varname></term> - <listitem> - <para>Takes a boolean. Multicast to unicast works on top of the multicast snooping feature of - the bridge. Which means unicast copies are only delivered to hosts which are interested in it. - When unset, the kernel's default will be used. - </para> - - <xi:include href="version-info.xml" xpointer="v240"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>NeighborSuppression=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether ARP and ND neighbor suppression is enabled for - this port. When unset, the kernel's default will be used. - </para> - - <xi:include href="version-info.xml" xpointer="v242"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Learning=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether MAC address learning is enabled for - this port. When unset, the kernel's default will be used. - </para> - - <xi:include href="version-info.xml" xpointer="v242"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>HairPin=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether traffic may be sent back out of the port on which it - was received. When this flag is false, then the bridge will not forward traffic back out of the - receiving port. When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v223"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Isolated=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether this port is isolated or not. Within a bridge, - isolated ports can only communicate with non-isolated ports. When set to true, this port can only - communicate with other ports whose Isolated setting is false. When set to false, this port - can communicate with any other ports. When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v251"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>UseBPDU=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether STP Bridge Protocol Data Units will be - processed by the bridge port. When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v223"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FastLeave=</varname></term> - <listitem> - <para>Takes a boolean. This flag allows the bridge to immediately stop multicast - traffic on a port that receives an IGMP Leave message. It is only used with - IGMP snooping if enabled on the bridge. When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v223"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>AllowPortToBeRoot=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether a given port is allowed to - become a root port. Only used when STP is enabled on the bridge. - When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v223"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ProxyARP=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether proxy ARP to be enabled on this port. - When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ProxyARPWiFi=</varname></term> - <listitem> - <para>Takes a boolean. Configures whether proxy ARP to be enabled on this port - which meets extended requirements by IEEE 802.11 and Hotspot 2.0 specifications. - When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>MulticastRouter=</varname></term> - <listitem> - <para>Configures this port for having multicast routers attached. A port with a multicast - router will receive all multicast traffic. Takes one of <literal>no</literal> - to disable multicast routers on this port, <literal>query</literal> to let the system detect - the presence of routers, <literal>permanent</literal> to permanently enable multicast traffic - forwarding on this port, or <literal>temporary</literal> to enable multicast routers temporarily - on this port, not depending on incoming queries. When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Cost=</varname></term> - <listitem> - <para>Sets the "cost" of sending packets of this interface. - Each port in a bridge may have a different speed and the cost - is used to decide which link to use. Faster interfaces - should have lower costs. It is an integer value between 1 and - 65535.</para> - - <xi:include href="version-info.xml" xpointer="v218"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Priority=</varname></term> - <listitem> - <para>Sets the "priority" of sending packets on this interface. - Each port in a bridge may have a different priority which is used - to decide which link to use. Lower value means higher priority. - It is an integer value between 0 to 63. Networkd does not set any - default, meaning the kernel default value of 32 is used.</para> - - <xi:include href="version-info.xml" xpointer="v234"/> - </listitem> - </varlistentry> - </variablelist> + <para>The [Bridge] section accepts the following keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>UnicastFlood=</varname></term> + <listitem> + <para>Takes a boolean. Controls whether the bridge should flood + traffic for which an FDB entry is missing and the destination + is unknown through this port. When unset, the kernel's default will be used. + </para> + + <xi:include href="version-info.xml" xpointer="v223"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastFlood=</varname></term> + <listitem> + <para>Takes a boolean. Controls whether the bridge should flood + traffic for which an MDB entry is missing and the destination + is unknown through this port. When unset, the kernel's default will be used. + </para> + + <xi:include href="version-info.xml" xpointer="v242"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastToUnicast=</varname></term> + <listitem> + <para>Takes a boolean. Multicast to unicast works on top of the multicast snooping feature of + the bridge. Which means unicast copies are only delivered to hosts which are interested in it. + When unset, the kernel's default will be used. + </para> + + <xi:include href="version-info.xml" xpointer="v240"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>NeighborSuppression=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether ARP and ND neighbor suppression is enabled for + this port. When unset, the kernel's default will be used. + </para> + + <xi:include href="version-info.xml" xpointer="v242"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Learning=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether MAC address learning is enabled for + this port. When unset, the kernel's default will be used. + </para> + + <xi:include href="version-info.xml" xpointer="v242"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>HairPin=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether traffic may be sent back out of the port on which it + was received. When this flag is false, then the bridge will not forward traffic back out of the + receiving port. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v223"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Isolated=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether this port is isolated or not. Within a bridge, + isolated ports can only communicate with non-isolated ports. When set to true, this port can only + communicate with other ports whose Isolated setting is false. When set to false, this port + can communicate with any other ports. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v251"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>UseBPDU=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether STP Bridge Protocol Data Units will be + processed by the bridge port. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v223"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FastLeave=</varname></term> + <listitem> + <para>Takes a boolean. This flag allows the bridge to immediately stop multicast + traffic on a port that receives an IGMP Leave message. It is only used with + IGMP snooping if enabled on the bridge. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v223"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AllowPortToBeRoot=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether a given port is allowed to + become a root port. Only used when STP is enabled on the bridge. + When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v223"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ProxyARP=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether proxy ARP to be enabled on this port. + When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v243"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ProxyARPWiFi=</varname></term> + <listitem> + <para>Takes a boolean. Configures whether proxy ARP to be enabled on this port + which meets extended requirements by IEEE 802.11 and Hotspot 2.0 specifications. + When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v243"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>MulticastRouter=</varname></term> + <listitem> + <para>Configures this port for having multicast routers attached. A port with a multicast + router will receive all multicast traffic. Takes one of <literal>no</literal> + to disable multicast routers on this port, <literal>query</literal> to let the system detect + the presence of routers, <literal>permanent</literal> to permanently enable multicast traffic + forwarding on this port, or <literal>temporary</literal> to enable multicast routers temporarily + on this port, not depending on incoming queries. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v243"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Cost=</varname></term> + <listitem> + <para>Sets the "cost" of sending packets of this interface. + Each port in a bridge may have a different speed and the cost + is used to decide which link to use. Faster interfaces + should have lower costs. It is an integer value between 1 and + 65535.</para> + + <xi:include href="version-info.xml" xpointer="v218"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Priority=</varname></term> + <listitem> + <para>Sets the "priority" of sending packets on this interface. + Each port in a bridge may have a different priority which is used + to decide which link to use. Lower value means higher priority. + It is an integer value between 0 to 63. Networkd does not set any + default, meaning the kernel default value of 32 is used.</para> + + <xi:include href="version-info.xml" xpointer="v234"/> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1> <title>[BridgeFDB] Section Options</title> - <para>The [BridgeFDB] section manages the forwarding database table of a port and accepts the following - keys. Specify several [BridgeFDB] sections to configure several static MAC table entries.</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MACAddress=</varname></term> - <listitem> - <para>As in the [Network] section. This key is mandatory.</para> + <para>The [BridgeFDB] section manages the forwarding database table of a port and accepts the following + keys. Specify several [BridgeFDB] sections to configure several static MAC table entries.</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MACAddress=</varname></term> + <listitem> + <para>As in the [Network] section. This key is mandatory.</para> <xi:include href="version-info.xml" xpointer="v219"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Destination=</varname></term> - <listitem> - <para>Takes an IP address of the destination VXLAN tunnel endpoint.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Destination=</varname></term> + <listitem> + <para>Takes an IP address of the destination VXLAN tunnel endpoint.</para> <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLANId=</varname></term> - <listitem> - <para>The VLAN ID for the new static MAC table entry. If - omitted, no VLAN ID information is appended to the new static MAC - table entry.</para> - - <xi:include href="version-info.xml" xpointer="v219"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VNI=</varname></term> - <listitem> - <para>The VXLAN Network Identifier (or VXLAN Segment ID) to use to connect to - the remote VXLAN tunnel endpoint. Takes a number in the range 1…16777215. - Defaults to unset.</para> - - <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>AssociatedWith=</varname></term> - <listitem> - <para>Specifies where the address is associated with. Takes one of <literal>use</literal>, - <literal>self</literal>, <literal>master</literal> or <literal>router</literal>. - <literal>use</literal> means the address is in use. User space can use this option to - indicate to the kernel that the fdb entry is in use. <literal>self</literal> means - the address is associated with the port drivers fdb. Usually hardware. <literal>master</literal> - means the address is associated with master devices fdb. <literal>router</literal> means - the destination address is associated with a router. Note that it's valid if the referenced - device is a VXLAN type device and has route shortcircuit enabled. Defaults to <literal>self</literal>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLANId=</varname></term> + <listitem> + <para>The VLAN ID for the new static MAC table entry. If + omitted, no VLAN ID information is appended to the new static MAC + table entry.</para> + + <xi:include href="version-info.xml" xpointer="v219"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VNI=</varname></term> + <listitem> + <para>The VXLAN Network Identifier (or VXLAN Segment ID) to use to connect to + the remote VXLAN tunnel endpoint. Takes a number in the range 1…16777215. + Defaults to unset.</para> <xi:include href="version-info.xml" xpointer="v243"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>OutgoingInterface=</varname></term> - <listitem> - <para>Specifies the name or index of the outgoing interface for the VXLAN device driver to - reach the remote VXLAN tunnel endpoint. Defaults to unset.</para> - - <xi:include href="version-info.xml" xpointer="v249"/> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>AssociatedWith=</varname></term> + <listitem> + <para>Specifies where the address is associated with. Takes one of <literal>use</literal>, + <literal>self</literal>, <literal>master</literal> or <literal>router</literal>. + <literal>use</literal> means the address is in use. User space can use this option to + indicate to the kernel that the fdb entry is in use. <literal>self</literal> means + the address is associated with the port drivers fdb. Usually hardware. <literal>master</literal> + means the address is associated with master devices fdb. <literal>router</literal> means + the destination address is associated with a router. Note that it's valid if the referenced + device is a VXLAN type device and has route shortcircuit enabled. Defaults to <literal>self</literal>.</para> + + <xi:include href="version-info.xml" xpointer="v243"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OutgoingInterface=</varname></term> + <listitem> + <para>Specifies the name or index of the outgoing interface for the VXLAN device driver to + reach the remote VXLAN tunnel endpoint. Defaults to unset.</para> + + <xi:include href="version-info.xml" xpointer="v249"/> + </listitem> + </varlistentry> + </variablelist> </refsect1> + <refsect1> <title>[BridgeMDB] Section Options</title> - <para>The [BridgeMDB] section manages the multicast membership entries forwarding database table of a port and accepts the following - keys. Specify several [BridgeMDB] sections to configure several permanent multicast membership entries.</para> + <para>The [BridgeMDB] section manages the multicast membership entries forwarding database table of a port and accepts the following + keys. Specify several [BridgeMDB] sections to configure several permanent multicast membership entries.</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MulticastGroupAddress=</varname></term> - <listitem> - <para>Specifies the IPv4 or IPv6 multicast group address to add. This setting is mandatory.</para> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MulticastGroupAddress=</varname></term> + <listitem> + <para>Specifies the IPv4 or IPv6 multicast group address to add. This setting is mandatory.</para> <xi:include href="version-info.xml" xpointer="v247"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>VLANId=</varname></term> - <listitem> - <para>The VLAN ID for the new entry. Valid ranges are 0 (no VLAN) to 4094. Optional, defaults to 0.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>VLANId=</varname></term> + <listitem> + <para>The VLAN ID for the new entry. Valid ranges are 0 (no VLAN) to 4094. Optional, defaults to 0.</para> <xi:include href="version-info.xml" xpointer="v247"/> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> <title>[LLDP] Section Options</title> - <para>The [LLDP] section manages the Link Layer Discovery Protocol (LLDP) and accepts the following - keys:</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>MUDURL=</varname></term> - <listitem> - <para>When configured, the specified Manufacturer Usage Descriptions (MUD) URL will be sent in - LLDP packets. The syntax and semantics are the same as for <varname>MUDURL=</varname> in the - [DHCPv4] section described above.</para> - - <para>The MUD URLs received via LLDP packets are saved and can be read using the - <function>sd_lldp_neighbor_get_mud_url()</function> function.</para> - - <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - </variablelist> + <para>The [LLDP] section manages the Link Layer Discovery Protocol (LLDP) and accepts the following + keys:</para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>MUDURL=</varname></term> + <listitem> + <para>When configured, the specified Manufacturer Usage Descriptions (MUD) URL will be sent in + LLDP packets. The syntax and semantics are the same as for <varname>MUDURL=</varname> in the + [DHCPv4] section described above.</para> + + <para>The MUD URLs received via LLDP packets are saved and can be read using the + <function>sd_lldp_neighbor_get_mud_url()</function> function.</para> + + <xi:include href="version-info.xml" xpointer="v246"/> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> <title>[CAN] Section Options</title> - <para>The [CAN] section manages the Controller Area Network (CAN bus) and accepts the - following keys:</para> - <variablelist class='network-directives'> - <varlistentry> - <term><varname>BitRate=</varname></term> - <listitem> - <para>The bitrate of CAN device in bits per second. The usual SI prefixes (K, M) with the base of 1000 can - be used here. Takes a number in the range 1…4294967295.</para> - - <xi:include href="version-info.xml" xpointer="v239"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>SamplePoint=</varname></term> - <listitem> - <para>Optional sample point in percent with one decimal (e.g. <literal>75%</literal>, - <literal>87.5%</literal>) or permille (e.g. <literal>875‰</literal>). This will be ignored when - <varname>BitRate=</varname> is unspecified.</para> + <para>The [CAN] section manages the Controller Area Network (CAN bus) and accepts the + following keys:</para> + <variablelist class='network-directives'> + <varlistentry> + <term><varname>BitRate=</varname></term> + <listitem> + <para>The bitrate of CAN device in bits per second. The usual SI prefixes (K, M) with the base of 1000 can + be used here. Takes a number in the range 1…4294967295.</para> + + <xi:include href="version-info.xml" xpointer="v239"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>SamplePoint=</varname></term> + <listitem> + <para>Optional sample point in percent with one decimal (e.g. <literal>75%</literal>, + <literal>87.5%</literal>) or permille (e.g. <literal>875‰</literal>). This will be ignored when + <varname>BitRate=</varname> is unspecified.</para> <xi:include href="version-info.xml" xpointer="v239"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TimeQuantaNSec=</varname></term> - <term><varname>PropagationSegment=</varname></term> - <term><varname>PhaseBufferSegment1=</varname></term> - <term><varname>PhaseBufferSegment2=</varname></term> - <term><varname>SyncJumpWidth=</varname></term> - <listitem> - <para>Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the - synchronization jump width, which allow one to define the CAN bit-timing in a hardware - independent format as proposed by the Bosch CAN 2.0 Specification. - <varname>TimeQuantaNSec=</varname> takes a timespan in nanoseconds. - <varname>PropagationSegment=</varname>, <varname>PhaseBufferSegment1=</varname>, - <varname>PhaseBufferSegment2=</varname>, and <varname>SyncJumpWidth=</varname> take number - of time quantum specified in <varname>TimeQuantaNSec=</varname> and must be an unsigned - integer in the range 0…4294967295. These settings except for - <varname>SyncJumpWidth=</varname> will be ignored when <varname>BitRate=</varname> is - specified.</para> - - <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DataBitRate=</varname></term> - <term><varname>DataSamplePoint=</varname></term> - <listitem> - <para>The bitrate and sample point for the data phase, if CAN-FD is used. These settings are - analogous to the <varname>BitRate=</varname> and <varname>SamplePoint=</varname> keys.</para> - - <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>DataTimeQuantaNSec=</varname></term> - <term><varname>DataPropagationSegment=</varname></term> - <term><varname>DataPhaseBufferSegment1=</varname></term> - <term><varname>DataPhaseBufferSegment2=</varname></term> - <term><varname>DataSyncJumpWidth=</varname></term> - <listitem> - <para>Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the - synchronization jump width for the data phase, if CAN-FD is used. These settings are - analogous to the <varname>TimeQuantaNSec=</varname> or related settings.</para> - - <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FDMode=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, CAN-FD mode is enabled for the interface. - Note, that a bitrate and optional sample point should also be set for the CAN-FD data phase using - the <varname>DataBitRate=</varname> and <varname>DataSamplePoint=</varname> keys, or - <varname>DataTimeQuanta=</varname> and related settings.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TimeQuantaNSec=</varname></term> + <term><varname>PropagationSegment=</varname></term> + <term><varname>PhaseBufferSegment1=</varname></term> + <term><varname>PhaseBufferSegment2=</varname></term> + <term><varname>SyncJumpWidth=</varname></term> + <listitem> + <para>Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the + synchronization jump width, which allow one to define the CAN bit-timing in a hardware + independent format as proposed by the Bosch CAN 2.0 Specification. + <varname>TimeQuantaNSec=</varname> takes a timespan in nanoseconds. + <varname>PropagationSegment=</varname>, <varname>PhaseBufferSegment1=</varname>, + <varname>PhaseBufferSegment2=</varname>, and <varname>SyncJumpWidth=</varname> take number + of time quantum specified in <varname>TimeQuantaNSec=</varname> and must be an unsigned + integer in the range 0…4294967295. These settings except for + <varname>SyncJumpWidth=</varname> will be ignored when <varname>BitRate=</varname> is + specified.</para> + + <xi:include href="version-info.xml" xpointer="v250"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DataBitRate=</varname></term> + <term><varname>DataSamplePoint=</varname></term> + <listitem> + <para>The bitrate and sample point for the data phase, if CAN-FD is used. These settings are + analogous to the <varname>BitRate=</varname> and <varname>SamplePoint=</varname> keys.</para> <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>FDNonISO=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, non-ISO CAN-FD mode is enabled for the - interface. When unset, the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>DataTimeQuantaNSec=</varname></term> + <term><varname>DataPropagationSegment=</varname></term> + <term><varname>DataPhaseBufferSegment1=</varname></term> + <term><varname>DataPhaseBufferSegment2=</varname></term> + <term><varname>DataSyncJumpWidth=</varname></term> + <listitem> + <para>Specifies the time quanta, propagation segment, phase buffer segment 1 and 2, and the + synchronization jump width for the data phase, if CAN-FD is used. These settings are + analogous to the <varname>TimeQuantaNSec=</varname> or related settings.</para> + + <xi:include href="version-info.xml" xpointer="v250"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FDMode=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, CAN-FD mode is enabled for the interface. + Note, that a bitrate and optional sample point should also be set for the CAN-FD data phase using + the <varname>DataBitRate=</varname> and <varname>DataSamplePoint=</varname> keys, or + <varname>DataTimeQuanta=</varname> and related settings.</para> + + <xi:include href="version-info.xml" xpointer="v246"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>FDNonISO=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, non-ISO CAN-FD mode is enabled for the + interface. When unset, the kernel's default will be used.</para> + + <xi:include href="version-info.xml" xpointer="v246"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>RestartSec=</varname></term> + <listitem> + <para>Automatic restart delay time. If set to a non-zero value, a restart of the CAN controller will be + 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> + + <xi:include href="version-info.xml" xpointer="v239"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Termination=</varname></term> + <listitem> + <para>Takes a boolean or a termination resistor value in ohm in the range 0…65535. When + <literal>yes</literal>, the termination resistor is set to 120 ohm. When + <literal>no</literal> or <literal>0</literal> is set, the termination resistor is disabled. + When unset, the kernel's default will be used.</para> <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>RestartSec=</varname></term> - <listitem> - <para>Automatic restart delay time. If set to a non-zero value, a restart of the CAN controller will be - 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> - - <xi:include href="version-info.xml" xpointer="v239"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Termination=</varname></term> - <listitem> - <para>Takes a boolean or a termination resistor value in ohm in the range 0…65535. When - <literal>yes</literal>, the termination resistor is set to 120 ohm. When - <literal>no</literal> or <literal>0</literal> is set, the termination resistor is disabled. - When unset, the kernel's default will be used.</para> - - <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>TripleSampling=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, three samples (instead of one) are used to determine - the value of a received bit by majority rule. When unset, the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>TripleSampling=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, three samples (instead of one) are used to determine + the value of a received bit by majority rule. When unset, the kernel's default will be used.</para> <xi:include href="version-info.xml" xpointer="v242"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>BusErrorReporting=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, reporting of CAN bus errors is activated - (those include single bit, frame format, and bit stuffing errors, unable to send dominant bit, - unable to send recessive bit, bus overload, active error announcement, error occurred on - transmission). When unset, the kernel's default will be used. Note: in case of a CAN bus with a - single CAN device, sending a CAN frame may result in a huge number of CAN bus errors.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>BusErrorReporting=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, reporting of CAN bus errors is activated + (those include single bit, frame format, and bit stuffing errors, unable to send dominant bit, + unable to send recessive bit, bus overload, active error announcement, error occurred on + transmission). When unset, the kernel's default will be used. Note: in case of a CAN bus with a + single CAN device, sending a CAN frame may result in a huge number of CAN bus errors.</para> <xi:include href="version-info.xml" xpointer="v248"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ListenOnly=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, listen-only mode is enabled. When the - interface is in listen-only mode, the interface neither transmit CAN frames nor send ACK - bit. Listen-only mode is important to debug CAN networks without interfering with the - communication or acknowledge the CAN frame. When unset, the kernel's default will be used. - </para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ListenOnly=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, listen-only mode is enabled. When the + interface is in listen-only mode, the interface neither transmit CAN frames nor send ACK + bit. Listen-only mode is important to debug CAN networks without interfering with the + communication or acknowledge the CAN frame. When unset, the kernel's default will be used. + </para> <xi:include href="version-info.xml" xpointer="v246"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>Loopback=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, loopback mode is enabled. When the - loopback mode is enabled, the interface treats messages transmitted by itself as received - messages. The loopback mode is important to debug CAN networks. When unset, the kernel's - default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>Loopback=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, loopback mode is enabled. When the + loopback mode is enabled, the interface treats messages transmitted by itself as received + messages. The loopback mode is important to debug CAN networks. When unset, the kernel's + default will be used.</para> <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>OneShot=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, one-shot mode is enabled. When unset, - the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>OneShot=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, one-shot mode is enabled. When unset, + the kernel's default will be used.</para> <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PresumeAck=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, the interface will ignore missing CAN - ACKs. When unset, the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PresumeAck=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, the interface will ignore missing CAN + ACKs. When unset, the kernel's default will be used.</para> <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>ClassicDataLengthCode=</varname></term> - <listitem> - <para>Takes a boolean. When <literal>yes</literal>, the interface will handle the 4bit data - length code (DLC). When unset, the kernel's default will be used.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>ClassicDataLengthCode=</varname></term> + <listitem> + <para>Takes a boolean. When <literal>yes</literal>, the interface will handle the 4bit data + length code (DLC). When unset, the kernel's default will be used.</para> <xi:include href="version-info.xml" xpointer="v250"/> - </listitem> - </varlistentry> - </variablelist> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> <title>[IPoIB] Section Options</title> - <para>The [IPoIB] section manages the IP over Infiniband and accepts the following keys:</para> - <variablelist class='network-directives'> - <xi:include href="systemd.netdev.xml" xpointer="ipoib_mode" /> - <xi:include href="systemd.netdev.xml" xpointer="ipoib_umcast" /> - </variablelist> + <para>The [IPoIB] section manages the IP over Infiniband and accepts the following keys:</para> + + <variablelist class='network-directives'> + <xi:include href="systemd.netdev.xml" xpointer="ipoib_mode" /> + <xi:include href="systemd.netdev.xml" xpointer="ipoib_umcast" /> + </variablelist> </refsect1> <refsect1> @@ -4599,7 +4798,7 @@ ServerAddress=192.168.0.1/24</programlisting> <para>Specifies the parent Queueing Discipline (qdisc). Takes one of <literal>clsact</literal> or <literal>ingress</literal>. This is mandatory.</para> - <xi:include href="version-info.xml" xpointer="v244"/> + <xi:include href="version-info.xml" xpointer="v244"/> </listitem> </varlistentry> @@ -5855,42 +6054,54 @@ ServerAddress=192.168.0.1/24</programlisting> <refsect1> <title>[BridgeVLAN] Section Options</title> - <para>The [BridgeVLAN] section manages the VLAN ID configuration of a bridge port and accepts the - following keys. Specify several [BridgeVLAN] sections to configure several VLAN entries. The - <varname>VLANFiltering=</varname> option has to be enabled, see the [Bridge] section in - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para> - - <variablelist class='network-directives'> - <varlistentry> - <term><varname>VLAN=</varname></term> - <listitem> - <para>The VLAN ID allowed on the port. This can be either a single ID or a range M-N. Takes - an integer in the range 1…4094.</para> - - <xi:include href="version-info.xml" xpointer="v231"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>EgressUntagged=</varname></term> - <listitem> - <para>The VLAN ID specified here will be used to untag frames on egress. Configuring - <varname>EgressUntagged=</varname> implicates the use of <varname>VLAN=</varname> above and will enable the - VLAN ID for ingress as well. This can be either a single ID or a range M-N.</para> - - <xi:include href="version-info.xml" xpointer="v231"/> - </listitem> - </varlistentry> - <varlistentry> - <term><varname>PVID=</varname></term> - <listitem> - <para>The Port VLAN ID specified here is assigned to all untagged frames at ingress. - <varname>PVID=</varname> can be used only once. Configuring <varname>PVID=</varname> implicates the use of - <varname>VLAN=</varname> above and will enable the VLAN ID for ingress as well.</para> - - <xi:include href="version-info.xml" xpointer="v231"/> - </listitem> - </varlistentry> - </variablelist> + <para> + The [BridgeVLAN] section manages the VLAN ID configurations of a bridge master or port, and accepts the + following keys. To make the settings in this section take an effect, + <varname>VLANFiltering=</varname> option has to be enabled on the bridge master, see the [Bridge] + section in + <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + If at least one valid settings specified in this section in a .network file for an interface, all + assigned VLAN IDs on the interface that are not configured in the .network file will be removed. If + VLAN IDs on an interface need to be managed by other tools, then the settings in this section cannot + be used in the matching .network file. + </para> + + <variablelist class='network-directives'> + <varlistentry> + <term><varname>VLAN=</varname></term> + <listitem> + <para>The VLAN ID allowed on the port. This can be either a single ID or a range M-N. Takes an + integer in the range 1…4094. This setting can be specified multiple times. If an empty string is + assigned, then the all previous assignments are cleared.</para> + + <xi:include href="version-info.xml" xpointer="v231"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>EgressUntagged=</varname></term> + <listitem> + <para>The VLAN ID specified here will be used to untag frames on egress. Configuring + <varname>EgressUntagged=</varname> implicates the use of <varname>VLAN=</varname> above and will + enable the VLAN ID for ingress as well. This can be either a single ID or a range M-N. This + setting can be specified multiple times. If an empty string is assigned, then the all previous + assignments are cleared.</para> + + <xi:include href="version-info.xml" xpointer="v231"/> + </listitem> + </varlistentry> + <varlistentry> + <term><varname>PVID=</varname></term> + <listitem> + <para>The port VLAN ID specified here is assigned to all untagged frames at ingress. Takes an + VLAN ID or negative boolean value (e.g. <literal>no</literal>). When false, the currently + assigned port VLAN ID will be dropped. Configuring <varname>PVID=</varname> implicates the use of + <varname>VLAN=</varname> setting in the above and will enable the VLAN ID for ingress as well. + Defaults to unset, and will keep the assigned port VLAN ID if exists.</para> + + <xi:include href="version-info.xml" xpointer="v231"/> + </listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> @@ -6217,14 +6428,14 @@ Xfrm=xfrm0</programlisting> <refsect1> <title>See Also</title> - <para> - <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, - <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> - </para> + <para><simplelist type="inline"> + <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + <member><citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member> + </simplelist></para> </refsect1> </refentry> |