man/systemd.link.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   2 <?xml-stylesheet type="text/xsl" href="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"?>
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   4         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5
   6 <!--
   7   This file is part of systemd.
   8
   9   Copyright 2014 Tom Gundersen
  10
  11   systemd is free software; you can redistribute it and/or modify it
  12   under the terms of the GNU Lesser General Public License as published by
  13   the Free Software Foundation; either version 2.1 of the License, or
  14   (at your option) any later version.
  15
  16   systemd is distributed in the hope that it will be useful, but
  17   WITHOUT ANY WARRANTY; without even the implied warranty of
  18   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  19   Lesser General Public License for more details.
  20
  21   You should have received a copy of the GNU Lesser General Public License
  22   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  23 -->
  24
  25 <refentry id="systemd.link">
  26         <refentryinfo>
  27                 <title>systemd.link</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Tom</firstname>
  34                                 <surname>Gundersen</surname>
  35                         </author>
  36                 </authorgroup>
  37         </refentryinfo>
  38
  39         <refmeta>
  40                 <refentrytitle>systemd.link</refentrytitle>
  41                 <manvolnum>5</manvolnum>
  42         </refmeta>
  43
  44         <refnamediv>
  45                 <refname>systemd.link</refname>
  46                 <refpurpose>Network device configuration</refpurpose>
  47         </refnamediv>
  48
  49         <refsynopsisdiv>
  50                 <para><filename><replaceable>link</replaceable>.link</filename></para>
  51         </refsynopsisdiv>
  52
  53         <refsect1>
  54                 <title>Description</title>
  55
  56                 <para>Network link configuration is performed by the <command>net_setup_link</command>
  57                 udev builtin.</para>
  58
  59                 <para>The link files are read from the files located in the
  60                 system network directory <filename>/usr/lib/systemd/network</filename>,
  61                 the volatile runtime network directory <filename>/run/systemd/network</filename>,
  62                 and the local administration network directory <filename>/etc/systemd/network</filename>.
  63                 Link files must have the extension <filename>.link</filename>; other extensions are ignored.
  64                 All link files are collectively sorted and processed in lexical order,
  65                 regardless of the directories in which they live. However, files with
  66                 identical filenames replace each other. Files in <filename>/etc</filename>
  67                 have the highest priority, files in <filename>/run</filename> take precedence
  68                 over files with the same name in <filename>/usr/lib</filename>. This can be
  69                 used to override a system-supplied link file with a local file if needed;
  70                 a symlink in <filename>/etc</filename> with the same name as a link file in
  71                 <filename>/usr/lib</filename>, pointing to <filename>/dev/null</filename>,
  72                 disables the link file entirely.</para>
  73
  74                 <para>The link file contains a
  75                 <literal>[Match]</literal> section, which determines
  76                 if a given link file may be applied to a given device,
  77                 as well as a <literal>[Link]</literal> section specifying how
  78                 the device should be configured. The first (in lexical
  79                 order) of the link files that matches a given device
  80                 is applied. Note that a default file
  81                 <filename>99-default.link</filename> is shipped by the
  82                 system, any user-supplied <filename>.link</filename>
  83                 should hence have a lexically earlier name to be
  84                 considered at all.</para>
  85         </refsect1>
  86
  87         <refsect1>
  88                 <title>[Match] Section Options</title>
  89
  90                 <para>A link file is said to match a device if each of the entries in the
  91                 <literal>[Match]</literal> section matches, or if the section is empty.
  92                 The following keys are accepted:</para>
  93
  94                 <variablelist class='network-directives'>
  95                         <varlistentry>
  96                                 <term><varname>MACAddress=</varname></term>
  97                                 <listitem>
  98                                         <para>The hardware address.</para>
  99                                 </listitem>
 100                         </varlistentry>
 101                         <varlistentry>
 102                                 <term><varname>OriginalName=</varname></term>
 103                                 <listitem>
 104                                         <para>The device name, as exposed by the udev
 105                                         property "INTERFACE". May contain shell style
 106                                         globs. This can not be used to match on names
 107                                         that have already been changed from userspace.
 108                                         Caution is advised when matching on
 109                                         kernel-assigned names, as they are known to
 110                                         be unstable between reboots.</para>
 111                                 </listitem>
 112                         </varlistentry>
 113                         <varlistentry>
 114                                 <term><varname>Path=</varname></term>
 115                                 <listitem>
 116                                         <para>The persistent path, as exposed by the
 117                                         udev property <literal>ID_PATH</literal>. May
 118                                         contain shell style globs.</para>
 119                                 </listitem>
 120                         </varlistentry>
 121                         <varlistentry>
 122                                 <term><varname>Driver=</varname></term>
 123                                 <listitem>
 124                                         <para>The driver currently bound to the device,
 125                                         as exposed by the udev property <literal>DRIVER</literal>
 126                                         of its parent device, or if that is not set, the
 127                                         driver as exposed by <literal>ethtool -i</literal>
 128                                         of the device itself.</para>
 129                                 </listitem>
 130                         </varlistentry>
 131                         <varlistentry>
 132                                 <term><varname>Type=</varname></term>
 133                                 <listitem>
 134                                         <para>The device type, as exposed by the udev
 135                                         property <literal>DEVTYPE</literal>.</para>
 136                                 </listitem>
 137                         </varlistentry>
 138                         <varlistentry>
 139                                 <term><varname>Host=</varname></term>
 140                                 <listitem>
 141                                         <para>Matches against the hostname or machine
 142                                         ID of the host. See <literal>ConditionHost=</literal> in
 143                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 144                                         for details.</para>
 145                                 </listitem>
 146                         </varlistentry>
 147                         <varlistentry>
 148                                 <term><varname>Virtualization=</varname></term>
 149                                 <listitem>
 150                                         <para>Checks whether the system is executed in
 151                                         a virtualized environment and optionally test
 152                                         whether it is a specific implementation. See
 153                                         <literal>ConditionVirtualization=</literal> in
 154                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 155                                         for details.</para>
 156                                 </listitem>
 157                         </varlistentry>
 158                         <varlistentry>
 159                                 <term><varname>KernelCommandLine=</varname></term>
 160                                 <listitem>
 161                                         <para>Checks whether a specific kernel command
 162                                         line option is set (or if prefixed with the
 163                                         exclamation mark unset). See
 164                                         <literal>ConditionKernelCommandLine=</literal> in
 165                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 166                                         for details.</para>
 167                                 </listitem>
 168                         </varlistentry>
 169                         <varlistentry>
 170                                 <term><varname>Architecture=</varname></term>
 171                                 <listitem>
 172                                         <para>Checks whether the system is running on a
 173                                         specific architecture. See
 174                                         <literal>ConditionArchitecture=</literal> in
 175                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 176                                         for details.</para>
 177                                 </listitem>
 178                         </varlistentry>
 179                 </variablelist>
 180
 181         </refsect1>
 182
 183         <refsect1>
 184                 <title>[Link] Section Options</title>
 185
 186                 <para>The <literal>[Link]</literal> section accepts the following
 187                 keys:</para>
 188
 189                 <variablelist class='network-directives'>
 190                         <varlistentry>
 191                                 <term><varname>Description=</varname></term>
 192                                 <listitem>
 193                                         <para>A description of the device.</para>
 194                                 </listitem>
 195                         </varlistentry>
 196                         <varlistentry>
 197                                 <term><varname>Alias=</varname></term>
 198                                 <listitem>
 199                                         <para>The <literal>ifalias</literal> is set to
 200                                         this value.</para>
 201                                 </listitem>
 202                         </varlistentry>
 203                         <varlistentry>
 204                                 <term><varname>MACAddressPolicy=</varname></term>
 205                                 <listitem>
 206                                         <para>The policy by which the MAC address
 207                                         should be set. The available policies are:
 208                                         </para>
 209
 210                                         <variablelist>
 211                                                 <varlistentry>
 212                                                         <term><literal>persistent</literal></term>
 213                                                         <listitem>
 214                                                                 <para>If the hardware has a persistent
 215                                                                 MAC address, as most hardware should,
 216                                                                 and if it is used by the kernel, nothing
 217                                                                 is done. Otherwise, a new MAC address
 218                                                                 is generated which is guaranteed to be
 219                                                                 the same on every boot for the given
 220                                                                 machine and the given device, but which
 221                                                                 is otherwise random.</para>
 222                                                         </listitem>
 223                                                 </varlistentry>
 224                                                 <varlistentry>
 225                                                         <term><literal>random</literal></term>
 226                                                         <listitem>
 227                                                                 <para>If the kernel is using a random MAC
 228                                                                 address, nothing is done. Otherwise, a new
 229                                                                 address is randomly generated each time the
 230                                                                 device appears, typically at boot.</para>
 231                                                         </listitem>
 232                                                 </varlistentry>
 233                                         </variablelist>
 234                                 </listitem>
 235                         </varlistentry>
 236                         <varlistentry>
 237                                 <term><varname>MACAddress=</varname></term>
 238                                 <listitem>
 239                                         <para>The MAC address to use, if no
 240                                         <literal>MACAddressPolicy=</literal>
 241                                         is specified.</para>
 242                                 </listitem>
 243                         </varlistentry>
 244                         <varlistentry>
 245                                 <term><varname>NamePolicy=</varname></term>
 246                                 <listitem>
 247                                         <para>An ordered, space-separated list of
 248                                         policies by which the interface name should
 249                                         be set. <literal>NamePolicy</literal> may be
 250                                         disabled by specifying
 251                                         <literal>net.ifnames=0</literal> on the kernel
 252                                         command line. Each of the policies may fail, and
 253                                         the first successful one is used. The name is
 254                                         not set directly, but is exported to udev as
 255                                         the property <literal>ID_NET_NAME</literal>,
 256                                         which is, by default, used by a udev rule to set
 257                                         <literal>NAME</literal>. If the name has already
 258                                         been set by userspace, no renaming is performed.
 259                                         The available policies are:</para>
 260
 261                                         <variablelist>
 262                                                 <varlistentry>
 263                                                         <term><literal>kernel</literal></term>
 264                                                         <listitem>
 265                                                                 <para>If the kernel claims that the name it
 266                                                                 has set for a device is predictable, then
 267                                                                 no renaming is performed.
 268                                                                 </para>
 269                                                         </listitem>
 270                                                 </varlistentry>
 271                                                 <varlistentry>
 272                                                         <term><literal>database</literal></term>
 273                                                         <listitem>
 274                                                                 <para>The name is set based on entries in
 275                                                                 the udev's Hardware Database with the key
 276                                                                 <literal>ID_NET_NAME_FROM_DATABASE</literal>.
 277                                                                 </para>
 278                                                         </listitem>
 279                                                 </varlistentry>
 280                                                 <varlistentry>
 281                                                         <term><literal>onboard</literal></term>
 282                                                         <listitem>
 283                                                                 <para>The name is set based on information given by
 284                                                                 the firmware for on-board devices, as exported by
 285                                                                 the udev property <literal>ID_NET_NAME_ONBOARD</literal>.
 286                                                                 </para>
 287                                                         </listitem>
 288                                                 </varlistentry>
 289                                                 <varlistentry>
 290                                                         <term><literal>slot</literal></term>
 291                                                         <listitem>
 292                                                                 <para>The name is set based on information given by
 293                                                                 the firmware for hot-plug devices, as exported by
 294                                                                 the udev property <literal>ID_NET_NAME_SLOT</literal>.
 295                                                                 </para>
 296                                                         </listitem>
 297                                                 </varlistentry>
 298                                                 <varlistentry>
 299                                                         <term><literal>path</literal></term>
 300                                                         <listitem>
 301                                                                 <para>The name is set based on the device's physical
 302                                                                 location, as exported by the udev property
 303                                                                 <literal>ID_NET_NAME_PATH</literal>.</para>
 304                                                         </listitem>
 305                                                 </varlistentry>
 306                                                 <varlistentry>
 307                                                         <term><literal>mac</literal></term>
 308                                                         <listitem>
 309                                                                 <para>The name is set based on the device's
 310                                                                 persistent MAC address, as exported by the udev
 311                                                                 property <literal>ID_NET_NAME_MAC</literal>.</para>
 312                                                         </listitem>
 313                                                 </varlistentry>
 314                                         </variablelist>
 315                                 </listitem>
 316                         </varlistentry>
 317                         <varlistentry>
 318                                 <term><varname>Name=</varname></term>
 319                                 <listitem>
 320                                         <para>The interface name to use in case all the
 321                                         policies specified in
 322                                         <varname>NamePolicy=</varname> fail, or in case
 323                                         <varname>NamePolicy=</varname> is missing or
 324                                         disabled.</para>
 325                                 </listitem>
 326                         </varlistentry>
 327                         <varlistentry>
 328                                 <term><varname>MTUBytes=</varname></term>
 329                                 <listitem>
 330                                         <para>The maximum transmission unit in bytes to
 331                                         set for the device. The usual suffixes K, M, G,
 332                                         are supported and are understood to the base of
 333                                         1024.</para>
 334                                 </listitem>
 335                         </varlistentry>
 336                         <varlistentry>
 337                                 <term><varname>BitsPerSecond=</varname></term>
 338                                 <listitem>
 339                                         <para>The speed to set for the device, the
 340                                         value is rounded down to the nearest Mbps.
 341                                         The usual suffixes K, M, G, are supported and
 342                                         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.
 349                                         The accepted values are <literal>half</literal>
 350                                         and <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
 357                                         device. The 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>/etc/systemd/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>