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
 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 seperate 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>,
 812           <literal>802.3ad</literal>, and
 813           <literal>encap3+4</literal>.
 814           </para>
 815         </listitem>
 816       </varlistentry>
 817
 818       <varlistentry>
 819         <term><varname>LACPTransmitRate=</varname></term>
 820         <listitem>
 821           <para>Specifies the rate with which link partner transmits
 822           Link Aggregation Control Protocol Data Unit packets in
 823           802.3ad mode. Possible values are <literal>slow</literal>,
 824           which requests partner to transmit LACPDUs every 30 seconds,
 825           and <literal>fast</literal>, which requests partner to
 826           transmit LACPDUs every second. The default value is
 827           <literal>slow</literal>.</para>
 828         </listitem>
 829       </varlistentry>
 830
 831       <varlistentry>
 832         <term><varname>MIIMonitorSec=</varname></term>
 833         <listitem>
 834           <para>Specifies the frequency that Media Independent
 835           Interface link monitoring will occur. A value of zero
 836           disables MII link monitoring. This value is rounded down to
 837           the nearest millisecond. The default value is 0.</para>
 838         </listitem>
 839       </varlistentry>
 840
 841       <varlistentry>
 842         <term><varname>UpDelaySec=</varname></term>
 843         <listitem>
 844           <para>Specifies the delay before a link is enabled after a
 845           link up status has been detected. This value is rounded down
 846           to a multiple of MIIMonitorSec. The default value is
 847           0.</para>
 848         </listitem>
 849       </varlistentry>
 850
 851       <varlistentry>
 852         <term><varname>DownDelaySec=</varname></term>
 853         <listitem>
 854           <para>Specifies the delay before a link is disabled after a
 855           link down status has been detected. This value is rounded
 856           down to a multiple of MIIMonitorSec. The default value is
 857           0.</para>
 858         </listitem>
 859       </varlistentry>
 860
 861       <varlistentry>
 862         <term><varname>LearnPacketIntervalSec=</varname></term>
 863         <listitem>
 864           <para>Specifies the number of seconds between instances where the bonding
 865           driver sends learning packets to each slave peer switch.
 866           The valid range is 1–0x7fffffff; the default value is 1. This option
 867           has an effect only for the balance-tlb and balance-alb modes.</para>
 868         </listitem>
 869       </varlistentry>
 870
 871       <varlistentry>
 872         <term><varname>AdSelect=</varname></term>
 873         <listitem>
 874           <para>Specifies the 802.3ad aggregation selection logic to use. Possible values are
 875           <literal>stable</literal>,
 876           <literal>bandwidth</literal> and
 877           <literal>count</literal>.
 878           </para>
 879         </listitem>
 880       </varlistentry>
 881
 882       <varlistentry>
 883         <term><varname>FailOverMACPolicy=</varname></term>
 884         <listitem>
 885           <para>Specifies whether the active-backup mode should set all slaves to
 886           the same MAC address at the time of enslavement or, when enabled, to perform special handling of the
 887           bond's MAC address in accordance with the selected policy. The default policy is none.
 888           Possible values are
 889           <literal>none</literal>,
 890           <literal>active</literal> and
 891           <literal>follow</literal>.
 892           </para>
 893         </listitem>
 894       </varlistentry>
 895
 896       <varlistentry>
 897         <term><varname>ARPValidate=</varname></term>
 898         <listitem>
 899           <para>Specifies whether or not ARP probes and replies should be
 900           validated in any mode that supports ARP monitoring, or whether
 901           non-ARP traffic should be filtered (disregarded) for link
 902           monitoring purposes. Possible values are
 903           <literal>none</literal>,
 904           <literal>active</literal>,
 905           <literal>backup</literal> and
 906           <literal>all</literal>.
 907           </para>
 908         </listitem>
 909       </varlistentry>
 910
 911       <varlistentry>
 912         <term><varname>ARPIntervalSec=</varname></term>
 913         <listitem>
 914           <para>Specifies the ARP link monitoring frequency in milliseconds.
 915           A value of 0 disables ARP monitoring. The default value is 0.
 916           </para>
 917         </listitem>
 918       </varlistentry>
 919
 920       <varlistentry>
 921         <term><varname>ARPIPTargets=</varname></term>
 922         <listitem>
 923           <para>Specifies the IP addresses to use as ARP monitoring peers when
 924           ARPIntervalSec is greater than 0. These are the targets of the ARP request
 925           sent to determine the health of the link to the targets.
 926           Specify these values in IPv4 dotted decimal format. At least one IP
 927           address must be given for ARP monitoring to function. The
 928           maximum number of targets that can be specified is 16. The
 929           default value is no IP addresses.
 930           </para>
 931         </listitem>
 932       </varlistentry>
 933
 934       <varlistentry>
 935         <term><varname>ARPAllTargets=</varname></term>
 936         <listitem>
 937           <para>Specifies the quantity of ARPIPTargets that must be reachable
 938           in order for the ARP monitor to consider a slave as being up.
 939           This option affects only active-backup mode for slaves with
 940           ARPValidate enabled. Possible values are
 941           <literal>any</literal> and
 942           <literal>all</literal>.
 943           </para>
 944         </listitem>
 945       </varlistentry>
 946
 947       <varlistentry>
 948         <term><varname>PrimaryReselectPolicy=</varname></term>
 949         <listitem>
 950           <para>Specifies the reselection policy for the primary slave.  This
 951           affects how the primary slave is chosen to become the active slave
 952           when failure of the active slave or recovery of the primary slave
 953           occurs. This option is designed to prevent flip-flopping between
 954           the primary slave and other slaves.  Possible values are
 955           <literal>always</literal>,
 956           <literal>better</literal> and
 957           <literal>failure</literal>.
 958           </para>
 959         </listitem>
 960       </varlistentry>
 961
 962       <varlistentry>
 963         <term><varname>ResendIGMP=</varname></term>
 964         <listitem>
 965           <para>Specifies the number of IGMP membership reports to be issued after
 966           a failover event. One membership report is issued immediately after
 967           the failover, subsequent packets are sent in each 200ms interval.
 968           The valid range is 0–255. Defaults to 1. A value of 0
 969           prevents the IGMP membership report from being issued in response
 970           to the failover event.
 971           </para>
 972         </listitem>
 973       </varlistentry>
 974
 975       <varlistentry>
 976         <term><varname>PacketsPerSlave=</varname></term>
 977         <listitem>
 978           <para>Specify the number of packets to transmit through a slave before
 979             moving to the next one. When set to 0, then a slave is chosen at
 980             random. The valid range is 0–65535. Defaults to 1. This option
 981             only has effect when in balance-rr mode.
 982           </para>
 983         </listitem>
 984       </varlistentry>
 985
 986       <varlistentry>
 987         <term><varname>GratuitousARP=</varname></term>
 988         <listitem>
 989           <para>Specify the number of peer notifications (gratuitous ARPs and
 990             unsolicited IPv6 Neighbor Advertisements) to be issued after a
 991             failover event.  As soon as the link is up on the new slave,
 992             a peer notification is sent on the  bonding device and each
 993             VLAN sub-device.  This is repeated at each link monitor interval
 994             (ARPIntervalSec or MIIMonitorSec, whichever is active) if the number is
 995             greater than 1. The valid range is 0–255. The default value is 1.
 996             These options affect only the active-backup mode.
 997           </para>
 998         </listitem>
 999       </varlistentry>
1000
1001       <varlistentry>
1002         <term><varname>AllSlavesActive=</varname></term>
1003         <listitem>
1004           <para>A boolean. Specifies that duplicate frames (received on inactive ports)
1005           should be dropped when false, or delivered when true. Normally, bonding will drop
1006           duplicate frames (received on inactive ports), which is desirable for
1007           most users. But there are some times it is nice to allow duplicate
1008           frames to be delivered. The default value is false (drop duplicate frames
1009           received on inactive ports).
1010           </para>
1011         </listitem>
1012       </varlistentry>
1013
1014       <varlistentry>
1015         <term><varname>MinLinks=</varname></term>
1016         <listitem>
1017           <para>Specifies the minimum number of links that must be active before
1018           asserting carrier. The default value is 0.
1019           </para>
1020         </listitem>
1021       </varlistentry>
1022
1023     </variablelist>
1024
1025     <para>For more detail information see
1026     <ulink url="https://www.kernel.org/doc/Documentation/networking/bonding.txt">
1027     Linux Ethernet Bonding Driver HOWTO</ulink></para>
1028
1029   </refsect1>
1030
1031   <refsect1>
1032     <title>Example</title>
1033     <example>
1034       <title>/etc/systemd/network/25-bridge.netdev</title>
1035
1036       <programlisting>[NetDev]
1037 Name=bridge0
1038 Kind=bridge</programlisting>
1039     </example>
1040
1041     <example>
1042       <title>/etc/systemd/network/25-vlan1.netdev</title>
1043
1044       <programlisting>[Match]
1045 Virtualization=no
1046
1047 [NetDev]
1048 Name=vlan1
1049 Kind=vlan
1050
1051 [VLAN]
1052 Id=1</programlisting>
1053     </example>
1054     <example>
1055       <title>/etc/systemd/network/25-ipip.netdev</title>
1056       <programlisting>[NetDev]
1057 Name=ipip-tun
1058 Kind=ipip
1059 MTUBytes=1480
1060
1061 [Tunnel]
1062 Local=192.168.223.238
1063 Remote=192.169.224.239
1064 TTL=64</programlisting>
1065     </example>
1066     <example>
1067       <title>/etc/systemd/network/25-tap.netdev</title>
1068       <programlisting>[NetDev]
1069 Name=tap-test
1070 Kind=tap
1071
1072 [Tap]
1073 MultiQueue=true
1074 PacketInfo=true</programlisting> </example>
1075
1076     <example>
1077       <title>/etc/systemd/network/25-sit.netdev</title>
1078       <programlisting>[NetDev]
1079 Name=sit-tun
1080 Kind=sit
1081 MTUBytes=1480
1082
1083 [Tunnel]
1084 Local=10.65.223.238
1085 Remote=10.65.223.239</programlisting>
1086     </example>
1087
1088     <example>
1089       <title>/etc/systemd/network/25-gre.netdev</title>
1090       <programlisting>[NetDev]
1091 Name=gre-tun
1092 Kind=gre
1093 MTUBytes=1480
1094
1095 [Tunnel]
1096 Local=10.65.223.238
1097 Remote=10.65.223.239</programlisting>
1098     </example>
1099
1100     <example>
1101       <title>/etc/systemd/network/25-vti.netdev</title>
1102
1103       <programlisting>[NetDev]
1104 Name=vti-tun
1105 Kind=vti
1106 MTUBytes=1480
1107
1108 [Tunnel]
1109 Local=10.65.223.238
1110 Remote=10.65.223.239</programlisting>
1111     </example>
1112
1113     <example>
1114       <title>/etc/systemd/network/25-veth.netdev</title>
1115       <programlisting>[NetDev]
1116 Name=veth-test
1117 Kind=veth
1118
1119 [Peer]
1120 Name=veth-peer</programlisting>
1121     </example>
1122
1123     <example>
1124       <title>/etc/systemd/network/25-bond.netdev</title>
1125       <programlisting>[NetDev]
1126 Name=bond1
1127 Kind=bond
1128
1129 [Bond]
1130 Mode=802.3ad
1131 TransmitHashPolicy=layer3+4
1132 MIIMonitorSec=1s
1133 LACPTransmitRate=fast
1134 </programlisting>
1135     </example>
1136
1137     <example>
1138       <title>/etc/systemd/network/25-dummy.netdev</title>
1139       <programlisting>[NetDev]
1140 Name=dummy-test
1141 Kind=dummy
1142 MACAddress=12:34:56:78:9a:bc</programlisting>
1143     </example>
1144     <example>
1145       <title>/etc/systemd/network/25-vrf.netdev</title>
1146       <para>Create an VRF interface with table 42.</para>
1147       <programlisting>[NetDev]
1148 Name=vrf-test
1149 Kind=vrf
1150
1151 [VRF]
1152 TableId=42</programlisting>
1153     </example>
1154   </refsect1>
1155   <refsect1>
1156     <title>See Also</title>
1157     <para>
1158       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
1159       <citerefentry><refentrytitle>systemd-networkd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
1160       <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
1161       <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
1162     </para>
1163   </refsect1>
1164
1165 </refentry>