man/systemd.link.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2014 Tom Gundersen
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd.link">
  28   <refentryinfo>
  29     <title>systemd.link</title>
  30     <productname>systemd</productname>
  31
  32     <authorgroup>
  33       <author>
  34         <contrib>Developer</contrib>
  35         <firstname>Tom</firstname>
  36         <surname>Gundersen</surname>
  37       </author>
  38     </authorgroup>
  39   </refentryinfo>
  40
  41   <refmeta>
  42     <refentrytitle>systemd.link</refentrytitle>
  43     <manvolnum>5</manvolnum>
  44   </refmeta>
  45
  46   <refnamediv>
  47     <refname>systemd.link</refname>
  48     <refpurpose>Network device configuration</refpurpose>
  49   </refnamediv>
  50
  51   <refsynopsisdiv>
  52     <para><filename><replaceable>link</replaceable>.link</filename></para>
  53   </refsynopsisdiv>
  54
  55   <refsect1>
  56     <title>Description</title>
  57
  58     <para>Network link configuration is performed by the
  59     <command>net_setup_link</command> udev builtin.</para>
  60
  61     <para>The link files are read from the files located in the system
  62     network directory <filename>&rootlibexecdir;/network</filename>,
  63     the volatile runtime network directory
  64     <filename>/run/systemd/network</filename>, and the local
  65     administration network directory
  66     <filename>&pkgsysconfdir;/network</filename>. Link files must have
  67     the extension <filename>.link</filename>; other extensions are
  68     ignored. All link files are collectively sorted and processed in
  69     lexical order, regardless of the directories in which they live.
  70     However, files with identical filenames replace each other. Files
  71     in <filename>/etc</filename> have the highest priority, files in
  72     <filename>/run</filename> take precedence over files with the same
  73     name in <filename>&rootprefix;/lib</filename>. This can be used to
  74     override a system-supplied link file with a local file if needed;
  75     a symlink in <filename>/etc</filename> with the same name as a
  76     link file in <filename>&rootprefix;/lib</filename>, pointing to
  77     <filename>/dev/null</filename>, disables the link file
  78     entirely.</para>
  79
  80     <para>The link file contains a <literal>[Match]</literal> section,
  81     which determines if a given link file may be applied to a given
  82     device, as well as a <literal>[Link]</literal> section specifying
  83     how the device should be configured. The first (in lexical order)
  84     of the link files that matches a given device is applied. Note
  85     that a default file <filename>99-default.link</filename> is
  86     shipped by the system, any user-supplied
  87     <filename>.link</filename> should hence have a lexically earlier
  88     name to be considered at all.</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 can not 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 existing 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.</para>
 236               </listitem>
 237             </varlistentry>
 238           </variablelist>
 239         </listitem>
 240       </varlistentry>
 241       <varlistentry>
 242         <term><varname>MACAddress=</varname></term>
 243         <listitem>
 244           <para>The MAC address to use, if no
 245           <literal>MACAddressPolicy=</literal>
 246           is specified.</para>
 247         </listitem>
 248       </varlistentry>
 249       <varlistentry>
 250         <term><varname>NamePolicy=</varname></term>
 251         <listitem>
 252           <para>An ordered, space-separated list of policies by which
 253           the interface name should be set.
 254           <literal>NamePolicy</literal> may be disabled by specifying
 255           <literal>net.ifnames=0</literal> on the kernel command line.
 256           Each of the policies may fail, and the first successful one
 257           is used. The name is not set directly, but is exported to
 258           udev as the property <literal>ID_NET_NAME</literal>, which
 259           is, by default, used by a udev rule to set
 260           <literal>NAME</literal>. If the name has already been set by
 261           userspace, no renaming is performed. The available policies
 262           are:</para>
 263
 264           <variablelist>
 265             <varlistentry>
 266               <term><literal>kernel</literal></term>
 267               <listitem>
 268                 <para>If the kernel claims that the name it has set
 269                 for a device is predictable, then no renaming is
 270                 performed.</para>
 271               </listitem>
 272             </varlistentry>
 273             <varlistentry>
 274               <term><literal>database</literal></term>
 275               <listitem>
 276                 <para>The name is set based on entries in the udev's
 277                 Hardware Database with the key
 278                 <literal>ID_NET_NAME_FROM_DATABASE</literal>.
 279                 </para>
 280               </listitem>
 281             </varlistentry>
 282             <varlistentry>
 283               <term><literal>onboard</literal></term>
 284               <listitem>
 285                 <para>The name is set based on information given by
 286                 the firmware for on-board devices, as exported by the
 287                 udev property <literal>ID_NET_NAME_ONBOARD</literal>.
 288                 </para>
 289               </listitem>
 290             </varlistentry>
 291             <varlistentry>
 292               <term><literal>slot</literal></term>
 293               <listitem>
 294                 <para>The name is set based on information given by
 295                 the firmware for hot-plug devices, as exported by the
 296                 udev property <literal>ID_NET_NAME_SLOT</literal>.
 297                 </para>
 298               </listitem>
 299             </varlistentry>
 300             <varlistentry>
 301               <term><literal>path</literal></term>
 302               <listitem>
 303                 <para>The name is set based on the device's physical
 304                 location, as exported by the udev property
 305                 <literal>ID_NET_NAME_PATH</literal>.</para>
 306               </listitem>
 307             </varlistentry>
 308             <varlistentry>
 309               <term><literal>mac</literal></term>
 310               <listitem>
 311                 <para>The name is set based on the device's persistent
 312                 MAC address, as exported by the udev property
 313                 <literal>ID_NET_NAME_MAC</literal>.</para>
 314               </listitem>
 315             </varlistentry>
 316           </variablelist>
 317         </listitem>
 318       </varlistentry>
 319       <varlistentry>
 320         <term><varname>Name=</varname></term>
 321         <listitem>
 322           <para>The interface name to use in case all the
 323           policies specified in
 324           <varname>NamePolicy=</varname> fail, or in case
 325           <varname>NamePolicy=</varname> is missing or
 326           disabled.</para>
 327         </listitem>
 328       </varlistentry>
 329       <varlistentry>
 330         <term><varname>MTUBytes=</varname></term>
 331         <listitem>
 332           <para>The maximum transmission unit in bytes to set for the
 333           device. The usual suffixes K, M, G, are supported and are
 334           understood to the base of 1024.</para>
 335         </listitem>
 336       </varlistentry>
 337       <varlistentry>
 338         <term><varname>BitsPerSecond=</varname></term>
 339         <listitem>
 340           <para>The speed to set for the device, the value is rounded
 341           down to the nearest Mbps. The usual suffixes K, M, G, are
 342           supported and are understood to the base of 1000.</para>
 343         </listitem>
 344       </varlistentry>
 345       <varlistentry>
 346         <term><varname>Duplex=</varname></term>
 347         <listitem>
 348           <para>The duplex mode to set for the device. The accepted
 349           values are <literal>half</literal> and
 350           <literal>full</literal>.</para>
 351         </listitem>
 352       </varlistentry>
 353       <varlistentry>
 354         <term><varname>WakeOnLan=</varname></term>
 355         <listitem>
 356           <para>The Wake-on-LAN policy to set for the device. The
 357           supported values are:</para>
 358
 359           <variablelist>
 360             <varlistentry>
 361               <term><literal>phy</literal></term>
 362               <listitem>
 363                 <para>Wake on PHY activity.</para>
 364               </listitem>
 365             </varlistentry>
 366             <varlistentry>
 367               <term><literal>magic</literal></term>
 368               <listitem>
 369                 <para>Wake on receipt of a magic packet.
 370                 </para>
 371               </listitem>
 372             </varlistentry>
 373             <varlistentry>
 374               <term><literal>off</literal></term>
 375               <listitem>
 376                 <para>Never wake.</para>
 377               </listitem>
 378             </varlistentry>
 379           </variablelist>
 380         </listitem>
 381       </varlistentry>
 382     </variablelist>
 383   </refsect1>
 384
 385   <refsect1>
 386     <title>Example</title>
 387     <example>
 388       <title>&pkgsysconfdir;/network/wireless.link</title>
 389
 390       <programlisting>[Match]
 391 MACAddress=12:34:56:78:9a:bc
 392 Driver=brcmsmac
 393 Path=pci-0000:02:00.0-*
 394 Type=wlan
 395 Virtualization=no
 396 Host=my-laptop
 397 Architecture=x86-64
 398
 399 [Link]
 400 Name=wireless0
 401 MTUBytes=1450
 402 BitsPerSecond=10M
 403 WakeOnLan=magic
 404 MACAddress=cb:a9:87:65:43:21</programlisting>
 405     </example>
 406   </refsect1>
 407
 408   <refsect1>
 409     <title>See Also</title>
 410     <para>
 411       <citerefentry>
 412         <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
 413       </citerefentry>,
 414       <citerefentry>
 415         <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
 416       </citerefentry>,
 417       <citerefentry>
 418         <refentrytitle>systemd.netdev</refentrytitle><manvolnum>5</manvolnum>
 419       </citerefentry>,
 420       <citerefentry>
 421         <refentrytitle>systemd.network</refentrytitle><manvolnum>5</manvolnum>
 422       </citerefentry>
 423     </para>
 424   </refsect1>
 425
 426 </refentry>