1SYSTEMD.LINK(5) systemd.link SYSTEMD.LINK(5)
2
6 systemd.link - Network device configuration
7
9 link.link
10
12 A plain ini-style text file that encodes configuration for matching
13 network devices, used by systemd-udev(8) and in particular its
14 net_setup_link builtin. See systemd.syntax(5) for a general description
15 of the syntax.
16 The link files are read from the files located in the system network
18 directory /usr/lib/systemd/network, the volatile runtime network
19 directory /run/systemd/network, and the local administration network
20 directory /etc/systemd/network. Link files must have the extension
21 .link; other extensions are ignored. All link files are collectively
22 sorted and processed in lexical order, regardless of the directories in
23 which they live. However, files with identical filenames replace each
24 other. Files in /etc have the highest priority, files in /run take
25 precedence over files with the same name in /usr/lib. This can be used
26 to override a system-supplied link file with a local file if needed. As
27 a special case, an empty file (file size 0) or symlink with the same
28 name pointing to /dev/null disables the configuration file entirely (it
29 is "masked").
30 The link file contains a [Match] section, which determines if a given
32 link file may be applied to a given device, as well as a [Link] section
33 specifying how the device should be configured. The first (in lexical
34 order) of the link files that matches a given device is applied. Note
35 that a default file 99-default.link is shipped by the system. Any
36 user-supplied .link should hence have a lexically earlier name to be
37 considered at all.
38 See udevadm(8) for diagnosing problems with .link files.
40
42 A link file is said to match a device if all matches specified by the
43 "[Match]" section are satisfied. When a link file does not contain
44 valid settings in "[Match]" section, then the file will match all
45 devices and systemd-udevd warns about that. Hint: to avoid the warning
46 and to make it clear that all interfaces shall be matched, add the
47 following:
48 OriginalName=*
50 The following keys are accepted:
52 MACAddress=
54 A whitespace-separated list of hardware addresses. Use full colon-,
55 hyphen- or dot-delimited hexadecimal. See the example below. This
56 option may appear more than once, in which case the lists are
57 merged. If the empty string is assigned to this option, the list of
58 hardware addresses defined prior to this is reset.
59 Example:
61 MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF
63 PermanentMACAddress=
65 A whitespace-separated list of hardware's permanent addresses.
66 While MACAddress= matches the device's current MAC address, this
67 matches the device's permanent MAC address, which may be different
68 from the current one. Use full colon-, hyphen- or dot-delimited
69 hexadecimal. This option may appear more than once, in which case
70 the lists are merged. If the empty string is assigned to this
71 option, the list of hardware addresses defined prior to this is
72 reset.
73 Path=
75 A whitespace-separated list of shell-style globs matching the
76 persistent path, as exposed by the udev property ID_PATH.
77 Driver=
79 A whitespace-separated list of shell-style globs matching the
80 driver currently bound to the device, as exposed by the udev
81 property ID_NET_DRIVER of its parent device, or if that is not set,
82 the driver as exposed by ethtool -i of the device itself. If the
83 list is prefixed with a "!", the test is inverted.
84 Type=
86 A whitespace-separated list of shell-style globs matching the
87 device type, as exposed by networkctl status. If the list is
88 prefixed with a "!", the test is inverted.
89 Property=
91 A whitespace-separated list of udev property name with its value
92 after a equal ("="). If multiple properties are specified, the test
93 results are ANDed. If the list is prefixed with a "!", the test is
94 inverted. If a value contains white spaces, then please quote whole
95 key and value pair. If a value contains quotation, then please
96 escape the quotation with "\".
97 Example: if a .link file has the following:
99 Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""
101 then, the .link file matches only when an interface has all the
103 above three properties.
104 OriginalName=
106 A whitespace-separated list of shell-style globs matching the
107 device name, as exposed by the udev property "INTERFACE". This
108 cannot be used to match on names that have already been changed
109 from userspace. Caution is advised when matching on kernel-assigned
110 names, as they are known to be unstable between reboots.
111 Host=
113 Matches against the hostname or machine ID of the host. See
114 ConditionHost= in systemd.unit(5) for details. When prefixed with
115 an exclamation mark ("!"), the result is negated. If an empty
116 string is assigned, then previously assigned value is cleared.
117 Virtualization=
119 Checks whether the system is executed in a virtualized environment
120 and optionally test whether it is a specific implementation. See
121 ConditionVirtualization= in systemd.unit(5) for details. When
122 prefixed with an exclamation mark ("!"), the result is negated. If
123 an empty string is assigned, then previously assigned value is
124 cleared.
125 KernelCommandLine=
127 Checks whether a specific kernel command line option is set. See
128 ConditionKernelCommandLine= in systemd.unit(5) for details. When
129 prefixed with an exclamation mark ("!"), the result is negated. If
130 an empty string is assigned, then previously assigned value is
131 cleared.
132 KernelVersion=
134 Checks whether the kernel version (as reported by uname -r) matches
135 a certain expression. See ConditionKernelVersion= in
136 systemd.unit(5) for details. When prefixed with an exclamation mark
137 ("!"), the result is negated. If an empty string is assigned, then
138 previously assigned value is cleared.
139 Architecture=
141 Checks whether the system is running on a specific architecture.
142 See ConditionArchitecture= in systemd.unit(5) for details. When
143 prefixed with an exclamation mark ("!"), the result is negated. If
144 an empty string is assigned, then previously assigned value is
145 cleared.
146
148 The [Link] section accepts the following keys:
149 Description=
151 A description of the device.
152 Alias=
154 The ifalias interface property is set to this value.
155 MACAddressPolicy=
157 The policy by which the MAC address should be set. The available
158 policies are:
159 persistent
161 If the hardware has a persistent MAC address, as most hardware
162 should, and if it is used by the kernel, nothing is done.
163 Otherwise, a new MAC address is generated which is guaranteed
164 to be the same on every boot for the given machine and the
165 given device, but which is otherwise random. This feature
166 depends on ID_NET_NAME_* properties to exist for the link. On
167 hardware where these properties are not set, the generation of
168 a persistent MAC address will fail.
169 random
171 If the kernel is using a random MAC address, nothing is done.
172 Otherwise, a new address is randomly generated each time the
173 device appears, typically at boot. Either way, the random
174 address will have the "unicast" and "locally administered" bits
175 set.
176 none
178 Keeps the MAC address assigned by the kernel.
179 MACAddress=
181 The MAC address to use, if no MACAddressPolicy= is specified.
182 NamePolicy=
184 An ordered, space-separated list of policies by which the interface
185 name should be set. NamePolicy= may be disabled by specifying
186 net.ifnames=0 on the kernel command line. Each of the policies may
187 fail, and the first successful one is used. The name is not set
188 directly, but is exported to udev as the property ID_NET_NAME,
189 which is, by default, used by a udev(7), rule to set NAME. The
190 available policies are:
191 kernel
193 If the kernel claims that the name it has set for a device is
194 predictable, then no renaming is performed.
195 database
197 The name is set based on entries in the udev's Hardware
198 Database with the key ID_NET_NAME_FROM_DATABASE.
199 onboard
201 The name is set based on information given by the firmware for
202 on-board devices, as exported by the udev property
203 ID_NET_NAME_ONBOARD. See systemd.net-naming-scheme(7).
204 slot
206 The name is set based on information given by the firmware for
207 hot-plug devices, as exported by the udev property
208 ID_NET_NAME_SLOT. See systemd.net-naming-scheme(7).
209 path
211 The name is set based on the device's physical location, as
212 exported by the udev property ID_NET_NAME_PATH. See
213 systemd.net-naming-scheme(7).
214 mac
216 The name is set based on the device's persistent MAC address,
217 as exported by the udev property ID_NET_NAME_MAC. See
218 systemd.net-naming-scheme(7).
219 keep
221 If the device already had a name given by userspace (as part of
222 creation of the device or a rename), keep it.
223 Name=
225 The interface name to use. This option has lower precedence than
226 NamePolicy=, so for this setting to take effect, NamePolicy= must
227 either be unset, empty, disabled, or all policies configured there
228 must fail. Also see the example below with "Name=dmz0".
229 Note that specifying a name that the kernel might use for another
231 interface (for example "eth0") is dangerous because the name
232 assignment done by udev will race with the assignment done by the
233 kernel, and only one interface may use the name. Depending on the
234 order of operations, either udev or the kernel will win, making the
235 naming unpredictable. It is best to use some different prefix, for
236 example "internal0"/"external0" or "lan0"/"lan1"/"lan3".
237 AlternativeNamesPolicy=
239 A space-separated list of policies by which the interface's
240 alternative names should be set. Each of the policies may fail, and
241 all successful policies are used. The available policies are
242 "database", "onboard", "slot", "path", and "mac". If the kernel
243 does not support the alternative names, then this setting will be
244 ignored.
245 AlternativeName=
247 The alternative interface name to use. This option can be specified
248 multiple times. If the empty string is assigned to this option, the
249 list is reset, and all prior assignments have no effect. If the
250 kernel does not support the alternative names, then this setting
251 will be ignored.
252 MTUBytes=
254 The maximum transmission unit in bytes to set for the device. The
255 usual suffixes K, M, G, are supported and are understood to the
256 base of 1024.
257 BitsPerSecond=
259 The speed to set for the device, the value is rounded down to the
260 nearest Mbps. The usual suffixes K, M, G, are supported and are
261 understood to the base of 1000.
262 Duplex=
264 The duplex mode to set for the device. The accepted values are half
265 and full.
266 AutoNegotiation=
268 Takes a boolean. If set to yes, automatic negotiation of
269 transmission parameters is enabled. Autonegotiation is a procedure
270 by which two connected ethernet devices choose common transmission
271 parameters, such as speed, duplex mode, and flow control. When
272 unset, the kernel's default will be used.
273 Note that if autonegotiation is enabled, speed and duplex settings
275 are read-only. If autonegotiation is disabled, speed and duplex
276 settings are writable if the driver supports multiple link modes.
277 WakeOnLan=
279 The Wake-on-LAN policy to set for the device. The supported values
280 are:
281 phy
283 Wake on PHY activity.
284 unicast
286 Wake on unicast messages.
287 multicast
289 Wake on multicast messages.
290 broadcast
292 Wake on broadcast messages.
293 arp
295 Wake on ARP.
296 magic
298 Wake on receipt of a magic packet.
299 secureon
301 Enable secureon(tm) password for MagicPacket(tm).
302 off
304 Never wake.
305 Defaults to off.
307 Port=
309 The port option is used to select the device port. The supported
310 values are:
311 tp
313 An Ethernet interface using Twisted-Pair cable as the medium.
314 aui
316 Attachment Unit Interface (AUI). Normally used with hubs.
317 bnc
319 An Ethernet interface using BNC connectors and co-axial cable.
320 mii
322 An Ethernet interface using a Media Independent Interface
323 (MII).
324 fibre
326 An Ethernet interface using Optical Fibre as the medium.
327 Advertise=
329 This sets what speeds and duplex modes of operation are advertised
330 for auto-negotiation. This implies "AutoNegotiation=yes". The
331 supported values are:
332 Table 1. Supported advertise values
334 ┌───────────────────┬──────────────┬─────────────┐
335 │Advertise │ Speed (Mbps) │ Duplex Mode │
336 ├───────────────────┼──────────────┼─────────────┤
337 │10baset-half │ 10 │ half │
338 ├───────────────────┼──────────────┼─────────────┤
339 │10baset-full │ 10 │ full │
340 ├───────────────────┼──────────────┼─────────────┤
341 │100baset-half │ 100 │ half │
342 ├───────────────────┼──────────────┼─────────────┤
343 │100baset-full │ 100 │ full │
344 ├───────────────────┼──────────────┼─────────────┤
345 │1000baset-half │ 1000 │ half │
346 ├───────────────────┼──────────────┼─────────────┤
347 │1000baset-full │ 1000 │ full │
348 ├───────────────────┼──────────────┼─────────────┤
349 │10000baset-full │ 10000 │ full │
350 ├───────────────────┼──────────────┼─────────────┤
351 │2500basex-full │ 2500 │ full │
352 ├───────────────────┼──────────────┼─────────────┤
353 │1000basekx-full │ 1000 │ full │
354 ├───────────────────┼──────────────┼─────────────┤
355 │10000basekx4-full │ 10000 │ full │
356 ├───────────────────┼──────────────┼─────────────┤
357 │10000basekr-full │ 10000 │ full │
358 ├───────────────────┼──────────────┼─────────────┤
359 │10000baser-fec │ 10000 │ full │
360 ├───────────────────┼──────────────┼─────────────┤
361 │20000basemld2-full │ 20000 │ full │
362 ├───────────────────┼──────────────┼─────────────┤
363 │20000basekr2-full │ 20000 │ full │
364 └───────────────────┴──────────────┴─────────────┘
365 By default this is unset, i.e. all possible modes will be
366 advertised. This option may be specified more than once, in which
367 case all specified speeds and modes are advertised. If the empty
368 string is assigned to this option, the list is reset, and all prior
369 assignments have no effect.
370 ReceiveChecksumOffload=
372 Takes a boolean. If set to true, the hardware offload for
373 checksumming of ingress network packets is enabled. When unset, the
374 kernel's default will be used.
375 TransmitChecksumOffload=
377 Takes a boolean. If set to true, the hardware offload for
378 checksumming of egress network packets is enabled. When unset, the
379 kernel's default will be used.
380 TCPSegmentationOffload=
382 Takes a boolean. If set to true, the TCP Segmentation Offload (TSO)
383 is enabled. When unset, the kernel's default will be used.
384 TCP6SegmentationOffload=
386 Takes a boolean. If set to true, the TCP6 Segmentation Offload
387 (tx-tcp6-segmentation) is enabled. When unset, the kernel's default
388 will be used.
389 GenericSegmentationOffload=
391 Takes a boolean. If set to true, the Generic Segmentation Offload
392 (GSO) is enabled. When unset, the kernel's default will be used.
393 GenericReceiveOffload=
395 Takes a boolean. If set to true, the Generic Receive Offload (GRO)
396 is enabled. When unset, the kernel's default will be used.
397 LargeReceiveOffload=
399 Takes a boolean. If set to true, the Large Receive Offload (LRO) is
400 enabled. When unset, the kernel's default will be used.
401 RxChannels=
403 Sets the number of receive channels (a number between 1 and
404 4294967295) .
405 TxChannels=
407 Sets the number of transmit channels (a number between 1 and
408 4294967295).
409 OtherChannels=
411 Sets the number of other channels (a number between 1 and
412 4294967295).
413 CombinedChannels=
415 Sets the number of combined set channels (a number between 1 and
416 4294967295).
417 RxBufferSize=
419 Takes a integer. Specifies the NIC receive ring buffer size. When
420 unset, the kernel's default will be used.
421 TxBufferSize=
423 Takes a integer. Specifies the NIC transmit ring buffer size. When
424 unset, the kernel's default will be used.
425
427 Example 1. /usr/lib/systemd/network/99-default.link
428 The link file 99-default.link that is shipped with systemd defines the
430 default naming policy for links.
431 [Link]
433 NamePolicy=kernel database onboard slot path
434 MACAddressPolicy=persistent
435 Example 2. /etc/systemd/network/10-dmz.link
437 This example assigns the fixed name "dmz0" to the interface with the
439 MAC address 00:a0:de:63:7a:e6:
440 [Match]
442 MACAddress=00:a0:de:63:7a:e6
443 [Link]
445 Name=dmz0
446 NamePolicy= is not set, so Name= takes effect. We use the "10-" prefix
448 to order this file early in the list. Note that it needs to be before
449 "99-link", i.e. it needs a numerical prefix, to have any effect at all.
450 Example 3. Debugging NamePolicy= assignments
452 $ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
454 ...
455 Parsed configuration file /usr/lib/systemd/network/99-default.link
456 Parsed configuration file /etc/systemd/network/10-eth0.link
457 ID_NET_DRIVER=cdc_ether
458 Config file /etc/systemd/network/10-eth0.link applies to device hub0
459 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
460 hub0: Device has name_assign_type=4
461 Using default interface naming scheme 'v240'.
462 hub0: Policies didn't yield a name, using specified Name=hub0.
463 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
464 ID_NET_NAME=hub0
465 ...
466 Explicit Name= configuration wins in this case.
468 sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
470 ...
471 Parsed configuration file /usr/lib/systemd/network/99-default.link
472 Parsed configuration file /etc/systemd/network/10-eth0.link
473 Created link configuration context.
474 ID_NET_DRIVER=e1000e
475 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
476 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
477 enp0s31f6: Device has name_assign_type=4
478 Using default interface naming scheme 'v240'.
479 enp0s31f6: Policy *keep*: keeping existing userspace name
480 enp0s31f6: Device has addr_assign_type=0
481 enp0s31f6: MAC on the device already matches policy *persistent*
482 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
483 ...
484 In this case, the interface was already renamed, so the keep policy
486 specified as the first option in 99-default.link means that the
487 existing name is preserved. If keep was removed, or if were in boot
488 before the renaming has happened, we might get the following instead:
489 enp0s31f6: Policy *path* yields "enp0s31f6".
491 enp0s31f6: Device has addr_assign_type=0
492 enp0s31f6: MAC on the device already matches policy *persistent*
493 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
494 ID_NET_NAME=enp0s31f6
495 ...
496 Please note that the details of output are subject to change.
498 Example 4. /etc/systemd/network/10-internet.link
500 This example assigns the fixed name "internet0" to the interface with
502 the device path "pci-0000:00:1a.0-*":
503 [Match]
505 Path=pci-0000:00:1a.0-*
506 [Link]
508 Name=internet0
509 Example 5. /etc/systemd/network/25-wireless.link
511 Here's an overly complex example that shows the use of a large number
513 of [Match] and [Link] settings.
514 [Match]
516 MACAddress=12:34:56:78:9a:bc
517 Driver=brcmsmac
518 Path=pci-0000:02:00.0-*
519 Type=wlan
520 Virtualization=no
521 Host=my-laptop
522 Architecture=x86-64
523 [Link]
525 Name=wireless0
526 MTUBytes=1450
527 BitsPerSecond=10M
528 WakeOnLan=magic
529 MACAddress=cb:a9:87:65:43:21
530
532 systemd-udevd.service(8), udevadm(8), systemd.netdev(5),
533 systemd.network(5)
534systemd 245 SYSTEMD.LINK(5)