<para>Virtual Network Device files must have the extension
<filename>.netdev</filename>; other extensions are ignored. Virtual
- network devices are created as soon as networkd is started.</para>
+ network devices are created as soon as networkd is started. If a netdev
+ with the specified name already exists, networkd will use that as-is
+ rather than create its own. Note that the settings of the pre-existing
+ netdev will not be changed by networkd.</para>
<para>The <filename>.netdev</filename> files are read from the files located in the
system network directory <filename>/usr/lib/systemd/network</filename>,
</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>, 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>
</variablelist>
</refsect1>
<refsect1>
- <title>[TUN] Section Options</title>
+ <title>[Tun] Section Options</title>
- <para>The <literal>[TUN]</literal> section only applies for netdevs of kind
+ <para>The <literal>[Tun]</literal> section only applies for netdevs of kind
<literal>tun</literal>, and accepts the following keys:</para>
<variablelist class='network-directives'>
<varlistentry>
<term><varname>OneQueue=</varname></term>
<listitem><para>Takes a boolean argument. Configures whether
- to enable disable one queue . it determines whether all packets
- queue at the device (enabled), or a fixed number queue at the device and
- the rest at the "qdisc". Defaults to <literal>no</literal>.</para>
+ all packets are queued at the device (enabled), or a fixed number
+ of packets are queued at the device and the rest at the
+ <literal>qdisc</literal>. Defaults to <literal>no</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>MultiQueue=</varname></term>
- <listitem><para>Takes a boolean argument. Configures whether the
- to disable or disable . Linux supports multiqueue tuntap which can
- uses multiple file descriptors (queues) to parallelize
- packets sending or receiving. The device allocation is the same as before,
- and if user wants to create multiple queues. Defaults to
- <literal>no</literal>.</para>
+ <listitem><para>Takes a boolean argument. Configures whether to
+ use multiple file descriptors (queues) to parallelize packets
+ sending and receiving. Defaults to <literal>no</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>PacketInfo=</varname></term>
- <listitem><para>Takes a boolean argument. Configures whether the
- to enable or disable . PacketInfo tells the kernel to not provide packet
- information. The purpose of PacketInfo is to tell the kernel that packets
- will be "pure" IP packets, with no added bytes. Otherwise (if PacketInfo is unset),
- 4 extra bytes are added to the beginning of the packet (2 flag bytes and 2 protocol bytes).
- Defaults to <literal>no</literal>.</para>
+ <listitem><para>Takes a boolean argument. Configures whether packets
+ should be prepened with four extra bytes (two flag bytes and two
+ protocol bytes). If disabled it indicates that the packets will be
+ pure IP packets. Defaults to <literal>no</literal>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>User=</varname></term>
- <listitem><para>User to be allowed to access this device. Give ownership to unprivileged users,
- so that /dev/net/tun device to be usable by this user.
- </para>
+ <listitem><para>User to grant access to the <filename>/dev/net/tun</filename>
+ device.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>Group=</varname></term>
- <listitem><para>Group to be allowed to access this device. Give ownership to unprivileged group,
- so that /dev/net/tun device to be usable by this group.</para>
+ <listitem><para>Group to grant access to the <filename>/dev/net/tun</filename>
+ device.</para>
</listitem>
</varlistentry>
</refsect1>
<refsect1>
- <title>[TAP] Section Options</title>
+ <title>[Tap] Section Options</title>
- <para>The <literal>[TAP]</literal> section only applies for netdevs of kind
- <literal>tap</literal>, and accepts the following keys:</para>
+ <para>The <literal>[Tap]</literal> section only applies for netdevs of kind
+ <literal>tap</literal>, and accepts the same keys as the
+ <literal>[Tun]</literal> section.</para>
</refsect1>
+ <refsect1>
+ <title>[Bond] Section Options</title>
+
+ <para>The <literal>[Bond]</literal> section accepts the following
+ key:</para>
+
<variablelist class='network-directives'>
<varlistentry>
- <term><varname>OneQueue=</varname></term>
- <listitem><para>Takes a boolean argument. Configures whether
- to enable disable one queue . it determines whether all packets
- queue at the device (enabled), or a fixed number queue at the device and
- the rest at the "qdisc". Defaults to <literal>no</literal>.</para>
+ <term><varname>Mode=</varname></term>
+ <listitem>
+ <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>
+
<varlistentry>
- <term><varname>MultiQueue=</varname></term>
- <listitem><para>Takes a boolean argument. Configures whether the
- to disable or disable . From version 3.8, Linux supports multiqueue
- tuntap which can uses multiple file descriptors (queues) to parallelize
- packets sending or receiving. The device allocation is the same as before,
- and if user wants to create multiple queues. Defaults to
- <literal>no</literal>.</para>
- </listitem>
+ <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. 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>PacketInfo=</varname></term>
- <listitem><para>Takes a boolean argument. Configures whether the
- to enable or disable . PacketInfo tells the kernel to not provide packet
- information. The purpose of PacketInfo is to tell the kernel that packets
- will be "pure" IP packets, with no added bytes. Otherwise (if PacketInfo is unset),
- 4 extra bytes are added to the beginning of the packet (2 flag bytes and 2 protocol bytes).
- Defaults to <literal>no</literal>.</para>
- </listitem>
+ <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>User=</varname></term>
- <listitem><para>User to be allowed to access this device. Give ownership to unprivileged users,
- so that /dev/net/tun device to be usable by this user.
- </para>
- </listitem>
+ <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>Group=</varname></term>
- <listitem><para>Group to be allowed to access this device. Give ownership to unprivileged group,
- so that /dev/net/tun device to be usable by this group.</para>
- </listitem>
+ <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>
- </variablelist>
+ <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>
<refsect1>
<title>Example</title>
<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>
~ianmdlvl / elogind.git / blobdiff