man/systemd.link.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.link"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8   <refentryinfo>
   9     <title>systemd.link</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd.link</refentrytitle>
  15     <manvolnum>5</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd.link</refname>
  20     <refpurpose>Network device configuration</refpurpose>
  21   </refnamediv>
  22
  23   <refsynopsisdiv>
  24     <para><filename><replaceable>link</replaceable>.link</filename></para>
  25   </refsynopsisdiv>
  26
  27   <refsect1>
  28     <title>Description</title>
  29
  30     <para>A plain ini-style text file that encodes configuration for matching network devices, used by
  31     <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry> and in
  32     particular its <command>net_setup_link</command> builtin. See
  33     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
  34     general description of the syntax.</para>
  35
  36     <para>The <filename>.link</filename> files are read from the files located in the system network
  37     directory <filename>/usr/lib/systemd/network</filename> and
  38     <filename>/usr/local/lib/systemd/network</filename>
  39     <xi:include href="standard-conf.xml" xpointer="usr-local-footnote" />,
  40     the volatile runtime network directory
  41     <filename>/run/systemd/network</filename>, and the local administration network directory
  42     <filename>/etc/systemd/network</filename>. All configuration files are collectively sorted and
  43     processed in alphanumeric order, regardless of the directories in which they live. However, files
  44     with identical filenames replace each other. It is recommended that each filename is prefixed with
  45     a number smaller than <literal>70</literal> (e.g. <filename>10-eth0.link</filename>). Otherwise, the
  46     default <filename>.link</filename> files or those generated by
  47     <citerefentry><refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  48     may take precedence over user configured files. Files in <filename>/etc/</filename> have the
  49     highest priority, files in <filename>/run/</filename> take precedence over files with the same name
  50     in <filename>/usr/lib/</filename>. This can be used to override a system-supplied link file with a
  51     local file if needed. As a special case, an empty file (file size 0) or symlink with the same name
  52     pointing to <filename>/dev/null</filename> disables the configuration file entirely (it is
  53     "masked").</para>
  54
  55     <para>Along with the link file <filename>foo.link</filename>, a "drop-in" directory
  56     <filename>foo.link.d/</filename> may exist. All files with the suffix <literal>.conf</literal>
  57     from this directory will be merged in the alphanumeric order and parsed after the main file itself
  58     has been parsed. This is useful to alter or add configuration settings, without having to modify
  59     the main configuration file. Each drop-in file must have appropriate section headers.</para>
  60
  61     <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal>
  62     directories can be placed in <filename>/usr/lib/systemd/network</filename> or
  63     <filename>/run/systemd/network</filename> directories. Drop-in files in <filename>/etc/</filename>
  64     take precedence over those in <filename>/run/</filename> which in turn take precedence over those
  65     in <filename>/usr/lib/</filename>. Drop-in files under any of these directories take precedence
  66     over the main link file wherever located.</para>
  67
  68     <para>The link file contains a [Match] section, which determines if a given link file may be applied to a
  69     given device, as well as a [Link] section specifying how the device should be configured. The first (in
  70     lexical order) of the link files that matches a given device is applied. Note that a default file
  71     <filename>99-default.link</filename> is shipped by the system. Any user-supplied
  72     <filename>.link</filename> should hence have a lexically earlier name to be considered at all.</para>
  73
  74     <para>See <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
  75     diagnosing problems with <filename>.link</filename> files.</para>
  76   </refsect1>
  77
  78   <refsect1>
  79     <title>[Match] Section Options</title>
  80
  81     <para>A link file is said to match an interface if all matches specified by the [Match] section are
  82     satisfied. When a link file does not contain valid settings in [Match] section, then the file will
  83     match all interfaces and <command>systemd-udevd</command> warns about that. Hint: to avoid the
  84     warning and to make it clear that all interfaces shall be matched, add the following:
  85     <programlisting>OriginalName=*</programlisting>
  86     The first (in alphanumeric order) of the link files that matches a given interface is applied, all
  87     later files are ignored, even if they match as well. The following keys are accepted:</para>
  88
  89     <variablelist class='network-directives'>
  90       <!-- This list is reused in systemd.network(3), hence maintain a specific order:
  91            1. device matches shared between the two lists
  92            2. non-shared settings
  93            3. host matches shared between the two lists
  94         -->
  95
  96       <varlistentry id='mac-address'>
  97         <term><varname>MACAddress=</varname></term>
  98         <listitem>
  99           <para>A whitespace-separated list of hardware addresses. The acceptable formats are:</para>
 100
 101           <variablelist>
 102             <varlistentry>
 103               <term><option>colon-delimited hexadecimal</option></term>
 104               <listitem><para>
 105                 Each field must be one byte.
 106                 E.g. <literal>12:34:56:78:90:ab</literal> or <literal>AA:BB:CC:DD:EE:FF</literal>.
 107               </para>
 108
 109                 <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 110             </varlistentry>
 111             <varlistentry>
 112               <term><option>hyphen-delimited hexadecimal</option></term>
 113               <listitem><para>
 114                 Each field must be one byte.
 115                 E.g. <literal>12-34-56-78-90-ab</literal> or <literal>AA-BB-CC-DD-EE-FF</literal>.
 116               </para>
 117
 118                 <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 119             </varlistentry>
 120             <varlistentry>
 121               <term><option>dot-delimited hexadecimal</option></term>
 122               <listitem><para>
 123                 Each field must be two bytes.
 124                 E.g. <literal>1234.5678.90ab</literal> or <literal>AABB.CCDD.EEFF</literal>.
 125               </para>
 126
 127                 <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 128             </varlistentry>
 129             <varlistentry>
 130               <term><option>IPv4 address format</option></term>
 131               <listitem><para>
 132                 E.g. <literal>127.0.0.1</literal> or <literal>192.168.0.1</literal>.
 133               </para>
 134
 135                 <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 136             </varlistentry>
 137             <varlistentry>
 138               <term><option>IPv6 address format</option></term>
 139               <listitem><para>
 140                 E.g. <literal>2001:0db8:85a3::8a2e:0370:7334</literal> or <literal>::1</literal>.
 141               </para>
 142
 143                 <xi:include href="version-info.xml" xpointer="v250"/></listitem>
 144             </varlistentry>
 145           </variablelist>
 146
 147           <para>The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16
 148           (for IPv6 tunnel), or 20 (for InfiniBand). This option may appear more than once, in which
 149           case the lists are merged. If the empty string is assigned to this option, the list of
 150           hardware addresses defined prior to this is reset. Defaults to unset.</para>
 151
 152           <xi:include href="version-info.xml" xpointer="v211"/>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry id='permanent-mac-address'>
 157         <term><varname>PermanentMACAddress=</varname></term>
 158         <listitem>
 159           <para>A whitespace-separated list of hardware's permanent addresses. While
 160           <varname>MACAddress=</varname> matches the device's current MAC address, this matches the
 161           device's permanent MAC address, which may be different from the current one. Use full
 162           colon-, hyphen- or dot-delimited hexadecimal, or IPv4 or IPv6 address format. This option may
 163           appear more than once, in which case the lists are merged. If the empty string is assigned to
 164           this option, the list of hardware addresses defined prior to this is reset. Defaults to
 165           unset.</para>
 166
 167           <xi:include href="version-info.xml" xpointer="v245"/>
 168         </listitem>
 169       </varlistentry>
 170
 171       <varlistentry id='path'>
 172         <term><varname>Path=</varname></term>
 173         <listitem>
 174           <para>A whitespace-separated list of shell-style globs matching
 175           the persistent path, as exposed by the udev property
 176           <varname>ID_PATH</varname>.</para>
 177
 178           <xi:include href="version-info.xml" xpointer="v211"/>
 179         </listitem>
 180       </varlistentry>
 181
 182       <varlistentry id='driver'>
 183         <term><varname>Driver=</varname></term>
 184         <listitem>
 185           <para>A whitespace-separated list of shell-style globs matching the driver currently bound to the
 186           device, as exposed by the udev property <varname>ID_NET_DRIVER</varname> of its parent device, or
 187           if that is not set, the driver as exposed by <command>ethtool -i</command> of the device itself.
 188           If the list is prefixed with a "!", the test is inverted.</para>
 189
 190           <xi:include href="version-info.xml" xpointer="v211"/>
 191         </listitem>
 192       </varlistentry>
 193
 194       <varlistentry id='type'>
 195         <term><varname>Type=</varname></term>
 196         <listitem>
 197           <para>A whitespace-separated list of shell-style globs matching the device type, as exposed by
 198           <command>networkctl list</command>. If the list is prefixed with a "!", the test is inverted.
 199           Some valid values are <literal>ether</literal>, <literal>loopback</literal>, <literal>wlan</literal>, <literal>wwan</literal>.
 200           Valid types are named either from the udev <literal>DEVTYPE</literal> attribute, or
 201           <literal>ARPHRD_</literal> macros in <filename>linux/if_arp.h</filename>, so this is not comprehensive.
 202           </para>
 203
 204           <xi:include href="version-info.xml" xpointer="v211"/>
 205         </listitem>
 206       </varlistentry>
 207
 208       <varlistentry id='kind'>
 209         <term><varname>Kind=</varname></term>
 210         <listitem>
 211           <para>A whitespace-separated list of shell-style globs matching the device kind, as exposed by
 212           <command>networkctl status <replaceable>INTERFACE</replaceable></command> or
 213           <command>ip -d link show <replaceable>INTERFACE</replaceable></command>. If the list is
 214           prefixed with a "!", the test is inverted. Some valid values are <literal>bond</literal>,
 215           <literal>bridge</literal>, <literal>gre</literal>, <literal>tun</literal>,
 216           <literal>veth</literal>. Valid kinds are given by netlink's <literal>IFLA_INFO_KIND</literal>
 217           attribute, so this is not comprehensive.
 218           </para>
 219
 220           <xi:include href="version-info.xml" xpointer="v251"/>
 221         </listitem>
 222       </varlistentry>
 223
 224       <varlistentry id='property'>
 225         <term><varname>Property=</varname></term>
 226         <listitem>
 227           <para>A whitespace-separated list of udev property names with their values after equals sign
 228           (<literal>=</literal>). If multiple properties are specified, the test results are ANDed.
 229           If the list is prefixed with a "!", the test is inverted. If a value contains white
 230           spaces, then please quote whole key and value pair. If a value contains quotation, then
 231           please escape the quotation with <literal>\</literal>.</para>
 232
 233           <para>Example: if a .link file has the following:
 234           <programlisting>Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""</programlisting>
 235           then, the .link file matches only when an interface has all the above three properties.
 236           </para>
 237
 238           <xi:include href="version-info.xml" xpointer="v243"/>
 239         </listitem>
 240       </varlistentry>
 241
 242       <varlistentry>
 243         <term><varname>OriginalName=</varname></term>
 244         <listitem>
 245           <para>A whitespace-separated list of shell-style globs matching the device name, as exposed by the
 246           udev property "INTERFACE". This cannot be used to match on names that have already been changed
 247           from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be
 248           unstable between reboots.</para>
 249
 250           <xi:include href="version-info.xml" xpointer="v218"/>
 251         </listitem>
 252       </varlistentry>
 253
 254       <varlistentry id='host'>
 255         <term><varname>Host=</varname></term>
 256         <listitem>
 257           <para>Matches against the hostname or machine ID of the host. See <varname>ConditionHost=</varname> in
 258           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 259           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 260           If an empty string is assigned, the previously assigned value is cleared.
 261           </para>
 262
 263         <xi:include href="version-info.xml" xpointer="v211"/>
 264         </listitem>
 265       </varlistentry>
 266
 267       <varlistentry id='virtualization'>
 268         <term><varname>Virtualization=</varname></term>
 269         <listitem>
 270           <para>Checks whether the system is executed in a virtualized environment and optionally test
 271           whether it is a specific implementation. See <varname>ConditionVirtualization=</varname> in
 272           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 273           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 274           If an empty string is assigned, the previously assigned value is cleared.
 275           </para>
 276
 277           <xi:include href="version-info.xml" xpointer="v211"/>
 278         </listitem>
 279       </varlistentry>
 280
 281       <varlistentry id='kernel-command-line'>
 282         <term><varname>KernelCommandLine=</varname></term>
 283         <listitem>
 284           <para>Checks whether a specific kernel command line option is set. See
 285           <varname>ConditionKernelCommandLine=</varname> in
 286           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 287           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 288           If an empty string is assigned, the previously assigned value is cleared.
 289           </para>
 290
 291           <xi:include href="version-info.xml" xpointer="v211"/>
 292         </listitem>
 293       </varlistentry>
 294
 295       <varlistentry id='kernel-version'>
 296         <term><varname>KernelVersion=</varname></term>
 297         <listitem>
 298           <para>Checks whether the kernel version (as reported by <command>uname -r</command>) matches a certain
 299           expression. See <varname>ConditionKernelVersion=</varname> in
 300           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 301           details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 302           If an empty string is assigned, the previously assigned value is cleared.
 303           </para>
 304
 305         <xi:include href="version-info.xml" xpointer="v237"/>
 306         </listitem>
 307       </varlistentry>
 308
 309       <varlistentry id='credential'>
 310         <term><varname>Credential=</varname></term>
 311         <listitem>
 312           <para>Checks whether the specified credential was passed to the
 313           <filename>systemd-udevd.service</filename> service. See <ulink
 314           url="https://systemd.io/CREDENTIALS">System and Service Credentials</ulink> for details. When
 315           prefixed with an exclamation mark (<literal>!</literal>), the result is negated.  If an empty
 316           string is assigned, the previously assigned value is cleared.
 317           </para>
 318
 319           <xi:include href="version-info.xml" xpointer="v252"/>
 320         </listitem>
 321       </varlistentry>
 322
 323       <varlistentry id='architecture'>
 324         <term><varname>Architecture=</varname></term>
 325         <listitem>
 326           <para>Checks whether the system is running on a specific architecture. See
 327           <varname>ConditionArchitecture=</varname> in
 328           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 329           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 330           If an empty string is assigned, the previously assigned value is cleared.
 331           </para>
 332
 333           <xi:include href="version-info.xml" xpointer="v211"/>
 334         </listitem>
 335       </varlistentry>
 336
 337       <varlistentry id='firmware'>
 338         <term><varname>Firmware=</varname></term>
 339         <listitem>
 340           <para>Checks whether the system is running on a machine with the specified firmware. See
 341           <varname>ConditionFirmware=</varname> in
 342           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 343           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 344           If an empty string is assigned, the previously assigned value is cleared.
 345           </para>
 346
 347           <xi:include href="version-info.xml" xpointer="v249"/>
 348         </listitem>
 349       </varlistentry>
 350     </variablelist>
 351
 352   </refsect1>
 353
 354   <refsect1>
 355     <title>[Link] Section Options</title>
 356
 357     <para>The [Link] section accepts the following
 358     keys:</para>
 359
 360     <variablelist class='network-directives'>
 361       <varlistentry>
 362         <term><varname>Description=</varname></term>
 363         <listitem>
 364           <para>A description of the device.</para>
 365
 366           <xi:include href="version-info.xml" xpointer="v211"/>
 367         </listitem>
 368       </varlistentry>
 369       <varlistentry>
 370         <term><varname>Property=</varname></term>
 371         <listitem>
 372           <para>Set specified udev properties. This takes space separated list of key-value pairs
 373           concatenated with equal sign (<literal>=</literal>). Example:
 374           <programlisting>Property=HOGE=foo BAR=baz</programlisting>
 375           This option supports simple specifier expansion, see the Specifiers section below.
 376           This option can be specified multiple times. If an empty string is assigned, then the all previous
 377           assignments are cleared.</para>
 378
 379           <para>This setting is useful to configure the <literal>ID_NET_MANAGED_BY=</literal> property which
 380           declares which network management service shall manage the interface, which is respected by
 381           <command>systemd-networkd</command> and others. Use
 382           <programlisting>Property=ID_NET_MANAGED_BY=io.systemd.Network</programlisting>
 383           to declare explicitly that <command>systemd-networkd</command> shall manage the interface, or set
 384           the property to something else to declare explicitly it shall not do so. See
 385           <citerefentry><refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 386           for details how this property is used to match interface names.</para>
 387
 388           <xi:include href="version-info.xml" xpointer="v256"/>
 389         </listitem>
 390       </varlistentry>
 391       <varlistentry>
 392         <term><varname>ImportProperty=</varname></term>
 393         <listitem>
 394           <para>Import specified udev properties from the saved database. This takes space separated list of
 395           property names. Example: <programlisting>ImportProperty=HOGE BAR</programlisting>
 396           This option supports simple specifier expansion, see the Specifiers section below.
 397           This option can be specified multiple times. If an empty string is assigned, then the all previous
 398           assignments are cleared.</para>
 399           <para>If the same property is also set in <varname>Property=</varname> in the above, then the
 400           imported property value will be overridden by the value specified in <varname>Property=</varname>.
 401           </para>
 402
 403           <xi:include href="version-info.xml" xpointer="v256"/>
 404         </listitem>
 405       </varlistentry>
 406       <varlistentry>
 407         <term><varname>UnsetProperty=</varname></term>
 408         <listitem>
 409           <para>Unset specified udev properties. This takes space separated list of
 410           property names. Example: <programlisting>ImportProperty=HOGE BAR</programlisting>
 411           This option supports simple specifier expansion, see the Specifiers section below.
 412           This option can be specified multiple times. If an empty string is assigned, then the all previous
 413           assignments are cleared.</para>
 414           <para>This setting is applied after <varname>ImportProperty=</varname> and
 415           <varname>Property=</varname> are applied. Hence, if the same property is specified in
 416           <varname>ImportProperty=</varname> or <varname>Property=</varname>, then the imported or specified
 417           property value will be ignored, and the property will be unset.</para>
 418
 419           <xi:include href="version-info.xml" xpointer="v256"/>
 420         </listitem>
 421       </varlistentry>
 422       <varlistentry>
 423         <term><varname>Alias=</varname></term>
 424         <listitem>
 425           <para>The <varname>ifalias</varname> interface property is set to this value.</para>
 426
 427           <xi:include href="version-info.xml" xpointer="v211"/>
 428         </listitem>
 429       </varlistentry>
 430       <varlistentry>
 431         <term><varname>MACAddressPolicy=</varname></term>
 432         <listitem>
 433           <para>The policy by which the MAC address should be set. The
 434           available policies are:
 435           </para>
 436
 437           <variablelist>
 438             <varlistentry>
 439               <term><option>persistent</option></term>
 440               <listitem>
 441                 <para>If the hardware has a persistent MAC address, as
 442                 most hardware should, and if it is used by the kernel,
 443                 nothing is done. Otherwise, a new MAC address is
 444                 generated which is guaranteed to be the same on every
 445                 boot for the given machine and the given device, but
 446                 which is otherwise random. This feature depends on ID_NET_NAME_*
 447                 properties to exist for the link. On hardware where these
 448                 properties are not set, the generation of a persistent MAC address
 449                 will fail.</para>
 450
 451                 <xi:include href="version-info.xml" xpointer="v211"/>
 452               </listitem>
 453             </varlistentry>
 454             <varlistentry>
 455               <term><option>random</option></term>
 456               <listitem>
 457                 <para>If the kernel is using a random MAC address,
 458                 nothing is done. Otherwise, a new address is randomly
 459                 generated each time the device appears, typically at
 460                 boot. Either way, the random address will have the
 461                 <literal>unicast</literal> and
 462                 <literal>locally administered</literal> bits set.</para>
 463
 464                 <xi:include href="version-info.xml" xpointer="v211"/>
 465               </listitem>
 466             </varlistentry>
 467             <varlistentry>
 468               <term><option>none</option></term>
 469               <listitem>
 470                 <para>Keeps the MAC address assigned by the kernel. Or use the MAC address specified in
 471                 <varname>MACAddress=</varname>.</para>
 472
 473                 <xi:include href="version-info.xml" xpointer="v227"/>
 474               </listitem>
 475             </varlistentry>
 476           </variablelist>
 477
 478           <para>An empty string assignment is equivalent to setting <literal>none</literal>.</para>
 479
 480           <xi:include href="version-info.xml" xpointer="v211"/>
 481         </listitem>
 482       </varlistentry>
 483       <varlistentry>
 484         <term><varname>MACAddress=</varname></term>
 485         <listitem>
 486           <para>The interface MAC address to use. For this setting to take effect,
 487           <varname>MACAddressPolicy=</varname> must either be unset, empty, or <literal>none</literal>.
 488           </para>
 489
 490           <xi:include href="version-info.xml" xpointer="v211"/>
 491         </listitem>
 492       </varlistentry>
 493       <varlistentry>
 494         <term><varname>NamePolicy=</varname></term>
 495         <listitem>
 496           <para>An ordered, space-separated list of policies by which the interface name should be set.
 497           <varname>NamePolicy=</varname> may be disabled by specifying <option>net.ifnames=0</option> on the
 498           kernel command line. Each of the policies may fail, and the first successful one is used. The name
 499           is not set directly, but is exported to udev as the property <option>ID_NET_NAME</option>, which
 500           is, by default, used by a
 501           <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 502           rule to set <varname>NAME</varname>. The available policies are:
 503           </para>
 504
 505           <variablelist>
 506             <varlistentry>
 507               <term><option>kernel</option></term>
 508               <listitem>
 509                 <para>If the kernel claims that the name it has set
 510                 for a device is predictable, then no renaming is
 511                 performed.</para>
 512
 513                 <xi:include href="version-info.xml" xpointer="v216"/>
 514               </listitem>
 515             </varlistentry>
 516             <varlistentry>
 517               <term><option>database</option></term>
 518               <listitem>
 519                 <para>The name is set based on entries in the udev's
 520                 Hardware Database with the key
 521                 <varname>ID_NET_NAME_FROM_DATABASE</varname>.
 522                 </para>
 523
 524                 <xi:include href="version-info.xml" xpointer="v211"/>
 525               </listitem>
 526             </varlistentry>
 527             <varlistentry>
 528               <term><option>onboard</option></term>
 529               <listitem>
 530                 <para>The name is set based on information given by
 531                 the firmware for on-board devices, as exported by the
 532                 udev property <varname>ID_NET_NAME_ONBOARD</varname>.
 533                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 534                 </para>
 535
 536                 <xi:include href="version-info.xml" xpointer="v211"/>
 537               </listitem>
 538             </varlistentry>
 539             <varlistentry>
 540               <term><option>slot</option></term>
 541               <listitem>
 542                 <para>The name is set based on information given by
 543                 the firmware for hot-plug devices, as exported by the
 544                 udev property <varname>ID_NET_NAME_SLOT</varname>.
 545                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 546                 </para>
 547
 548                 <xi:include href="version-info.xml" xpointer="v211"/>
 549               </listitem>
 550             </varlistentry>
 551             <varlistentry>
 552               <term><option>path</option></term>
 553               <listitem>
 554                 <para>The name is set based on the device's physical
 555                 location, as exported by the udev property
 556                 <varname>ID_NET_NAME_PATH</varname>.
 557                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 558                 </para>
 559
 560                 <xi:include href="version-info.xml" xpointer="v211"/>
 561               </listitem>
 562             </varlistentry>
 563             <varlistentry>
 564               <term><option>mac</option></term>
 565               <listitem>
 566                 <para>The name is set based on the device's persistent
 567                 MAC address, as exported by the udev property
 568                 <varname>ID_NET_NAME_MAC</varname>.
 569                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 570                 </para>
 571
 572                 <xi:include href="version-info.xml" xpointer="v211"/>
 573               </listitem>
 574             </varlistentry>
 575             <varlistentry>
 576               <term><option>keep</option></term>
 577               <listitem>
 578                 <para>If the device already had a name given by userspace (as part of creation of the device
 579                 or a rename), keep it.</para>
 580
 581                 <xi:include href="version-info.xml" xpointer="v241"/>
 582               </listitem>
 583             </varlistentry>
 584           </variablelist>
 585
 586             <xi:include href="version-info.xml" xpointer="v211"/>
 587         </listitem>
 588       </varlistentry>
 589       <varlistentry>
 590         <term><varname>Name=</varname></term>
 591         <listitem>
 592           <para>The interface name to use. This option has lower precedence than
 593           <varname>NamePolicy=</varname>, so for this setting to take effect, <varname>NamePolicy=</varname>
 594           must either be unset, empty, disabled, or all policies configured there must fail. Also see the
 595           example below with <literal>Name=dmz0</literal>.</para>
 596
 597           <para>Note that specifying a name that the kernel might use for another interface (for example
 598           <literal>eth0</literal>) is dangerous because the name assignment done by udev will race with the
 599           assignment done by the kernel, and only one interface may use the name. Depending on the order of
 600           operations, either udev or the kernel will win, making the naming unpredictable. It is best to use
 601           some different prefix, for example <literal>internal0</literal>/<literal>external0</literal> or
 602           <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.</para>
 603
 604           <para>Interface names must have a minimum length of 1 character and a maximum length of 15
 605           characters, and may contain any 7bit ASCII character, with the exception of control characters,
 606           <literal>:</literal>, <literal>/</literal> and <literal>%</literal>. While <literal>.</literal> is
 607           an allowed character, it is recommended to avoid it when naming interfaces as various tools (such as
 608           <citerefentry><refentrytitle>resolvconf</refentrytitle><manvolnum>1</manvolnum></citerefentry>) use
 609           it as separator character. Also, fully numeric interface names are not allowed (in order to avoid
 610           ambiguity with interface specification by numeric indexes), nor are the special strings
 611           <literal>.</literal>, <literal>..</literal>, <literal>all</literal> and
 612           <literal>default</literal>.</para>
 613
 614           <xi:include href="version-info.xml" xpointer="v211"/>
 615         </listitem>
 616       </varlistentry>
 617       <varlistentry>
 618         <term><varname>AlternativeNamesPolicy=</varname></term>
 619         <listitem>
 620           <para>A space-separated list of policies by which the interface's alternative names
 621           should be set. Each of the policies may fail, and all successful policies are used. The
 622           available policies are <literal>database</literal>, <literal>onboard</literal>,
 623           <literal>slot</literal>, <literal>path</literal>, and <literal>mac</literal>. If the
 624           kernel does not support the alternative names, then this setting will be ignored.
 625           </para>
 626
 627           <xi:include href="version-info.xml" xpointer="v245"/>
 628         </listitem>
 629       </varlistentry>
 630       <varlistentry>
 631         <term><varname>AlternativeName=</varname></term>
 632         <listitem>
 633           <para>The alternative interface name to use. This option can be specified multiple times.
 634           If the empty string is assigned to this option, the list is reset, and all prior assignments
 635           have no effect. If the kernel does not support the alternative names, then this setting will
 636           be ignored.</para>
 637
 638           <para>Alternative interface names may be used to identify interfaces in various tools. In contrast
 639           to the primary name (as configured with <varname>Name=</varname> above) there may be multiple
 640           alternative names referring to the same interface. Alternative names may have a maximum length of
 641           127 characters, in contrast to the 15 allowed for the primary interface name, but otherwise are
 642           subject to the same naming constraints.</para>
 643
 644           <xi:include href="version-info.xml" xpointer="v245"/>
 645         </listitem>
 646       </varlistentry>
 647       <varlistentry>
 648         <term><varname>TransmitQueues=</varname></term>
 649         <listitem>
 650           <para>Specifies the device's number of transmit queues. An integer in the range 1…4096.
 651           When unset, the kernel's default will be used.</para>
 652
 653           <xi:include href="version-info.xml" xpointer="v248"/>
 654         </listitem>
 655       </varlistentry>
 656       <varlistentry>
 657         <term><varname>ReceiveQueues=</varname></term>
 658         <listitem>
 659           <para>Specifies the device's number of receive queues. An integer in the range 1…4096.
 660           When unset, the kernel's default will be used.</para>
 661
 662           <xi:include href="version-info.xml" xpointer="v248"/>
 663         </listitem>
 664       </varlistentry>
 665       <varlistentry>
 666         <term><varname>TransmitQueueLength=</varname></term>
 667         <listitem>
 668           <para>Specifies the transmit queue length of the device in number of packets. An unsigned integer
 669           in the range 0…4294967294. When unset, the kernel's default will be used.</para>
 670
 671           <xi:include href="version-info.xml" xpointer="v248"/>
 672         </listitem>
 673       </varlistentry>
 674       <varlistentry>
 675         <term><varname>MTUBytes=</varname></term>
 676         <listitem>
 677           <para>The maximum transmission unit in bytes to set for the
 678           device. The usual suffixes K, M, G are supported and are
 679           understood to the base of 1024.</para>
 680
 681           <xi:include href="version-info.xml" xpointer="v211"/>
 682         </listitem>
 683       </varlistentry>
 684       <varlistentry>
 685         <term><varname>BitsPerSecond=</varname></term>
 686         <listitem>
 687           <para>The speed to set for the device, the value is rounded
 688           down to the nearest Mbps. The usual suffixes K, M, G are
 689           supported and are understood to the base of 1000.</para>
 690
 691           <xi:include href="version-info.xml" xpointer="v211"/>
 692         </listitem>
 693       </varlistentry>
 694       <varlistentry>
 695         <term><varname>Duplex=</varname></term>
 696         <listitem>
 697           <para>The duplex mode to set for the device. The accepted values are <option>half</option> and
 698           <option>full</option>.</para>
 699
 700         <xi:include href="version-info.xml" xpointer="v211"/>
 701         </listitem>
 702       </varlistentry>
 703       <varlistentry>
 704         <term><varname>AutoNegotiation=</varname></term>
 705         <listitem>
 706           <para>Takes a boolean. If set to yes, automatic negotiation of transmission parameters is enabled.
 707           Autonegotiation is a procedure by which two connected ethernet devices choose
 708           common transmission parameters, such as speed, duplex mode, and flow control.
 709           When unset, the kernel's default will be used.</para>
 710
 711           <para>Note that if autonegotiation is enabled, speed and duplex settings are
 712           read-only. If autonegotiation is disabled, speed and duplex settings are writable
 713           if the driver supports multiple link modes.</para>
 714
 715           <xi:include href="version-info.xml" xpointer="v233"/>
 716         </listitem>
 717       </varlistentry>
 718       <varlistentry>
 719         <term><varname>WakeOnLan=</varname></term>
 720         <listitem>
 721           <para>The Wake-on-LAN policy to set for the device. Takes the special value
 722           <literal>off</literal> which disables Wake-on-LAN, or space separated list of the following
 723           words:</para>
 724
 725           <variablelist>
 726             <varlistentry>
 727               <term><option>phy</option></term>
 728               <listitem>
 729                 <para>Wake on PHY activity.</para>
 730
 731               <xi:include href="version-info.xml" xpointer="v211"/>
 732               </listitem>
 733             </varlistentry>
 734             <varlistentry>
 735               <term><option>unicast</option></term>
 736               <listitem>
 737                 <para>Wake on unicast messages.</para>
 738
 739               <xi:include href="version-info.xml" xpointer="v235"/>
 740               </listitem>
 741             </varlistentry>
 742             <varlistentry>
 743               <term><option>multicast</option></term>
 744               <listitem>
 745                 <para>Wake on multicast messages.</para>
 746
 747               <xi:include href="version-info.xml" xpointer="v235"/>
 748               </listitem>
 749             </varlistentry>
 750             <varlistentry>
 751               <term><option>broadcast</option></term>
 752               <listitem>
 753                 <para>Wake on broadcast messages.</para>
 754
 755               <xi:include href="version-info.xml" xpointer="v235"/>
 756               </listitem>
 757             </varlistentry>
 758             <varlistentry>
 759               <term><option>arp</option></term>
 760               <listitem>
 761                 <para>Wake on ARP.</para>
 762
 763               <xi:include href="version-info.xml" xpointer="v235"/>
 764               </listitem>
 765             </varlistentry>
 766             <varlistentry>
 767               <term><option>magic</option></term>
 768               <listitem>
 769                 <para>Wake on receipt of a magic packet.
 770                 </para>
 771
 772                 <xi:include href="version-info.xml" xpointer="v211"/>
 773               </listitem>
 774             </varlistentry>
 775             <varlistentry>
 776               <term><option>secureon</option></term>
 777               <listitem>
 778                 <para>Enable SecureOn password for MagicPacket. Implied when
 779                 <varname>WakeOnLanPassword=</varname> is specified. If specified without
 780                 <varname>WakeOnLanPassword=</varname> option, then the password is read from the
 781                 credential <literal><replaceable>LINK</replaceable>.link.wol.password</literal> (e.g.,
 782                 <literal>60-foo.link.wol.password</literal>), and if the credential not found, then
 783                 read from <literal>wol.password</literal>. See
 784                 <varname>ImportCredential=</varname>/<varname>LoadCredential=</varname>/<varname>SetCredential=</varname> in
 785                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 786                 for details. The password in the credential, must be 6 bytes in hex format with each
 787                 byte separated by a colon (<literal>:</literal>) like an Ethernet MAC address, e.g.,
 788                 <literal>aa:bb:cc:dd:ee:ff</literal>.</para>
 789
 790                 <xi:include href="version-info.xml" xpointer="v235"/>
 791               </listitem>
 792             </varlistentry>
 793           </variablelist>
 794
 795           <para>Defaults to unset, and the device's default will be used. This setting can be specified
 796           multiple times. If an empty string is assigned, then the all previous assignments are
 797           cleared.</para>
 798
 799           <xi:include href="version-info.xml" xpointer="v211"/>
 800         </listitem>
 801       </varlistentry>
 802       <varlistentry>
 803         <term><varname>WakeOnLanPassword=</varname></term>
 804         <listitem>
 805           <para>Specifies the SecureOn password for MagicPacket. Takes an absolute path to a regular
 806           file or an <constant>AF_UNIX</constant> stream socket, or the plain password. When a path to
 807           a regular file is specified, the password is read from it. When an
 808           <constant>AF_UNIX</constant> stream socket is specified, a connection is made to it and the
 809           password is read from it. The password must be 6 bytes in hex format with each byte separated
 810           by a colon (<literal>:</literal>) like an Ethernet MAC address, e.g.,
 811           <literal>aa:bb:cc:dd:ee:ff</literal>. This implies <varname>WakeOnLan=secureon</varname>.
 812           Defaults to unset, and the current value will not be changed.</para>
 813
 814           <xi:include href="version-info.xml" xpointer="v250"/>
 815         </listitem>
 816       </varlistentry>
 817       <varlistentry>
 818         <term><varname>Port=</varname></term>
 819         <listitem>
 820           <para>The port option is used to select the device port. The
 821           supported values are:</para>
 822
 823           <variablelist>
 824             <varlistentry>
 825               <term><option>tp</option></term>
 826               <listitem>
 827                 <para>An Ethernet interface using Twisted-Pair cable as the medium.</para>
 828
 829               <xi:include href="version-info.xml" xpointer="v234"/>
 830               </listitem>
 831             </varlistentry>
 832             <varlistentry>
 833               <term><option>aui</option></term>
 834               <listitem>
 835                 <para>Attachment Unit Interface (AUI). Normally used with hubs.
 836                 </para>
 837
 838                 <xi:include href="version-info.xml" xpointer="v234"/>
 839               </listitem>
 840             </varlistentry>
 841             <varlistentry>
 842               <term><option>bnc</option></term>
 843               <listitem>
 844                 <para>An Ethernet interface using BNC connectors and co-axial cable.</para>
 845
 846               <xi:include href="version-info.xml" xpointer="v234"/>
 847               </listitem>
 848             </varlistentry>
 849             <varlistentry>
 850               <term><option>mii</option></term>
 851               <listitem>
 852                 <para>An Ethernet interface using a Media Independent Interface (MII).</para>
 853
 854               <xi:include href="version-info.xml" xpointer="v234"/>
 855               </listitem>
 856             </varlistentry>
 857             <varlistentry>
 858               <term><option>fibre</option></term>
 859               <listitem>
 860                 <para>An Ethernet interface using Optical Fibre as the medium.</para>
 861
 862               <xi:include href="version-info.xml" xpointer="v234"/>
 863               </listitem>
 864             </varlistentry>
 865           </variablelist>
 866
 867             <xi:include href="version-info.xml" xpointer="v234"/>
 868         </listitem>
 869       </varlistentry>
 870       <varlistentry>
 871         <term><varname>Advertise=</varname></term>
 872         <listitem>
 873           <para>This sets what speeds and duplex modes of operation are advertised for auto-negotiation.
 874           This implies <literal>AutoNegotiation=yes</literal>. The supported values are:
 875
 876           <table>
 877             <title>Supported advertise values</title>
 878             <tgroup cols='3'>
 879               <colspec colname='Advertise' />
 880               <colspec colname='Speed' />
 881               <colspec colname='Duplex Mode' />
 882
 883               <thead><row>
 884                 <entry>Advertise</entry>
 885                 <entry>Speed (Mbps)</entry>
 886                 <entry>Duplex Mode</entry>
 887               </row></thead>
 888               <xi:include href="ethtool-link-mode.xml" />
 889             </tgroup>
 890           </table>
 891
 892           By default, this is unset, i.e. all possible modes will be advertised.
 893           This option may be specified more than once, in which case all specified speeds and modes are advertised.
 894           If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect.
 895           </para>
 896
 897           <xi:include href="version-info.xml" xpointer="v240"/>
 898         </listitem>
 899       </varlistentry>
 900       <varlistentry>
 901         <term><varname>ReceiveChecksumOffload=</varname></term>
 902         <listitem>
 903           <para>Takes a boolean. If set to true, hardware offload for checksumming of ingress
 904           network packets is enabled. When unset, the kernel's default will be used.</para>
 905
 906           <xi:include href="version-info.xml" xpointer="v245"/>
 907         </listitem>
 908       </varlistentry>
 909       <varlistentry>
 910         <term><varname>TransmitChecksumOffload=</varname></term>
 911         <listitem>
 912           <para>Takes a boolean. If set to true, hardware offload for checksumming of egress
 913           network packets is enabled. When unset, the kernel's default will be used.</para>
 914
 915           <xi:include href="version-info.xml" xpointer="v245"/>
 916         </listitem>
 917       </varlistentry>
 918       <varlistentry>
 919         <term><varname>TCPSegmentationOffload=</varname></term>
 920         <listitem>
 921           <para>Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is enabled.
 922           When unset, the kernel's default will be used.</para>
 923
 924           <xi:include href="version-info.xml" xpointer="v232"/>
 925         </listitem>
 926       </varlistentry>
 927        <varlistentry>
 928       <term><varname>TCP6SegmentationOffload=</varname></term>
 929         <listitem>
 930           <para>Takes a boolean. If set to true, TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled.
 931           When unset, the kernel's default will be used.</para>
 932
 933           <xi:include href="version-info.xml" xpointer="v235"/>
 934         </listitem>
 935       </varlistentry>
 936       <varlistentry>
 937         <term><varname>GenericSegmentationOffload=</varname></term>
 938         <listitem>
 939           <para>Takes a boolean. If set to true, Generic Segmentation Offload (GSO) is enabled.
 940           When unset, the kernel's default will be used.</para>
 941
 942           <xi:include href="version-info.xml" xpointer="v232"/>
 943         </listitem>
 944       </varlistentry>
 945       <varlistentry>
 946         <term><varname>PartialGenericSegmentationOffload=</varname></term>
 947         <listitem>
 948           <para>Takes a boolean. If set to true, Partial Generic Segmentation Offload (GSO_Partial) is
 949           enabled. See
 950           <ulink url="https://docs.kernel.org/networking/segmentation-offloads.html#partial-generic-segmentation-offload">
 951           Partial Generic Segmentation Offload</ulink> for more details.
 952           When unset, the kernel's default will be used.</para>
 953
 954           <xi:include href="version-info.xml" xpointer="v258"/>
 955         </listitem>
 956       </varlistentry>
 957       <varlistentry>
 958         <term><varname>GenericReceiveOffload=</varname></term>
 959         <listitem>
 960           <para>Takes a boolean. If set to true, Generic Receive Offload (GRO) is enabled.
 961           When unset, the kernel's default will be used.</para>
 962
 963           <xi:include href="version-info.xml" xpointer="v232"/>
 964         </listitem>
 965       </varlistentry>
 966       <varlistentry>
 967         <term><varname>GenericReceiveOffloadHardware=</varname></term>
 968         <listitem>
 969           <para>Takes a boolean. If set to true, hardware accelerated Generic Receive Offload (GRO) is
 970           enabled. When unset, the kernel's default will be used.</para>
 971
 972           <xi:include href="version-info.xml" xpointer="v250"/>
 973         </listitem>
 974       </varlistentry>
 975       <varlistentry>
 976         <term><varname>LargeReceiveOffload=</varname></term>
 977         <listitem>
 978           <para>Takes a boolean. If set to true, Large Receive Offload (LRO) is enabled.
 979           When unset, the kernel's default will be used.</para>
 980
 981           <xi:include href="version-info.xml" xpointer="v232"/>
 982         </listitem>
 983       </varlistentry>
 984       <varlistentry>
 985         <term><varname>ReceivePacketSteeringCPUMask=</varname></term>
 986         <listitem>
 987           <para>Configures Receive Packet Steering (RPS) list of CPUs to which RPS may forward traffic.
 988           Takes a list of CPU indices or ranges separated by either whitespace or commas. Alternatively,
 989           takes the special value <literal>all</literal>, which will include all available CPUs in the mask.
 990           CPU ranges are specified by the lower and upper CPU indices separated by a dash (e.g. <literal>2-6</literal>).
 991           This option may be specified more than once, in which case the specified list of CPU ranges are merged.
 992           If an empty string is assigned, the list is reset, all assignments prior to this will have no effect.
 993           Defaults to unset and RPS CPU list is unchanged. To disable RPS when it was previously enabled, use the
 994           special value <literal>disable</literal>.</para>
 995
 996           <xi:include href="version-info.xml" xpointer="v256"/>
 997         </listitem>
 998       </varlistentry>
 999       <varlistentry>
1000         <term><varname>ReceiveVLANCTAGHardwareAcceleration=</varname></term>
1001         <listitem>
1002           <para>Takes a boolean. If set to true, receive VLAN CTAG hardware acceleration is enabled.
1003           When unset, the kernel's default will be used.</para>
1004
1005           <xi:include href="version-info.xml" xpointer="v250"/>
1006         </listitem>
1007       </varlistentry>
1008       <varlistentry>
1009         <term><varname>TransmitVLANCTAGHardwareAcceleration=</varname></term>
1010         <listitem>
1011           <para>Takes a boolean. If set to true, transmit VLAN CTAG hardware acceleration is enabled.
1012           When unset, the kernel's default will be used.</para>
1013
1014           <xi:include href="version-info.xml" xpointer="v250"/>
1015         </listitem>
1016       </varlistentry>
1017       <varlistentry>
1018         <term><varname>ReceiveVLANCTAGFilter=</varname></term>
1019         <listitem>
1020           <para>Takes a boolean. If set to true, receive filtering on VLAN CTAGs is enabled.
1021           When unset, the kernel's default will be used.</para>
1022
1023           <xi:include href="version-info.xml" xpointer="v250"/>
1024         </listitem>
1025       </varlistentry>
1026       <varlistentry>
1027         <term><varname>TransmitVLANSTAGHardwareAcceleration=</varname></term>
1028         <listitem>
1029           <para>Takes a boolean. If set to true, transmit VLAN STAG hardware acceleration is enabled.
1030           When unset, the kernel's default will be used.</para>
1031
1032           <xi:include href="version-info.xml" xpointer="v250"/>
1033         </listitem>
1034       </varlistentry>
1035       <varlistentry>
1036         <term><varname>NTupleFilter=</varname></term>
1037         <listitem>
1038           <para>Takes a boolean. If set to true, receive N-tuple filters and actions are enabled.
1039           When unset, the kernel's default will be used.</para>
1040
1041           <xi:include href="version-info.xml" xpointer="v250"/>
1042         </listitem>
1043       </varlistentry>
1044       <varlistentry>
1045         <term><varname>ReceiveFCS=</varname></term>
1046         <listitem>
1047           <para>Takes a boolean. If set to true, pass the Frame Check Sequence (FCS) value up the stack
1048           without trimming it, and allow userspace to calculate error rate or link health.
1049           When unset, the kernel's default will be used.</para>
1050
1051           <xi:include href="version-info.xml" xpointer="v258"/>
1052         </listitem>
1053       </varlistentry>
1054       <varlistentry>
1055         <term><varname>ReceiveAll=</varname></term>
1056         <listitem>
1057           <para>Takes a boolean. If set to true, allow to also receive damaged ethernet frames.
1058           When unset, the kernel's default will be used.</para>
1059
1060           <xi:include href="version-info.xml" xpointer="v258"/>
1061         </listitem>
1062       </varlistentry>
1063       <varlistentry>
1064         <term><varname>RxChannels=</varname></term>
1065         <term><varname>TxChannels=</varname></term>
1066         <term><varname>OtherChannels=</varname></term>
1067         <term><varname>CombinedChannels=</varname></term>
1068         <listitem>
1069           <para>Specifies the number of receive, transmit, other, or combined channels, respectively.
1070           Takes an unsigned integer in the range 1…4294967295 or <literal>max</literal>. If set to
1071           <literal>max</literal>, the advertised maximum value of the hardware will be used. When
1072           unset, the number will not be changed. Defaults to unset.</para>
1073
1074           <xi:include href="version-info.xml" xpointer="v239"/>
1075         </listitem>
1076       </varlistentry>
1077       <varlistentry>
1078         <term><varname>RxBufferSize=</varname></term>
1079         <term><varname>RxMiniBufferSize=</varname></term>
1080         <term><varname>RxJumboBufferSize=</varname></term>
1081         <term><varname>TxBufferSize=</varname></term>
1082         <listitem>
1083           <para>Specifies the maximum number of pending packets in the NIC receive buffer, mini receive
1084           buffer, jumbo receive buffer, or transmit buffer, respectively. Takes an unsigned integer in
1085           the range 1…4294967295 or <literal>max</literal>. If set to <literal>max</literal>, the
1086           advertised maximum value of the hardware will be used. When unset, the number will not be
1087           changed. Defaults to unset.</para>
1088
1089           <xi:include href="version-info.xml" xpointer="v244"/>
1090         </listitem>
1091       </varlistentry>
1092       <varlistentry>
1093         <term><varname>RxFlowControl=</varname></term>
1094         <listitem>
1095           <para>Takes a boolean. When set, enables receive flow control, also known as the ethernet
1096           receive PAUSE message (generate and send ethernet PAUSE frames). When unset, the kernel's
1097           default will be used.</para>
1098
1099           <xi:include href="version-info.xml" xpointer="v246"/>
1100         </listitem>
1101       </varlistentry>
1102       <varlistentry>
1103         <term><varname>TxFlowControl=</varname></term>
1104         <listitem>
1105           <para>Takes a boolean. When set, enables transmit flow control, also known as the ethernet
1106           transmit PAUSE message (respond to received ethernet PAUSE frames). When unset, the kernel's
1107           default will be used.</para>
1108
1109           <xi:include href="version-info.xml" xpointer="v246"/>
1110         </listitem>
1111       </varlistentry>
1112       <varlistentry>
1113         <term><varname>AutoNegotiationFlowControl=</varname></term>
1114         <listitem>
1115           <para>Takes a boolean. When set, auto negotiation enables the interface to exchange state
1116           advertisements with the connected peer so that the two devices can agree on the ethernet
1117           PAUSE configuration. When unset, the kernel's default will be used.</para>
1118
1119           <xi:include href="version-info.xml" xpointer="v246"/>
1120         </listitem>
1121       </varlistentry>
1122       <varlistentry>
1123         <term><varname>GenericSegmentOffloadMaxBytes=</varname></term>
1124         <listitem>
1125           <para>Specifies the maximum size of a Generic Segment Offload (GSO) packet the
1126           device should accept. The usual suffixes K, M, G are supported and are
1127           understood to the base of 1024. An unsigned integer in the range 1…65536.
1128           Defaults to unset.</para>
1129
1130           <xi:include href="version-info.xml" xpointer="v248"/>
1131         </listitem>
1132       </varlistentry>
1133       <varlistentry>
1134         <term><varname>GenericSegmentOffloadMaxSegments=</varname></term>
1135         <listitem>
1136           <para>Specifies the maximum number of Generic Segment Offload (GSO) segments the device should
1137           accept. An unsigned integer in the range 1…65535. Defaults to unset.</para>
1138
1139           <xi:include href="version-info.xml" xpointer="v248"/>
1140         </listitem>
1141       </varlistentry>
1142       <varlistentry>
1143         <term><varname>UseAdaptiveRxCoalesce=</varname></term>
1144         <term><varname>UseAdaptiveTxCoalesce=</varname></term>
1145         <listitem>
1146           <para>Boolean properties that, when set, enable/disable adaptive Rx/Tx coalescing if the hardware
1147           supports it. When unset, the kernel's default will be used.</para>
1148
1149           <xi:include href="version-info.xml" xpointer="v250"/>
1150         </listitem>
1151       </varlistentry>
1152       <varlistentry>
1153         <term><varname>RxCoalesceSec=</varname></term>
1154         <term><varname>RxCoalesceIrqSec=</varname></term>
1155         <term><varname>RxCoalesceLowSec=</varname></term>
1156         <term><varname>RxCoalesceHighSec=</varname></term>
1157         <term><varname>TxCoalesceSec=</varname></term>
1158         <term><varname>TxCoalesceIrqSec=</varname></term>
1159         <term><varname>TxCoalesceLowSec=</varname></term>
1160         <term><varname>TxCoalesceHighSec=</varname></term>
1161         <listitem>
1162           <para>These properties configure the delay before Rx/Tx interrupts are generated after a packet is
1163           sent/received. The <literal>Irq</literal> properties come into effect when the host is servicing an
1164           IRQ. The <literal>Low</literal> and <literal>High</literal> properties come into effect when the
1165           packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold
1166           respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's defaults will be
1167           used.</para>
1168
1169           <xi:include href="version-info.xml" xpointer="v250"/>
1170         </listitem>
1171       </varlistentry>
1172         <varlistentry>
1173         <term><varname>RxMaxCoalescedFrames=</varname></term>
1174         <term><varname>RxMaxCoalescedIrqFrames=</varname></term>
1175         <term><varname>RxMaxCoalescedLowFrames=</varname></term>
1176         <term><varname>RxMaxCoalescedHighFrames=</varname></term>
1177         <term><varname>TxMaxCoalescedFrames=</varname></term>
1178         <term><varname>TxMaxCoalescedIrqFrames=</varname></term>
1179         <term><varname>TxMaxCoalescedLowFrames=</varname></term>
1180         <term><varname>TxMaxCoalescedHighFrames=</varname></term>
1181         <listitem>
1182           <para>These properties configure the maximum number of frames that are sent/received before a Rx/Tx
1183           interrupt is generated. The <literal>Irq</literal> properties come into effect when the host is
1184           servicing an IRQ. The <literal>Low</literal> and <literal>High</literal> properties come into
1185           effect when the packet rate drops below the low packet rate threshold or exceeds the high packet
1186           rate threshold respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's
1187           defaults will be used.</para>
1188
1189           <xi:include href="version-info.xml" xpointer="v250"/>
1190         </listitem>
1191       </varlistentry>
1192       <varlistentry>
1193         <term><varname>CoalescePacketRateLow=</varname></term>
1194         <term><varname>CoalescePacketRateHigh=</varname></term>
1195         <listitem>
1196           <para>These properties configure the low and high packet rate (expressed in packets per second)
1197           threshold respectively and are used to determine when the corresponding coalescing settings for low
1198           and high packet rates come into effect if adaptive Rx/Tx coalescing is enabled. If unset, the
1199           kernel's defaults will be used.</para>
1200
1201           <xi:include href="version-info.xml" xpointer="v250"/>
1202         </listitem>
1203       </varlistentry>
1204       <varlistentry>
1205         <term><varname>CoalescePacketRateSampleIntervalSec=</varname></term>
1206         <listitem>
1207           <para>Configures how often to sample the packet rate used for adaptive Rx/Tx coalescing. This
1208           property cannot be zero. This lowest time granularity supported by this property is seconds.
1209           Partial seconds will be rounded up before being passed to the kernel. If unset, the kernel's
1210           default will be used.</para>
1211
1212           <xi:include href="version-info.xml" xpointer="v250"/>
1213         </listitem>
1214       </varlistentry>
1215       <varlistentry>
1216         <term><varname>StatisticsBlockCoalesceSec=</varname></term>
1217         <listitem>
1218           <para>How long to delay driver in-memory statistics block updates. If the driver does not have an
1219           in-memory statistic block, this property is ignored. This property cannot be zero. If unset, the
1220           kernel's default will be used.</para>
1221
1222           <xi:include href="version-info.xml" xpointer="v250"/>
1223         </listitem>
1224       </varlistentry>
1225
1226       <varlistentry>
1227         <term><varname>MDI=</varname></term>
1228         <listitem>
1229           <para>Specifies the medium dependent interface (MDI) mode for the interface. A MDI describes
1230           the interface from a physical layer implementation to the physical medium used to carry the
1231           transmission. Takes one of the following words: <literal>straight</literal> (or equivalently:
1232           <literal>mdi</literal>), <literal>crossover</literal> (or equivalently:
1233           <literal>mdi-x</literal>, <literal>mdix</literal>), and <literal>auto</literal>. When
1234           <literal>straight</literal>, the MDI straight through mode will be used. When
1235           <literal>crossover</literal>, the MDI crossover (MDI-X) mode will be used. When
1236           <literal>auto</literal>, the MDI status is automatically detected. Defaults to unset, and the
1237           kernel's default will be used.</para>
1238
1239           <xi:include href="version-info.xml" xpointer="v251"/>
1240         </listitem>
1241       </varlistentry>
1242
1243       <varlistentry>
1244         <term><varname>SR-IOVVirtualFunctions=</varname></term>
1245         <listitem>
1246           <para>Specifies the number of SR-IOV virtual functions. Takes an integer in the range
1247           0…2147483647. Defaults to unset, and automatically determined from the values specified in
1248           the <varname>VirtualFunction=</varname> settings in the [SR-IOV] sections.</para>
1249
1250           <xi:include href="version-info.xml" xpointer="v251"/>
1251         </listitem>
1252       </varlistentry>
1253
1254     </variablelist>
1255   </refsect1>
1256
1257   <refsect1 id='sr-iov'>
1258     <title>[SR-IOV] Section Options</title>
1259     <para>The [SR-IOV] section accepts the following keys. Specify several [SR-IOV] sections to
1260     configure several SR-IOVs. SR-IOV provides the ability to partition a single physical PCI resource
1261     into virtual PCI functions which can then be injected into a VM. In the case of network VFs, SR-IOV
1262     improves north-south network performance (that is, traffic with endpoints outside the host machine)
1263     by allowing traffic to bypass the host machine’s network stack.</para>
1264
1265     <variablelist class='network-directives'>
1266       <varlistentry>
1267         <term><varname>VirtualFunction=</varname></term>
1268         <listitem>
1269           <para>Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move
1270           data in and out. Takes an integer in the range 0…2147483646. This option is compulsory.
1271           </para>
1272
1273           <xi:include href="version-info.xml" xpointer="v251"/>
1274         </listitem>
1275       </varlistentry>
1276
1277       <varlistentry>
1278         <term><varname>VLANId=</varname></term>
1279         <listitem>
1280           <para>Specifies VLAN ID of the virtual function. Takes an integer in the range 1…4095.</para>
1281
1282         <xi:include href="version-info.xml" xpointer="v251"/>
1283         </listitem>
1284       </varlistentry>
1285
1286       <varlistentry>
1287         <term><varname>QualityOfService=</varname></term>
1288         <listitem>
1289           <para>Specifies quality of service of the virtual function. Takes an integer in the range
1290           1…4294967294.</para>
1291
1292           <xi:include href="version-info.xml" xpointer="v251"/>
1293         </listitem>
1294       </varlistentry>
1295
1296       <varlistentry>
1297         <term><varname>VLANProtocol=</varname></term>
1298         <listitem>
1299           <para>Specifies VLAN protocol of the virtual function. Takes <literal>802.1Q</literal> or
1300           <literal>802.1ad</literal>.</para>
1301
1302         <xi:include href="version-info.xml" xpointer="v251"/>
1303         </listitem>
1304       </varlistentry>
1305
1306       <varlistentry>
1307         <term><varname>MACSpoofCheck=</varname></term>
1308         <listitem>
1309           <para>Takes a boolean. Controls the MAC spoof checking. When unset, the kernel's default will
1310           be used.</para>
1311
1312           <xi:include href="version-info.xml" xpointer="v251"/>
1313         </listitem>
1314       </varlistentry>
1315
1316       <varlistentry>
1317         <term><varname>QueryReceiveSideScaling=</varname></term>
1318         <listitem>
1319           <para>Takes a boolean. Toggle the ability of querying the receive side scaling (RSS)
1320           configuration of the virtual function (VF). The VF RSS information like RSS hash key may be
1321           considered sensitive on some devices where this information is shared between VF and the
1322           physical function (PF). When unset, the kernel's default will be used.</para>
1323
1324           <xi:include href="version-info.xml" xpointer="v251"/>
1325         </listitem>
1326       </varlistentry>
1327
1328       <varlistentry>
1329         <term><varname>Trust=</varname></term>
1330         <listitem>
1331           <para>Takes a boolean. Allows one to set trust mode of the virtual function (VF). When set,
1332           VF users can set a specific feature which may impact security and/or performance. When unset,
1333           the kernel's default will be used.</para>
1334
1335           <xi:include href="version-info.xml" xpointer="v251"/>
1336         </listitem>
1337       </varlistentry>
1338
1339       <varlistentry>
1340         <term><varname>LinkState=</varname></term>
1341         <listitem>
1342           <para>Allows one to set the link state of the virtual function (VF). Takes a boolean or a
1343           special value <literal>auto</literal>. Setting to <literal>auto</literal> means a
1344           reflection of the physical function (PF) link state, <literal>yes</literal> lets the VF to
1345           communicate with other VFs on this host even if the PF link state is down,
1346           <literal>no</literal> causes the hardware to drop any packets sent by the VF. When unset,
1347           the kernel's default will be used.</para>
1348
1349           <xi:include href="version-info.xml" xpointer="v251"/>
1350         </listitem>
1351       </varlistentry>
1352
1353       <varlistentry>
1354         <term><varname>MACAddress=</varname></term>
1355         <listitem>
1356           <para>Specifies the MAC address for the virtual function.</para>
1357
1358         <xi:include href="version-info.xml" xpointer="v251"/>
1359         </listitem>
1360       </varlistentry>
1361     </variablelist>
1362   </refsect1>
1363
1364   <refsect1>
1365     <title>Specifiers</title>
1366
1367     <para>Some settings resolve specifiers which may be used to write generic unit files referring to runtime
1368     or unit parameters that are replaced when the unit files are loaded. Specifiers must be known and
1369     resolvable for the setting to be valid. The following specifiers are understood:</para>
1370
1371     <table class='specifiers'>
1372       <title>Specifiers available in unit files</title>
1373       <tgroup cols='3' align='left' colsep='1' rowsep='1'>
1374         <colspec colname="spec" />
1375         <colspec colname="mean" />
1376         <colspec colname="detail" />
1377         <thead>
1378           <row>
1379             <entry>Specifier</entry>
1380             <entry>Meaning</entry>
1381             <entry>Details</entry>
1382           </row>
1383         </thead>
1384         <tbody>
1385           <xi:include href="standard-specifiers.xml" xpointer="a"/>
1386           <xi:include href="standard-specifiers.xml" xpointer="A"/>
1387           <xi:include href="standard-specifiers.xml" xpointer="b"/>
1388           <xi:include href="standard-specifiers.xml" xpointer="B"/>
1389           <xi:include href="standard-specifiers.xml" xpointer="H"/>
1390           <xi:include href="standard-specifiers.xml" xpointer="l"/>
1391           <xi:include href="standard-specifiers.xml" xpointer="m"/>
1392           <xi:include href="standard-specifiers.xml" xpointer="M"/>
1393           <xi:include href="standard-specifiers.xml" xpointer="o"/>
1394           <xi:include href="standard-specifiers.xml" xpointer="q"/>
1395           <xi:include href="standard-specifiers.xml" xpointer="T"/>
1396           <xi:include href="standard-specifiers.xml" xpointer="v"/>
1397           <xi:include href="standard-specifiers.xml" xpointer="V"/>
1398           <xi:include href="standard-specifiers.xml" xpointer="w"/>
1399           <xi:include href="standard-specifiers.xml" xpointer="W"/>
1400         </tbody>
1401       </tgroup>
1402     </table>
1403   </refsect1>
1404
1405   <refsect1>
1406     <title>Examples</title>
1407
1408     <example>
1409       <title>/usr/lib/systemd/network/99-default.link</title>
1410
1411       <para>The link file <filename>99-default.link</filename> that is shipped with systemd defines the
1412       default policies for the interface name, alternative names, and MAC address of links.</para>
1413
1414       <programlisting>[Match]
1415 OriginalName=*
1416
1417 [Link]
1418 NamePolicy=keep kernel database onboard slot path
1419 AlternativeNamesPolicy=database onboard slot path
1420 MACAddressPolicy=persistent</programlisting>
1421     </example>
1422
1423     <example>
1424       <title>/etc/systemd/network/10-dmz.link</title>
1425
1426       <para>This example assigns the fixed name <literal>dmz0</literal> to the interface with the MAC address
1427       00:a0:de:63:7a:e6:</para>
1428
1429       <programlisting>[Match]
1430 MACAddress=00:a0:de:63:7a:e6
1431
1432 [Link]
1433 Name=dmz0</programlisting>
1434
1435       <para><varname>NamePolicy=</varname> is not set, so <varname>Name=</varname> takes effect. We use the
1436       <literal>10-</literal> prefix to order this file early in the list. Note that it needs to be before
1437       <filename>99-default.link</filename>, i.e. it needs a numerical prefix, to have any effect at all.</para>
1438     </example>
1439
1440     <example>
1441       <title>(Re-)applying a .link file to an interface</title>
1442
1443       <para>After a new .link file has been created, or an existing .link file modified, the new settings
1444       may be applied to the matching interface with the following commands:</para>
1445
1446       <programlisting>$ sudo udevadm control --reload
1447 $ sudo ip link set eth0 down
1448 $ sudo udevadm trigger --verbose --settle --action add /sys/class/net/eth0</programlisting>
1449
1450       <para>You may also need to stop the service that manages the network interface, e.g.
1451       <citerefentry><refentrytitle>systemd-networkd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
1452       or <filename>NetworkManager.service</filename> before the above operation, and then restart the service
1453       after that. For more details about <command>udevadm</command> command, see
1454       <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
1455     </example>
1456
1457     <example>
1458       <title>Debugging <varname>NamePolicy=</varname> assignments</title>
1459
1460       <programlisting>$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
1461 …
1462 Parsed configuration file /usr/lib/systemd/network/99-default.link
1463 Parsed configuration file /etc/systemd/network/10-eth0.link
1464 ID_NET_DRIVER=cdc_ether
1465 Config file /etc/systemd/network/10-eth0.link applies to device hub0
1466 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
1467 hub0: Device has name_assign_type=4
1468 Using default interface naming scheme 'v240'.
1469 hub0: Policies did not yield a name, using specified Name=hub0.
1470 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
1471 ID_NET_NAME=hub0
1472 …</programlisting>
1473
1474      <para>Explicit <varname>Name=</varname> configuration wins in this case.</para>
1475
1476      <programlisting>sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
1477 …
1478 Parsed configuration file /usr/lib/systemd/network/99-default.link
1479 Parsed configuration file /etc/systemd/network/10-eth0.link
1480 Created link configuration context.
1481 ID_NET_DRIVER=e1000e
1482 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
1483 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
1484 enp0s31f6: Device has name_assign_type=4
1485 Using default interface naming scheme 'v240'.
1486 enp0s31f6: Policy *keep*: keeping existing userspace name
1487 enp0s31f6: Device has addr_assign_type=0
1488 enp0s31f6: MAC on the device already matches policy *persistent*
1489 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
1490 …
1491 </programlisting>
1492
1493      <para>In this case, the interface was already renamed, so the <option>keep</option> policy specified as
1494      the first option in <filename index="false">99-default.link</filename> means that the existing name is
1495      preserved. If <option>keep</option> was removed, or if were in boot before the renaming has happened,
1496      we might get the following instead:</para>
1497
1498      <programlisting>enp0s31f6: Policy *path* yields "enp0s31f6".
1499 enp0s31f6: Device has addr_assign_type=0
1500 enp0s31f6: MAC on the device already matches policy *persistent*
1501 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
1502 ID_NET_NAME=enp0s31f6
1503 …
1504 </programlisting>
1505
1506       <para>Please note that the details of output are subject to change.</para>
1507     </example>
1508
1509     <example>
1510       <title>/etc/systemd/network/10-internet.link</title>
1511
1512       <para>This example assigns the fixed name
1513       <literal>internet0</literal> to the interface with the device
1514       path <literal>pci-0000:00:1a.0-*</literal>:</para>
1515
1516       <programlisting>[Match]
1517 Path=pci-0000:00:1a.0-*
1518
1519 [Link]
1520 Name=internet0</programlisting>
1521     </example>
1522
1523     <example>
1524       <title>/etc/systemd/network/25-wireless.link</title>
1525
1526       <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para>
1527
1528       <programlisting>[Match]
1529 MACAddress=12:34:56:78:9a:bc
1530 Driver=brcmsmac
1531 Path=pci-0000:02:00.0-*
1532 Type=wlan
1533 Virtualization=no
1534 Host=my-laptop
1535 Architecture=x86-64
1536
1537 [Link]
1538 Name=wireless0
1539 MTUBytes=1450
1540 BitsPerSecond=10M
1541 WakeOnLan=magic
1542 MACAddress=cb:a9:87:65:43:21</programlisting>
1543     </example>
1544   </refsect1>
1545
1546   <refsect1>
1547     <title>See Also</title>
1548     <para><simplelist type="inline">
1549       <member><citerefentry>
1550         <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
1551       </citerefentry></member>
1552       <member><citerefentry>
1553         <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
1554       </citerefentry></member>
1555       <member><citerefentry>
1556         <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum>
1557       </citerefentry></member>
1558       <member><citerefentry>
1559         <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
1560       </citerefentry></member>
1561       <member><citerefentry>
1562         <refentrytitle>systemd-network-generator.service</refentrytitle><manvolnum>8</manvolnum>
1563       </citerefentry></member>
1564     </simplelist></para>
1565   </refsect1>
1566
1567 </refentry>