[systemd.git] / man / systemd.netdev.html

<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>systemd.netdev</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><style>
    a.headerlink {
      color: #c60f0f;
      font-size: 0.8em;
      padding: 0 4px 0 4px;
      text-decoration: none;
      visibility: hidden;
    }

    a.headerlink:hover {
      background-color: #c60f0f;
      color: white;
    }

    h1:hover > a.headerlink, h2:hover > a.headerlink, h3:hover > a.headerlink, dt:hover > a.headerlink {
      visibility: visible;
    }
  </style><a href="index.html">Index </a>·
  <a href="systemd.directives.html">Directives </a>·
  <a href="../python-systemd/index.html">Python </a>·
  <a href="../libudev/index.html">libudev </a>·
  <a href="../libudev/index.html">gudev </a><span style="float:right">systemd 217</span><hr><div class="refentry"><a name="systemd.netdev"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>systemd.netdev — Virtual Network Device configuration</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><p><code class="filename"><em class="replaceable"><code>netdev</code></em>.netdev</code></p></div><div class="refsect1"><a name="idm214168274432"></a><h2 id="Description">Description<a class="headerlink" title="Permalink to this headline" href="#Description">¶</a></h2><p>Network setup is performed by
                <a href="systemd-networkd.html"><span class="citerefentry"><span class="refentrytitle">systemd-networkd</span>(8)</span></a>.
                </p><p>Virtual Network Device files must have the extension
                <code class="filename">.netdev</code>; other extensions are ignored. Virtual
                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.</p><p>The <code class="filename">.netdev</code> files are read from the files located in the
                system network directory <code class="filename">/usr/lib/systemd/network</code>,
                the volatile runtime network directory
                <code class="filename">/run/systemd/network</code> and the local administration
                network directory <code class="filename">/etc/systemd/network</code>.
                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
                <code class="filename">/etc</code> have the highest priority, files in
                <code class="filename">/run</code> take precedence over files with the same
                name in <code class="filename">/usr/lib</code>. This can be used to override a
                system-supplied configuration file with a local file if needed; a symlink in
                <code class="filename">/etc</code> with the same name as a configuration file in
                <code class="filename">/usr/lib</code>, pointing to <code class="filename">/dev/null</code>,
                disables the configuration file entirely.</p></div><div class="refsect1"><a name="idm214171375568"></a><h2 id="[Match] Section Options">[Match] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BMatch%5D%20Section%20Options">¶</a></h2><p>A virtual network device is only created if the
                "<code class="literal">[Match]</code>" section matches the current
                environment, or if the section is empty. The following keys are accepted:</p><div class="variablelist"><dl class="variablelist"><dt id="Host="><span class="term"><code class="varname">Host=</code></span><a class="headerlink" title="Permalink to this term" href="#Host=">¶</a></dt><dd><p>Matches against the hostname or machine ID of the
                                                host. See "<code class="literal">ConditionHost=</code>" in
                                                <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
                                                for details.
                                                </p></dd><dt id="Virtualization="><span class="term"><code class="varname">Virtualization=</code></span><a class="headerlink" title="Permalink to this term" href="#Virtualization=">¶</a></dt><dd><p>Checks whether the system is executed in a virtualized
                                                environment and optionally test whether it is a specific
                                                implementation. See "<code class="literal">ConditionVirtualization=</code>" in
                                                <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
                                                for details.
                                                </p></dd><dt id="KernelCommandLine="><span class="term"><code class="varname">KernelCommandLine=</code></span><a class="headerlink" title="Permalink to this term" href="#KernelCommandLine=">¶</a></dt><dd><p>Checks whether a specific kernel command line option is
                                                set (or if prefixed with the exclamation mark unset). See
                                                "<code class="literal">ConditionKernelCommandLine=</code>" in
                                                <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
                                                for details.
                                                </p></dd><dt id="Architecture="><span class="term"><code class="varname">Architecture=</code></span><a class="headerlink" title="Permalink to this term" href="#Architecture=">¶</a></dt><dd><p>Checks whether the system is running on a specific
                                                architecture. See "<code class="literal">ConditionArchitecture=</code>" in
                                                <a href="systemd.unit.html"><span class="citerefentry"><span class="refentrytitle">systemd.unit</span>(5)</span></a>
                                                for details.
                                                </p></dd></dl></div></div><div class="refsect1"><a name="idm214171434800"></a><h2 id="[NetDev] Section Options">[NetDev] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BNetDev%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[NetDev]</code>" section accepts the following
                        keys:</p><div class="variablelist"><dl class="variablelist"><dt id="Description="><span class="term"><code class="varname">Description=</code></span><a class="headerlink" title="Permalink to this term" href="#Description=">¶</a></dt><dd><p>A free-form description of the netdev.
                                                </p></dd><dt id="Name="><span class="term"><code class="varname">Name=</code></span><a class="headerlink" title="Permalink to this term" href="#Name=">¶</a></dt><dd><p>The interface name used when creating the
                                                netdev. This option is compulsory.</p></dd><dt id="Kind="><span class="term"><code class="varname">Kind=</code></span><a class="headerlink" title="Permalink to this term" href="#Kind=">¶</a></dt><dd><p>The netdev kind. Currently, "<code class="literal">bridge</code>",
                                                "<code class="literal">bond</code>", "<code class="literal">vlan</code>",
                                                "<code class="literal">macvlan</code>", "<code class="literal">vxlan</code>",
                                                "<code class="literal">ipip</code>", "<code class="literal">gre</code>",
                                                "<code class="literal">sit</code>", "<code class="literal">vti</code>",
                                                "<code class="literal">veth</code>", "<code class="literal">tun</code>",
                                                "<code class="literal">tap</code>" and "<code class="literal">dummy</code>"
                                                are supported. This option is compulsory.</p></dd><dt id="MTUBytes="><span class="term"><code class="varname">MTUBytes=</code></span><a class="headerlink" title="Permalink to this term" href="#MTUBytes=">¶</a></dt><dd><p>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. This key is not currently suported for
                                                "<code class="literal">tun</code>" or "<code class="literal">tap</code>" devices.
                                                </p></dd><dt id="MACAddress="><span class="term"><code class="varname">MACAddress=</code></span><a class="headerlink" title="Permalink to this term" href="#MACAddress=">¶</a></dt><dd><p>The MAC address to use for the device.
                                                If none is given, one is generated based on
                                                the interface name and the
                                                <a href="machine-id.html"><span class="citerefentry"><span class="refentrytitle">machine-id</span>(5)</span></a>.
                                                This key is not currently suported for "<code class="literal">tun</code>" or "<code class="literal">tap</code>" devices.
                                                </p></dd></dl></div></div><div class="refsect1"><a name="idm214171403216"></a><h2 id="[VLAN] Section Options">[VLAN] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BVLAN%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[VLAN]</code>" section only applies for netdevs of kind "<code class="literal">vlan</code>",
                        and accepts the following key:</p><div class="variablelist"><dl class="variablelist"><dt id="Id="><span class="term"><code class="varname">Id=</code></span><a class="headerlink" title="Permalink to this term" href="#Id=">¶</a></dt><dd><p>The VLAN ID to use. An integer in the range 0–4094.
                                                This option is compulsory.</p></dd></dl></div></div><div class="refsect1"><a name="idm214171397904"></a><h2 id="[MACVLAN] Section Options">[MACVLAN] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BMACVLAN%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[MACVLAN]</code>" section only applies for netdevs of kind
                        "<code class="literal">macvlan</code>", and accepts the following key:</p><div class="variablelist"><dl class="variablelist"><dt id="Mode="><span class="term"><code class="varname">Mode=</code></span><a class="headerlink" title="Permalink to this term" href="#Mode=">¶</a></dt><dd><p>The MACVLAN mode to use. The supported options are
                                                "<code class="literal">private</code>", "<code class="literal">vepa</code>",
                                                "<code class="literal">bridge</code>" and "<code class="literal">passthru</code>".
                                                </p></dd></dl></div></div><div class="refsect1"><a name="idm214166770112"></a><h2 id="[VXLAN] Section Options">[VXLAN] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BVXLAN%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[VXLAN]</code>" section only applies for netdevs of kind
                        "<code class="literal">vxlan</code>", and accepts the following key:</p><div class="variablelist"><dl class="variablelist"><dt id="Id="><span class="term"><code class="varname">Id=</code></span><a class="headerlink" title="Permalink to this term" href="#Id=">¶</a></dt><dd><p>The VXLAN ID to use.</p></dd><dt id="Group="><span class="term"><code class="varname">Group=</code></span><a class="headerlink" title="Permalink to this term" href="#Group=">¶</a></dt><dd><p>An assigned multicast group IP address.</p></dd><dt id="TOS="><span class="term"><code class="varname">TOS=</code></span><a class="headerlink" title="Permalink to this term" href="#TOS=">¶</a></dt><dd><p>The Type Of Service byte value for a vxlan interface.</p></dd><dt id="TTL="><span class="term"><code class="varname">TTL=</code></span><a class="headerlink" title="Permalink to this term" href="#TTL=">¶</a></dt><dd><p>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.</p></dd><dt id="MacLearning="><span class="term"><code class="varname">MacLearning=</code></span><a class="headerlink" title="Permalink to this term" href="#MacLearning=">¶</a></dt><dd><p>A boolean. When true, enables dynamic MAC learning
                                                to discover remote MAC addresses.</p></dd></dl></div></div><div class="refsect1"><a name="idm214166758336"></a><h2 id="[Tunnel] Section Options">[Tunnel] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BTunnel%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[Tunnel]</code>" section only applies for netdevs of kind
                        "<code class="literal">ipip</code>", "<code class="literal">sit</code>", "<code class="literal">gre</code>" and
                        "<code class="literal">vti</code>" and accepts the following keys:</p><div class="variablelist"><dl class="variablelist"><dt id="Local="><span class="term"><code class="varname">Local=</code></span><a class="headerlink" title="Permalink to this term" href="#Local=">¶</a></dt><dd><p>A static local address for tunneled packets.
                                                It must be an address on another interface of this host.</p></dd><dt id="Remote="><span class="term"><code class="varname">Remote=</code></span><a class="headerlink" title="Permalink to this term" href="#Remote=">¶</a></dt><dd><p>The remote endpoint of the tunnel.</p></dd><dt id="TOS="><span class="term"><code class="varname">TOS=</code></span><a class="headerlink" title="Permalink to this term" href="#TOS=">¶</a></dt><dd><p>The Type Of Service byte value for a tunnel interface.
                                                For details about the TOS see the
                                                <a class="ulink" href="http://tools.ietf.org/html/rfc1349" target="_top">
                                                Type of Service in the Internet Protocol Suite
                                                </a> document.
                                                </p></dd><dt id="TTL="><span class="term"><code class="varname">TTL=</code></span><a class="headerlink" title="Permalink to this term" href="#TTL=">¶</a></dt><dd><p>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.</p></dd><dt id="DiscoverPathMTU="><span class="term"><code class="varname">DiscoverPathMTU=</code></span><a class="headerlink" title="Permalink to this term" href="#DiscoverPathMTU=">¶</a></dt><dd><p>A boolean. When true, enables Path MTU Discovery on the tunnel.</p></dd></dl></div></div><div class="refsect1"><a name="idm214166743568"></a><h2 id="[Peer] Section Options">[Peer] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BPeer%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[Peer]</code>" section only applies for netdevs of kind "<code class="literal">veth</code>"
                        and accepts the following key:</p><div class="variablelist"><dl class="variablelist"><dt id="Name="><span class="term"><code class="varname">Name=</code></span><a class="headerlink" title="Permalink to this term" href="#Name=">¶</a></dt><dd><p>The interface name used when creating the netdev.
                                                This option is compulsory.</p></dd><dt id="MACAddress="><span class="term"><code class="varname">MACAddress=</code></span><a class="headerlink" title="Permalink to this term" href="#MACAddress=">¶</a></dt><dd><p>The peer MACAddress, if not set it is generated in the same
                                                way as the MAC address of the main interface.</p></dd></dl></div></div><div class="refsect1"><a name="idm214166736896"></a><h2 id="[Tun] Section Options">[Tun] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BTun%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[Tun]</code>" section only applies for netdevs of kind
                        "<code class="literal">tun</code>", and accepts the following keys:</p><div class="variablelist"><dl class="variablelist"><dt id="OneQueue="><span class="term"><code class="varname">OneQueue=</code></span><a class="headerlink" title="Permalink to this term" href="#OneQueue=">¶</a></dt><dd><p>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
                                        "<code class="literal">qdisc</code>". Defaults to "<code class="literal">no</code>".</p></dd><dt id="MultiQueue="><span class="term"><code class="varname">MultiQueue=</code></span><a class="headerlink" title="Permalink to this term" href="#MultiQueue=">¶</a></dt><dd><p>Takes a boolean argument. Configures whether to
                                        use multiple file descriptors (queues) to parallelize packets
                                        sending and receiving. Defaults to "<code class="literal">no</code>".</p></dd><dt id="PacketInfo="><span class="term"><code class="varname">PacketInfo=</code></span><a class="headerlink" title="Permalink to this term" href="#PacketInfo=">¶</a></dt><dd><p>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 "<code class="literal">no</code>".</p></dd><dt id="User="><span class="term"><code class="varname">User=</code></span><a class="headerlink" title="Permalink to this term" href="#User=">¶</a></dt><dd><p>User to grant access to the <code class="filename">/dev/net/tun</code>
                                        device.</p></dd><dt id="Group="><span class="term"><code class="varname">Group=</code></span><a class="headerlink" title="Permalink to this term" href="#Group=">¶</a></dt><dd><p>Group to grant access to the <code class="filename">/dev/net/tun</code>
                                        device.</p></dd></dl></div></div><div class="refsect1"><a name="idm214166721472"></a><h2 id="[Tap] Section Options">[Tap] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BTap%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[Tap]</code>" section only applies for netdevs of kind
                        "<code class="literal">tap</code>", and accepts the same keys as the
                        "<code class="literal">[Tun]</code>" section.</p></div><div class="refsect1"><a name="idm214166718288"></a><h2 id="[Bond] Section Options">[Bond] Section Options<a class="headerlink" title="Permalink to this headline" href="#%5BBond%5D%20Section%20Options">¶</a></h2><p>The "<code class="literal">[Bond]</code>" section accepts the following
                        key:</p><div class="variablelist"><dl class="variablelist"><dt id="Mode="><span class="term"><code class="varname">Mode=</code></span><a class="headerlink" title="Permalink to this term" href="#Mode=">¶</a></dt><dd><p>Specifies one of the bonding policies. The default is
                                          "<code class="literal">balance-rr</code>" (round robin). Possible values are
                                                "<code class="literal">balance-rr</code>",
                                                "<code class="literal">active-backup</code>",
                                                "<code class="literal">balance-xor</code>",
                                                "<code class="literal">broadcast</code>",
                                                "<code class="literal">802.3ad</code>",
                                                "<code class="literal">balance-tlb</code>", and
                                                "<code class="literal">balance-alb</code>".
                                          </p></dd><dt id="TransmitHashPolicy="><span class="term"><code class="varname">TransmitHashPolicy=</code></span><a class="headerlink" title="Permalink to this term" href="#TransmitHashPolicy=">¶</a></dt><dd><p>Selects the transmit hash policy to use for slave selection in
                                    balance-xor, 802.3ad, and tlb modes. Possible values are
                                    "<code class="literal">layer2</code>",
                                    "<code class="literal">layer3+4</code>",
                                    "<code class="literal">layer2+3</code>",
                                    "<code class="literal">encap2+3</code>",
                                    "<code class="literal">802.3ad</code>", and
                                    "<code class="literal">encap3+4</code>".
                                    </p></dd><dt id="LACPTransmitRate="><span class="term"><code class="varname">LACPTransmitRate=</code></span><a class="headerlink" title="Permalink to this term" href="#LACPTransmitRate=">¶</a></dt><dd><p>Specifies the rate with which link partner
                                    transmits Link Aggregation Control Protocol Data Unit packets
                                    in 802.3ad mode. Possible values are
                                    "<code class="literal">slow</code>", which requests partner to transmit LACPDUs every 30 seconds, and
                                    "<code class="literal">fast</code>", which requests partner to transmit LACPDUs every second.
                                    The default value is "<code class="literal">slow</code>".</p></dd><dt id="MIIMonitorSec="><span class="term"><code class="varname">MIIMonitorSec=</code></span><a class="headerlink" title="Permalink to this term" href="#MIIMonitorSec=">¶</a></dt><dd><p>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.</p></dd><dt id="UpDelaySec="><span class="term"><code class="varname">UpDelaySec=</code></span><a class="headerlink" title="Permalink to this term" href="#UpDelaySec=">¶</a></dt><dd><p>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.</p></dd><dt id="DownDelaySec="><span class="term"><code class="varname">DownDelaySec=</code></span><a class="headerlink" title="Permalink to this term" href="#DownDelaySec=">¶</a></dt><dd><p>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.</p></dd></dl></div></div><div class="refsect1"><a name="idm214166693440"></a><h2 id="Example">Example<a class="headerlink" title="Permalink to this headline" href="#Example">¶</a></h2><div class="example"><a name="idm214166692800"></a><p class="title"><b>Example 1. /etc/systemd/network/bridge.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=bridge0
Kind=bridge</pre></div></div><br class="example-break"><div class="example"><a name="idm214166691408"></a><p class="title"><b>Example 2. /etc/systemd/network/vlan1.netdev</b></p><div class="example-contents"><pre class="programlisting">[Match]
Virtualization=no

[NetDev]
Name=vlan1
Kind=vlan

[VLAN]
Id=1</pre></div></div><br class="example-break"><div class="example"><a name="idm214166689936"></a><p class="title"><b>Example 3. /etc/systemd/network/ipip.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=ipip-tun
Kind=ipip
MTUBytes=1480

[Tunnel]
Local=192.168.223.238
Remote=192.169.224.239
TTL=64</pre></div></div><br class="example-break"><div class="example"><a name="idm214166688416"></a><p class="title"><b>Example 4. /etc/systemd/network/tap.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=tap-test
Kind=tap

[Tap]
MultiQueue=true
PacketInfo=true</pre></div></div><br class="example-break"><div class="example"><a name="idm214166686944"></a><p class="title"><b>Example 5. /etc/systemd/network/sit.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=sit-tun
Kind=sit
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</pre></div></div><br class="example-break"><div class="example"><a name="idm214166685440"></a><p class="title"><b>Example 6. /etc/systemd/network/gre.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=gre-tun
Kind=gre
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</pre></div></div><br class="example-break"><div class="example"><a name="idm214166683936"></a><p class="title"><b>Example 7. /etc/systemd/network/vti.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=vti-tun
Kind=vti
MTUBytes=1480

[Tunnel]
Local=10.65.223.238
Remote=10.65.223.239</pre></div></div><br class="example-break"><div class="example"><a name="idm214166682432"></a><p class="title"><b>Example 8. /etc/systemd/network/veth.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=veth-test
Kind=veth

[Peer]
Name=veth-peer</pre></div></div><br class="example-break"><div class="example"><a name="idm214166680960"></a><p class="title"><b>Example 9. /etc/systemd/network/dummy.netdev</b></p><div class="example-contents"><pre class="programlisting">[NetDev]
Name=dummy-test
Kind=dummy
MACAddress=12:34:56:78:9a:bc</pre></div></div><br class="example-break"></div><div class="refsect1"><a name="idm214166679360"></a><h2 id="See Also">See Also<a class="headerlink" title="Permalink to this headline" href="#See%20Also">¶</a></h2><p>
                        <a href="systemd.html"><span class="citerefentry"><span class="refentrytitle">systemd</span>(1)</span></a>,
                        <a href="systemd-networkd.html"><span class="citerefentry"><span class="refentrytitle">systemd-networkd</span>(8)</span></a>,
                        <a href="systemd.network.html"><span class="citerefentry"><span class="refentrytitle">systemd.network</span>(5)</span></a>
                </p></div></div></body></html>