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">
6 This file is part of systemd.
8 Copyright 2013 Tom Gundersen
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.
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.
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/>.
24 <refentry id="systemd.netdev" conditional='ENABLE_NETWORKD'>
27 <title>systemd.network</title>
28 <productname>systemd</productname>
32 <contrib>Developer</contrib>
33 <firstname>Tom</firstname>
34 <surname>Gundersen</surname>
35 <email>teg@jklm.no</email>
41 <refentrytitle>systemd.netdev</refentrytitle>
42 <manvolnum>5</manvolnum>
46 <refname>systemd.netdev</refname>
47 <refpurpose>Virtual Network Device configuration</refpurpose>
51 <para><filename><replaceable>netdev</replaceable>.netdev</filename></para>
55 <title>Description</title>
57 <para>Network setup is performed by
58 <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
61 <para>Virtual Network Device files must have the extension
62 <filename>.netdev</filename>; other extensions are ignored.
63 Virtual network devices are created as soon as networkd is
64 started. If a netdev with the specified name already exists,
65 networkd will use that as-is rather than create its own. Note that
66 the settings of the pre-existing netdev will not be changed by
69 <para>The <filename>.netdev</filename> files are read from the
70 files located in the system network directory
71 <filename>/usr/lib/systemd/network</filename>, the volatile
72 runtime network directory
73 <filename>/run/systemd/network</filename> and the local
74 administration network directory
75 <filename>/etc/systemd/network</filename>. All configuration files
76 are collectively sorted and processed in lexical order, regardless
77 of the directories in which they live. However, files with
78 identical filenames replace each other. Files in
79 <filename>/etc</filename> have the highest priority, files in
80 <filename>/run</filename> take precedence over files with the same
81 name in <filename>/usr/lib</filename>. This can be used to
82 override a system-supplied configuration file with a local file if
83 needed; a symlink in <filename>/etc</filename> with the same name
84 as a configuration file in <filename>/usr/lib</filename>, pointing
85 to <filename>/dev/null</filename>, disables the configuration file
91 <title>Supported netdev kinds</title>
93 <para>The following kinds of virtual network devices may be
94 configured in <filename>.netdev</filename> files:</para>
97 <title>Supported kinds of virtual network devices</title>
100 <colspec colname='kind' />
101 <colspec colname='explanation' />
104 <entry>Description</entry>
107 <row><entry><varname>bond</varname></entry>
108 <entry>A bond device is an aggregation of all its slave devices. See <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">Linux Ethernet Bonding Driver HOWTO</ulink> for details.Local configuration</entry></row>
110 <row><entry><varname>bridge</varname></entry>
111 <entry>A bridge devcie is a software switch, each of its slave devices and the bridge itself are ports of the switch.</entry></row>
113 <row><entry><varname>dummy</varname></entry>
114 <entry>A dummy device drops all packets sent to it.</entry></row>
116 <row><entry><varname>gre</varname></entry>
117 <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row>
119 <row><entry><varname>gretap</varname></entry>
120 <entry>A Level 2 GRE tunnel over IPv4.</entry></row>
122 <row><entry><varname>ip6gre</varname></entry>
123 <entry>A Level 3 GRE tunnel over IPv6.</entry></row>
125 <row><entry><varname>ip6tnl</varname></entry>
126 <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row>
128 <row><entry><varname>ip6gretap</varname></entry>
129 <entry>An Level 2 GRE tunnel over IPv6.</entry></row>
131 <row><entry><varname>ipip</varname></entry>
132 <entry>An IPv4 over IPv4 tunnel.</entry></row>
134 <row><entry><varname>ipvlan</varname></entry>
135 <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row>
137 <row><entry><varname>macvlan</varname></entry>
138 <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row>
140 <row><entry><varname>sit</varname></entry>
141 <entry>An IPv6 over IPv4 tunnel.</entry></row>
143 <row><entry><varname>tap</varname></entry>
144 <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row>
146 <row><entry><varname>tun</varname></entry>
147 <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row>
149 <row><entry><varname>veth</varname></entry>
150 <entry>An ethernet tunnel between a pair of network devices.</entry></row>
152 <row><entry><varname>vlan</varname></entry>
153 <entry>A VLAN is a stacked device which receives packets from its underlying device based on VLAN tagging. See <ulink url="http://www.ieee802.org/1/pages/802.1Q.html">IEEE 802.1Q</ulink> for details.</entry></row>
155 <row><entry><varname>vti</varname></entry>
156 <entry>An IPv4 over IPSec tunnel.</entry></row>
158 <row><entry><varname>vxlan</varname></entry>
159 <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row>
167 <title>[Match] Section Options</title>
169 <para>A virtual network device is only created if the
170 <literal>[Match]</literal> section matches the current
171 environment, or if the section is empty. The following keys are
174 <variablelist class='network-directives'>
176 <term><varname>Host=</varname></term>
178 <para>Matches against the hostname or machine ID of the
179 host. See <literal>ConditionHost=</literal> in
180 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
186 <term><varname>Virtualization=</varname></term>
188 <para>Checks whether the system is executed in a virtualized
189 environment and optionally test whether it is a specific
191 <literal>ConditionVirtualization=</literal> in
192 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
198 <term><varname>KernelCommandLine=</varname></term>
200 <para>Checks whether a specific kernel command line option
201 is set (or if prefixed with the exclamation mark unset). See
202 <literal>ConditionKernelCommandLine=</literal> in
203 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
209 <term><varname>Architecture=</varname></term>
211 <para>Checks whether the system is running on a specific
212 architecture. See <literal>ConditionArchitecture=</literal> in
213 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
223 <title>[NetDev] Section Options</title>
225 <para>The <literal>[NetDev]</literal> section accepts the
226 following keys:</para>
228 <variablelist class='network-directives'>
230 <term><varname>Description=</varname></term>
232 <para>A free-form description of the netdev.</para>
236 <term><varname>Name=</varname></term>
238 <para>The interface name used when creating the netdev.
239 This option is compulsory.</para>
243 <term><varname>Kind=</varname></term>
245 <para>The netdev kind. This option is compulsory. See the
246 <literal>Supported netdev kinds</literal> section for the
251 <term><varname>MTUBytes=</varname></term>
253 <para>The maximum transmission unit in bytes to set for
254 the device. The usual suffixes K, M, G, are supported and
255 are understood to the base of 1024. This key is not
256 currently suported for <literal>tun</literal> or
257 <literal>tap</literal> devices.
262 <term><varname>MACAddress=</varname></term>
264 <para>The MAC address to use for the device. If none is
265 given, one is generated based on the interface name and
267 <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
268 This key is not currently suported for
269 <literal>tun</literal> or <literal>tap</literal> devices.
277 <title>[VLAN] Section Options</title>
279 <para>The <literal>[VLAN]</literal> section only applies for
280 netdevs of kind <literal>vlan</literal>, and accepts the
281 following key:</para>
283 <variablelist class='network-directives'>
285 <term><varname>Id=</varname></term>
287 <para>The VLAN ID to use. An integer in the range 0–4094.
288 This option is compulsory.</para>
296 <title>[MACVLAN] Section Options</title>
298 <para>The <literal>[MACVLAN]</literal> section only applies for
299 netdevs of kind <literal>macvlan</literal>, and accepts the
300 following key:</para>
302 <variablelist class='network-directives'>
304 <term><varname>Mode=</varname></term>
306 <para>The MACVLAN mode to use. The supported options are
307 <literal>private</literal>,
308 <literal>vepa</literal>,
309 <literal>bridge</literal>, and
310 <literal>passthru</literal>.
319 <title>[IPVLAN] Section Options</title>
321 <para>The <literal>[IPVLAN]</literal> section only applies for
322 netdevs of kind <literal>ipvlan</literal>, and accepts the
323 following key:</para>
325 <variablelist class='network-directives'>
327 <term><varname>Mode=</varname></term>
329 <para>The IPVLAN mode to use. The supported options are
330 <literal>L2</literal> and <literal>L3</literal>.
339 <title>[VXLAN] Section Options</title>
340 <para>The <literal>[VXLAN]</literal> section only applies for
341 netdevs of kind <literal>vxlan</literal>, and accepts the
342 following keys:</para>
344 <variablelist class='network-directives'>
346 <term><varname>Id=</varname></term>
348 <para>The VXLAN ID to use.</para>
352 <term><varname>Group=</varname></term>
354 <para>An assigned multicast group IP address.</para>
358 <term><varname>TOS=</varname></term>
360 <para>The Type Of Service byte value for a vxlan interface.</para>
364 <term><varname>TTL=</varname></term>
366 <para>A fixed Time To Live N on Virtual eXtensible Local
367 Area Network packets. N is a number in the range 1-255. 0
368 is a special value meaning that packets inherit the TTL
373 <term><varname>MacLearning=</varname></term>
375 <para>A boolean. When true, enables dynamic MAC learning
376 to discover remote MAC addresses.</para>
380 <term><varname>FDBAgeingSec=</varname></term>
382 <para>The lifetime of Forwarding Database entry learnt by
383 the kernel in seconds.</para>
387 <term><varname>ARPProxy=</varname></term>
389 <para>A boolean. When true, enables ARP proxy.</para>
393 <term><varname>L2MissNotification=</varname></term>
395 <para>A boolean. When true, enables netlink LLADDR miss
396 notifications.</para>
400 <term><varname>L3MissNotification=</varname></term>
402 <para>A boolean. When true, enables netlink IP ADDR miss
403 notifications.</para>
407 <term><varname>RouteShortCircuit=</varname></term>
409 <para>A boolean. When true route short circuit is turned
416 <title>[Tunnel] Section Options</title>
418 <para>The <literal>[Tunnel]</literal> section only applies for
420 <literal>ipip</literal>,
421 <literal>sit</literal>,
422 <literal>gre</literal>,
423 <literal>gretap</literal>,
424 <literal>ip6gre</literal>,
425 <literal>ip6gretap</literal>,
426 <literal>vti</literal>, and
427 <literal>ip6tnl</literal> and accepts
428 the following keys:</para>
430 <variablelist class='network-directives'>
432 <term><varname>Local=</varname></term>
434 <para>A static local address for tunneled packets. It must
435 be an address on another interface of this host.</para>
439 <term><varname>Remote=</varname></term>
441 <para>The remote endpoint of the tunnel.</para>
445 <term><varname>TOS=</varname></term>
447 <para>The Type Of Service byte value for a tunnel interface.
448 For details about the TOS see the
449 <ulink url="http://tools.ietf.org/html/rfc1349"> Type of
450 Service in the Internet Protocol Suite </ulink> document.
455 <term><varname>TTL=</varname></term>
457 <para>A fixed Time To Live N on tunneled packets. N is a
458 number in the range 1-255. 0 is a special value meaning that
459 packets inherit the TTL value. The default value for IPv4
460 tunnels is: inherit. The default value for IPv6 tunnels is:
465 <term><varname>DiscoverPathMTU=</varname></term>
467 <para>A boolean. When true, enables Path MTU Discovery on
472 <term><varname>Mode=</varname></term>
474 <para>An <literal>ip6tnl</literal> tunnels can have three
476 <literal>ip6ip6</literal> for IPv6 over IPv6,
477 <literal>ipip6</literal> for IPv4 over IPv6 or
478 <literal>any</literal> for either.
485 <title>[Peer] Section Options</title>
487 <para>The <literal>[Peer]</literal> section only applies for
488 netdevs of kind <literal>veth</literal> and accepts the
489 following key:</para>
491 <variablelist class='network-directives'>
493 <term><varname>Name=</varname></term>
495 <para>The interface name used when creating the netdev.
496 This option is compulsory.</para>
500 <term><varname>MACAddress=</varname></term>
502 <para>The peer MACAddress, if not set it is generated in
503 the same way as the MAC address of the main
510 <title>[Tun] Section Options</title>
512 <para>The <literal>[Tun]</literal> section only applies for
513 netdevs of kind <literal>tun</literal>, and accepts the following
516 <variablelist class='network-directives'>
518 <term><varname>OneQueue=</varname></term>
519 <listitem><para>Takes a boolean argument. Configures whether
520 all packets are queued at the device (enabled), or a fixed
521 number of packets are queued at the device and the rest at the
522 <literal>qdisc</literal>. Defaults to
523 <literal>no</literal>.</para>
527 <term><varname>MultiQueue=</varname></term>
528 <listitem><para>Takes a boolean argument. Configures whether
529 to use multiple file descriptors (queues) to parallelize
530 packets sending and receiving. Defaults to
531 <literal>no</literal>.</para>
535 <term><varname>PacketInfo=</varname></term>
536 <listitem><para>Takes a boolean argument. Configures whether
537 packets should be prepened with four extra bytes (two flag
538 bytes and two protocol bytes). If disabled it indicates that
539 the packets will be pure IP packets. Defaults to
540 <literal>no</literal>.</para>
544 <term><varname>User=</varname></term>
545 <listitem><para>User to grant access to the
546 <filename>/dev/net/tun</filename> device.</para>
550 <term><varname>Group=</varname></term>
551 <listitem><para>Group to grant access to the
552 <filename>/dev/net/tun</filename> device.</para>
561 <title>[Tap] Section Options</title>
563 <para>The <literal>[Tap]</literal> section only applies for
564 netdevs of kind <literal>tap</literal>, and accepts the same keys
565 as the <literal>[Tun]</literal> section.</para>
569 <title>[Bond] Section Options</title>
571 <para>The <literal>[Bond]</literal> section accepts the following
574 <variablelist class='network-directives'>
576 <term><varname>Mode=</varname></term>
578 <para>Specifies one of the bonding policies. The default is
579 <literal>balance-rr</literal> (round robin). Possible values are
580 <literal>balance-rr</literal>,
581 <literal>active-backup</literal>,
582 <literal>balance-xor</literal>,
583 <literal>broadcast</literal>,
584 <literal>802.3ad</literal>,
585 <literal>balance-tlb</literal>, and
586 <literal>balance-alb</literal>.
592 <term><varname>TransmitHashPolicy=</varname></term>
594 <para>Selects the transmit hash policy to use for slave
595 selection in balance-xor, 802.3ad, and tlb modes. Possible
597 <literal>layer2</literal>,
598 <literal>layer3+4</literal>,
599 <literal>layer2+3</literal>,
600 <literal>encap2+3</literal>,
601 <literal>802.3ad</literal>, and
602 <literal>encap3+4</literal>.
608 <term><varname>LACPTransmitRate=</varname></term>
610 <para>Specifies the rate with which link partner transmits
611 Link Aggregation Control Protocol Data Unit packets in
612 802.3ad mode. Possible values are <literal>slow</literal>,
613 which requests partner to transmit LACPDUs every 30 seconds,
614 and <literal>fast</literal>, which requests partner to
615 transmit LACPDUs every second. The default value is
616 <literal>slow</literal>.</para>
621 <term><varname>MIIMonitorSec=</varname></term>
623 <para>Specifies the frequency that Media Independent
624 Interface link monitoring will occur. A value of zero
625 disables MII link monitoring. This values is rounded down to
626 the nearest millisecond. The default value is 0.</para>
631 <term><varname>UpDelaySec=</varname></term>
633 <para>Specifies the delay before a link is enabled after a
634 link up status has been detected. This value is rounded down
635 to a multiple of MIIMonitorSec. The default value is
641 <term><varname>DownDelaySec=</varname></term>
643 <para>Specifies the delay before a link is disabled after a
644 link down status has been detected. This value is rounded
645 down to a multiple of MIIMonitorSec. The default value is
654 <title>Example</title>
656 <title>/etc/systemd/network/bridge.netdev</title>
658 <programlisting>[NetDev]
660 Kind=bridge</programlisting>
664 <title>/etc/systemd/network/vlan1.netdev</title>
666 <programlisting>[Match]
674 Id=1</programlisting>
677 <title>/etc/systemd/network/ipip.netdev</title>
678 <programlisting>[NetDev]
684 Local=192.168.223.238
685 Remote=192.169.224.239
686 TTL=64</programlisting>
689 <title>/etc/systemd/network/tap.netdev</title>
690 <programlisting>[NetDev]
696 PacketInfo=true</programlisting> </example>
699 <title>/etc/systemd/network/sit.netdev</title>
700 <programlisting>[NetDev]
707 Remote=10.65.223.239</programlisting>
711 <title>/etc/systemd/network/gre.netdev</title>
712 <programlisting>[NetDev]
719 Remote=10.65.223.239</programlisting>
723 <title>/etc/systemd/network/vti.netdev</title>
725 <programlisting>[NetDev]
732 Remote=10.65.223.239</programlisting>
736 <title>/etc/systemd/network/veth.netdev</title>
737 <programlisting>[NetDev]
742 Name=veth-peer</programlisting>
746 <title>/etc/systemd/network/dummy.netdev</title>
747 <programlisting>[NetDev]
750 MACAddress=12:34:56:78:9a:bc</programlisting>
755 <title>See Also</title>
757 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
758 <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
759 <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
760 <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>