chiark / gitweb /
man: netdev - add some minimal explanation to the different netdev kinds and modes
[elogind.git] / man / systemd.netdev.xml
index ba212ec065b9667642d5bc1488343004ec241619..751dd00fd83e6c852df52c0e843c6d3135947ac8 100644 (file)
 
         </refsect1>
 
+        <refsect1>
+                <title>Supported netdev kinds</title>
+
+                <para>The following kinds of virtual network devices may be configured in <filename>.netdev</filename> files:</para>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>bond</varname></term>
+                                <listitem>
+                                        <para>A bond device is an aggregation of all its slave devices. See
+                                        <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">
+                                        Linux Ethernet Bonding Driver HOWTO</ulink> for details.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>bridge</varname></term>
+                                <listitem>
+                                        <para>A bridge devcie is a software switch, each of its slave devices and the bridge itself are ports of the switch.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>dummy</varname></term>
+                                <listitem>
+                                        <para>A dummy device drops all packets sent to it.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>gre</varname></term>
+                                <listitem>
+                                        <para>A Level 3 GRE tunnel over IPv4. See
+                                        <ulink url="https://tools.ietf.org/html/rfc2784">
+                                        RFC 2784</ulink> for details.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>gretap</varname></term>
+                                <listitem>
+                                        <para>A Level 2 GRE tunnel over IPv4.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>ip6gre</varname></term>
+                                <listitem>
+                                        <para>A Level 3 GRE tunnel over IPv6.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>ip6tnl</varname></term>
+                                <listitem>
+                                        <para>An IPv4 or IPv6 tunnel over IPv6</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>ip6gretap</varname></term>
+                                <listitem>
+                                        <para>An Level 2 GRE tunnel over IPv6.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>ipip</varname></term>
+                                <listitem>
+                                        <para>An IPv4 over IPv4 tunnel.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>ipvlan</varname></term>
+                                <listitem>
+                                        <para>An ipvlan device is a stacked device which receives packets from its
+                                        underlying device based on IP address filtering.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>macvlan</varname></term>
+                                <listitem>
+                                        <para>A macvlan device is a stacked device which receives packets from its
+                                        underlying device based on MAC address filtering.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>sit</varname></term>
+                                <listitem>
+                                        <para>An IPv6 over IPv4 tunnel.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>tap</varname></term>
+                                <listitem>
+                                        <para>A persistent Level 2 tunnel between a network device and a device node.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>tun</varname></term>
+                                <listitem>
+                                        <para>A persistent Level 3 tunnel between a network device and a device node.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>veth</varname></term>
+                                <listitem>
+                                        <para>An ethernet tunnel between a pair of network devices.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>vlan</varname></term>
+                                <listitem>
+                                        <para>A vlan is a stacked device which receives packets from its underlying
+                                        device based on VLAN tagging. See
+                                        <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">
+                                        IEEE 802.1Q</ulink> for details.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>vti</varname></term>
+                                <listitem>
+                                        <para>An IPv4 over IPSec tunnel.</para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+                <variablelist>
+                        <varlistentry>
+                                <term><varname>vxlan</varname></term>
+                                <listitem>
+                                        <para></para>
+                                </listitem>
+                        </varlistentry>
+                </variablelist>
+
+        </refsect1>
+
         <refsect1>
                 <title>[Match] Section Options</title>
 
                                 <varlistentry>
                                         <term><varname>Kind=</varname></term>
                                         <listitem>
-                                                <para>The netdev kind. Currently, <literal>bridge</literal>,
-                                                <literal>bond</literal>, <literal>vlan</literal>,
-                                                <literal>macvlan</literal>, <literal>vxlan</literal>,
-                                                <literal>ipip</literal>, <literal>gre</literal>,
-                                                <literal>sit</literal>, <literal>vti</literal>,
-                                                <literal>veth</literal>, <literal>tun</literal>,
-                                                <literal>tap</literal> and <literal>dummy</literal>
-                                                are supported. This option is compulsory.</para>
+                                                <para>The netdev kind. This option is compulsory. See the <literal>Supported netdev kinds</literal> section
+                                                for the valid keys.</para>
                                         </listitem>
                                 </varlistentry>
                                 <varlistentry>
                                                 <para>The maximum transmission unit in bytes to
                                                 set for the device. The usual suffixes K, M, G,
                                                 are supported and are understood to the base of
-                                                1024.</para>
+                                                1024. This key is not currently suported for
+                                                <literal>tun</literal> or <literal>tap</literal> devices.
+                                                </para>
                                         </listitem>
                                 </varlistentry>
                                 <varlistentry>
                                                 If none is given, one is generated based on
                                                 the interface name and the
                                                 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
+                                                This key is not currently suported for <literal>tun</literal> or <literal>tap</literal> devices.
                                                 </para>
                                         </listitem>
                                 </varlistentry>
                         </variablelist>
 
         </refsect1>
+
+        <refsect1>
+                <title>[IPVLAN] Section Options</title>
+
+                        <para>The <literal>[IPVLAN]</literal> section only applies for netdevs of kind
+                        <literal>ipvlan</literal>, and accepts the following key:</para>
+
+                        <variablelist class='network-directives'>
+                                <varlistentry>
+                                        <term><varname>Mode=</varname></term>
+                                        <listitem>
+                                                <para>The IPVLAN mode to use. The supported options are
+                                                <literal>L2</literal> and <literal>L3</literal>.
+                                                </para>
+                                        </listitem>
+                                </varlistentry>
+                        </variablelist>
+
+        </refsect1>
+
         <refsect1>
                 <title>[VXLAN] Section Options</title>
                         <para>The <literal>[VXLAN]</literal> section only applies for netdevs of kind
                                                 to discover remote MAC addresses.</para>
                                         </listitem>
                                 </varlistentry>
+                                <varlistentry>
+                                        <term><varname>FDBAgeingSec=</varname></term>
+                                        <listitem>
+                                                <para>The lifetime of Forwarding Database entry learnt by the kernel in seconds.</para>
+                                        </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                        <term><varname>ARPProxy=</varname></term>
+                                        <listitem>
+                                                <para>A boolean. When true, enables ARP proxy.</para>
+                                        </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                        <term><varname>L2MissNotification=</varname></term>
+                                        <listitem>
+                                                <para>A boolean. When true, enables netlink LLADDR miss notifications.</para>
+                                        </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                        <term><varname>L3MissNotification=</varname></term>
+                                        <listitem>
+                                                <para>A boolean. When true, enables netlink IP ADDR miss notifications.</para>
+                                        </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                        <term><varname>RouteShortCircuit=</varname></term>
+                                        <listitem>
+                                                <para>A boolean. When true route short circuit is turned on.</para>
+                                        </listitem>
+                                </varlistentry>
                         </variablelist>
         </refsect1>
         <refsect1>
                 <title>[Tunnel] Section Options</title>
 
                         <para>The <literal>[Tunnel]</literal> section only applies for netdevs of kind
-                        <literal>ipip</literal>, <literal>sit</literal>, <literal>gre</literal> and
-                        <literal>vti</literal> and accepts the following keys:</para>
+                        <literal>ipip</literal>, <literal>sit</literal>, <literal>gre</literal>, <literal>gretap</literal>,
+                        <literal>ip6gre</literal>, <literal>ip6gretap</literal>, <literal>vti</literal> and <literal>ip6tnl</literal>
+                        and accepts the following keys:</para>
 
                         <variablelist class='network-directives'>
                                 <varlistentry>
                                                 <para>A boolean. When true, enables Path MTU Discovery on the tunnel.</para>
                                         </listitem>
                                 </varlistentry>
+                                <varlistentry>
+                                  <term><varname>Mode=</varname></term>
+                                  <listitem>
+                                    <para>An <literal>ip6tnl</literal> tunnels can have three modes
+                                    <literal>ip6ip6</literal> for IPv6 over IPv6,
+                                    <literal>ipip6</literal> for IPv4 over IPv6 or
+                                    <literal>any</literal> for either.
+                                    </para>
+                                  </listitem>
+                                </varlistentry>
                         </variablelist>
         </refsect1>
         <refsect1>
                                 <varlistentry>
                                         <term><varname>Mode=</varname></term>
                                         <listitem>
-                                          <para>Specifies one of the bonding policies. The default is balance-rr (round robin).
-                                                <literal>balance-rr</literal>
-                                                <literal>active-backup</literal>
-                                                <literal>balance-xor</literal>
-                                                <literal>broadcast</literal>
-                                                <literal>802.3ad</literal>
-                                                <literal>balance-tlb</literal>
-                                                <literal>balance-alb</literal>
+                                          <para>Specifies one of the bonding policies. The default is
+                                          <literal>balance-rr</literal> (round robin). Possible values are
+                                                <literal>balance-rr</literal>,
+                                                <literal>active-backup</literal>,
+                                                <literal>balance-xor</literal>,
+                                                <literal>broadcast</literal>,
+                                                <literal>802.3ad</literal>,
+                                                <literal>balance-tlb</literal>, and
+                                                <literal>balance-alb</literal>.
                                           </para>
                                         </listitem>
                                 </varlistentry>
                                   <term><varname>TransmitHashPolicy=</varname></term>
                                   <listitem>
                                     <para>Selects the transmit hash policy to use for slave selection in
-                                    balance-xor, 802.3ad, and tlb modes.
-                                    <literal>layer2</literal>
-                                    <literal>layer3+4</literal>
-                                    <literal>layer2+3</literal>
-                                    <literal>encap2+3</literal>
-                                    <literal>802.3ad</literal>
-                                    <literal>encap3+4</literal>
+                                    balance-xor, 802.3ad, and tlb modes. Possible values are
+                                    <literal>layer2</literal>,
+                                    <literal>layer3+4</literal>,
+                                    <literal>layer2+3</literal>,
+                                    <literal>encap2+3</literal>,
+                                    <literal>802.3ad</literal>, and
+                                    <literal>encap3+4</literal>.
                                     </para>
                                   </listitem>
                                 </varlistentry>
 
+                                <varlistentry>
+                                  <term><varname>LACPTransmitRate=</varname></term>
+                                  <listitem>
+                                    <para>Specifies the rate with which link partner
+                                    transmits Link Aggregation Control Protocol Data Unit packets
+                                    in 802.3ad mode. Possible values are
+                                    <literal>slow</literal>, which requests partner to transmit LACPDUs every 30 seconds, and
+                                    <literal>fast</literal>, which requests partner to transmit LACPDUs every second.
+                                    The default value is <literal>slow</literal>.</para>
+                                  </listitem>
+                                </varlistentry>
+
+                                <varlistentry>
+                                  <term><varname>MIIMonitorSec=</varname></term>
+                                  <listitem>
+                                    <para>Specifies the frequency that Media Independent Interface link
+                                    monitoring will occur. A value of zero disables MII link monitoring.
+                                    This values is rounded down to the nearest millisecond. The default
+                                    value is 0.</para>
+                                  </listitem>
+                                </varlistentry>
+
+                                <varlistentry>
+                                  <term><varname>UpDelaySec=</varname></term>
+                                  <listitem>
+                                    <para>Specifies the delay before a link is enabled after a link up
+                                    status has been detected. This value is rounded down to a multiple of
+                                    MIIMonitorSec. The default value is 0.</para>
+                                  </listitem>
+                                </varlistentry>
+
+                                <varlistentry>
+                                  <term><varname>DownDelaySec=</varname></term>
+                                  <listitem>
+                                    <para>Specifies the delay before a link is disabled after a link down
+                                    status has been detected. This value is rounded down to a multiple of
+                                    MIIMonitorSec. The default value is 0.</para>
+                                  </listitem>
+                                </varlistentry>
+
                         </variablelist>
         </refsect1>
 
@@ -544,6 +821,7 @@ MACAddress=12:34:56:78:9a:bc</programlisting>
                 <para>
                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
+                        <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                         <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                 </para>
         </refsect1>