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