<?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">

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

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