man/systemd.netdev.xml

   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.
  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
  67     networkd.</para>
  68
  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. As a special case, an empty file (file size 0) or symlink
  84     with the same name pointing to <filename>/dev/null</filename>
  85     disables the configuration file entirely (it is "masked").</para>
  86   </refsect1>
  87
  88   <refsect1>
  89     <title>Supported netdev kinds</title>
  90
  91     <para>The following kinds of virtual network devices may be
  92     configured in <filename>.netdev</filename> files:</para>
  93
  94     <table>
  95       <title>Supported kinds of virtual network devices</title>
  96
  97       <tgroup cols='2'>
  98         <colspec colname='kind' />
  99         <colspec colname='explanation' />
 100         <thead><row>
 101           <entry>Kind</entry>
 102           <entry>Description</entry>
 103         </row></thead>
 104         <tbody>
 105           <row><entry><varname>bond</varname></entry>
 106           <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>
 107
 108           <row><entry><varname>bridge</varname></entry>
 109           <entry>A bridge device is a software switch, and each of its slave devices and the bridge itself are ports of the switch.</entry></row>
 110
 111           <row><entry><varname>dummy</varname></entry>
 112           <entry>A dummy device drops all packets sent to it.</entry></row>
 113
 114           <row><entry><varname>gre</varname></entry>
 115           <entry>A Level 3 GRE tunnel over IPv4. See <ulink url="https://tools.ietf.org/html/rfc2784">RFC 2784</ulink> for details.</entry></row>
 116
 117           <row><entry><varname>gretap</varname></entry>
 118           <entry>A Level 2 GRE tunnel over IPv4.</entry></row>
 119
 120           <row><entry><varname>ip6gre</varname></entry>
 121           <entry>A Level 3 GRE tunnel over IPv6.</entry></row>
 122
 123           <row><entry><varname>ip6tnl</varname></entry>
 124           <entry>An IPv4 or IPv6 tunnel over IPv6</entry></row>
 125
 126           <row><entry><varname>ip6gretap</varname></entry>
 127           <entry>An Level 2 GRE tunnel over IPv6.</entry></row>
 128
 129           <row><entry><varname>ipip</varname></entry>
 130           <entry>An IPv4 over IPv4 tunnel.</entry></row>
 131
 132           <row><entry><varname>ipvlan</varname></entry>
 133           <entry>An ipvlan device is a stacked device which receives packets from its underlying device based on IP address filtering.</entry></row>
 134
 135           <row><entry><varname>macvlan</varname></entry>
 136           <entry>A macvlan device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row>
 137
 138           <row><entry><varname>macvtap</varname></entry>
 139           <entry>A macvtap device is a stacked device which receives packets from its underlying device based on MAC address filtering.</entry></row>
 140
 141           <row><entry><varname>sit</varname></entry>
 142           <entry>An IPv6 over IPv4 tunnel.</entry></row>
 143
 144           <row><entry><varname>tap</varname></entry>
 145           <entry>A persistent Level 2 tunnel between a network device and a device node.</entry></row>
 146
 147           <row><entry><varname>tun</varname></entry>
 148           <entry>A persistent Level 3 tunnel between a network device and a device node.</entry></row>
 149
 150           <row><entry><varname>veth</varname></entry>
 151           <entry>An Ethernet tunnel between a pair of network devices.</entry></row>
 152
 153           <row><entry><varname>vlan</varname></entry>
 154           <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
 156           <row><entry><varname>vti</varname></entry>
 157           <entry>An IPv4 over IPSec tunnel.</entry></row>
 158
 159           <row><entry><varname>vti6</varname></entry>
 160           <entry>An IPv6 over IPSec tunnel.</entry></row>
 161
 162           <row><entry><varname>vxlan</varname></entry>
 163           <entry>A virtual extensible LAN (vxlan), for connecting Cloud computing deployments.</entry></row>
 164         </tbody>
 165       </tgroup>
 166     </table>
 167
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>[Match] Section Options</title>
 172
 173     <para>A virtual network device is only created if the
 174     <literal>[Match]</literal> section matches the current
 175     environment, or if the section is empty. The following keys are
 176     accepted:</para>
 177
 178     <variablelist class='network-directives'>
 179       <varlistentry>
 180         <term><varname>Host=</varname></term>
 181         <listitem>
 182           <para>Matches against the hostname or machine ID of the
 183           host. See <literal>ConditionHost=</literal> in
 184           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 185           for details.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189       <varlistentry>
 190         <term><varname>Virtualization=</varname></term>
 191         <listitem>
 192           <para>Checks whether the system is executed in a virtualized
 193           environment and optionally test whether it is a specific
 194           implementation. See
 195           <literal>ConditionVirtualization=</literal> in
 196           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 197           for details.
 198           </para>
 199         </listitem>
 200       </varlistentry>
 201       <varlistentry>
 202         <term><varname>KernelCommandLine=</varname></term>
 203         <listitem>
 204           <para>Checks whether a specific kernel command line option
 205           is set (or if prefixed with the exclamation mark unset). See
 206           <literal>ConditionKernelCommandLine=</literal> in
 207           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 208           for details.
 209           </para>
 210         </listitem>
 211       </varlistentry>
 212       <varlistentry>
 213         <term><varname>Architecture=</varname></term>
 214         <listitem>
 215           <para>Checks whether the system is running on a specific
 216           architecture. See <literal>ConditionArchitecture=</literal> in
 217           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 218           for details.
 219           </para>
 220         </listitem>
 221       </varlistentry>
 222     </variablelist>
 223
 224   </refsect1>
 225
 226   <refsect1>
 227     <title>[NetDev] Section Options</title>
 228
 229       <para>The <literal>[NetDev]</literal> section accepts the
 230       following keys:</para>
 231
 232       <variablelist class='network-directives'>
 233         <varlistentry>
 234           <term><varname>Description=</varname></term>
 235           <listitem>
 236             <para>A free-form description of the netdev.</para>
 237           </listitem>
 238         </varlistentry>
 239         <varlistentry>
 240           <term><varname>Name=</varname></term>
 241           <listitem>
 242             <para>The interface name used when creating the netdev.
 243             This option is compulsory.</para>
 244           </listitem>
 245         </varlistentry>
 246         <varlistentry>
 247           <term><varname>Kind=</varname></term>
 248           <listitem>
 249             <para>The netdev kind. This option is compulsory. See the
 250             <literal>Supported netdev kinds</literal> section for the
 251             valid keys.</para>
 252           </listitem>
 253         </varlistentry>
 254         <varlistentry>
 255           <term><varname>MTUBytes=</varname></term>
 256           <listitem>
 257             <para>The maximum transmission unit in bytes to set for
 258             the device. The usual suffixes K, M, G, are supported and
 259             are understood to the base of 1024. This key is not
 260             currently supported for <literal>tun</literal> or
 261             <literal>tap</literal> devices.
 262             </para>
 263           </listitem>
 264         </varlistentry>
 265         <varlistentry>
 266           <term><varname>MACAddress=</varname></term>
 267           <listitem>
 268             <para>The MAC address to use for the device. If none is
 269             given, one is generated based on the interface name and
 270             the
 271             <citerefentry><refentrytitle>machine-id</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
 272             This key is not currently supported for
 273             <literal>tun</literal> or <literal>tap</literal> devices.
 274             </para>
 275           </listitem>
 276         </varlistentry>
 277       </variablelist>
 278   </refsect1>
 279
 280     <refsect1>
 281     <title>[Bridge] Section Options</title>
 282
 283       <para>The <literal>[Bridge]</literal> section only applies for
 284       netdevs of kind <literal>bridge</literal>, and accepts the
 285       following keys:</para>
 286
 287       <variablelist class='network-directives'>
 288         <varlistentry>
 289           <term><varname>HelloTimeSec=</varname></term>
 290           <listitem>
 291             <para>HelloTimeSec specifies the number of seconds between two hello packets
 292             sent out by the root bridge and the designated bridges. Hello packets are
 293             used to communicate information about the topology throughout the entire
 294             bridged local area network.</para>
 295           </listitem>
 296         </varlistentry>
 297         <varlistentry>
 298           <term><varname>MaxAgeSec=</varname></term>
 299           <listitem>
 300             <para>MaxAgeSec specifies the number of seconds of maximum message age.
 301             If the last seen (received) hello packet is more than this number of
 302             seconds old, the bridge in question will start the takeover procedure
 303             in attempt to become the Root Bridge itself.</para>
 304           </listitem>
 305         </varlistentry>
 306         <varlistentry>
 307           <term><varname>ForwardDelaySec=</varname></term>
 308           <listitem>
 309             <para>ForwardDelaySec specifies the number of seconds spent in each
 310             of the Listening and Learning states before the Forwarding state is entered.</para>
 311           </listitem>
 312         </varlistentry>
 313       </variablelist>
 314
 315   </refsect1>
 316
 317   <refsect1>
 318     <title>[VLAN] Section Options</title>
 319
 320       <para>The <literal>[VLAN]</literal> section only applies for
 321       netdevs of kind <literal>vlan</literal>, and accepts the
 322       following key:</para>
 323
 324       <variablelist class='network-directives'>
 325         <varlistentry>
 326           <term><varname>Id=</varname></term>
 327           <listitem>
 328             <para>The VLAN ID to use. An integer in the range 0–4094.
 329             This option is compulsory.</para>
 330           </listitem>
 331         </varlistentry>
 332       </variablelist>
 333
 334   </refsect1>
 335
 336   <refsect1>
 337     <title>[MACVLAN] Section Options</title>
 338
 339     <para>The <literal>[MACVLAN]</literal> section only applies for
 340     netdevs of kind <literal>macvlan</literal>, and accepts the
 341     following key:</para>
 342
 343     <variablelist class='network-directives'>
 344       <varlistentry>
 345         <term><varname>Mode=</varname></term>
 346         <listitem>
 347           <para>The MACVLAN mode to use. The supported options are
 348           <literal>private</literal>,
 349           <literal>vepa</literal>,
 350           <literal>bridge</literal>, and
 351           <literal>passthru</literal>.
 352           </para>
 353         </listitem>
 354       </varlistentry>
 355     </variablelist>
 356
 357   </refsect1>
 358
 359     <refsect1>
 360     <title>[MACVTAP] Section Options</title>
 361
 362     <para>The <literal>[MACVTAP]</literal> section applies for
 363     netdevs of kind <literal>macvtap</literal> and accepts the
 364     same key as <literal>[MACVLAN].</literal> </para>
 365
 366     </refsect1>
 367
 368   <refsect1>
 369     <title>[IPVLAN] Section Options</title>
 370
 371     <para>The <literal>[IPVLAN]</literal> section only applies for
 372     netdevs of kind <literal>ipvlan</literal>, and accepts the
 373     following key:</para>
 374
 375     <variablelist class='network-directives'>
 376       <varlistentry>
 377         <term><varname>Mode=</varname></term>
 378           <listitem>
 379             <para>The IPVLAN mode to use. The supported options are
 380             <literal>L2</literal> and <literal>L3</literal>.
 381             </para>
 382           </listitem>
 383       </varlistentry>
 384     </variablelist>
 385
 386   </refsect1>
 387
 388   <refsect1>
 389     <title>[VXLAN] Section Options</title>
 390     <para>The <literal>[VXLAN]</literal> section only applies for
 391     netdevs of kind <literal>vxlan</literal>, and accepts the
 392     following keys:</para>
 393
 394     <variablelist class='network-directives'>
 395       <varlistentry>
 396         <term><varname>Id=</varname></term>
 397         <listitem>
 398           <para>The VXLAN ID to use.</para>
 399         </listitem>
 400       </varlistentry>
 401       <varlistentry>
 402         <term><varname>Group=</varname></term>
 403         <listitem>
 404           <para>An assigned multicast group IP address.</para>
 405         </listitem>
 406       </varlistentry>
 407       <varlistentry>
 408         <term><varname>TOS=</varname></term>
 409         <listitem>
 410           <para>The Type Of Service byte value for a vxlan interface.</para>
 411         </listitem>
 412       </varlistentry>
 413       <varlistentry>
 414         <term><varname>TTL=</varname></term>
 415         <listitem>
 416           <para>A fixed Time To Live N on Virtual eXtensible Local
 417           Area Network packets. N is a number in the range 1–255. 0
 418           is a special value meaning that packets inherit the TTL
 419           value.</para>
 420         </listitem>
 421       </varlistentry>
 422       <varlistentry>
 423         <term><varname>MacLearning=</varname></term>
 424         <listitem>
 425           <para>A boolean. When true, enables dynamic MAC learning
 426           to discover remote MAC addresses.</para>
 427         </listitem>
 428       </varlistentry>
 429       <varlistentry>
 430         <term><varname>FDBAgeingSec=</varname></term>
 431         <listitem>
 432           <para>The lifetime of Forwarding Database entry learnt by
 433           the kernel, in seconds.</para>
 434         </listitem>
 435       </varlistentry>
 436       <varlistentry>
 437         <term><varname>ARPProxy=</varname></term>
 438         <listitem>
 439           <para>A boolean. When true, enables ARP proxying.</para>
 440         </listitem>
 441       </varlistentry>
 442       <varlistentry>
 443         <term><varname>L2MissNotification=</varname></term>
 444         <listitem>
 445           <para>A boolean. When true, enables netlink LLADDR miss
 446           notifications.</para>
 447         </listitem>
 448       </varlistentry>
 449       <varlistentry>
 450         <term><varname>L3MissNotification=</varname></term>
 451         <listitem>
 452           <para>A boolean. When true, enables netlink IP address miss
 453           notifications.</para>
 454         </listitem>
 455       </varlistentry>
 456       <varlistentry>
 457         <term><varname>RouteShortCircuit=</varname></term>
 458         <listitem>
 459           <para>A boolean. When true, route short circuiting is turned
 460           on.</para>
 461         </listitem>
 462       </varlistentry>
 463       <varlistentry>
 464         <term><varname>UDPCheckSum=</varname></term>
 465         <listitem>
 466           <para>A boolean. When true, transmitting UDP checksums when doing VXLAN/IPv4 is turned on.</para>
 467         </listitem>
 468       </varlistentry>
 469       <varlistentry>
 470         <term><varname>UDP6ZeroChecksumTx=</varname></term>
 471         <listitem>
 472           <para>A boolean. When true, sending zero checksums in VXLAN/IPv6 is turned on.</para>
 473         </listitem>
 474       </varlistentry>
 475       <varlistentry>
 476         <term><varname>UDP6ZeroCheckSumRx=</varname></term>
 477         <listitem>
 478           <para>A boolean. When true, receiving zero checksums in VXLAN/IPv6 is turned on.</para>
 479         </listitem>
 480       </varlistentry>
 481     <varlistentry>
 482       <term><varname>GroupPolicyExtension=</varname></term>
 483       <listitem>
 484         <para>A boolean. When true, it enables Group Policy VXLAN extension security label mechanism
 485         across network peers based on VXLAN. For details about the Group Policy VXLAN, see the
 486         <ulink url="https://tools.ietf.org/html/draft-smith-vxlan-group-policy">
 487         VXLAN Group Policy </ulink> document. Defaults to false.</para>
 488       </listitem>
 489     </varlistentry>
 490     </variablelist>
 491   </refsect1>
 492   <refsect1>
 493     <title>[Tunnel] Section Options</title>
 494
 495     <para>The <literal>[Tunnel]</literal> section only applies for
 496     netdevs of kind
 497     <literal>ipip</literal>,
 498     <literal>sit</literal>,
 499     <literal>gre</literal>,
 500     <literal>gretap</literal>,
 501     <literal>ip6gre</literal>,
 502     <literal>ip6gretap</literal>,
 503     <literal>vti</literal>,
 504     <literal>vti6</literal>, and
 505     <literal>ip6tnl</literal> and accepts
 506     the following keys:</para>
 507
 508     <variablelist class='network-directives'>
 509       <varlistentry>
 510         <term><varname>Local=</varname></term>
 511         <listitem>
 512           <para>A static local address for tunneled packets. It must
 513           be an address on another interface of this host.</para>
 514         </listitem>
 515       </varlistentry>
 516       <varlistentry>
 517         <term><varname>Remote=</varname></term>
 518         <listitem>
 519           <para>The remote endpoint of the tunnel.</para>
 520         </listitem>
 521       </varlistentry>
 522       <varlistentry>
 523         <term><varname>TOS=</varname></term>
 524         <listitem>
 525           <para>The Type Of Service byte value for a tunnel interface.
 526           For details about the TOS, see the
 527           <ulink url="http://tools.ietf.org/html/rfc1349"> Type of
 528           Service in the Internet Protocol Suite </ulink> document.
 529           </para>
 530         </listitem>
 531       </varlistentry>
 532       <varlistentry>
 533         <term><varname>TTL=</varname></term>
 534         <listitem>
 535           <para>A fixed Time To Live N on tunneled packets. N is a
 536           number in the range 1–255. 0 is a special value meaning that
 537           packets inherit the TTL value. The default value for IPv4
 538           tunnels is: inherit. The default value for IPv6 tunnels is
 539           64.</para>
 540         </listitem>
 541       </varlistentry>
 542       <varlistentry>
 543         <term><varname>DiscoverPathMTU=</varname></term>
 544         <listitem>
 545           <para>A boolean. When true, enables Path MTU Discovery on
 546           the tunnel.</para>
 547         </listitem>
 548       </varlistentry>
 549       <varlistentry>
 550         <term><varname>IPv6FlowLabel=</varname></term>
 551         <listitem>
 552           <para>Configures the 20-bit flow label (see <ulink url="https://tools.ietf.org/html/rfc6437">
 553           RFC 6437</ulink>) field in the IPv6 header (see <ulink url="https://tools.ietf.org/html/rfc2460">
 554           RFC 2460</ulink>), which is used by a node to label packets of a flow.
 555           It is only used for IPv6 tunnels.
 556           A flow label of zero is used to indicate packets that have
 557           not been labeled.
 558           It can be configured to a value in the range 0–0xFFFFF, or be
 559           set to <literal>inherit</literal>, in which case the original flowlabel is used.</para>
 560         </listitem>
 561       </varlistentry>
 562       <varlistentry>
 563         <term><varname>CopyDSCP=</varname></term>
 564         <listitem>
 565           <para>A boolean. When true, the Differentiated Service Code
 566           Point (DSCP) field will be copied to the inner header from
 567           outer header during the decapsulation of an IPv6 tunnel
 568           packet. DSCP is a field in an IP packet that enables different
 569           levels of service to be assigned to network traffic.
 570           Defaults to <literal>no</literal>.
 571           </para>
 572         </listitem>
 573       </varlistentry>
 574       <varlistentry>
 575         <term><varname>EncapsulationLimit=</varname></term>
 576         <listitem>
 577           <para>The Tunnel Encapsulation Limit option specifies how many additional
 578           levels of encapsulation are permitted to be prepended to the packet.
 579           For example, a Tunnel Encapsulation Limit option containing a limit
 580           value of zero means that a packet carrying that option may not enter
 581           another tunnel before exiting the current tunnel.
 582           (see <ulink url="https://tools.ietf.org/html/rfc2473#section-4.1.1"> RFC 2473</ulink>).
 583           The valid range is 0–255 and <literal>none</literal>. Defaults to 4.
 584         </para>
 585         </listitem>
 586       </varlistentry>
 587       <varlistentry>
 588         <term><varname>Mode=</varname></term>
 589         <listitem>
 590           <para>An <literal>ip6tnl</literal> tunnel can be in one of three
 591           modes
 592           <literal>ip6ip6</literal> for IPv6 over IPv6,
 593           <literal>ipip6</literal> for IPv4 over IPv6 or
 594           <literal>any</literal> for either.
 595           </para>
 596         </listitem>
 597       </varlistentry>
 598     </variablelist>
 599   </refsect1>
 600   <refsect1>
 601     <title>[Peer] Section Options</title>
 602
 603       <para>The <literal>[Peer]</literal> section only applies for
 604       netdevs of kind <literal>veth</literal> and accepts the
 605       following keys:</para>
 606
 607       <variablelist class='network-directives'>
 608         <varlistentry>
 609           <term><varname>Name=</varname></term>
 610           <listitem>
 611             <para>The interface name used when creating the netdev.
 612             This option is compulsory.</para>
 613           </listitem>
 614         </varlistentry>
 615         <varlistentry>
 616           <term><varname>MACAddress=</varname></term>
 617           <listitem>
 618             <para>The peer MACAddress, if not set, it is generated in
 619             the same way as the MAC address of the main
 620             interface.</para>
 621           </listitem>
 622         </varlistentry>
 623       </variablelist>
 624   </refsect1>
 625   <refsect1>
 626     <title>[Tun] Section Options</title>
 627
 628     <para>The <literal>[Tun]</literal> section only applies for
 629     netdevs of kind <literal>tun</literal>, and accepts the following
 630     keys:</para>
 631
 632     <variablelist class='network-directives'>
 633       <varlistentry>
 634         <term><varname>OneQueue=</varname></term>
 635         <listitem><para>Takes a boolean argument. Configures whether
 636         all packets are queued at the device (enabled), or a fixed
 637         number of packets are queued at the device and the rest at the
 638         <literal>qdisc</literal>. Defaults to
 639         <literal>no</literal>.</para>
 640         </listitem>
 641       </varlistentry>
 642       <varlistentry>
 643         <term><varname>MultiQueue=</varname></term>
 644         <listitem><para>Takes a boolean argument. Configures whether
 645         to use multiple file descriptors (queues) to parallelize
 646         packets sending and receiving. Defaults to
 647         <literal>no</literal>.</para>
 648         </listitem>
 649       </varlistentry>
 650       <varlistentry>
 651         <term><varname>PacketInfo=</varname></term>
 652         <listitem><para>Takes a boolean argument. Configures whether
 653         packets should be prepended with four extra bytes (two flag
 654         bytes and two protocol bytes). If disabled, it indicates that
 655         the packets will be pure IP packets. Defaults to
 656         <literal>no</literal>.</para>
 657         </listitem>
 658       </varlistentry>
 659       <varlistentry>
 660         <term><varname>VNetHeader=</varname></term>
 661         <listitem><para>Takes a boolean argument. Configures
 662         IFF_VNET_HDR flag for a tap device. It allows sending
 663         and receiving larger Generic Segmentation Offload (GSO)
 664         packets. This may increase throughput significantly.
 665         Defaults to
 666         <literal>no</literal>.</para>
 667         </listitem>
 668       </varlistentry>
 669       <varlistentry>
 670         <term><varname>User=</varname></term>
 671         <listitem><para>User to grant access to the
 672         <filename>/dev/net/tun</filename> device.</para>
 673         </listitem>
 674       </varlistentry>
 675       <varlistentry>
 676         <term><varname>Group=</varname></term>
 677         <listitem><para>Group to grant access to the
 678         <filename>/dev/net/tun</filename> device.</para>
 679         </listitem>
 680       </varlistentry>
 681
 682     </variablelist>
 683
 684   </refsect1>
 685
 686   <refsect1>
 687     <title>[Tap] Section Options</title>
 688
 689     <para>The <literal>[Tap]</literal> section only applies for
 690     netdevs of kind <literal>tap</literal>, and accepts the same keys
 691     as the <literal>[Tun]</literal> section.</para>
 692   </refsect1>
 693
 694   <refsect1>
 695     <title>[Bond] Section Options</title>
 696
 697     <para>The <literal>[Bond]</literal> section accepts the following
 698     key:</para>
 699
 700     <variablelist class='network-directives'>
 701       <varlistentry>
 702         <term><varname>Mode=</varname></term>
 703         <listitem>
 704           <para>Specifies one of the bonding policies. The default is
 705           <literal>balance-rr</literal> (round robin). Possible values are
 706           <literal>balance-rr</literal>,
 707           <literal>active-backup</literal>,
 708           <literal>balance-xor</literal>,
 709           <literal>broadcast</literal>,
 710           <literal>802.3ad</literal>,
 711           <literal>balance-tlb</literal>, and
 712           <literal>balance-alb</literal>.
 713           </para>
 714         </listitem>
 715       </varlistentry>
 716
 717       <varlistentry>
 718         <term><varname>TransmitHashPolicy=</varname></term>
 719         <listitem>
 720           <para>Selects the transmit hash policy to use for slave
 721           selection in balance-xor, 802.3ad, and tlb modes. Possible
 722           values are
 723           <literal>layer2</literal>,
 724           <literal>layer3+4</literal>,
 725           <literal>layer2+3</literal>,
 726           <literal>encap2+3</literal>,
 727           <literal>802.3ad</literal>, and
 728           <literal>encap3+4</literal>.
 729           </para>
 730         </listitem>
 731       </varlistentry>
 732
 733       <varlistentry>
 734         <term><varname>LACPTransmitRate=</varname></term>
 735         <listitem>
 736           <para>Specifies the rate with which link partner transmits
 737           Link Aggregation Control Protocol Data Unit packets in
 738           802.3ad mode. Possible values are <literal>slow</literal>,
 739           which requests partner to transmit LACPDUs every 30 seconds,
 740           and <literal>fast</literal>, which requests partner to
 741           transmit LACPDUs every second. The default value is
 742           <literal>slow</literal>.</para>
 743         </listitem>
 744       </varlistentry>
 745
 746       <varlistentry>
 747         <term><varname>MIIMonitorSec=</varname></term>
 748         <listitem>
 749           <para>Specifies the frequency that Media Independent
 750           Interface link monitoring will occur. A value of zero
 751           disables MII link monitoring. This value is rounded down to
 752           the nearest millisecond. The default value is 0.</para>
 753         </listitem>
 754       </varlistentry>
 755
 756       <varlistentry>
 757         <term><varname>UpDelaySec=</varname></term>
 758         <listitem>
 759           <para>Specifies the delay before a link is enabled after a
 760           link up status has been detected. This value is rounded down
 761           to a multiple of MIIMonitorSec. The default value is
 762           0.</para>
 763         </listitem>
 764       </varlistentry>
 765
 766       <varlistentry>
 767         <term><varname>DownDelaySec=</varname></term>
 768         <listitem>
 769           <para>Specifies the delay before a link is disabled after a
 770           link down status has been detected. This value is rounded
 771           down to a multiple of MIIMonitorSec. The default value is
 772           0.</para>
 773         </listitem>
 774       </varlistentry>
 775
 776       <varlistentry>
 777         <term><varname>LearnPacketIntervalSec=</varname></term>
 778         <listitem>
 779           <para>Specifies the number of seconds between instances where the bonding
 780           driver sends learning packets to each slave peer switch.
 781           The valid range is 1–0x7fffffff; the default value is 1. This option
 782           has an effect only for the balance-tlb and balance-alb modes.</para>
 783         </listitem>
 784       </varlistentry>
 785
 786       <varlistentry>
 787         <term><varname>AdSelect=</varname></term>
 788         <listitem>
 789           <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are
 790           <literal>stable</literal>,
 791           <literal>bandwidth</literal> and
 792           <literal>count</literal>.
 793           </para>
 794         </listitem>
 795       </varlistentry>
 796
 797       <varlistentry>
 798         <term><varname>FailOverMACPolicy=</varname></term>
 799         <listitem>
 800           <para>Specifies whether the active-backup mode should set all slaves to
 801           the same MAC address at the time of enslavement or, when enabled, to perform special handling of the
 802           bond's MAC address in accordance with the selected policy. The default policy is none.
 803           Possible values are
 804           <literal>none</literal>,
 805           <literal>active</literal> and
 806           <literal>follow</literal>.
 807           </para>
 808         </listitem>
 809       </varlistentry>
 810
 811       <varlistentry>
 812         <term><varname>ARPValidate=</varname></term>
 813         <listitem>
 814           <para>Specifies whether or not ARP probes and replies should be
 815           validated in any mode that supports ARP monitoring, or whether
 816           non-ARP traffic should be filtered (disregarded) for link
 817           monitoring purposes. Possible values are
 818           <literal>none</literal>,
 819           <literal>active</literal>,
 820           <literal>backup</literal> and
 821           <literal>all</literal>.
 822           </para>
 823         </listitem>
 824       </varlistentry>
 825
 826       <varlistentry>
 827         <term><varname>ARPIntervalSec=</varname></term>
 828         <listitem>
 829           <para>Specifies the ARP link monitoring frequency in milliseconds.
 830           A value of 0 disables ARP monitoring. The default value is 0.
 831           </para>
 832         </listitem>
 833       </varlistentry>
 834
 835       <varlistentry>
 836         <term><varname>ARPIPTargets=</varname></term>
 837         <listitem>
 838           <para>Specifies the IP addresses to use as ARP monitoring peers when
 839           ARPIntervalSec is greater than 0. These are the targets of the ARP request
 840           sent to determine the health of the link to the targets.
 841           Specify these values in IPv4 dotted decimal format. At least one IP
 842           address must be given for ARP monitoring to function. The
 843           maximum number of targets that can be specified is 16. The
 844           default value is no IP addresses.
 845           </para>
 846         </listitem>
 847       </varlistentry>
 848
 849       <varlistentry>
 850         <term><varname>ARPAllTargets=</varname></term>
 851         <listitem>
 852           <para>Specifies the quantity of ARPIPTargets that must be reachable
 853           in order for the ARP monitor to consider a slave as being up.
 854           This option affects only active-backup mode for slaves with
 855           ARPValidate enabled. Possible values are
 856           <literal>any</literal> and
 857           <literal>all</literal>.
 858           </para>
 859         </listitem>
 860       </varlistentry>
 861
 862       <varlistentry>
 863         <term><varname>PrimaryReselectPolicy=</varname></term>
 864         <listitem>
 865           <para>Specifies the reselection policy for the primary slave.  This
 866           affects how the primary slave is chosen to become the active slave
 867           when failure of the active slave or recovery of the primary slave
 868           occurs. This option is designed to prevent flip-flopping between
 869           the primary slave and other slaves.  Possible values are
 870           <literal>always</literal>,
 871           <literal>better</literal> and
 872           <literal>failure</literal>.
 873           </para>
 874         </listitem>
 875       </varlistentry>
 876
 877       <varlistentry>
 878         <term><varname>ResendIGMP=</varname></term>
 879         <listitem>
 880           <para>Specifies the number of IGMP membership reports to be issued after
 881           a failover event. One membership report is issued immediately after
 882           the failover, subsequent packets are sent in each 200ms interval.
 883           The valid range is 0–255. Defaults to 1. A value of 0
 884           prevents the IGMP membership report from being issued in response
 885           to the failover event.
 886           </para>
 887         </listitem>
 888       </varlistentry>
 889
 890       <varlistentry>
 891         <term><varname>PacketsPerSlave=</varname></term>
 892         <listitem>
 893           <para>Specify the number of packets to transmit through a slave before
 894             moving to the next one. When set to 0, then a slave is chosen at
 895             random. The valid range is 0–65535. Defaults to 1. This option
 896             only has effect when in balance-rr mode.
 897           </para>
 898         </listitem>
 899       </varlistentry>
 900
 901       <varlistentry>
 902         <term><varname>GratuitousARP=</varname></term>
 903         <listitem>
 904           <para>Specify the number of peer notifications (gratuitous ARPs and
 905             unsolicited IPv6 Neighbor Advertisements) to be issued after a
 906             failover event.  As soon as the link is up on the new slave,
 907             a peer notification is sent on the  bonding device and each
 908             VLAN sub-device.  This is repeated at each link monitor interval
 909             (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is
 910             greater than 1. The valid range is 0–255. The default value is 1.
 911             These options affect only the active-backup mode.
 912           </para>
 913         </listitem>
 914       </varlistentry>
 915
 916       <varlistentry>
 917         <term><varname>AllSlavesActive=</varname></term>
 918         <listitem>
 919           <para>A boolean. Specifies that duplicate frames (received on inactive ports)
 920           should be dropped when false, or delivered when true. Normally, bonding will drop
 921           duplicate frames (received on inactive ports), which is desirable for
 922           most users. But there are some times it is nice to allow duplicate
 923           frames to be delivered. The default value is false (drop duplicate frames
 924           received on inactive ports).
 925           </para>
 926         </listitem>
 927       </varlistentry>
 928
 929       <varlistentry>
 930         <term><varname>MinLinks=</varname></term>
 931         <listitem>
 932           <para>Specifies the minimum number of links that must be active before
 933           asserting carrier. The default value is 0.
 934           </para>
 935         </listitem>
 936       </varlistentry>
 937
 938     </variablelist>
 939
 940     <para>For more detail information see
 941     <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">
 942     Linux Ethernet Bonding Driver HOWTO</ulink></para>
 943
 944   </refsect1>
 945
 946   <refsect1>
 947     <title>Example</title>
 948     <example>
 949       <title>/etc/systemd/network/25-bridge.netdev</title>
 950
 951       <programlisting>[NetDev]
 952 Name=bridge0
 953 Kind=bridge</programlisting>
 954     </example>
 955
 956     <example>
 957       <title>/etc/systemd/network/25-vlan1.netdev</title>
 958
 959       <programlisting>[Match]
 960 Virtualization=no
 961
 962 [NetDev]
 963 Name=vlan1
 964 Kind=vlan
 965
 966 [VLAN]
 967 Id=1</programlisting>
 968     </example>
 969     <example>
 970       <title>/etc/systemd/network/25-ipip.netdev</title>
 971       <programlisting>[NetDev]
 972 Name=ipip-tun
 973 Kind=ipip
 974 MTUBytes=1480
 975
 976 [Tunnel]
 977 Local=192.168.223.238
 978 Remote=192.169.224.239
 979 TTL=64</programlisting>
 980     </example>
 981     <example>
 982       <title>/etc/systemd/network/25-tap.netdev</title>
 983       <programlisting>[NetDev]
 984 Name=tap-test
 985 Kind=tap
 986
 987 [Tap]
 988 MultiQueue=true
 989 PacketInfo=true</programlisting> </example>
 990
 991     <example>
 992       <title>/etc/systemd/network/25-sit.netdev</title>
 993       <programlisting>[NetDev]
 994 Name=sit-tun
 995 Kind=sit
 996 MTUBytes=1480
 997
 998 [Tunnel]
 999 Local=10.65.223.238
1000 Remote=10.65.223.239</programlisting>
1001     </example>
1002
1003     <example>
1004       <title>/etc/systemd/network/25-gre.netdev</title>
1005       <programlisting>[NetDev]
1006 Name=gre-tun
1007 Kind=gre
1008 MTUBytes=1480
1009
1010 [Tunnel]
1011 Local=10.65.223.238
1012 Remote=10.65.223.239</programlisting>
1013     </example>
1014
1015     <example>
1016       <title>/etc/systemd/network/25-vti.netdev</title>
1017
1018       <programlisting>[NetDev]
1019 Name=vti-tun
1020 Kind=vti
1021 MTUBytes=1480
1022
1023 [Tunnel]
1024 Local=10.65.223.238
1025 Remote=10.65.223.239</programlisting>
1026     </example>
1027
1028     <example>
1029       <title>/etc/systemd/network/25-veth.netdev</title>
1030       <programlisting>[NetDev]
1031 Name=veth-test
1032 Kind=veth
1033
1034 [Peer]
1035 Name=veth-peer</programlisting>
1036     </example>
1037
1038     <example>
1039       <title>/etc/systemd/network/25-bond.netdev</title>
1040       <programlisting>[NetDev]
1041 Name=bond1
1042 Kind=bond
1043
1044 [Bond]
1045 Mode=802.3ad
1046 TransmitHashPolicy=layer3+4
1047 MIIMonitorSec=1s
1048 LACPTransmitRate=fast
1049 </programlisting>
1050     </example>
1051
1052     <example>
1053       <title>/etc/systemd/network/25-dummy.netdev</title>
1054       <programlisting>[NetDev]
1055 Name=dummy-test
1056 Kind=dummy
1057 MACAddress=12:34:56:78:9a:bc</programlisting>
1058     </example>
1059
1060   </refsect1>
1061   <refsect1>
1062     <title>See Also</title>
1063     <para>
1064       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1065       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1066       <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1067       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1068     </para>
1069   </refsect1>
1070
1071 </refentry>