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