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