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