path: root/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> 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>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/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>

        </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>