[thirdparty/systemd.git] / man / systemd.netdev.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2013 Tom Gundersen

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd.netdev" conditional='ENABLE_NETWORKD'>

        <refentryinfo>
                <title>systemd.network</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Tom</firstname>
                                <surname>Gundersen</surname>
                                <email>teg@jklm.no</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd.netdev</refentrytitle>
                <manvolnum>5</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd.netdev</refname>
                <refpurpose>Virtual Network Device configuration</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <para><filename><replaceable>netdev</replaceable>.netdev</filename></para>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para>Network setup is performed by
                <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
                </para>

                <para>Virtual Network Device files must have the extension
                <filename>.netdev</filename>; other extensions are ignored. Virtual
                network devices are created as soon as networkd is started.</para>

                <para>The <filename>.netdev</filename> files are read from the files located in the
                system network directory <filename>/usr/lib/systemd/network</filename>,
                the volatile runtime network directory
                <filename>/run/systemd/network</filename> and the local administration
                network directory <filename>/etc/systemd/network</filename>.
                All configuration files are collectively sorted and processed in lexical order,
                regardless of the directories in which they live. However, files with
                identical filenames replace each other. Files in
                <filename>/etc</filename> have the highest priority, files in
                <filename>/run</filename> take precedence over files with the same
                name in <filename>/usr/lib</filename>. This can be used to override a
                system-supplied configuration file with a local file if needed; a symlink in
                <filename>/etc</filename> with the same name as a configuration file in
                <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
                disables the configuration file entirely.</para>

        </refsect1>

        <refsect1>
                <title>[Match] Section Options</title>

                <para>A virtual network device is only created if the
                <literal>[Match]</literal> section matches the current
                environment, or if the section is empty. The following keys are accepted:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Host=</varname></term>
                                        <listitem>
                                                <para>Matches against the hostname or machine ID of the
                                                host. See <literal>ConditionHost=</literal> in
                                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                                for details.
                                                </para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Virtualization=</varname></term>
                                        <listitem>
                                                <para>Checks whether the system is executed in a virtualized
                                                environment and optionally test whether it is a specific
                                                implementation. See <literal>ConditionVirtualization=</literal> in
                                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                                for details.
                                                </para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>KernelCommandLine=</varname></term>
                                        <listitem>
                                                <para>Checks whether a specific kernel command line option is
                                                set (or if prefixed with the exclamation mark unset). See
                                                <literal>ConditionKernelCommandLine=</literal> in
                                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                                for details.
                                                </para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Architecture=</varname></term>
                                        <listitem>
                                                <para>Checks whether the system is running on a specific
                                                architecture. See <literal>ConditionArchitecture=</literal> in
                                                <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                                                for details.
                                                </para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>

        </refsect1>

        <refsect1>
                <title>[NetDev] Section Options</title>

                        <para>The <literal>[NetDev]</literal> section accepts the following
                        keys:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Description=</varname></term>
                                        <listitem>
                                                <para>A free-form description of the netdev.
                                                </para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Name=</varname></term>
                                        <listitem>
                                                <para>The interface name used when creating the
                                                netdev. This option is compulsory.</para>
                                        </listitem>
                                </varlistentry>
                                <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>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>MTUBytes=</varname></term>
                                        <listitem>
                                                <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>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>MACAddress=</varname></term>
                                        <listitem>
                                                <para>The MAC address to use for the device.
                                                If none is given, one is generated based on
                                                the interface name and the
                                                <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
                                                </para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>
        </refsect1>

        <refsect1>
                <title>[VLAN] Section Options</title>

                        <para>The <literal>[VLAN]</literal> section only applies for netdevs of kind <literal>vlan</literal>,
                        and accepts the following key:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Id=</varname></term>
                                        <listitem>
                                                <para>The VLAN ID to use. An integer in the range 0–4094.
                                                This option is compulsory.</para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>

        </refsect1>

        <refsect1>
                <title>[MACVLAN] Section Options</title>

                        <para>The <literal>[MACVLAN]</literal> section only applies for netdevs of kind
                        <literal>macvlan</literal>, and accepts the following key:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Mode=</varname></term>
                                        <listitem>
                                                <para>The MACVLAN mode to use. The supported options are
                                                <literal>private</literal>, <literal>vepa</literal>,
                                                <literal>bridge</literal> and <literal>passthru</literal>.
                                                </para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>

        </refsect1>
        <refsect1>
                <title>[VXLAN] Section Options</title>
                        <para>The <literal>[VXLAN]</literal> section only applies for netdevs of kind
                        <literal>vxlan</literal>, and accepts the following key:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Id=</varname></term>
                                        <listitem>
                                                <para>The VXLAN ID to use.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Group=</varname></term>
                                        <listitem>
                                                <para>An assigned multicast group IP address.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>TOS=</varname></term>
                                        <listitem>
                                                <para>The Type Of Service byte value for a vxlan interface.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>TTL=</varname></term>
                                        <listitem>
                                                <para>A fixed Time To Live N on Virtual eXtensible Local Area Network packets.
                                                N is a number in the range 1-255. 0 is a special value meaning that packets
                                                inherit the TTL value.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>MacLearning=</varname></term>
                                        <listitem>
                                                <para>A boolean. When true, enables dynamic MAC learning
                                                to discover remote MAC addresses.</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>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Local=</varname></term>
                                        <listitem>
                                                <para>A static local address for tunneled packets.
                                                It must be an address on another interface of this host.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Remote=</varname></term>
                                        <listitem>
                                                <para>The remote endpoint of the tunnel.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>TOS=</varname></term>
                                        <listitem>
                                                <para>The Type Of Service byte value for a tunnel interface.
                                                For details about the TOS see the
                                                <ulink url="http://tools.ietf.org/html/rfc1349">
                                                Type of Service in the Internet Protocol Suite
                                                </ulink> document.
                                                </para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>TTL=</varname></term>
                                        <listitem>
                                                <para>A fixed Time To Live N on tunneled packets.
                                                N is a number in the range 1-255. 0 is a special value meaning that packets
                                                inherit the TTL value. The default value for IPv4 tunnels is: inherit.
                                                The default value for IPv6 tunnels is: 64.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>DiscoverPathMTU=</varname></term>
                                        <listitem>
                                                <para>A boolean. When true, enables Path MTU Discovery on the tunnel.</para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>
        </refsect1>
        <refsect1>
                <title>[Peer] Section Options</title>

                        <para>The <literal>[Peer]</literal> section only applies for netdevs of kind <literal>veth</literal>
                        and accepts the following key:</para>

                        <variablelist class='network-directives'>
                                <varlistentry>
                                        <term><varname>Name=</varname></term>
                                        <listitem>
                                                <para>The interface name used when creating the netdev.
                                                This option is compulsory.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>MACAddress=</varname></term>
                                        <listitem>
                                                <para>The peer MACAddress, if not set it is generated in the same
                                                way as the MAC address of the main interface.</para>
                                        </listitem>
                                </varlistentry>
                        </variablelist>
        </refsect1>
        <refsect1>
                <title>[Tun] Section Options</title>

                        <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
                                        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 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 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 grant access to the <filename>/dev/net/tun</filename>
                                        device.</para>
                                        </listitem>
                                </varlistentry>
                                <varlistentry>
                                        <term><varname>Group=</varname></term>
                                        <listitem><para>Group to grant access to the <filename>/dev/net/tun</filename>
                                        device.</para>
                                        </listitem>
                                </varlistentry>

                        </variablelist>

        </refsect1>

        <refsect1>
                <title>[Tap] Section Options</title>

                        <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>Example</title>
                <example>
                        <title>/etc/systemd/network/bridge.netdev</title>

                        <programlisting>[NetDev]
Name=bridge0
Kind=bridge</programlisting>
                </example>

                <example>
                        <title>/etc/systemd/network/vlan1.netdev</title>

                        <programlisting>[Match]
Virtualization=no

[NetDev]
Name=vlan1
Kind=vlan

[VLAN]
Id=1</programlisting>
                </example>
                <example>
                        <title>/etc/systemd/network/ipip.netdev</title>
                        <programlisting>[NetDev]
Name=ipip-tun
Kind=ipip
MTUBytes=1480

[Tunnel]
Local=192.168.223.238
Remote=192.169.224.239
TTL=64</programlisting>
                </example>
                <example>
                  <title>/etc/systemd/network/tap.netdev</title>
                  <programlisting>[NetDev]
Name=tap-test
Kind=tap

[Tap]
MultiQueue=true
PacketInfo=true</programlisting> </example>

                <example>
                        <title>/etc/systemd/network/sit.netdev</title>
                        <programlisting>[NetDev]
Name=sit-tun
Kind=sit
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</programlisting>
                </example>

                <example>
                        <title>/etc/systemd/network/gre.netdev</title>
                        <programlisting>[NetDev]
Name=gre-tun
Kind=gre
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</programlisting>
                </example>

                <example>
                        <title>/etc/systemd/network/vti.netdev</title>

                        <programlisting>[NetDev]
Name=vti-tun
Kind=vti
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</programlisting>
                </example>

                <example>
                        <title>/etc/systemd/network/veth.netdev</title>
                        <programlisting>[NetDev]
Name=veth-test
Kind=veth

[Peer]
Name=veth-peer</programlisting>
                </example>

                <example>
                        <title>/etc/systemd/network/dummy.netdev</title>
                        <programlisting>[NetDev]
Name=dummy-test
Kind=dummy
MACAddress=12:34:56:78:9a:bc</programlisting>
                </example>

        </refsect1>
        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
eac684ef TG	1	<?xml version='1.0'?> <!---nxml--->
	2	<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
	3	"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
	4
	5	<!--
	6	This file is part of systemd.
	7
	8	Copyright 2013 Tom Gundersen
	9
	10	systemd is free software; you can redistribute it and/or modify it
	11	under the terms of the GNU Lesser General Public License as published by
	12	the Free Software Foundation; either version 2.1 of the License, or
	13	(at your option) any later version.
	14
	15	systemd is distributed in the hope that it will be useful, but
	16	WITHOUT ANY WARRANTY; without even the implied warranty of
	17	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	18	Lesser General Public License for more details.
	19
	20	You should have received a copy of the GNU Lesser General Public License
	21	along with systemd; If not, see <http://www.gnu.org/licenses/>.
	22	-->
	23
	24	<refentry id="systemd.netdev" conditional='ENABLE_NETWORKD'>
	25
	26	<refentryinfo>
	27	<title>systemd.network</title>
	28	<productname>systemd</productname>
	29
	30	<authorgroup>
	31	<author>
	32	<contrib>Developer</contrib>
	33	<firstname>Tom</firstname>
	34	<surname>Gundersen</surname>
	35	<email>teg@jklm.no</email>
	36	</author>
	37	</authorgroup>
	38	</refentryinfo>
	39
	40	<refmeta>
	41	<refentrytitle>systemd.netdev</refentrytitle>
	42	<manvolnum>5</manvolnum>
	43	</refmeta>
	44
	45	<refnamediv>
	46	<refname>systemd.netdev</refname>
	47	<refpurpose>Virtual Network Device configuration</refpurpose>
	48	</refnamediv>
	49
	50	<refsynopsisdiv>
	51	<para><filename><replaceable>netdev</replaceable>.netdev</filename></para>
	52	</refsynopsisdiv>
	53
	54	<refsect1>
	55	<title>Description</title>
	56
	57	<para>Network setup is performed by
	58	<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
	59	</para>
	60
	61	<para>Virtual Network Device files must have the extension
	62	<filename>.netdev</filename>; other extensions are ignored. Virtual
	63	network devices are created as soon as networkd is started.</para>
	64
65	<para>The <filename>.netdev</filename> files are read from the files located in the
66	system network directory <filename>/usr/lib/systemd/network</filename>,
67	the volatile runtime network directory
68	<filename>/run/systemd/network</filename> and the local administration
69	network directory <filename>/etc/systemd/network</filename>.
70	All configuration files are collectively sorted and processed in lexical order,
71	regardless of the directories in which they live. However, files with
72	identical filenames replace each other. Files in
73	<filename>/etc</filename> have the highest priority, files in
74	<filename>/run</filename> take precedence over files with the same
75	name in <filename>/usr/lib</filename>. This can be used to override a
76	system-supplied configuration file with a local file if needed; a symlink in
77	<filename>/etc</filename> with the same name as a configuration file in
78	<filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
79	disables the configuration file entirely.</para>
80
102bd40e LP	81	</refsect1>
	82
	83	<refsect1>
	84	<title>[Match] Section Options</title>
	85
eac684ef TG	86	<para>A virtual network device is only created if the
	87	<literal>[Match]</literal> section matches the current
	88	environment, or if the section is empty. The following keys are accepted:</para>
	89
	90	<variablelist class='network-directives'>
	91	<varlistentry>
	92	<term><varname>Host=</varname></term>
	93	<listitem>
	94	<para>Matches against the hostname or machine ID of the
	95	host. See <literal>ConditionHost=</literal> in
	96	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	97	for details.
	98	</para>
	99	</listitem>
	100	</varlistentry>
	101	<varlistentry>
	102	<term><varname>Virtualization=</varname></term>
	103	<listitem>
	104	<para>Checks whether the system is executed in a virtualized
	105	environment and optionally test whether it is a specific
	106	implementation. See <literal>ConditionVirtualization=</literal> in
	107	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	108	for details.
	109	</para>
	110	</listitem>
	111	</varlistentry>
	112	<varlistentry>
	113	<term><varname>KernelCommandLine=</varname></term>
	114	<listitem>
	115	<para>Checks whether a specific kernel command line option is
	116	set (or if prefixed with the exclamation mark unset). See
	117	<literal>ConditionKernelCommandLine=</literal> in
	118	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	119	for details.
	120	</para>
	121	</listitem>
	122	</varlistentry>
	123	<varlistentry>
	124	<term><varname>Architecture=</varname></term>
	125	<listitem>
	126	<para>Checks whether the system is running on a specific
	127	architecture. See <literal>ConditionArchitecture=</literal> in
	128	<citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
	129	for details.
	130	</para>
	131	</listitem>
	132	</varlistentry>
	133	</variablelist>
	134
102bd40e LP	135	</refsect1>
	136
	137	<refsect1>
	138	<title>[NetDev] Section Options</title>
	139
eac684ef TG	140	<para>The <literal>[NetDev]</literal> section accepts the following
	141	keys:</para>
	142
	143	<variablelist class='network-directives'>
b35a2909 TG	144	<varlistentry>
	145	<term><varname>Description=</varname></term>
	146	<listitem>
	147	<para>A free-form description of the netdev.
	148	</para>
	149	</listitem>
	150	</varlistentry>
eac684ef TG	151	<varlistentry>
	152	<term><varname>Name=</varname></term>
	153	<listitem>
	154	<para>The interface name used when creating the
	155	netdev. This option is compulsory.</para>
	156	</listitem>
	157	</varlistentry>
	158	<varlistentry>
	159	<term><varname>Kind=</varname></term>
	160	<listitem>
	161	<para>The netdev kind. Currently, <literal>bridge</literal>,
b35a2909 TG	162	<literal>bond</literal>, <literal>vlan</literal>,
	163	<literal>macvlan</literal>, <literal>vxlan</literal>,
	164	<literal>ipip</literal>, <literal>gre</literal>,
	165	<literal>sit</literal>, <literal>vti</literal>,
9e358851 TG	166	<literal>veth</literal>, and <literal>dummy</literal>
9e358851 TG	167	are supported. This option is compulsory.</para>
eac684ef TG	168	</listitem>
eac684ef TG	169	</varlistentry>
b35a2909 TG	170	<varlistentry>
	171	<term><varname>MTUBytes=</varname></term>
	172	<listitem>
	173	<para>The maximum transmission unit in bytes to
	174	set for the device. The usual suffixes K, M, G,
	175	are supported and are understood to the base of
	176	1024.</para>
	177	</listitem>
	178	</varlistentry>
	179	<varlistentry>
	180	<term><varname>MACAddress=</varname></term>
	181	<listitem>
	182	<para>The MAC address to use for the device.
	183	If none is given, one is generated based on
	184	the interface name and the
	185	<citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
	186	</para>
	187	</listitem>
	188	</varlistentry>
eac684ef	189	</variablelist>
102bd40e LP	190	</refsect1>
	191
	192	<refsect1>
	193	<title>[VLAN] Section Options</title>
	194
eac684ef TG	195	<para>The <literal>[VLAN]</literal> section only applies for netdevs of kind <literal>vlan</literal>,
	196	and accepts the following key:</para>
	197
	198	<variablelist class='network-directives'>
	199	<varlistentry>
	200	<term><varname>Id=</varname></term>
	201	<listitem>
	202	<para>The VLAN ID to use. An integer in the range 0–4094.
	203	This option is compulsory.</para>
	204	</listitem>
	205	</varlistentry>
fe6b2d55 TG	206	</variablelist>
fe6b2d55 TG	207
102bd40e LP	208	</refsect1>
	209
	210	<refsect1>
	211	<title>[MACVLAN] Section Options</title>
	212
fe6b2d55 TG	213	<para>The <literal>[MACVLAN]</literal> section only applies for netdevs of kind
	214	<literal>macvlan</literal>, and accepts the following key:</para>
	215
	216	<variablelist class='network-directives'>
	217	<varlistentry>
	218	<term><varname>Mode=</varname></term>
	219	<listitem>
	220	<para>The MACVLAN mode to use. The supported options are
	221	<literal>private</literal>, <literal>vepa</literal>,
	222	<literal>bridge</literal> and <literal>passthru</literal>.
	223	</para>
	224	</listitem>
	225	</varlistentry>
eac684ef TG	226	</variablelist>
	227
	228	</refsect1>
b35a2909 TG	229	<refsect1>
	230	<title>[VXLAN] Section Options</title>
	231	<para>The <literal>[VXLAN]</literal> section only applies for netdevs of kind
	232	<literal>vxlan</literal>, and accepts the following key:</para>
eac684ef	233
b35a2909 TG	234	<variablelist class='network-directives'>
	235	<varlistentry>
	236	<term><varname>Id=</varname></term>
	237	<listitem>
	238	<para>The VXLAN ID to use.</para>
	239	</listitem>
	240	</varlistentry>
	241	<varlistentry>
	242	<term><varname>Group=</varname></term>
	243	<listitem>
	244	<para>An assigned multicast group IP address.</para>
	245	</listitem>
	246	</varlistentry>
	247	<varlistentry>
	248	<term><varname>TOS=</varname></term>
	249	<listitem>
	250	<para>The Type Of Service byte value for a vxlan interface.</para>
	251	</listitem>
	252	</varlistentry>
	253	<varlistentry>
	254	<term><varname>TTL=</varname></term>
	255	<listitem>
	256	<para>A fixed Time To Live N on Virtual eXtensible Local Area Network packets.
	257	N is a number in the range 1-255. 0 is a special value meaning that packets
	258	inherit the TTL value.</para>
	259	</listitem>
	260	</varlistentry>
	261	<varlistentry>
	262	<term><varname>MacLearning=</varname></term>
	263	<listitem>
	264	<para>A boolean. When true, enables dynamic MAC learning
	265	to discover remote MAC addresses.</para>
	266	</listitem>
	267	</varlistentry>
	268	</variablelist>
	269	</refsect1>
	270	<refsect1>
	271	<title>[Tunnel] Section Options</title>
	272
	273	<para>The <literal>[Tunnel]</literal> section only applies for netdevs of kind
	274	<literal>ipip</literal>, <literal>sit</literal>, <literal>gre</literal> and
	275	<literal>vti</literal> and accepts the following keys:</para>
	276
	277	<variablelist class='network-directives'>
	278	<varlistentry>
	279	<term><varname>Local=</varname></term>
	280	<listitem>
	281	<para>A static local address for tunneled packets.
	282	It must be an address on another interface of this host.</para>
	283	</listitem>
	284	</varlistentry>
	285	<varlistentry>
	286	<term><varname>Remote=</varname></term>
	287	<listitem>
	288	<para>The remote endpoint of the tunnel.</para>
	289	</listitem>
	290	</varlistentry>
	291	<varlistentry>
	292	<term><varname>TOS=</varname></term>
	293	<listitem>
	294	<para>The Type Of Service byte value for a tunnel interface.
	295	For details about the TOS see the
	296	<ulink url="http://tools.ietf.org/html/rfc1349">
	297	Type of Service in the Internet Protocol Suite
298	</ulink> document.
299	</para>
300	</listitem>
301	</varlistentry>
302	<varlistentry>
303	<term><varname>TTL=</varname></term>
304	<listitem>
305	<para>A fixed Time To Live N on tunneled packets.
306	N is a number in the range 1-255. 0 is a special value meaning that packets
307	inherit the TTL value. The default value for IPv4 tunnels is: inherit.
308	The default value for IPv6 tunnels is: 64.</para>
309	</listitem>
310	</varlistentry>
311	<varlistentry>
312	<term><varname>DiscoverPathMTU=</varname></term>
313	<listitem>
314	<para>A boolean. When true, enables Path MTU Discovery on the tunnel.</para>
315	</listitem>
316	</varlistentry>
317	</variablelist>
318	</refsect1>
319	<refsect1>
320	<title>[Peer] Section Options</title>
321
322	<para>The <literal>[Peer]</literal> section only applies for netdevs of kind <literal>veth</literal>
323	and accepts the following key:</para>
324
325	<variablelist class='network-directives'>
326	<varlistentry>
327	<term><varname>Name=</varname></term>
328	<listitem>
329	<para>The interface name used when creating the netdev.
330	This option is compulsory.</para>
331	</listitem>
332	</varlistentry>
333	<varlistentry>
334	<term><varname>MACAddress=</varname></term>
335	<listitem>
336	<para>The peer MACAddress, if not set it is generated in the same
337	way as the MAC address of the main interface.</para>
338	</listitem>
339	</varlistentry>
340	</variablelist>
341	</refsect1>
30ae9dfd	342	<refsect1>
72d33d99	343	<title>[Tun] Section Options</title>
30ae9dfd	344
72d33d99	345	<para>The <literal>[Tun]</literal> section only applies for netdevs of kind
30ae9dfd SS	346	<literal>tun</literal>, and accepts the following keys:</para>
	347
	348	<variablelist class='network-directives'>
	349	<varlistentry>
	350	<term><varname>OneQueue=</varname></term>
	351	<listitem><para>Takes a boolean argument. Configures whether
72d33d99 TG	352	all packets are queued at the device (enabled), or a fixed number
	353	of packets are queued at the device and the rest at the
	354	<literal>qdisc</literal>. Defaults to <literal>no</literal>.</para>
30ae9dfd SS	355	</listitem>
	356	</varlistentry>
	357	<varlistentry>
	358	<term><varname>MultiQueue=</varname></term>
72d33d99 TG	359	<listitem><para>Takes a boolean argument. Configures whether to
	360	use multiple file descriptors (queues) to parallelize packets
	361	sending and receiving. Defaults to <literal>no</literal>.</para>
30ae9dfd SS	362	</listitem>
	363	</varlistentry>
	364	<varlistentry>
	365	<term><varname>PacketInfo=</varname></term>
72d33d99 TG	366	<listitem><para>Takes a boolean argument. Configures whether packets
	367	should be prepened with four extra bytes (two flag bytes and two
	368	protocol bytes). If disabled it indicates that the packets will be
ffd488e2	369	pure IP packets. Defaults to <literal>no</literal>.</para>
30ae9dfd SS	370	</listitem>
	371	</varlistentry>
	372	<varlistentry>
	373	<term><varname>User=</varname></term>
72d33d99 TG	374	<listitem><para>User to grant access to the <filename>/dev/net/tun</filename>
72d33d99 TG	375	device.</para>
30ae9dfd SS	376	</listitem>
	377	</varlistentry>
	378	<varlistentry>
	379	<term><varname>Group=</varname></term>
72d33d99 TG	380	<listitem><para>Group to grant access to the <filename>/dev/net/tun</filename>
72d33d99 TG	381	device.</para>
30ae9dfd SS	382	</listitem>
	383	</varlistentry>
	384
	385	</variablelist>
	386
	387	</refsect1>
	388
	389	<refsect1>
72d33d99	390	<title>[Tap] Section Options</title>
30ae9dfd	391
72d33d99 TG	392	<para>The <literal>[Tap]</literal> section only applies for netdevs of kind
	393	<literal>tap</literal>, and accepts the same keys as the
	394	<literal>[Tun]</literal> section.</para>
30ae9dfd SS	395	</refsect1>
30ae9dfd SS	396
eac684ef TG	397	<refsect1>
	398	<title>Example</title>
	399	<example>
	400	<title>/etc/systemd/network/bridge.netdev</title>
	401
	402	<programlisting>[NetDev]
	403	Name=bridge0
	404	Kind=bridge</programlisting>
	405	</example>
	406
	407	<example>
	408	<title>/etc/systemd/network/vlan1.netdev</title>
	409
	410	<programlisting>[Match]
	411	Virtualization=no
	412
	413	[NetDev]
	414	Name=vlan1
	415	Kind=vlan
	416
	417	[VLAN]
	418	Id=1</programlisting>
	419	</example>
b35a2909 TG	420	<example>
	421	<title>/etc/systemd/network/ipip.netdev</title>
	422	<programlisting>[NetDev]
	423	Name=ipip-tun
	424	Kind=ipip
	425	MTUBytes=1480
	426
	427	[Tunnel]
	428	Local=192.168.223.238
	429	Remote=192.169.224.239
	430	TTL=64</programlisting>
	431	</example>
30ae9dfd SS	432	<example>
	433	<title>/etc/systemd/network/tap.netdev</title>
	434	<programlisting>[NetDev]
	435	Name=tap-test
	436	Kind=tap
	437
	438	[Tap]
	439	MultiQueue=true
	440	PacketInfo=true</programlisting> </example>
eac684ef	441
b35a2909 TG	442	<example>
	443	<title>/etc/systemd/network/sit.netdev</title>
	444	<programlisting>[NetDev]
	445	Name=sit-tun
	446	Kind=sit
	447	MTUBytes=1480
	448
	449	[Tunnel]
	450	Local=10.65.223.238
	451	Remote=10.65.223.239</programlisting>
	452	</example>
eac684ef	453
b35a2909 TG	454	<example>
	455	<title>/etc/systemd/network/gre.netdev</title>
	456	<programlisting>[NetDev]
	457	Name=gre-tun
	458	Kind=gre
	459	MTUBytes=1480
	460
	461	[Tunnel]
	462	Local=10.65.223.238
	463	Remote=10.65.223.239</programlisting>
	464	</example>
	465
	466	<example>
	467	<title>/etc/systemd/network/vti.netdev</title>
	468
	469	<programlisting>[NetDev]
	470	Name=vti-tun
	471	Kind=vti
	472	MTUBytes=1480
	473
	474	[Tunnel]
	475	Local=10.65.223.238
	476	Remote=10.65.223.239</programlisting>
	477	</example>
	478
	479	<example>
	480	<title>/etc/systemd/network/veth.netdev</title>
	481	<programlisting>[NetDev]
	482	Name=veth-test
	483	Kind=veth
	484
	485	[Peer]
	486	Name=veth-peer</programlisting>
	487	</example>
	488
9e358851 TG	489	<example>
	490	<title>/etc/systemd/network/dummy.netdev</title>
	491	<programlisting>[NetDev]
	492	Name=dummy-test
	493	Kind=dummy
	494	MACAddress=12:34:56:78:9a:bc</programlisting>
	495	</example>
	496
b35a2909	497	</refsect1>
eac684ef TG	498	<refsect1>
	499	<title>See Also</title>
	500	<para>
	501	<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
f47c5c47	502	<citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
f47c5c47	503	<citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
eac684ef TG	504	</para>
	505	</refsect1>
	506
	507	</refentry>