man/systemd.link.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2014 Tom Gundersen
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="systemd.link">
  27   <refentryinfo>
  28     <title>systemd.link</title>
  29     <productname>systemd</productname>
  30
  31     <authorgroup>
  32       <author>
  33         <contrib>Developer</contrib>
  34         <firstname>Tom</firstname>
  35         <surname>Gundersen</surname>
  36       </author>
  37     </authorgroup>
  38   </refentryinfo>
  39
  40   <refmeta>
  41     <refentrytitle>systemd.link</refentrytitle>
  42     <manvolnum>5</manvolnum>
  43   </refmeta>
  44
  45   <refnamediv>
  46     <refname>systemd.link</refname>
  47     <refpurpose>Network device configuration</refpurpose>
  48   </refnamediv>
  49
  50   <refsynopsisdiv>
  51     <para><filename><replaceable>link</replaceable>.link</filename></para>
  52   </refsynopsisdiv>
  53
  54   <refsect1>
  55     <title>Description</title>
  56
  57     <para>Network link configuration is performed by the
  58     <command>net_setup_link</command> udev builtin.</para>
  59
  60     <para>The link files are read from the files located in the system
  61     network directory <filename>/usr/lib/systemd/network</filename>,
  62     the volatile runtime network directory
  63     <filename>/run/systemd/network</filename>, and the local
  64     administration network directory
  65     <filename>/etc/systemd/network</filename>. Link files must have
  66     the extension <filename>.link</filename>; other extensions are
  67     ignored. All link files are collectively sorted and processed in
  68     lexical order, regardless of the directories in which they live.
  69     However, files with identical filenames replace each other. Files
  70     in <filename>/etc</filename> have the highest priority, files in
  71     <filename>/run</filename> take precedence over files with the same
  72     name in <filename>/usr/lib</filename>. This can be used to
  73     override a system-supplied link file with a local file if needed.
  74     As a special case, an empty file (file size 0) or symlink with the
  75     same name pointing to <filename>/dev/null</filename> disables the
  76     configuration file entirely (it is "masked").</para>
  77
  78     <para>The link file contains a <literal>[Match]</literal> section,
  79     which determines if a given link file may be applied to a given
  80     device, as well as a <literal>[Link]</literal> section specifying
  81     how the device should be configured. The first (in lexical order)
  82     of the link files that matches a given device is applied. Note
  83     that a default file <filename>99-default.link</filename> is
  84     shipped by the system. Any user-supplied
  85     <filename>.link</filename> should hence have a lexically earlier
  86     name to be considered at all.</para>
  87
  88     <para>See
  89     <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  90     for diagnosing problems with <filename>.link</filename> files.</para>
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>[Match] Section Options</title>
  95
  96     <para>A link file is said to match a device if each of the entries
  97     in the <literal>[Match]</literal> section matches, or if the
  98     section is empty. The following keys are accepted:</para>
  99
 100     <variablelist class='network-directives'>
 101       <varlistentry>
 102         <term><varname>MACAddress=</varname></term>
 103         <listitem>
 104           <para>The hardware address.</para>
 105         </listitem>
 106       </varlistentry>
 107       <varlistentry>
 108         <term><varname>OriginalName=</varname></term>
 109         <listitem>
 110           <para>A whitespace-separated list of shell-style globs matching
 111           the device name, as exposed by the udev property
 112           "INTERFACE". This cannot be used to match on names that have
 113           already been changed from userspace. Caution is advised when matching on
 114           kernel-assigned names, as they are known to be unstable
 115           between reboots.</para>
 116         </listitem>
 117       </varlistentry>
 118       <varlistentry>
 119         <term><varname>Path=</varname></term>
 120         <listitem>
 121           <para>A whitespace-separated list of shell-style globs matching
 122           the persistent path, as exposed by the udev property
 123           <literal>ID_PATH</literal>.</para>
 124         </listitem>
 125       </varlistentry>
 126       <varlistentry>
 127         <term><varname>Driver=</varname></term>
 128         <listitem>
 129           <para>A whitespace-separated list of shell-style globs matching
 130           the driver currently bound to the device,
 131           as exposed by the udev property <literal>DRIVER</literal>
 132           of its parent device, or if that is not set, the
 133           driver as exposed by <literal>ethtool -i</literal>
 134           of the device itself.</para>
 135         </listitem>
 136       </varlistentry>
 137       <varlistentry>
 138         <term><varname>Type=</varname></term>
 139         <listitem>
 140           <para>A whitespace-separated list of shell-style globs matching
 141           the device type, as exposed by the udev
 142           property <literal>DEVTYPE</literal>.</para>
 143         </listitem>
 144       </varlistentry>
 145       <varlistentry>
 146         <term><varname>Host=</varname></term>
 147         <listitem>
 148           <para>Matches against the hostname or machine
 149           ID of the host. See <literal>ConditionHost=</literal> in
 150           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 151           for details.</para>
 152         </listitem>
 153       </varlistentry>
 154       <varlistentry>
 155         <term><varname>Virtualization=</varname></term>
 156         <listitem>
 157           <para>Checks whether the system is executed in
 158           a virtualized environment and optionally test
 159           whether it is a specific implementation. See
 160           <literal>ConditionVirtualization=</literal> in
 161           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 162           for details.</para>
 163         </listitem>
 164       </varlistentry>
 165       <varlistentry>
 166         <term><varname>KernelCommandLine=</varname></term>
 167         <listitem>
 168           <para>Checks whether a specific kernel command line option
 169           is set (or if prefixed with the exclamation mark unset). See
 170           <literal>ConditionKernelCommandLine=</literal> in
 171           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 172           for details.</para>
 173         </listitem>
 174       </varlistentry>
 175         <varlistentry>
 176           <term><varname>KernelVersion=</varname></term>
 177           <listitem>
 178             <para>Checks whether the kernel version (as reported by <command>uname -r</command>) matches a certain
 179             expression (or if prefixed with the exclamation mark does not match it). See
 180             <literal>ConditionKernelVersion=</literal> in
 181             <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for
 182             details.
 183             </para>
 184           </listitem>
 185         </varlistentry>
 186       <varlistentry>
 187         <term><varname>Architecture=</varname></term>
 188         <listitem>
 189           <para>Checks whether the system is running on a specific
 190           architecture. See <literal>ConditionArchitecture=</literal>
 191           in
 192           <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 193           for details.</para>
 194         </listitem>
 195       </varlistentry>
 196     </variablelist>
 197
 198   </refsect1>
 199
 200   <refsect1>
 201     <title>[Link] Section Options</title>
 202
 203     <para>The <literal>[Link]</literal> section accepts the following
 204     keys:</para>
 205
 206     <variablelist class='network-directives'>
 207       <varlistentry>
 208         <term><varname>Description=</varname></term>
 209         <listitem>
 210           <para>A description of the device.</para>
 211         </listitem>
 212       </varlistentry>
 213       <varlistentry>
 214         <term><varname>Alias=</varname></term>
 215         <listitem>
 216           <para>The <literal>ifalias</literal> is set to this
 217           value.</para>
 218         </listitem>
 219       </varlistentry>
 220       <varlistentry>
 221         <term><varname>MACAddressPolicy=</varname></term>
 222         <listitem>
 223           <para>The policy by which the MAC address should be set. The
 224           available policies are:
 225           </para>
 226
 227           <variablelist>
 228             <varlistentry>
 229               <term><literal>persistent</literal></term>
 230               <listitem>
 231                 <para>If the hardware has a persistent MAC address, as
 232                 most hardware should, and if it is used by the kernel,
 233                 nothing is done. Otherwise, a new MAC address is
 234                 generated which is guaranteed to be the same on every
 235                 boot for the given machine and the given device, but
 236                 which is otherwise random. This feature depends on ID_NET_NAME_*
 237                 properties to exist for the link. On hardware where these
 238                 properties are not set, the generation of a persistent MAC address
 239                 will fail.</para>
 240               </listitem>
 241             </varlistentry>
 242             <varlistentry>
 243               <term><literal>random</literal></term>
 244               <listitem>
 245                 <para>If the kernel is using a random MAC address,
 246                 nothing is done. Otherwise, a new address is randomly
 247                 generated each time the device appears, typically at
 248                 boot. Either way, the random address will have the
 249                 <literal>unicast</literal> and
 250                 <literal>locally administered</literal> bits set.</para>
 251               </listitem>
 252             </varlistentry>
 253             <varlistentry>
 254               <term><literal>none</literal></term>
 255               <listitem>
 256                 <para>Keeps the MAC address assigned by the kernel.</para>
 257               </listitem>
 258             </varlistentry>
 259           </variablelist>
 260         </listitem>
 261       </varlistentry>
 262       <varlistentry>
 263         <term><varname>MACAddress=</varname></term>
 264         <listitem>
 265           <para>The MAC address to use, if no
 266           <literal>MACAddressPolicy=</literal>
 267           is specified.</para>
 268         </listitem>
 269       </varlistentry>
 270       <varlistentry>
 271         <term><varname>NamePolicy=</varname></term>
 272         <listitem>
 273           <para>An ordered, space-separated list of policies by which
 274           the interface name should be set.
 275           <literal>NamePolicy</literal> may be disabled by specifying
 276           <literal>net.ifnames=0</literal> on the kernel command line.
 277           Each of the policies may fail, and the first successful one
 278           is used. The name is not set directly, but is exported to
 279           udev as the property <literal>ID_NET_NAME</literal>, which
 280           is, by default, used by a udev rule to set
 281           <literal>NAME</literal>. If the name has already been set by
 282           userspace, no renaming is performed. The available policies
 283           are:</para>
 284
 285           <variablelist>
 286             <varlistentry>
 287               <term><literal>kernel</literal></term>
 288               <listitem>
 289                 <para>If the kernel claims that the name it has set
 290                 for a device is predictable, then no renaming is
 291                 performed.</para>
 292               </listitem>
 293             </varlistentry>
 294             <varlistentry>
 295               <term><literal>database</literal></term>
 296               <listitem>
 297                 <para>The name is set based on entries in the udev's
 298                 Hardware Database with the key
 299                 <literal>ID_NET_NAME_FROM_DATABASE</literal>.
 300                 </para>
 301               </listitem>
 302             </varlistentry>
 303             <varlistentry>
 304               <term><literal>onboard</literal></term>
 305               <listitem>
 306                 <para>The name is set based on information given by
 307                 the firmware for on-board devices, as exported by the
 308                 udev property <literal>ID_NET_NAME_ONBOARD</literal>.
 309                 </para>
 310               </listitem>
 311             </varlistentry>
 312             <varlistentry>
 313               <term><literal>slot</literal></term>
 314               <listitem>
 315                 <para>The name is set based on information given by
 316                 the firmware for hot-plug devices, as exported by the
 317                 udev property <literal>ID_NET_NAME_SLOT</literal>.
 318                 </para>
 319               </listitem>
 320             </varlistentry>
 321             <varlistentry>
 322               <term><literal>path</literal></term>
 323               <listitem>
 324                 <para>The name is set based on the device's physical
 325                 location, as exported by the udev property
 326                 <literal>ID_NET_NAME_PATH</literal>.</para>
 327               </listitem>
 328             </varlistentry>
 329             <varlistentry>
 330               <term><literal>mac</literal></term>
 331               <listitem>
 332                 <para>The name is set based on the device's persistent
 333                 MAC address, as exported by the udev property
 334                 <literal>ID_NET_NAME_MAC</literal>.</para>
 335               </listitem>
 336             </varlistentry>
 337           </variablelist>
 338         </listitem>
 339       </varlistentry>
 340       <varlistentry>
 341         <term><varname>Name=</varname></term>
 342         <listitem>
 343           <para>The interface name to use in case all the
 344           policies specified in
 345           <varname>NamePolicy=</varname> fail, or in case
 346           <varname>NamePolicy=</varname> is missing or
 347           disabled.</para>
 348
 349           <para>Note that specifying a name that the kernel might use for another
 350           interface (for example <literal>eth0</literal>) is dangerous because the
 351           name assignment done by udev will race with the assignment done by the
 352           kernel, and only one interface may use the name. Depending on the order of
 353           operations, either udev or the kernel will win, making the naming
 354           unpredictable. It is best to use some different prefix, for example
 355           <literal>internal0</literal>/<literal>external0</literal> or
 356           <literal>lan0</literal>/<literal>lan1</literal>/<literal>lan3</literal>.
 357           </para>
 358         </listitem>
 359       </varlistentry>
 360       <varlistentry>
 361         <term><varname>MTUBytes=</varname></term>
 362         <listitem>
 363           <para>The maximum transmission unit in bytes to set for the
 364           device. The usual suffixes K, M, G, are supported and are
 365           understood to the base of 1024.</para>
 366         </listitem>
 367       </varlistentry>
 368       <varlistentry>
 369         <term><varname>BitsPerSecond=</varname></term>
 370         <listitem>
 371           <para>The speed to set for the device, the value is rounded
 372           down to the nearest Mbps. The usual suffixes K, M, G, are
 373           supported and are understood to the base of 1000.</para>
 374         </listitem>
 375       </varlistentry>
 376       <varlistentry>
 377         <term><varname>Duplex=</varname></term>
 378         <listitem>
 379           <para>The duplex mode to set for the device. The accepted
 380           values are <literal>half</literal> and
 381           <literal>full</literal>.</para>
 382         </listitem>
 383       </varlistentry>
 384       <varlistentry>
 385         <term><varname>AutoNegotiation=</varname></term>
 386         <listitem>
 387           <para>Enables or disables automatic negotiation of transmission parameters.
 388           Autonegotiation is a procedure by which two connected ethernet devices choose
 389           common transmission parameters, such as speed, duplex mode, and flow control.
 390           Takes a boolean value. Unset by default, which means that the kernel default
 391           will be used.</para>
 392
 393           <para>Note that if autonegotiation is enabled, speed and duplex settings are
 394           read-only. If autonegotation is disabled, speed and duplex settings are writable
 395           if the driver supports multiple link modes.</para>
 396         </listitem>
 397       </varlistentry>
 398       <varlistentry>
 399         <term><varname>WakeOnLan=</varname></term>
 400         <listitem>
 401           <para>The Wake-on-LAN policy to set for the device. The
 402           supported values are:</para>
 403
 404           <variablelist>
 405             <varlistentry>
 406               <term><literal>phy</literal></term>
 407               <listitem>
 408                 <para>Wake on PHY activity.</para>
 409               </listitem>
 410             </varlistentry>
 411             <varlistentry>
 412               <term><literal>unicast</literal></term>
 413               <listitem>
 414                 <para>Wake on unicast messages.</para>
 415               </listitem>
 416             </varlistentry>
 417             <varlistentry>
 418               <term><literal>multicast</literal></term>
 419               <listitem>
 420                 <para>Wake on multicast messages.</para>
 421               </listitem>
 422             </varlistentry>
 423             <varlistentry>
 424               <term><literal>broadcast</literal></term>
 425               <listitem>
 426                 <para>Wake on broadcast messages.</para>
 427               </listitem>
 428             </varlistentry>
 429             <varlistentry>
 430               <term><literal>arp</literal></term>
 431               <listitem>
 432                 <para>Wake on ARP.</para>
 433               </listitem>
 434             </varlistentry>
 435             <varlistentry>
 436               <term><literal>magic</literal></term>
 437               <listitem>
 438                 <para>Wake on receipt of a magic packet.
 439                 </para>
 440               </listitem>
 441             </varlistentry>
 442             <varlistentry>
 443               <term><literal>secureon</literal></term>
 444               <listitem>
 445                 <para>Enable secureon(tm) password for MagicPacket(tm).
 446                 </para>
 447               </listitem>
 448             </varlistentry>
 449             <varlistentry>
 450               <term><literal>off</literal></term>
 451               <listitem>
 452                 <para>Never wake.</para>
 453               </listitem>
 454             </varlistentry>
 455           </variablelist>
 456
 457           <para>Defaults to <literal>off</literal>.</para>
 458         </listitem>
 459       </varlistentry>
 460       <varlistentry>
 461         <term><varname>Port=</varname></term>
 462         <listitem>
 463           <para>The port option is used to select the device port. The
 464           supported values are:</para>
 465
 466           <variablelist>
 467             <varlistentry>
 468               <term><literal>tp</literal></term>
 469               <listitem>
 470                 <para>An Ethernet interface using Twisted-Pair cable as the medium.</para>
 471               </listitem>
 472             </varlistentry>
 473             <varlistentry>
 474               <term><literal>aui</literal></term>
 475               <listitem>
 476                 <para>Attachment Unit Interface (AUI). Normally used with hubs.
 477                 </para>
 478               </listitem>
 479             </varlistentry>
 480             <varlistentry>
 481               <term><literal>bnc</literal></term>
 482               <listitem>
 483                 <para>An Ethernet interface using BNC connectors and co-axial cable.</para>
 484               </listitem>
 485             </varlistentry>
 486             <varlistentry>
 487               <term><literal>mii</literal></term>
 488               <listitem>
 489                 <para>An Ethernet interface using a Media Independent Interface (MII).</para>
 490               </listitem>
 491             </varlistentry>
 492             <varlistentry>
 493               <term><literal>fibre</literal></term>
 494               <listitem>
 495                 <para>An Ethernet interface using Optical Fibre as the medium.</para>
 496               </listitem>
 497             </varlistentry>
 498           </variablelist>
 499         </listitem>
 500       </varlistentry>
 501       <varlistentry>
 502         <term><varname>TCPSegmentationOffload=</varname></term>
 503         <listitem>
 504           <para>The TCP Segmentation Offload (TSO) when true enables
 505           TCP segmentation offload. Takes a boolean value.
 506           Defaults to "unset".</para>
 507         </listitem>
 508       </varlistentry>
 509        <varlistentry>
 510       <term><varname>TCP6SegmentationOffload=</varname></term>
 511         <listitem>
 512           <para>The TCP6 Segmentation Offload (tx-tcp6-segmentation) when true enables
 513           TCP6 segmentation offload. Takes a boolean value.
 514           Defaults to "unset".</para>
 515         </listitem>
 516       </varlistentry>
 517       <varlistentry>
 518         <term><varname>GenericSegmentationOffload=</varname></term>
 519         <listitem>
 520           <para>The Generic Segmentation Offload (GSO) when true enables
 521           generic segmentation offload. Takes a boolean value.
 522           Defaults to "unset".</para>
 523         </listitem>
 524       </varlistentry>
 525       <varlistentry>
 526         <term><varname>UDPSegmentationOffload=</varname></term>
 527         <listitem>
 528           <para>The UDP Segmentation Offload (USO) when true enables
 529           UDP segmentation offload. Takes a boolean value.
 530           Defaults to "unset".</para>
 531         </listitem>
 532       </varlistentry>
 533     <varlistentry>
 534         <term><varname>GenericReceiveOffload=</varname></term>
 535         <listitem>
 536           <para>The Generic Receive Offload (GRO) when true enables
 537           generic receive offload. Takes a boolean value.
 538           Defaults to "unset".</para>
 539         </listitem>
 540       </varlistentry>
 541       <varlistentry>
 542         <term><varname>LargeReceiveOffload=</varname></term>
 543         <listitem>
 544           <para>The Large Receive Offload (LRO) when true enables
 545           large receive offload. Takes a boolean value.
 546           Defaults to "unset".</para>
 547         </listitem>
 548       </varlistentry>
 549     </variablelist>
 550   </refsect1>
 551
 552   <refsect1>
 553     <title>Examples</title>
 554
 555     <example>
 556       <title>/usr/lib/systemd/network/99-default.link</title>
 557
 558       <para>The link file <filename>99-default.link</filename> that is
 559       shipped with systemd defines the default naming policy for
 560       links.</para>
 561
 562       <programlisting>[Link]
 563 NamePolicy=kernel database onboard slot path
 564 MACAddressPolicy=persistent</programlisting>
 565     </example>
 566
 567     <example>
 568       <title>/etc/systemd/network/10-dmz.link</title>
 569
 570       <para>This example assigns the fixed name
 571       <literal>dmz0</literal> to the interface with the MAC address
 572       00:a0:de:63:7a:e6:</para>
 573
 574       <programlisting>[Match]
 575 MACAddress=00:a0:de:63:7a:e6
 576
 577 [Link]
 578 Name=dmz0</programlisting>
 579     </example>
 580
 581     <example>
 582       <title>/etc/systemd/network/10-internet.link</title>
 583
 584       <para>This example assigns the fixed name
 585       <literal>internet0</literal> to the interface with the device
 586       path <literal>pci-0000:00:1a.0-*</literal>:</para>
 587
 588       <programlisting>[Match]
 589 Path=pci-0000:00:1a.0-*
 590
 591 [Link]
 592 Name=internet0</programlisting>
 593     </example>
 594
 595     <example>
 596       <title>/etc/systemd/network/25-wireless.link</title>
 597
 598       <para>Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.</para>
 599
 600       <programlisting>[Match]
 601 MACAddress=12:34:56:78:9a:bc
 602 Driver=brcmsmac
 603 Path=pci-0000:02:00.0-*
 604 Type=wlan
 605 Virtualization=no
 606 Host=my-laptop
 607 Architecture=x86-64
 608
 609 [Link]
 610 Name=wireless0
 611 MTUBytes=1450
 612 BitsPerSecond=10M
 613 WakeOnLan=magic
 614 MACAddress=cb:a9:87:65:43:21</programlisting>
 615     </example>
 616   </refsect1>
 617
 618   <refsect1>
 619     <title>See Also</title>
 620     <para>
 621       <citerefentry>
 622         <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
 623       </citerefentry>,
 624       <citerefentry>
 625         <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
 626       </citerefentry>,
 627       <citerefentry>
 628         <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum>
 629       </citerefentry>,
 630       <citerefentry>
 631         <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
 632       </citerefentry>
 633     </para>
 634   </refsect1>
 635
 636 </refentry>