man/systemd.netdev.xml

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