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-udevd(8) and in particular its
14 net_setup_link builtin. See systemd.syntax(7) 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 Along with the link file foo.link, a "drop-in" directory foo.link.d/
32 may exist. All files with the suffix ".conf" from this directory will
33 be parsed after the file itself is parsed. This is useful to alter or
34 add configuration settings, without having to modify the main
35 configuration file. Each drop-in file must have appropriate section
36 headers.
37 In addition to /etc/systemd/network, drop-in ".d" directories can be
39 placed in /usr/lib/systemd/network or /run/systemd/network directories.
40 Drop-in files in /etc/ take precedence over those in /run/ which in
41 turn take precedence over those in /usr/lib/. Drop-in files under any
42 of these directories take precedence over the main link file wherever
43 located.
44 The link file contains a [Match] section, which determines if a given
46 link file may be applied to a given device, as well as a [Link] section
47 specifying how the device should be configured. The first (in lexical
48 order) of the link files that matches a given device is applied. Note
49 that a default file 99-default.link is shipped by the system. Any
50 user-supplied .link should hence have a lexically earlier name to be
51 considered at all.
52 See udevadm(8) for diagnosing problems with .link files.
54
56 A link file is said to match a device if all matches specified by the
57 [Match] section are satisfied. When a link file does not contain valid
58 settings in [Match] section, then the file will match all devices and
59 systemd-udevd warns about that. Hint: to avoid the warning and to make
60 it clear that all interfaces shall be matched, add the following:
61 OriginalName=*
63 The following keys are accepted:
65 MACAddress=
67 A whitespace-separated list of hardware addresses. Use full colon-,
68 hyphen- or dot-delimited hexadecimal. See the example below. This
69 option may appear more than once, in which case the lists are
70 merged. If the empty string is assigned to this option, the list of
71 hardware addresses defined prior to this is reset.
72 Example:
74 MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF
76 PermanentMACAddress=
78 A whitespace-separated list of hardware's permanent addresses.
79 While MACAddress= matches the device's current MAC address, this
80 matches the device's permanent MAC address, which may be different
81 from the current one. Use full colon-, hyphen- or dot-delimited
82 hexadecimal. This option may appear more than once, in which case
83 the lists are merged. If the empty string is assigned to this
84 option, the list of hardware addresses defined prior to this is
85 reset.
86 Path=
88 A whitespace-separated list of shell-style globs matching the
89 persistent path, as exposed by the udev property ID_PATH.
90 Driver=
92 A whitespace-separated list of shell-style globs matching the
93 driver currently bound to the device, as exposed by the udev
94 property ID_NET_DRIVER of its parent device, or if that is not set,
95 the driver as exposed by ethtool -i of the device itself. If the
96 list is prefixed with a "!", the test is inverted.
97 Type=
99 A whitespace-separated list of shell-style globs matching the
100 device type, as exposed by networkctl list. If the list is prefixed
101 with a "!", the test is inverted. Some valid values are "ether",
102 "loopback", "wlan", "wwan". Valid types are named either from the
103 udev "DEVTYPE" attribute, or "ARPHRD_" macros in linux/if_arp.h, so
104 this is not comprehensive.
105 Property=
107 A whitespace-separated list of udev property name with its value
108 after a equal ("="). If multiple properties are specified, the test
109 results are ANDed. If the list is prefixed with a "!", the test is
110 inverted. If a value contains white spaces, then please quote whole
111 key and value pair. If a value contains quotation, then please
112 escape the quotation with "\".
113 Example: if a .link file has the following:
115 Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""
117 then, the .link file matches only when an interface has all the
119 above three properties.
120 OriginalName=
122 A whitespace-separated list of shell-style globs matching the
123 device name, as exposed by the udev property "INTERFACE". This
124 cannot be used to match on names that have already been changed
125 from userspace. Caution is advised when matching on kernel-assigned
126 names, as they are known to be unstable between reboots.
127 Host=
129 Matches against the hostname or machine ID of the host. See
130 ConditionHost= in systemd.unit(5) for details. When prefixed with
131 an exclamation mark ("!"), the result is negated. If an empty
132 string is assigned, then previously assigned value is cleared.
133 Virtualization=
135 Checks whether the system is executed in a virtualized environment
136 and optionally test whether it is a specific implementation. See
137 ConditionVirtualization= in systemd.unit(5) for details. When
138 prefixed with an exclamation mark ("!"), the result is negated. If
139 an empty string is assigned, then previously assigned value is
140 cleared.
141 KernelCommandLine=
143 Checks whether a specific kernel command line option is set. See
144 ConditionKernelCommandLine= in systemd.unit(5) for details. When
145 prefixed with an exclamation mark ("!"), the result is negated. If
146 an empty string is assigned, then previously assigned value is
147 cleared.
148 KernelVersion=
150 Checks whether the kernel version (as reported by uname -r) matches
151 a certain expression. See ConditionKernelVersion= in
152 systemd.unit(5) for details. When prefixed with an exclamation mark
153 ("!"), the result is negated. If an empty string is assigned, then
154 previously assigned value is cleared.
155 Architecture=
157 Checks whether the system is running on a specific architecture.
158 See ConditionArchitecture= in systemd.unit(5) for details. When
159 prefixed with an exclamation mark ("!"), the result is negated. If
160 an empty string is assigned, then previously assigned value is
161 cleared.
162
164 The [Link] section accepts the following keys:
165 Description=
167 A description of the device.
168 Alias=
170 The ifalias interface property is set to this value.
171 MACAddressPolicy=
173 The policy by which the MAC address should be set. The available
174 policies are:
175 persistent
177 If the hardware has a persistent MAC address, as most hardware
178 should, and if it is used by the kernel, nothing is done.
179 Otherwise, a new MAC address is generated which is guaranteed
180 to be the same on every boot for the given machine and the
181 given device, but which is otherwise random. This feature
182 depends on ID_NET_NAME_* properties to exist for the link. On
183 hardware where these properties are not set, the generation of
184 a persistent MAC address will fail.
185 random
187 If the kernel is using a random MAC address, nothing is done.
188 Otherwise, a new address is randomly generated each time the
189 device appears, typically at boot. Either way, the random
190 address will have the "unicast" and "locally administered" bits
191 set.
192 none
194 Keeps the MAC address assigned by the kernel. Or use the MAC
195 address specified in MACAddress=.
196 An empty string assignment is equivalent to setting "none".
198 MACAddress=
200 The interface MAC address to use. For this setting to take effect,
201 MACAddressPolicy= must either be unset, empty, or "none".
202 NamePolicy=
204 An ordered, space-separated list of policies by which the interface
205 name should be set. NamePolicy= may be disabled by specifying
206 net.ifnames=0 on the kernel command line. Each of the policies may
207 fail, and the first successful one is used. The name is not set
208 directly, but is exported to udev as the property ID_NET_NAME,
209 which is, by default, used by a udev(7), rule to set NAME. The
210 available policies are:
211 kernel
213 If the kernel claims that the name it has set for a device is
214 predictable, then no renaming is performed.
215 database
217 The name is set based on entries in the udev's Hardware
218 Database with the key ID_NET_NAME_FROM_DATABASE.
219 onboard
221 The name is set based on information given by the firmware for
222 on-board devices, as exported by the udev property
223 ID_NET_NAME_ONBOARD. See systemd.net-naming-scheme(7).
224 slot
226 The name is set based on information given by the firmware for
227 hot-plug devices, as exported by the udev property
228 ID_NET_NAME_SLOT. See systemd.net-naming-scheme(7).
229 path
231 The name is set based on the device's physical location, as
232 exported by the udev property ID_NET_NAME_PATH. See
233 systemd.net-naming-scheme(7).
234 mac
236 The name is set based on the device's persistent MAC address,
237 as exported by the udev property ID_NET_NAME_MAC. See
238 systemd.net-naming-scheme(7).
239 keep
241 If the device already had a name given by userspace (as part of
242 creation of the device or a rename), keep it.
243 Name=
245 The interface name to use. This option has lower precedence than
246 NamePolicy=, so for this setting to take effect, NamePolicy= must
247 either be unset, empty, disabled, or all policies configured there
248 must fail. Also see the example below with "Name=dmz0".
249 Note that specifying a name that the kernel might use for another
251 interface (for example "eth0") is dangerous because the name
252 assignment done by udev will race with the assignment done by the
253 kernel, and only one interface may use the name. Depending on the
254 order of operations, either udev or the kernel will win, making the
255 naming unpredictable. It is best to use some different prefix, for
256 example "internal0"/"external0" or "lan0"/"lan1"/"lan3".
257 AlternativeNamesPolicy=
259 A space-separated list of policies by which the interface's
260 alternative names should be set. Each of the policies may fail, and
261 all successful policies are used. The available policies are
262 "database", "onboard", "slot", "path", and "mac". If the kernel
263 does not support the alternative names, then this setting will be
264 ignored.
265 AlternativeName=
267 The alternative interface name to use. This option can be specified
268 multiple times. If the empty string is assigned to this option, the
269 list is reset, and all prior assignments have no effect. If the
270 kernel does not support the alternative names, then this setting
271 will be ignored.
272 TransmitQueues=
274 Specifies the device's number of transmit queues. An integer in the
275 range 1...4096. When unset, the kernel's default will be used.
276 ReceiveQueues=
278 Specifies the device's number of receive queues. An integer in the
279 range 1...4096. When unset, the kernel's default will be used.
280 TransmitQueueLength=
282 Specifies the transmit queue length of the device in number of
283 packets. An unsigned integer in the range 0...4294967294. When
284 unset, the kernel's default will be used.
285 MTUBytes=
287 The maximum transmission unit in bytes to set for the device. The
288 usual suffixes K, M, G, are supported and are understood to the
289 base of 1024.
290 BitsPerSecond=
292 The speed to set for the device, the value is rounded down to the
293 nearest Mbps. The usual suffixes K, M, G, are supported and are
294 understood to the base of 1000.
295 Duplex=
297 The duplex mode to set for the device. The accepted values are half
298 and full.
299 AutoNegotiation=
301 Takes a boolean. If set to yes, automatic negotiation of
302 transmission parameters is enabled. Autonegotiation is a procedure
303 by which two connected ethernet devices choose common transmission
304 parameters, such as speed, duplex mode, and flow control. When
305 unset, the kernel's default will be used.
306 Note that if autonegotiation is enabled, speed and duplex settings
308 are read-only. If autonegotiation is disabled, speed and duplex
309 settings are writable if the driver supports multiple link modes.
310 WakeOnLan=
312 The Wake-on-LAN policy to set for the device. The supported values
313 are:
314 phy
316 Wake on PHY activity.
317 unicast
319 Wake on unicast messages.
320 multicast
322 Wake on multicast messages.
323 broadcast
325 Wake on broadcast messages.
326 arp
328 Wake on ARP.
329 magic
331 Wake on receipt of a magic packet.
332 secureon
334 Enable secureon(tm) password for MagicPacket(tm).
335 off
337 Never wake.
338 Defaults to off.
340 Port=
342 The port option is used to select the device port. The supported
343 values are:
344 tp
346 An Ethernet interface using Twisted-Pair cable as the medium.
347 aui
349 Attachment Unit Interface (AUI). Normally used with hubs.
350 bnc
352 An Ethernet interface using BNC connectors and co-axial cable.
353 mii
355 An Ethernet interface using a Media Independent Interface
356 (MII).
357 fibre
359 An Ethernet interface using Optical Fibre as the medium.
360 Advertise=
362 This sets what speeds and duplex modes of operation are advertised
363 for auto-negotiation. This implies "AutoNegotiation=yes". The
364 supported values are:
365 Table 1. Supported advertise values
367 ┌───────────────────┬──────────────┬─────────────┐
368 │Advertise │ Speed (Mbps) │ Duplex Mode │
369 ├───────────────────┼──────────────┼─────────────┤
370 │10baset-half │ 10 │ half │
371 ├───────────────────┼──────────────┼─────────────┤
372 │10baset-full │ 10 │ full │
373 ├───────────────────┼──────────────┼─────────────┤
374 │100baset-half │ 100 │ half │
375 ├───────────────────┼──────────────┼─────────────┤
376 │100baset-full │ 100 │ full │
377 ├───────────────────┼──────────────┼─────────────┤
378 │1000baset-half │ 1000 │ half │
379 ├───────────────────┼──────────────┼─────────────┤
380 │1000baset-full │ 1000 │ full │
381 ├───────────────────┼──────────────┼─────────────┤
382 │10000baset-full │ 10000 │ full │
383 ├───────────────────┼──────────────┼─────────────┤
384 │2500basex-full │ 2500 │ full │
385 ├───────────────────┼──────────────┼─────────────┤
386 │1000basekx-full │ 1000 │ full │
387 ├───────────────────┼──────────────┼─────────────┤
388 │10000basekx4-full │ 10000 │ full │
389 ├───────────────────┼──────────────┼─────────────┤
390 │10000basekr-full │ 10000 │ full │
391 ├───────────────────┼──────────────┼─────────────┤
392 │10000baser-fec │ 10000 │ full │
393 ├───────────────────┼──────────────┼─────────────┤
394 │20000basemld2-full │ 20000 │ full │
395 ├───────────────────┼──────────────┼─────────────┤
396 │20000basekr2-full │ 20000 │ full │
397 └───────────────────┴──────────────┴─────────────┘
398 By default this is unset, i.e. all possible modes will be
399 advertised. This option may be specified more than once, in which
400 case all specified speeds and modes are advertised. If the empty
401 string is assigned to this option, the list is reset, and all prior
402 assignments have no effect.
403 ReceiveChecksumOffload=
405 Takes a boolean. If set to true, the hardware offload for
406 checksumming of ingress network packets is enabled. When unset, the
407 kernel's default will be used.
408 TransmitChecksumOffload=
410 Takes a boolean. If set to true, the hardware offload for
411 checksumming of egress network packets is enabled. When unset, the
412 kernel's default will be used.
413 TCPSegmentationOffload=
415 Takes a boolean. If set to true, the TCP Segmentation Offload (TSO)
416 is enabled. When unset, the kernel's default will be used.
417 TCP6SegmentationOffload=
419 Takes a boolean. If set to true, the TCP6 Segmentation Offload
420 (tx-tcp6-segmentation) is enabled. When unset, the kernel's default
421 will be used.
422 GenericSegmentationOffload=
424 Takes a boolean. If set to true, the Generic Segmentation Offload
425 (GSO) is enabled. When unset, the kernel's default will be used.
426 GenericReceiveOffload=
428 Takes a boolean. If set to true, the Generic Receive Offload (GRO)
429 is enabled. When unset, the kernel's default will be used.
430 LargeReceiveOffload=
432 Takes a boolean. If set to true, the Large Receive Offload (LRO) is
433 enabled. When unset, the kernel's default will be used.
434 RxChannels=
436 Sets the number of receive channels (a number between 1 and
437 4294967295) .
438 TxChannels=
440 Sets the number of transmit channels (a number between 1 and
441 4294967295).
442 OtherChannels=
444 Sets the number of other channels (a number between 1 and
445 4294967295).
446 CombinedChannels=
448 Sets the number of combined set channels (a number between 1 and
449 4294967295).
450 RxBufferSize=
452 Takes an integer. Specifies the maximum number of pending packets
453 in the NIC receive buffer. When unset, the kernel's default will be
454 used.
455 RxMiniBufferSize=
457 Takes an integer. Specifies the maximum number of pending packets
458 in the NIC mini receive buffer. When unset, the kernel's default
459 will be used.
460 RxJumboBufferSize=
462 Takes an integer. Specifies the maximum number of pending packets
463 in the NIC jumbo receive buffer. When unset, the kernel's default
464 will be used.
465 TxBufferSize=
467 Takes an integer. Specifies the maximum number of pending packets
468 in the NIC transmit buffer. When unset, the kernel's default will
469 be used.
470 RxFlowControl=
472 Takes a boolean. When set, enables the receive flow control, also
473 known as the ethernet receive PAUSE message (generate and send
474 ethernet PAUSE frames). When unset, the kernel's default will be
475 used.
476 TxFlowControl=
478 Takes a boolean. When set, enables the transmit flow control, also
479 known as the ethernet transmit PAUSE message (respond to received
480 ethernet PAUSE frames). When unset, the kernel's default will be
481 used.
482 AutoNegotiationFlowControl=
484 Takes a boolean. When set, the auto negotiation enables the
485 interface to exchange state advertisements with the connected peer
486 so that the two devices can agree on the ethernet PAUSE
487 configuration. When unset, the kernel's default will be used.
488 GenericSegmentOffloadMaxBytes=
490 Specifies the maximum size of a Generic Segment Offload (GSO)
491 packet the device should accept. The usual suffixes K, M, G, are
492 supported and are understood to the base of 1024. An unsigned
493 integer in the range 1...65536. Defaults to unset.
494 GenericSegmentOffloadMaxSegments=
496 Specifies the maximum number of a Generic Segment Offload (GSO)
497 segments the device should accept. An unsigned integer in the range
498 1...65535. Defaults to unset.
499
501 Example 1. /usr/lib/systemd/network/99-default.link
502 The link file 99-default.link that is shipped with systemd defines the
504 default naming policy for links.
505 [Link]
507 NamePolicy=kernel database onboard slot path
508 MACAddressPolicy=persistent
509 Example 2. /etc/systemd/network/10-dmz.link
511 This example assigns the fixed name "dmz0" to the interface with the
513 MAC address 00:a0:de:63:7a:e6:
514 [Match]
516 MACAddress=00:a0:de:63:7a:e6
517 [Link]
519 Name=dmz0
520 NamePolicy= is not set, so Name= takes effect. We use the "10-" prefix
522 to order this file early in the list. Note that it needs to be before
523 "99-link", i.e. it needs a numerical prefix, to have any effect at all.
524 Example 3. Debugging NamePolicy= assignments
526 $ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
528 ...
529 Parsed configuration file /usr/lib/systemd/network/99-default.link
530 Parsed configuration file /etc/systemd/network/10-eth0.link
531 ID_NET_DRIVER=cdc_ether
532 Config file /etc/systemd/network/10-eth0.link applies to device hub0
533 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
534 hub0: Device has name_assign_type=4
535 Using default interface naming scheme 'v240'.
536 hub0: Policies didn't yield a name, using specified Name=hub0.
537 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
538 ID_NET_NAME=hub0
539 ...
540 Explicit Name= configuration wins in this case.
542 sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
544 ...
545 Parsed configuration file /usr/lib/systemd/network/99-default.link
546 Parsed configuration file /etc/systemd/network/10-eth0.link
547 Created link configuration context.
548 ID_NET_DRIVER=e1000e
549 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
550 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
551 enp0s31f6: Device has name_assign_type=4
552 Using default interface naming scheme 'v240'.
553 enp0s31f6: Policy *keep*: keeping existing userspace name
554 enp0s31f6: Device has addr_assign_type=0
555 enp0s31f6: MAC on the device already matches policy *persistent*
556 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
557 ...
558 In this case, the interface was already renamed, so the keep policy
560 specified as the first option in 99-default.link means that the
561 existing name is preserved. If keep was removed, or if were in boot
562 before the renaming has happened, we might get the following instead:
563 enp0s31f6: Policy *path* yields "enp0s31f6".
565 enp0s31f6: Device has addr_assign_type=0
566 enp0s31f6: MAC on the device already matches policy *persistent*
567 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
568 ID_NET_NAME=enp0s31f6
569 ...
570 Please note that the details of output are subject to change.
572 Example 4. /etc/systemd/network/10-internet.link
574 This example assigns the fixed name "internet0" to the interface with
576 the device path "pci-0000:00:1a.0-*":
577 [Match]
579 Path=pci-0000:00:1a.0-*
580 [Link]
582 Name=internet0
583 Example 5. /etc/systemd/network/25-wireless.link
585 Here's an overly complex example that shows the use of a large number
587 of [Match] and [Link] settings.
588 [Match]
590 MACAddress=12:34:56:78:9a:bc
591 Driver=brcmsmac
592 Path=pci-0000:02:00.0-*
593 Type=wlan
594 Virtualization=no
595 Host=my-laptop
596 Architecture=x86-64
597 [Link]
599 Name=wireless0
600 MTUBytes=1450
601 BitsPerSecond=10M
602 WakeOnLan=magic
603 MACAddress=cb:a9:87:65:43:21
604
606 systemd-udevd.service(8), udevadm(8), systemd.netdev(5),
607 systemd.network(5)
608systemd 248 SYSTEMD.LINK(5)