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.2/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.link">
   7   <refentryinfo>
   8     <title>systemd.link</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd.link</refentrytitle>
  14     <manvolnum>5</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd.link</refname>
  19     <refpurpose>Network device configuration</refpurpose>
  20   </refnamediv>
  21
  22   <refsynopsisdiv>
  23     <para><filename><replaceable>link</replaceable>.link</filename></para>
  24   </refsynopsisdiv>
  25
  26   <refsect1>
  27     <title>Description</title>
  28
  29     <para>A plain ini-style text file that encodes configuration for matching network devices, used by
  30     <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry> and in
  31     particular its <command>net_setup_link</command> builtin. See
  32     <citerefentry><refentrytitle>systemd.syntax</refentrytitle><manvolnum>7</manvolnum></citerefentry> for a
  33     general description of the syntax.</para>
  34
  35     <para>The link files are read from the files located in the system network directory
  36     <filename>/usr/lib/systemd/network</filename>, the volatile runtime network directory
  37     <filename>/run/systemd/network</filename>, and the local administration network directory
  38     <filename>/etc/systemd/network</filename>. Link files must have the extension
  39     <filename>.link</filename>; other extensions are ignored. All link files are collectively sorted
  40     and processed in lexical order, regardless of the directories in which they live. However, files
  41     with identical filenames replace each other. Files in <filename>/etc/</filename> have the highest
  42     priority, files in <filename>/run/</filename> take precedence over files with the same name in
  43     <filename>/usr/lib/</filename>. This can be used to override a system-supplied link file with a
  44     local file if needed. As a special case, an empty file (file size 0) or symlink with the same name
  45     pointing to <filename>/dev/null</filename> disables the configuration file entirely (it is
  46     "masked").</para>
  47
  48     <para>Along with the link file <filename>foo.link</filename>, a "drop-in" directory
  49     <filename>foo.link.d/</filename> may exist. All files with the suffix <literal>.conf</literal>
  50     from this directory will be merged in the alphanumeric order and parsed after the main file itself
  51     has been parsed. This is useful to alter or add configuration settings, without having to modify
  52     the main configuration file. Each drop-in file must have appropriate section headers.</para>
  53
  54     <para>In addition to <filename>/etc/systemd/network</filename>, drop-in <literal>.d</literal>
  55     directories can be placed in <filename>/usr/lib/systemd/network</filename> or
  56     <filename>/run/systemd/network</filename> directories. Drop-in files in <filename>/etc/</filename>
  57     take precedence over those in <filename>/run/</filename> which in turn take precedence over those
  58     in <filename>/usr/lib/</filename>. Drop-in files under any of these directories take precedence
  59     over the main link file wherever located.</para>
  60
  61     <para>The link file contains a [Match] section, which determines if a given link file may be applied to a
  62     given device, as well as a [Link] section specifying how the device should be configured. The first (in
  63     lexical order) of the link files that matches a given device is applied. Note that a default file
  64     <filename>99-default.link</filename> is shipped by the system. Any user-supplied
  65     <filename>.link</filename> should hence have a lexically earlier name to be considered at all.</para>
  66
  67     <para>See <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry> for
  68     diagnosing problems with <filename>.link</filename> files.</para>
  69   </refsect1>
  70
  71   <refsect1>
  72     <title>[Match] Section Options</title>
  73
  74     <para>A link file is said to match a device if all matches specified by the
  75     [Match] section are satisfied. When a link file does not contain valid settings
  76     in [Match] section, then the file will match all devices and
  77     <command>systemd-udevd</command> warns about that. Hint: to avoid the warning and to make it clear
  78     that all interfaces shall be matched, add the following:
  79     <programlisting>OriginalName=*</programlisting>
  80     The following keys are accepted:</para>
  81
  82     <variablelist class='network-directives'>
  83       <!-- This list is reused in systemd.network(3), hence maintain a specific order:
  84            1. device matches shared between the two lists
  85            2. non-shared settings
  86            3. host matches shared between the two lists
  87         -->
  88
  89       <varlistentry id='mac-address'>
  90         <term><varname>MACAddress=</varname></term>
  91         <listitem>
  92           <para>A whitespace-separated list of hardware addresses. The acceptable formats are:</para>
  93
  94           <variablelist>
  95             <varlistentry>
  96               <term><option>colon-delimited hexadecimal</option></term>
  97               <listitem><para>
  98                 Each field must be one byte.
  99                 E.g. <literal>12:34:56:78:90:ab</literal> or <literal>AA:BB:CC:DD:EE:FF</literal>.
 100               </para></listitem>
 101             </varlistentry>
 102             <varlistentry>
 103               <term><option>hyphen-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></listitem>
 108             </varlistentry>
 109             <varlistentry>
 110               <term><option>dot-delimited hexadecimal</option></term>
 111               <listitem><para>
 112                 Each field must be two bytes.
 113                 E.g. <literal>1234.5678.90ab</literal> or <literal>AABB.CCDD.EEFF</literal>.
 114               </para></listitem>
 115             </varlistentry>
 116             <varlistentry>
 117               <term><option>IPv4 address format</option></term>
 118               <listitem><para>
 119                 E.g. <literal>127.0.0.1</literal> or <literal>192.168.0.1</literal>.
 120               </para></listitem>
 121             </varlistentry>
 122             <varlistentry>
 123               <term><option>IPv6 address format</option></term>
 124               <listitem><para>
 125                 E.g. <literal>2001:0db8:85a3::8a2e:0370:7334</literal> or <literal>::1</literal>.
 126               </para></listitem>
 127             </varlistentry>
 128           </variablelist>
 129
 130           <para>The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16
 131           (for IPv6 tunnel), or 20 (for InfiniBand). This option may appear more than once, in which
 132           case the lists are merged. If the empty string is assigned to this option, the list of
 133           hardware addresses defined prior to this is reset. Defaults to unset.</para>
 134         </listitem>
 135       </varlistentry>
 136
 137       <varlistentry id='permanent-mac-address'>
 138         <term><varname>PermanentMACAddress=</varname></term>
 139         <listitem>
 140           <para>A whitespace-separated list of hardware's permanent addresses. While
 141           <varname>MACAddress=</varname> matches the device's current MAC address, this matches the
 142           device's permanent MAC address, which may be different from the current one. Use full
 143           colon-, hyphen- or dot-delimited hexadecimal, or IPv4 or IPv6 address format. This option may
 144           appear more than once, in which case the lists are merged. If the empty string is assigned to
 145           this option, the list of hardware addresses defined prior to this is reset. Defaults to
 146           unset.</para>
 147         </listitem>
 148       </varlistentry>
 149
 150       <varlistentry id='path'>
 151         <term><varname>Path=</varname></term>
 152         <listitem>
 153           <para>A whitespace-separated list of shell-style globs matching
 154           the persistent path, as exposed by the udev property
 155           <varname>ID_PATH</varname>.</para>
 156         </listitem>
 157       </varlistentry>
 158
 159       <varlistentry id='driver'>
 160         <term><varname>Driver=</varname></term>
 161         <listitem>
 162           <para>A whitespace-separated list of shell-style globs matching the driver currently bound to the
 163           device, as exposed by the udev property <varname>ID_NET_DRIVER</varname> of its parent device, or
 164           if that is not set, the driver as exposed by <command>ethtool -i</command> of the device itself.
 165           If the list is prefixed with a "!", the test is inverted.</para>
 166         </listitem>
 167       </varlistentry>
 168
 169       <varlistentry id='type'>
 170         <term><varname>Type=</varname></term>
 171         <listitem>
 172           <para>A whitespace-separated list of shell-style globs matching the device type, as exposed by
 173           <command>networkctl list</command>. If the list is prefixed with a "!", the test is inverted.
 174           Some valid values are <literal>ether</literal>, <literal>loopback</literal>, <literal>wlan</literal>, <literal>wwan</literal>.
 175           Valid types are named either from the udev <literal>DEVTYPE</literal> attribute, or
 176           <literal>ARPHRD_</literal> macros in <filename>linux/if_arp.h</filename>, so this is not comprehensive.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry id='property'>
 182         <term><varname>Property=</varname></term>
 183         <listitem>
 184           <para>A whitespace-separated list of udev property names with their values after equals sign
 185           (<literal>=</literal>). If multiple properties are specified, the test results are ANDed.
 186           If the list is prefixed with a "!", the test is inverted. If a value contains white
 187           spaces, then please quote whole key and value pair. If a value contains quotation, then
 188           please escape the quotation with <literal>\</literal>.</para>
 189
 190           <para>Example: if a .link file has the following:
 191           <programlisting>Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""</programlisting>
 192           then, the .link file matches only when an interface has all the above three properties.
 193           </para>
 194         </listitem>
 195       </varlistentry>
 196
 197       <varlistentry>
 198         <term><varname>OriginalName=</varname></term>
 199         <listitem>
 200           <para>A whitespace-separated list of shell-style globs matching the device name, as exposed by the
 201           udev property "INTERFACE". This cannot be used to match on names that have already been changed
 202           from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be
 203           unstable between reboots.</para>
 204         </listitem>
 205       </varlistentry>
 206
 207       <varlistentry id='host'>
 208         <term><varname>Host=</varname></term>
 209         <listitem>
 210           <para>Matches against the hostname or machine ID of the host. See <varname>ConditionHost=</varname> in
 211           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 212           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 213           If an empty string is assigned, then previously assigned value is cleared.
 214           </para>
 215         </listitem>
 216       </varlistentry>
 217
 218       <varlistentry id='virtualization'>
 219         <term><varname>Virtualization=</varname></term>
 220         <listitem>
 221           <para>Checks whether the system is executed in a virtualized environment and optionally test
 222           whether it is a specific implementation. See <varname>ConditionVirtualization=</varname> in
 223           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 224           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 225           If an empty string is assigned, then previously assigned value is cleared.
 226           </para>
 227         </listitem>
 228       </varlistentry>
 229
 230       <varlistentry id='kernel-command-line'>
 231         <term><varname>KernelCommandLine=</varname></term>
 232         <listitem>
 233           <para>Checks whether a specific kernel command line option is set. See
 234           <varname>ConditionKernelCommandLine=</varname> in
 235           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 236           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 237           If an empty string is assigned, then previously assigned value is cleared.
 238           </para>
 239         </listitem>
 240       </varlistentry>
 241
 242       <varlistentry id='kernel-version'>
 243         <term><varname>KernelVersion=</varname></term>
 244         <listitem>
 245           <para>Checks whether the kernel version (as reported by <command>uname -r</command>) matches a certain
 246           expression. See <varname>ConditionKernelVersion=</varname> in
 247           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 248           details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 249           If an empty string is assigned, then previously assigned value is cleared.
 250           </para>
 251         </listitem>
 252       </varlistentry>
 253
 254       <varlistentry id='architecture'>
 255         <term><varname>Architecture=</varname></term>
 256         <listitem>
 257           <para>Checks whether the system is running on a specific architecture. See
 258           <varname>ConditionArchitecture=</varname> in
 259           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 260           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 261           If an empty string is assigned, then previously assigned value is cleared.
 262           </para>
 263         </listitem>
 264       </varlistentry>
 265
 266       <varlistentry id='firmware'>
 267         <term><varname>Firmware=</varname></term>
 268         <listitem>
 269           <para>Checks whether the system is running on a machine with the specified firmware. See
 270           <varname>ConditionFirmware=</varname> in
 271           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 272           for details. When prefixed with an exclamation mark (<literal>!</literal>), the result is negated.
 273           If an empty string is assigned, then previously assigned value is cleared.
 274           </para>
 275         </listitem>
 276       </varlistentry>
 277     </variablelist>
 278
 279   </refsect1>
 280
 281   <refsect1>
 282     <title>[Link] Section Options</title>
 283
 284     <para>The [Link] section accepts the following
 285     keys:</para>
 286
 287     <variablelist class='network-directives'>
 288       <varlistentry>
 289         <term><varname>Description=</varname></term>
 290         <listitem>
 291           <para>A description of the device.</para>
 292         </listitem>
 293       </varlistentry>
 294       <varlistentry>
 295         <term><varname>Alias=</varname></term>
 296         <listitem>
 297           <para>The <varname>ifalias</varname> interface property is set to this value.</para>
 298         </listitem>
 299       </varlistentry>
 300       <varlistentry>
 301         <term><varname>MACAddressPolicy=</varname></term>
 302         <listitem>
 303           <para>The policy by which the MAC address should be set. The
 304           available policies are:
 305           </para>
 306
 307           <variablelist>
 308             <varlistentry>
 309               <term><option>persistent</option></term>
 310               <listitem>
 311                 <para>If the hardware has a persistent MAC address, as
 312                 most hardware should, and if it is used by the kernel,
 313                 nothing is done. Otherwise, a new MAC address is
 314                 generated which is guaranteed to be the same on every
 315                 boot for the given machine and the given device, but
 316                 which is otherwise random. This feature depends on ID_NET_NAME_*
 317                 properties to exist for the link. On hardware where these
 318                 properties are not set, the generation of a persistent MAC address
 319                 will fail.</para>
 320               </listitem>
 321             </varlistentry>
 322             <varlistentry>
 323               <term><option>random</option></term>
 324               <listitem>
 325                 <para>If the kernel is using a random MAC address,
 326                 nothing is done. Otherwise, a new address is randomly
 327                 generated each time the device appears, typically at
 328                 boot. Either way, the random address will have the
 329                 <literal>unicast</literal> and
 330                 <literal>locally administered</literal> bits set.</para>
 331               </listitem>
 332             </varlistentry>
 333             <varlistentry>
 334               <term><option>none</option></term>
 335               <listitem>
 336                 <para>Keeps the MAC address assigned by the kernel. Or use the MAC address specified in
 337                 <varname>MACAddress=</varname>.</para>
 338               </listitem>
 339             </varlistentry>
 340           </variablelist>
 341
 342           <para>An empty string assignment is equivalent to setting <literal>none</literal>.</para>
 343         </listitem>
 344       </varlistentry>
 345       <varlistentry>
 346         <term><varname>MACAddress=</varname></term>
 347         <listitem>
 348           <para>The interface MAC address to use. For this setting to take effect,
 349           <varname>MACAddressPolicy=</varname> must either be unset, empty, or <literal>none</literal>.
 350           </para>
 351         </listitem>
 352       </varlistentry>
 353       <varlistentry>
 354         <term><varname>NamePolicy=</varname></term>
 355         <listitem>
 356           <para>An ordered, space-separated list of policies by which the interface name should be set.
 357           <varname>NamePolicy=</varname> may be disabled by specifying <option>net.ifnames=0</option> on the
 358           kernel command line. Each of the policies may fail, and the first successful one is used. The name
 359           is not set directly, but is exported to udev as the property <option>ID_NET_NAME</option>, which
 360           is, by default, used by a
 361           <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 362           rule to set <varname>NAME</varname>. The available policies are:
 363           </para>
 364
 365           <variablelist>
 366             <varlistentry>
 367               <term><option>kernel</option></term>
 368               <listitem>
 369                 <para>If the kernel claims that the name it has set
 370                 for a device is predictable, then no renaming is
 371                 performed.</para>
 372               </listitem>
 373             </varlistentry>
 374             <varlistentry>
 375               <term><option>database</option></term>
 376               <listitem>
 377                 <para>The name is set based on entries in the udev's
 378                 Hardware Database with the key
 379                 <varname>ID_NET_NAME_FROM_DATABASE</varname>.
 380                 </para>
 381               </listitem>
 382             </varlistentry>
 383             <varlistentry>
 384               <term><option>onboard</option></term>
 385               <listitem>
 386                 <para>The name is set based on information given by
 387                 the firmware for on-board devices, as exported by the
 388                 udev property <varname>ID_NET_NAME_ONBOARD</varname>.
 389                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 390                 </para>
 391               </listitem>
 392             </varlistentry>
 393             <varlistentry>
 394               <term><option>slot</option></term>
 395               <listitem>
 396                 <para>The name is set based on information given by
 397                 the firmware for hot-plug devices, as exported by the
 398                 udev property <varname>ID_NET_NAME_SLOT</varname>.
 399                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 400                 </para>
 401               </listitem>
 402             </varlistentry>
 403             <varlistentry>
 404               <term><option>path</option></term>
 405               <listitem>
 406                 <para>The name is set based on the device's physical
 407                 location, as exported by the udev property
 408                 <varname>ID_NET_NAME_PATH</varname>.
 409                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 410                 </para>
 411               </listitem>
 412             </varlistentry>
 413             <varlistentry>
 414               <term><option>mac</option></term>
 415               <listitem>
 416                 <para>The name is set based on the device's persistent
 417                 MAC address, as exported by the udev property
 418                 <varname>ID_NET_NAME_MAC</varname>.
 419                 See <citerefentry><refentrytitle>systemd.net-naming-scheme</refentrytitle><manvolnum>7</manvolnum></citerefentry>.
 420                 </para>
 421               </listitem>
 422             </varlistentry>
 423             <varlistentry>
 424               <term><option>keep</option></term>
 425               <listitem>
 426                 <para>If the device already had a name given by userspace (as part of creation of the device
 427                 or a rename), keep it.</para>
 428               </listitem>
 429             </varlistentry>
 430           </variablelist>
 431         </listitem>
 432       </varlistentry>
 433       <varlistentry>
 434         <term><varname>Name=</varname></term>
 435         <listitem>
 436           <para>The interface name to use. This option has lower precedence than
 437           <varname>NamePolicy=</varname>, so for this setting to take effect, <varname>NamePolicy=</varname>
 438           must either be unset, empty, disabled, or all policies configured there must fail. Also see the
 439           example below with <literal>Name=dmz0</literal>.</para>
 440
 441           <para>Note that specifying a name that the kernel might use for another
 442           interface (for example <literal>eth0</literal>) is dangerous because the
 443           name assignment done by udev will race with the assignment done by the
 444           kernel, and only one interface may use the name. Depending on the order of
 445           operations, either udev or the kernel will win, making the naming
 446           unpredictable. It is best to use some different prefix, for example
 447           <literal>internal0</literal>/<literal>external0</literal> or
 448           <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.
 449           </para>
 450         </listitem>
 451       </varlistentry>
 452       <varlistentry>
 453         <term><varname>AlternativeNamesPolicy=</varname></term>
 454         <listitem>
 455           <para>A space-separated list of policies by which the interface's alternative names
 456           should be set. Each of the policies may fail, and all successful policies are used. The
 457           available policies are <literal>database</literal>, <literal>onboard</literal>,
 458           <literal>slot</literal>, <literal>path</literal>, and <literal>mac</literal>. If the
 459           kernel does not support the alternative names, then this setting will be ignored.
 460           </para>
 461         </listitem>
 462       </varlistentry>
 463       <varlistentry>
 464         <term><varname>AlternativeName=</varname></term>
 465         <listitem>
 466           <para>The alternative interface name to use. This option can be specified multiple times.
 467           If the empty string is assigned to this option, the list is reset, and all prior assignments
 468           have no effect. If the kernel does not support the alternative names, then this setting will
 469           be ignored.</para>
 470         </listitem>
 471       </varlistentry>
 472       <varlistentry>
 473         <term><varname>TransmitQueues=</varname></term>
 474         <listitem>
 475           <para>Specifies the device's number of transmit queues. An integer in the range 1…4096.
 476           When unset, the kernel's default will be used.</para>
 477         </listitem>
 478       </varlistentry>
 479       <varlistentry>
 480         <term><varname>ReceiveQueues=</varname></term>
 481         <listitem>
 482           <para>Specifies the device's number of receive queues. An integer in the range 1…4096.
 483           When unset, the kernel's default will be used.</para>
 484         </listitem>
 485       </varlistentry>
 486       <varlistentry>
 487         <term><varname>TransmitQueueLength=</varname></term>
 488         <listitem>
 489           <para>Specifies the transmit queue length of the device in number of packets. An unsigned integer
 490           in the range 0…4294967294. When unset, the kernel's default will be used.</para>
 491         </listitem>
 492       </varlistentry>
 493       <varlistentry>
 494         <term><varname>MTUBytes=</varname></term>
 495         <listitem>
 496           <para>The maximum transmission unit in bytes to set for the
 497           device. The usual suffixes K, M, G are supported and are
 498           understood to the base of 1024.</para>
 499         </listitem>
 500       </varlistentry>
 501       <varlistentry>
 502         <term><varname>BitsPerSecond=</varname></term>
 503         <listitem>
 504           <para>The speed to set for the device, the value is rounded
 505           down to the nearest Mbps. The usual suffixes K, M, G are
 506           supported and are understood to the base of 1000.</para>
 507         </listitem>
 508       </varlistentry>
 509       <varlistentry>
 510         <term><varname>Duplex=</varname></term>
 511         <listitem>
 512           <para>The duplex mode to set for the device. The accepted values are <option>half</option> and
 513           <option>full</option>.</para>
 514         </listitem>
 515       </varlistentry>
 516       <varlistentry>
 517         <term><varname>AutoNegotiation=</varname></term>
 518         <listitem>
 519           <para>Takes a boolean. If set to yes, automatic negotiation of transmission parameters is enabled.
 520           Autonegotiation is a procedure by which two connected ethernet devices choose
 521           common transmission parameters, such as speed, duplex mode, and flow control.
 522           When unset, the kernel's default will be used.</para>
 523
 524           <para>Note that if autonegotiation is enabled, speed and duplex settings are
 525           read-only. If autonegotiation is disabled, speed and duplex settings are writable
 526           if the driver supports multiple link modes.</para>
 527         </listitem>
 528       </varlistentry>
 529       <varlistentry>
 530         <term><varname>WakeOnLan=</varname></term>
 531         <listitem>
 532           <para>The Wake-on-LAN policy to set for the device. Takes the special value
 533           <literal>off</literal> which disables Wake-on-LAN, or space separated list of the following
 534           words:</para>
 535
 536           <variablelist>
 537             <varlistentry>
 538               <term><option>phy</option></term>
 539               <listitem>
 540                 <para>Wake on PHY activity.</para>
 541               </listitem>
 542             </varlistentry>
 543             <varlistentry>
 544               <term><option>unicast</option></term>
 545               <listitem>
 546                 <para>Wake on unicast messages.</para>
 547               </listitem>
 548             </varlistentry>
 549             <varlistentry>
 550               <term><option>multicast</option></term>
 551               <listitem>
 552                 <para>Wake on multicast messages.</para>
 553               </listitem>
 554             </varlistentry>
 555             <varlistentry>
 556               <term><option>broadcast</option></term>
 557               <listitem>
 558                 <para>Wake on broadcast messages.</para>
 559               </listitem>
 560             </varlistentry>
 561             <varlistentry>
 562               <term><option>arp</option></term>
 563               <listitem>
 564                 <para>Wake on ARP.</para>
 565               </listitem>
 566             </varlistentry>
 567             <varlistentry>
 568               <term><option>magic</option></term>
 569               <listitem>
 570                 <para>Wake on receipt of a magic packet.
 571                 </para>
 572               </listitem>
 573             </varlistentry>
 574             <varlistentry>
 575               <term><option>secureon</option></term>
 576               <listitem>
 577                 <para>Enable SecureOn password for MagicPacket. Implied when
 578                 <varname>WakeOnLanPassword=</varname> is specified. If specified without
 579                 <varname>WakeOnLanPassword=</varname> option, then the password is read from the
 580                 credential <literal><replaceable>LINK</replaceable>.link.wol.password</literal> (e.g.,
 581                 <literal>60-foo.link.wol.password</literal>), and if the credential not found, then
 582                 read from <literal>wol.password</literal>. See
 583                 <varname>LoadCredential=</varname>/<varname>SetCredential=</varname> in
 584                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 585                 for details. The password in the credential, must be 6 bytes in hex format with each
 586                 byte separated by a colon (<literal>:</literal>) like an Ethernet MAC address, e.g.,
 587                 <literal>aa:bb:cc:dd:ee:ff</literal>.</para>
 588               </listitem>
 589             </varlistentry>
 590           </variablelist>
 591
 592           <para>Defaults to unset, and the device's default will be used. This setting can be specified
 593           multiple times. If an empty string is assigned, then the all previous assignments are
 594           cleared.</para>
 595         </listitem>
 596       </varlistentry>
 597       <varlistentry>
 598         <term><varname>WakeOnLanPassword=</varname></term>
 599         <listitem>
 600           <para>Specifies the SecureOn password for MagicPacket. Takes an absolute path to a regular
 601           file or an <constant>AF_UNIX</constant> stream socket, or the plain password. When a path to
 602           a regular file is specified, the password is read from it. When an
 603           <constant>AF_UNIX</constant> stream socket is specified, a connection is made to it and the
 604           password is read from it. The password must be 6 bytes in hex format with each byte separated
 605           by a colon (<literal>:</literal>) like an Ethernet MAC address, e.g.,
 606           <literal>aa:bb:cc:dd:ee:ff</literal>. This implies <varname>WakeOnLan=secureon</varname>.
 607           Defaults to unset, and the current value will not be changed.</para>
 608         </listitem>
 609       </varlistentry>
 610       <varlistentry>
 611         <term><varname>Port=</varname></term>
 612         <listitem>
 613           <para>The port option is used to select the device port. The
 614           supported values are:</para>
 615
 616           <variablelist>
 617             <varlistentry>
 618               <term><option>tp</option></term>
 619               <listitem>
 620                 <para>An Ethernet interface using Twisted-Pair cable as the medium.</para>
 621               </listitem>
 622             </varlistentry>
 623             <varlistentry>
 624               <term><option>aui</option></term>
 625               <listitem>
 626                 <para>Attachment Unit Interface (AUI). Normally used with hubs.
 627                 </para>
 628               </listitem>
 629             </varlistentry>
 630             <varlistentry>
 631               <term><option>bnc</option></term>
 632               <listitem>
 633                 <para>An Ethernet interface using BNC connectors and co-axial cable.</para>
 634               </listitem>
 635             </varlistentry>
 636             <varlistentry>
 637               <term><option>mii</option></term>
 638               <listitem>
 639                 <para>An Ethernet interface using a Media Independent Interface (MII).</para>
 640               </listitem>
 641             </varlistentry>
 642             <varlistentry>
 643               <term><option>fibre</option></term>
 644               <listitem>
 645                 <para>An Ethernet interface using Optical Fibre as the medium.</para>
 646               </listitem>
 647             </varlistentry>
 648           </variablelist>
 649         </listitem>
 650       </varlistentry>
 651       <varlistentry>
 652         <term><varname>Advertise=</varname></term>
 653         <listitem>
 654           <para>This sets what speeds and duplex modes of operation are advertised for auto-negotiation.
 655           This implies <literal>AutoNegotiation=yes</literal>. The supported values are:
 656
 657           <table>
 658             <title>Supported advertise values</title>
 659             <tgroup cols='3'>
 660               <colspec colname='Advertise' />
 661               <colspec colname='Speed' />
 662               <colspec colname='Duplex Mode' />
 663
 664               <thead><row>
 665                 <entry>Advertise</entry>
 666                 <entry>Speed (Mbps)</entry>
 667                 <entry>Duplex Mode</entry>
 668               </row></thead>
 669               <tbody>
 670                 <row><entry><option>10baset-half</option></entry>
 671                 <entry>10</entry><entry>half</entry></row>
 672
 673                 <row><entry><option>10baset-full</option></entry>
 674                 <entry>10</entry><entry>full</entry></row>
 675
 676                 <row><entry><option>100baset-half</option></entry>
 677                 <entry>100</entry><entry>half</entry></row>
 678
 679                 <row><entry><option>100baset-full</option></entry>
 680                 <entry>100</entry><entry>full</entry></row>
 681
 682                 <row><entry><option>1000baset-half</option></entry>
 683                 <entry>1000</entry><entry>half</entry></row>
 684
 685                 <row><entry><option>1000baset-full</option></entry>
 686                 <entry>1000</entry><entry>full</entry></row>
 687
 688                 <row><entry><option>10000baset-full</option></entry>
 689                 <entry>10000</entry><entry>full</entry></row>
 690
 691                 <row><entry><option>2500basex-full</option></entry>
 692                 <entry>2500</entry><entry>full</entry></row>
 693
 694                 <row><entry><option>1000basekx-full</option></entry>
 695                 <entry>1000</entry><entry>full</entry></row>
 696
 697                 <row><entry><option>10000basekx4-full</option></entry>
 698                 <entry>10000</entry><entry>full</entry></row>
 699
 700                 <row><entry><option>10000basekr-full</option></entry>
 701                 <entry>10000</entry><entry>full</entry></row>
 702
 703                 <row><entry><option>10000baser-fec</option></entry>
 704                 <entry>10000</entry><entry>full</entry></row>
 705
 706                 <row><entry><option>20000basemld2-full</option></entry>
 707                 <entry>20000</entry><entry>full</entry></row>
 708
 709                 <row><entry><option>20000basekr2-full</option></entry>
 710                 <entry>20000</entry><entry>full</entry></row>
 711               </tbody>
 712             </tgroup>
 713           </table>
 714
 715           By default this is unset, i.e. all possible modes will be advertised.
 716           This option may be specified more than once, in which case all specified speeds and modes are advertised.
 717           If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect.
 718           </para>
 719         </listitem>
 720       </varlistentry>
 721       <varlistentry>
 722         <term><varname>ReceiveChecksumOffload=</varname></term>
 723         <listitem>
 724           <para>Takes a boolean. If set to true, hardware offload for checksumming of ingress
 725           network packets is enabled. When unset, the kernel's default will be used.</para>
 726         </listitem>
 727       </varlistentry>
 728       <varlistentry>
 729         <term><varname>TransmitChecksumOffload=</varname></term>
 730         <listitem>
 731           <para>Takes a boolean. If set to true, hardware offload for checksumming of egress
 732           network packets is enabled. When unset, the kernel's default will be used.</para>
 733         </listitem>
 734       </varlistentry>
 735       <varlistentry>
 736         <term><varname>TCPSegmentationOffload=</varname></term>
 737         <listitem>
 738           <para>Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is enabled.
 739           When unset, the kernel's default will be used.</para>
 740         </listitem>
 741       </varlistentry>
 742        <varlistentry>
 743       <term><varname>TCP6SegmentationOffload=</varname></term>
 744         <listitem>
 745           <para>Takes a boolean. If set to true, TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled.
 746           When unset, the kernel's default will be used.</para>
 747         </listitem>
 748       </varlistentry>
 749       <varlistentry>
 750         <term><varname>GenericSegmentationOffload=</varname></term>
 751         <listitem>
 752           <para>Takes a boolean. If set to true, Generic Segmentation Offload (GSO) is enabled.
 753           When unset, the kernel's default will be used.</para>
 754         </listitem>
 755       </varlistentry>
 756       <varlistentry>
 757         <term><varname>GenericReceiveOffload=</varname></term>
 758         <listitem>
 759           <para>Takes a boolean. If set to true, Generic Receive Offload (GRO) is enabled.
 760           When unset, the kernel's default will be used.</para>
 761         </listitem>
 762       </varlistentry>
 763       <varlistentry>
 764         <term><varname>GenericReceiveOffloadHardware=</varname></term>
 765         <listitem>
 766           <para>Takes a boolean. If set to true, hardware accelerated Generic Receive Offload (GRO) is
 767           enabled. When unset, the kernel's default will be used.</para>
 768         </listitem>
 769       </varlistentry>
 770       <varlistentry>
 771         <term><varname>LargeReceiveOffload=</varname></term>
 772         <listitem>
 773           <para>Takes a boolean. If set to true, Large Receive Offload (LRO) is enabled.
 774           When unset, the kernel's default will be used.</para>
 775         </listitem>
 776       </varlistentry>
 777       <varlistentry>
 778         <term><varname>ReceiveVLANCTAGHardwareAcceleration=</varname></term>
 779         <listitem>
 780           <para>Takes a boolean. If set to true, receive VLAN CTAG hardware acceleration is enabled.
 781           When unset, the kernel's default will be used.</para>
 782         </listitem>
 783       </varlistentry>
 784       <varlistentry>
 785         <term><varname>TransmitVLANCTAGHardwareAcceleration=</varname></term>
 786         <listitem>
 787           <para>Takes a boolean. If set to true, transmit VLAN CTAG hardware acceleration is enabled.
 788           When unset, the kernel's default will be used.</para>
 789         </listitem>
 790       </varlistentry>
 791       <varlistentry>
 792         <term><varname>ReceiveVLANCTAGFilter=</varname></term>
 793         <listitem>
 794           <para>Takes a boolean. If set to true, receive filtering on VLAN CTAGs is enabled.
 795           When unset, the kernel's default will be used.</para>
 796         </listitem>
 797       </varlistentry>
 798       <varlistentry>
 799         <term><varname>TransmitVLANSTAGHardwareAcceleration=</varname></term>
 800         <listitem>
 801           <para>Takes a boolean. If set to true, transmit VLAN STAG HW acceleration is enabled.
 802           When unset, the kernel's default will be used.</para>
 803         </listitem>
 804       </varlistentry>
 805       <varlistentry>
 806         <term><varname>NTupleFilter=</varname></term>
 807         <listitem>
 808           <para>Takes a boolean. If set to true, receive N-tuple filters and actions are enabled.
 809           When unset, the kernel's default will be used.</para>
 810         </listitem>
 811       </varlistentry>
 812       <varlistentry>
 813         <term><varname>RxChannels=</varname></term>
 814         <term><varname>TxChannels=</varname></term>
 815         <term><varname>OtherChannels=</varname></term>
 816         <term><varname>CombinedChannels=</varname></term>
 817         <listitem>
 818           <para>Specifies the number of receive, transmit, other, or combined channels, respectively.
 819           Takes an unsigned integer in the range 1…4294967295 or <literal>max</literal>. If set to
 820           <literal>max</literal>, the advertised maximum value of the hardware will be used. When
 821           unset, the number will not be changed. Defaults to unset.</para>
 822         </listitem>
 823       </varlistentry>
 824       <varlistentry>
 825         <term><varname>RxBufferSize=</varname></term>
 826         <term><varname>RxMiniBufferSize=</varname></term>
 827         <term><varname>RxJumboBufferSize=</varname></term>
 828         <term><varname>TxBufferSize=</varname></term>
 829         <listitem>
 830           <para>Specifies the maximum number of pending packets in the NIC receive buffer, mini receive
 831           buffer, jumbo receive buffer, or transmit buffer, respectively. Takes an unsigned integer in
 832           the range 1…4294967295 or <literal>max</literal>. If set to <literal>max</literal>, the
 833           advertised maximum value of the hardware will be used. When unset, the number will not be
 834           changed. Defaults to unset.</para>
 835         </listitem>
 836       </varlistentry>
 837       <varlistentry>
 838         <term><varname>RxFlowControl=</varname></term>
 839         <listitem>
 840           <para>Takes a boolean. When set, enables receive flow control, also known as the ethernet
 841           receive PAUSE message (generate and send ethernet PAUSE frames). When unset, the kernel's
 842           default will be used.</para>
 843         </listitem>
 844       </varlistentry>
 845       <varlistentry>
 846         <term><varname>TxFlowControl=</varname></term>
 847         <listitem>
 848           <para>Takes a boolean. When set, enables transmit flow control, also known as the ethernet
 849           transmit PAUSE message (respond to received ethernet PAUSE frames). When unset, the kernel's
 850           default will be used.</para>
 851         </listitem>
 852       </varlistentry>
 853       <varlistentry>
 854         <term><varname>AutoNegotiationFlowControl=</varname></term>
 855         <listitem>
 856           <para>Takes a boolean. When set, auto negotiation enables the interface to exchange state
 857           advertisements with the connected peer so that the two devices can agree on the ethernet
 858           PAUSE configuration. When unset, the kernel's default will be used.</para>
 859         </listitem>
 860       </varlistentry>
 861       <varlistentry>
 862         <term><varname>GenericSegmentOffloadMaxBytes=</varname></term>
 863         <listitem>
 864           <para>Specifies the maximum size of a Generic Segment Offload (GSO) packet the
 865           device should accept. The usual suffixes K, M, G are supported and are
 866           understood to the base of 1024. An unsigned integer in the range 1…65536.
 867           Defaults to unset.</para>
 868         </listitem>
 869       </varlistentry>
 870       <varlistentry>
 871         <term><varname>GenericSegmentOffloadMaxSegments=</varname></term>
 872         <listitem>
 873           <para>Specifies the maximum number of Generic Segment Offload (GSO) segments the device should
 874           accept. An unsigned integer in the range 1…65535. Defaults to unset.</para>
 875         </listitem>
 876       </varlistentry>
 877       <varlistentry>
 878         <term><varname>UseAdaptiveRxCoalesce=</varname></term>
 879         <term><varname>UseAdaptiveTxCoalesce=</varname></term>
 880         <listitem>
 881           <para>Boolean properties that, when set, enable/disable adaptive Rx/Tx coalescing if the hardware
 882           supports it. When unset, the kernel's default will be used.</para>
 883         </listitem>
 884       </varlistentry>
 885       <varlistentry>
 886         <term><varname>RxCoalesceSec=</varname></term>
 887         <term><varname>RxCoalesceIrqSec=</varname></term>
 888         <term><varname>RxCoalesceLowSec=</varname></term>
 889         <term><varname>RxCoalesceHighSec=</varname></term>
 890         <term><varname>TxCoalesceSec=</varname></term>
 891         <term><varname>TxCoalesceIrqSec=</varname></term>
 892         <term><varname>TxCoalesceLowSec=</varname></term>
 893         <term><varname>TxCoalesceHighSec=</varname></term>
 894         <listitem>
 895           <para>These properties configure the delay before Rx/Tx interrupts are generated after a packet is
 896           sent/received. The <literal>Irq</literal> properties come into effect when the host is servicing an
 897           IRQ. The <literal>Low</literal> and <literal>High</literal> properties come into effect when the
 898           packet rate drops below the low packet rate threshold or exceeds the high packet rate threshold
 899           respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's defaults will be
 900           used.</para>
 901         </listitem>
 902       </varlistentry>
 903         <varlistentry>
 904         <term><varname>RxMaxCoalescedFrames=</varname></term>
 905         <term><varname>RxMaxCoalescedIrqFrames=</varname></term>
 906         <term><varname>RxMaxCoalescedLowFrames=</varname></term>
 907         <term><varname>RxMaxCoalescedHighFrames=</varname></term>
 908         <term><varname>TxMaxCoalescedFrames=</varname></term>
 909         <term><varname>TxMaxCoalescedIrqFrames=</varname></term>
 910         <term><varname>TxMaxCoalescedLowFrames=</varname></term>
 911         <term><varname>TxMaxCoalescedHighFrames=</varname></term>
 912         <listitem>
 913           <para>These properties configure the maximum number of frames that are sent/received before a Rx/Tx
 914           interrupt is generated. The <literal>Irq</literal> properties come into effect when the host is
 915           servicing an IRQ. The <literal>Low</literal> and <literal>High</literal> properties come into
 916           effect when the packet rate drops below the low packet rate threshold or exceeds the high packet
 917           rate threshold respectively if adaptive Rx/Tx coalescing is enabled. When unset, the kernel's
 918           defaults will be used.</para>
 919         </listitem>
 920       </varlistentry>
 921       <varlistentry>
 922         <term><varname>CoalescePacketRateLow=</varname></term>
 923         <term><varname>CoalescePacketRateHigh=</varname></term>
 924         <listitem>
 925           <para>These properties configure the low and high packet rate (expressed in packets per second)
 926           threshold respectively and are used to determine when the corresponding coalescing settings for low
 927           and high packet rates come into effect if adaptive Rx/Tx coalescing is enabled. If unset, the
 928           kernel's defaults will be used.</para>
 929         </listitem>
 930       </varlistentry>
 931       <varlistentry>
 932         <term><varname>CoalescePacketRateSampleIntervalSec=</varname></term>
 933         <listitem>
 934           <para>Configures how often to sample the packet rate used for adaptive Rx/Tx coalescing. This
 935           property cannot be zero. This lowest time granularity supported by this property is seconds.
 936           Partial seconds will be rounded up before being passed to the kernel. If unset, the kernel's
 937           default will be used.</para>
 938         </listitem>
 939       </varlistentry>
 940       <varlistentry>
 941         <term><varname>StatisticsBlockCoalesceSec=</varname></term>
 942         <listitem>
 943           <para>How long to delay driver in-memory statistics block updates. If the driver does not have an
 944           in-memory statistic block, this property is ignored. This property cannot be zero. If unset, the
 945           kernel's default will be used.</para>
 946         </listitem>
 947       </varlistentry>
 948
 949       <varlistentry>
 950         <term><varname>SR-IOVVirtualFunctions=</varname></term>
 951         <listitem>
 952           <para>Specifies the number of SR-IOV virtual functions. Takes an integer in the range
 953           0…2147483647. Defaults to unset, and automatically determined from the values specified in
 954           the <varname>VirtualFunction=</varname> settings in the [SR-IOV] sections.</para>
 955         </listitem>
 956       </varlistentry>
 957
 958     </variablelist>
 959   </refsect1>
 960
 961   <refsect1 id='sr-iov'>
 962     <title>[SR-IOV] Section Options</title>
 963     <para>The [SR-IOV] section accepts the following keys. Specify several [SR-IOV] sections to
 964     configure several SR-IOVs. SR-IOV provides the ability to partition a single physical PCI resource
 965     into virtual PCI functions which can then be injected into a VM. In the case of network VFs, SR-IOV
 966     improves north-south network performance (that is, traffic with endpoints outside the host machine)
 967     by allowing traffic to bypass the host machine’s network stack.</para>
 968
 969     <variablelist class='network-directives'>
 970       <varlistentry>
 971         <term><varname>VirtualFunction=</varname></term>
 972         <listitem>
 973           <para>Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move
 974           data in and out. Takes an integer in the range 0…2147483646. This option is compulsory.
 975           </para>
 976         </listitem>
 977       </varlistentry>
 978
 979       <varlistentry>
 980         <term><varname>VLANId=</varname></term>
 981         <listitem>
 982           <para>Specifies VLAN ID of the virtual function. Takes an integer in the range 1…4095.</para>
 983         </listitem>
 984       </varlistentry>
 985
 986       <varlistentry>
 987         <term><varname>QualityOfService=</varname></term>
 988         <listitem>
 989           <para>Specifies quality of service of the virtual function. Takes an integer in the range
 990           1…4294967294.</para>
 991         </listitem>
 992       </varlistentry>
 993
 994       <varlistentry>
 995         <term><varname>VLANProtocol=</varname></term>
 996         <listitem>
 997           <para>Specifies VLAN protocol of the virtual function. Takes <literal>802.1Q</literal> or
 998           <literal>802.1ad</literal>.</para>
 999         </listitem>
1000       </varlistentry>
1001
1002       <varlistentry>
1003         <term><varname>MACSpoofCheck=</varname></term>
1004         <listitem>
1005           <para>Takes a boolean. Controls the MAC spoof checking. When unset, the kernel's default will
1006           be used.</para>
1007         </listitem>
1008       </varlistentry>
1009
1010       <varlistentry>
1011         <term><varname>QueryReceiveSideScaling=</varname></term>
1012         <listitem>
1013           <para>Takes a boolean. Toggle the ability of querying the receive side scaling (RSS)
1014           configuration of the virtual function (VF). The VF RSS information like RSS hash key may be
1015           considered sensitive on some devices where this information is shared between VF and the
1016           physical function (PF). When unset, the kernel's default will be used.</para>
1017         </listitem>
1018       </varlistentry>
1019
1020       <varlistentry>
1021         <term><varname>Trust=</varname></term>
1022         <listitem>
1023           <para>Takes a boolean. Allows one to set trust mode of the virtual function (VF). When set,
1024           VF users can set a specific feature which may impact security and/or performance. When unset,
1025           the kernel's default will be used.</para>
1026         </listitem>
1027       </varlistentry>
1028
1029       <varlistentry>
1030         <term><varname>LinkState=</varname></term>
1031         <listitem>
1032           <para>Allows one to set the link state of the virtual function (VF). Takes a boolean or a
1033           special value <literal>auto</literal>. Setting to <literal>auto</literal> means a
1034           reflection of the physical function (PF) link state, <literal>yes</literal> lets the VF to
1035           communicate with other VFs on this host even if the PF link state is down,
1036           <literal>no</literal> causes the hardware to drop any packets sent by the VF. When unset,
1037           the kernel's default will be used.</para>
1038         </listitem>
1039       </varlistentry>
1040
1041       <varlistentry>
1042         <term><varname>MACAddress=</varname></term>
1043         <listitem>
1044           <para>Specifies the MAC address for the virtual function.</para>
1045         </listitem>
1046       </varlistentry>
1047     </variablelist>
1048   </refsect1>
1049
1050   <refsect1>
1051     <title>Examples</title>
1052
1053     <example>
1054       <title>/usr/lib/systemd/network/99-default.link</title>
1055
1056       <para>The link file <filename>99-default.link</filename> that is
1057       shipped with systemd defines the default naming policy for
1058       links.</para>
1059
1060       <programlisting>[Link]
1061 NamePolicy=kernel database onboard slot path
1062 MACAddressPolicy=persistent</programlisting>
1063     </example>
1064
1065     <example>
1066       <title>/etc/systemd/network/10-dmz.link</title>
1067
1068       <para>This example assigns the fixed name <literal>dmz0</literal> to the interface with the MAC address
1069       00:a0:de:63:7a:e6:</para>
1070
1071       <programlisting>[Match]
1072 MACAddress=00:a0:de:63:7a:e6
1073
1074 [Link]
1075 Name=dmz0</programlisting>
1076
1077       <para><varname>NamePolicy=</varname> is not set, so <varname>Name=</varname> takes effect. We use the
1078       <literal>10-</literal> prefix to order this file early in the list. Note that it needs to be before
1079       <literal>99-link</literal>, i.e. it needs a numerical prefix, to have any effect at all.</para>
1080     </example>
1081
1082     <example>
1083       <title>Debugging <varname>NamePolicy=</varname> assignments</title>
1084
1085       <programlisting>$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
1086 …
1087 Parsed configuration file /usr/lib/systemd/network/99-default.link
1088 Parsed configuration file /etc/systemd/network/10-eth0.link
1089 ID_NET_DRIVER=cdc_ether
1090 Config file /etc/systemd/network/10-eth0.link applies to device hub0
1091 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
1092 hub0: Device has name_assign_type=4
1093 Using default interface naming scheme 'v240'.
1094 hub0: Policies didn't yield a name, using specified Name=hub0.
1095 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
1096 ID_NET_NAME=hub0
1097 …</programlisting>
1098
1099      <para>Explicit <varname>Name=</varname> configuration wins in this case.</para>
1100
1101      <programlisting>sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
1102 …
1103 Parsed configuration file /usr/lib/systemd/network/99-default.link
1104 Parsed configuration file /etc/systemd/network/10-eth0.link
1105 Created link configuration context.
1106 ID_NET_DRIVER=e1000e
1107 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
1108 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
1109 enp0s31f6: Device has name_assign_type=4
1110 Using default interface naming scheme 'v240'.
1111 enp0s31f6: Policy *keep*: keeping existing userspace name
1112 enp0s31f6: Device has addr_assign_type=0
1113 enp0s31f6: MAC on the device already matches policy *persistent*
1114 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
1115 …
1116 </programlisting>
1117
1118      <para>In this case, the interface was already renamed, so the <option>keep</option> policy specified as
1119      the first option in <filename index="false">99-default.link</filename> means that the existing name is
1120      preserved. If <option>keep</option> was removed, or if were in boot before the renaming has happened,
1121      we might get the following instead:</para>
1122
1123      <programlisting>enp0s31f6: Policy *path* yields "enp0s31f6".
1124 enp0s31f6: Device has addr_assign_type=0
1125 enp0s31f6: MAC on the device already matches policy *persistent*
1126 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
1127 ID_NET_NAME=enp0s31f6
1128 …
1129 </programlisting>
1130
1131       <para>Please note that the details of output are subject to change.</para>
1132     </example>
1133
1134     <example>
1135       <title>/etc/systemd/network/10-internet.link</title>
1136
1137       <para>This example assigns the fixed name
1138       <literal>internet0</literal> to the interface with the device
1139       path <literal>pci-0000:00:1a.0-*</literal>:</para>
1140
1141       <programlisting>[Match]
1142 Path=pci-0000:00:1a.0-*
1143
1144 [Link]
1145 Name=internet0</programlisting>
1146     </example>
1147
1148     <example>
1149       <title>/etc/systemd/network/25-wireless.link</title>
1150
1151       <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para>
1152
1153       <programlisting>[Match]
1154 MACAddress=12:34:56:78:9a:bc
1155 Driver=brcmsmac
1156 Path=pci-0000:02:00.0-*
1157 Type=wlan
1158 Virtualization=no
1159 Host=my-laptop
1160 Architecture=x86-64
1161
1162 [Link]
1163 Name=wireless0
1164 MTUBytes=1450
1165 BitsPerSecond=10M
1166 WakeOnLan=magic
1167 MACAddress=cb:a9:87:65:43:21</programlisting>
1168     </example>
1169   </refsect1>
1170
1171   <refsect1>
1172     <title>See Also</title>
1173     <para>
1174       <citerefentry>
1175         <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
1176       </citerefentry>,
1177       <citerefentry>
1178         <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
1179       </citerefentry>,
1180       <citerefentry>
1181         <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum>
1182       </citerefentry>,
1183       <citerefentry>
1184         <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
1185       </citerefentry>
1186     </para>
1187   </refsect1>
1188
1189 </refentry>