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 <literal>[Match]</literal> section, which
  75                 determines if a given link file may be applied to a given device; and a
  76                 <literal>[Link]</literal> section specifying how the device should be
  77                 configured. The first (in lexical order) of the link files that matches
  78                 a given device is applied.</para>
  79
  80                 <para>A link file is said to match a device if each of the entries in the
  81                 <literal>[Match]</literal> section matches, or if the section is empty.
  82                 The following keys are accepted:</para>
  83
  84                 <variablelist class='network-directives'>
  85                         <varlistentry>
  86                                 <term><varname>MACAddress=</varname></term>
  87                                 <listitem>
  88                                         <para>The hardware address.</para>
  89                                 </listitem>
  90                         </varlistentry>
  91                         <varlistentry>
  92                                 <term><varname>Path=</varname></term>
  93                                 <listitem>
  94                                 <para>The persistent path, as exposed by the
  95                                 udev property <literal>ID_PATH</literal>. May
  96                                 contain shell style globs.</para>
  97                         </listitem>
  98                         </varlistentry>
  99                         <varlistentry>
 100                                 <term><varname>Driver=</varname></term>
 101                                 <listitem>
 102                                         <para>The driver currently bound to the device,
 103                                         as exposed by the udev property <literal>DRIVER</literal>
 104                                         of its parent device, or if that is not set the
 105                                         driver as exposed by <literal>ethtool -i</literal>
 106                                         of the device itself.</para>
 107                                 </listitem>
 108                         </varlistentry>
 109                         <varlistentry>
 110                                 <term><varname>Type=</varname></term>
 111                                 <listitem>
 112                                         <para>The device type, as exposed by the udev
 113                                         property <literal>DEVTYPE</literal>.</para>
 114                                 </listitem>
 115                         </varlistentry>
 116                         <varlistentry>
 117                                 <term><varname>Host=</varname></term>
 118                                 <listitem>
 119                                         <para>Matches against the hostname or machine
 120                                         ID of the host. See <literal>ConditionHost=</literal> in
 121                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 122                                         for details.</para>
 123                                 </listitem>
 124                         </varlistentry>
 125                         <varlistentry>
 126                                 <term><varname>Virtualization=</varname></term>
 127                                 <listitem>
 128                                         <para>Checks whether the system is executed in
 129                                         a virtualized environment and optionally test
 130                                         whether it is a specific implementation. See
 131                                         <literal>ConditionVirtualization=</literal> in
 132                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 133                                         for details.</para>
 134                                 </listitem>
 135                         </varlistentry>
 136                         <varlistentry>
 137                                 <term><varname>KernelCommandLine=</varname></term>
 138                                 <listitem>
 139                                         <para>Checks whether a specific kernel command
 140                                         line option is set (or if prefixed with the
 141                                         exclamation mark unset). See
 142                                         <literal>ConditionKernelCommandLine=</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>Architecture=</varname></term>
 149                                 <listitem>
 150                                         <para>Checks whether the system is running on a
 151                                         specific architecture. See
 152                                         <literal>ConditionArchitecture=</literal> in
 153                                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 154                                         for details.</para>
 155                                 </listitem>
 156                         </varlistentry>
 157                 </variablelist>
 158
 159                 <para>The <literal>[Link]</literal> section accepts the following
 160                 keys:</para>
 161
 162                 <variablelist class='network-directives'>
 163                         <varlistentry>
 164                                 <term><varname>Description=</varname></term>
 165                                 <listitem>
 166                                         <para>A description of the device.</para>
 167                                 </listitem>
 168                         </varlistentry>
 169                         <varlistentry>
 170                                 <term><varname>Alias=</varname></term>
 171                                 <listitem>
 172                                         <para>The <literal>ifalias</literal> is set to
 173                                         this value.</para>
 174                                 </listitem>
 175                         </varlistentry>
 176                         <varlistentry>
 177                                 <term><varname>MACAddressPolicy=</varname></term>
 178                                 <listitem>
 179                                         <para>The policy by which the MAC address
 180                                         should be set. The available policies are:
 181                                         </para>
 182
 183                                         <variablelist>
 184                                                 <varlistentry>
 185                                                         <term><literal>persistent</literal></term>
 186                                                         <listitem>
 187                                                                 <para>If the hardware has a persistent
 188                                                                 MAC address, as most hardware should,
 189                                                                 and this is used by the kernel, nothing
 190                                                                 is done. Otherwise, a new MAC address
 191                                                                 is generated which is guaranteed to be
 192                                                                 the same on every boot for the given
 193                                                                 machine and the given device, but which
 194                                                                 is otherwise random.</para>
 195                                                         </listitem>
 196                                                 </varlistentry>
 197                                                 <varlistentry>
 198                                                         <term><literal>random</literal></term>
 199                                                         <listitem>
 200                                                                 <para>If the kernel is using a random MAC
 201                                                                 address, nothing is done. Otherwise, a new
 202                                                                 address is randomly generated each time the
 203                                                                 device appears, typically at boot.</para>
 204                                                         </listitem>
 205                                                 </varlistentry>
 206                                         </variablelist>
 207                                 </listitem>
 208                         </varlistentry>
 209                         <varlistentry>
 210                                 <term><varname>MACAddress=</varname></term>
 211                                 <listitem>
 212                                         <para>The MAC address to use, if no
 213                                         <literal>MACAddressPolicy=</literal>
 214                                         is specified.</para>
 215                                 </listitem>
 216                         </varlistentry>
 217                         <varlistentry>
 218                                 <term><varname>NamePolicy=</varname></term>
 219                                 <listitem>
 220                                         <para>An ordered, space-separated list of
 221                                         policies by which the interface name should
 222                                         be set. <literal>NamePolicy</literal> may be
 223                                         disabled by specifying
 224                                         <literal>net.ifnames=0</literal> on the kernel
 225                                         commandline. Each of the policies may fail, and
 226                                         the first successful one is used. The name is
 227                                         not set directly, but is exported to udev as
 228                                         the property <literal>ID_NET_NAME</literal>,
 229                                         which is, by default, used by a udev rule to set
 230                                         <literal>NAME</literal>. The available policies
 231                                         are:</para>
 232
 233                                         <variablelist>
 234                                                 <varlistentry>
 235                                                         <term><literal>database</literal></term>
 236                                                         <listitem>
 237                                                                 <para>The name is set based on entries in
 238                                                                 the udev's Hardware Database with the key
 239                                                                 <literal>ID_NET_NAME_FROM_DATABASE</literal>
 240                                                                 .</para>
 241                                                         </listitem>
 242                                                 </varlistentry>
 243                                                 <varlistentry>
 244                                                         <term><literal>onboard</literal></term>
 245                                                         <listitem>
 246                                                                 <para>The name is set based on information given by
 247                                                                 the firmware for on-board devices, as exported by
 248                                                                 the udev property <literal>ID_NET_NAME_ONBOARD</literal>
 249                                                                 .</para>
 250                                                         </listitem>
 251                                                 </varlistentry>
 252                                                 <varlistentry>
 253                                                         <term><literal>slot</literal></term>
 254                                                         <listitem>
 255                                                                 <para>The name is set based on information given by
 256                                                                 the firmware for hot-plug devices, as exported by
 257                                                                 the udev property <literal>ID_NET_NAME_SLOT</literal>
 258                                                                 .</para>
 259                                                         </listitem>
 260                                                 </varlistentry>
 261                                                 <varlistentry>
 262                                                         <term><literal>path</literal></term>
 263                                                         <listitem>
 264                                                                 <para>The name is set based on the device's physical
 265                                                                 location, as exported by the udev property
 266                                                                 <literal>ID_NET_NAME_PATH</literal>.</para>
 267                                                         </listitem>
 268                                                 </varlistentry>
 269                                                 <varlistentry>
 270                                                         <term><literal>mac</literal></term>
 271                                                         <listitem>
 272                                                                 <para>The name is set based on the device's
 273                                                                 persistent MAC address, as exported by the udev
 274                                                                 property <literal>ID_NET_NAME_MAC</literal>.</para>
 275                                                         </listitem>
 276                                                 </varlistentry>
 277                                         </variablelist>
 278                                 </listitem>
 279                         </varlistentry>
 280                         <varlistentry>
 281                                 <term><varname>Name=</varname></term>
 282                                 <listitem>
 283                                         <para>The interface name to use in case all the
 284                                         policies specified in
 285                                         <varname>NamePolicy=</varname> fail, or in case
 286                                         <varname>NamePolicy=</varname> is missing or
 287                                         disabled.</para>
 288                                 </listitem>
 289                         </varlistentry>
 290                         <varlistentry>
 291                                 <term><varname>MTUBytes=</varname></term>
 292                                 <listitem>
 293                                         <para>The maximum transmission unit in bytes to
 294                                         set for the device. The usual suffixes K, M, G,
 295                                         are supported and are understood to the base of
 296                                         1024.</para>
 297                                 </listitem>
 298                         </varlistentry>
 299                         <varlistentry>
 300                                 <term><varname>BitsPerSecond=</varname></term>
 301                                 <listitem>
 302                                         <para>The speed to set for the device, the
 303                                         value is rounded down to the nearest Mbps.
 304                                         The usual suffixes K, M, G, are supported and
 305                                         are understood to the base of 1000.</para>
 306                                 </listitem>
 307                         </varlistentry>
 308                         <varlistentry>
 309                                 <term><varname>Duplex=</varname></term>
 310                                 <listitem>
 311                                         <para>The duplex mode to set for the device.
 312                                         The accepted values are <literal>half</literal>
 313                                         and <literal>full</literal>.</para>
 314                                 </listitem>
 315                         </varlistentry>
 316                         <varlistentry>
 317                                 <term><varname>WakeOnLan=</varname></term>
 318                                 <listitem>
 319                                         <para>The Wake-on-LAN policy to set for the
 320                                         device. The supported values are:</para>
 321
 322                                         <variablelist>
 323                                                 <varlistentry>
 324                                                         <term><literal>phy</literal></term>
 325                                                         <listitem>
 326                                                                 <para>Wake on PHY activity.</para>
 327                                                         </listitem>
 328                                                 </varlistentry>
 329                                                 <varlistentry>
 330                                                         <term><literal>magic</literal></term>
 331                                                         <listitem>
 332                                                                 <para>Wake on receipt of a magic packet
 333                                                                 </para>
 334                                                         </listitem>
 335                                                 </varlistentry>
 336                                                 <varlistentry>
 337                                                         <term><literal>off</literal></term>
 338                                                         <listitem>
 339                                                                 <para>Never wake.</para>
 340                                                         </listitem>
 341                                                 </varlistentry>
 342                                         </variablelist>
 343                                 </listitem>
 344                         </varlistentry>
 345                 </variablelist>
 346         </refsect1>
 347
 348         <refsect1>
 349                 <title>Example</title>
 350                 <example>
 351                         <title>/etc/systemd/network/wireless.link</title>
 352
 353                         <programlisting>[Match]
 354 MACAddress=12:34:56:78:9a:bc
 355 Driver=brcmsmac
 356 Path=pci-0000:02:00.0-*
 357 Type=wlan
 358 Virtualization=no
 359 Host=my-laptop
 360 Architecture=x86-64
 361
 362 [Link]
 363 Name=wireless0
 364 MTUBytes=1450
 365 BitsPerSecond=10M
 366 WakeOnLan=magic
 367 MACAddress=cb:a9:87:65:43:21</programlisting>
 368                 </example>
 369         </refsect1>
 370
 371         <refsect1>
 372                 <title>See Also</title>
 373                 <para>
 374                         <citerefentry>
 375                                 <refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum>
 376                         </citerefentry>,
 377                         <citerefentry>
 378                                 <refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum>
 379                         </citerefentry>
 380                 </para>
 381         </refsect1>
 382
 383 </refentry>