man/systemd.netdev.xml

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