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 merged in the alphanumeric order and parsed after the main file
34 itself has been parsed. This is useful to alter or add configuration
35 settings, without having to modify the main configuration file. Each
36 drop-in file must have appropriate section 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 names with their
108 values after equals sign ("="). If multiple properties are
109 specified, the test results are ANDed. If the list is prefixed with
110 a "!", the test is inverted. If a value contains white spaces, then
111 please quote whole key and value pair. If a value contains
112 quotation, then please 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 Firmware=
164 Checks whether the system is running on a machine with the
165 specified firmware. See ConditionFirmware= in systemd.unit(5) for
166 details. When prefixed with an exclamation mark ("!"), the result
167 is negated. If an empty string is assigned, then previously
168 assigned value is cleared.
169
171 The [Link] section accepts the following keys:
172 Description=
174 A description of the device.
175 Alias=
177 The ifalias interface property is set to this value.
178 MACAddressPolicy=
180 The policy by which the MAC address should be set. The available
181 policies are:
182 persistent
184 If the hardware has a persistent MAC address, as most hardware
185 should, and if it is used by the kernel, nothing is done.
186 Otherwise, a new MAC address is generated which is guaranteed
187 to be the same on every boot for the given machine and the
188 given device, but which is otherwise random. This feature
189 depends on ID_NET_NAME_* properties to exist for the link. On
190 hardware where these properties are not set, the generation of
191 a persistent MAC address will fail.
192 random
194 If the kernel is using a random MAC address, nothing is done.
195 Otherwise, a new address is randomly generated each time the
196 device appears, typically at boot. Either way, the random
197 address will have the "unicast" and "locally administered" bits
198 set.
199 none
201 Keeps the MAC address assigned by the kernel. Or use the MAC
202 address specified in MACAddress=.
203 An empty string assignment is equivalent to setting "none".
205 MACAddress=
207 The interface MAC address to use. For this setting to take effect,
208 MACAddressPolicy= must either be unset, empty, or "none".
209 NamePolicy=
211 An ordered, space-separated list of policies by which the interface
212 name should be set. NamePolicy= may be disabled by specifying
213 net.ifnames=0 on the kernel command line. Each of the policies may
214 fail, and the first successful one is used. The name is not set
215 directly, but is exported to udev as the property ID_NET_NAME,
216 which is, by default, used by a udev(7), rule to set NAME. The
217 available policies are:
218 kernel
220 If the kernel claims that the name it has set for a device is
221 predictable, then no renaming is performed.
222 database
224 The name is set based on entries in the udev's Hardware
225 Database with the key ID_NET_NAME_FROM_DATABASE.
226 onboard
228 The name is set based on information given by the firmware for
229 on-board devices, as exported by the udev property
230 ID_NET_NAME_ONBOARD. See systemd.net-naming-scheme(7).
231 slot
233 The name is set based on information given by the firmware for
234 hot-plug devices, as exported by the udev property
235 ID_NET_NAME_SLOT. See systemd.net-naming-scheme(7).
236 path
238 The name is set based on the device's physical location, as
239 exported by the udev property ID_NET_NAME_PATH. See
240 systemd.net-naming-scheme(7).
241 mac
243 The name is set based on the device's persistent MAC address,
244 as exported by the udev property ID_NET_NAME_MAC. See
245 systemd.net-naming-scheme(7).
246 keep
248 If the device already had a name given by userspace (as part of
249 creation of the device or a rename), keep it.
250 Name=
252 The interface name to use. This option has lower precedence than
253 NamePolicy=, so for this setting to take effect, NamePolicy= must
254 either be unset, empty, disabled, or all policies configured there
255 must fail. Also see the example below with "Name=dmz0".
256 Note that specifying a name that the kernel might use for another
258 interface (for example "eth0") is dangerous because the name
259 assignment done by udev will race with the assignment done by the
260 kernel, and only one interface may use the name. Depending on the
261 order of operations, either udev or the kernel will win, making the
262 naming unpredictable. It is best to use some different prefix, for
263 example "internal0"/"external0" or "lan0"/"lan1"/"lan3".
264 AlternativeNamesPolicy=
266 A space-separated list of policies by which the interface's
267 alternative names should be set. Each of the policies may fail, and
268 all successful policies are used. The available policies are
269 "database", "onboard", "slot", "path", and "mac". If the kernel
270 does not support the alternative names, then this setting will be
271 ignored.
272 AlternativeName=
274 The alternative interface name to use. This option can be specified
275 multiple times. If the empty string is assigned to this option, the
276 list is reset, and all prior assignments have no effect. If the
277 kernel does not support the alternative names, then this setting
278 will be ignored.
279 TransmitQueues=
281 Specifies the device's number of transmit queues. An integer in the
282 range 1...4096. When unset, the kernel's default will be used.
283 ReceiveQueues=
285 Specifies the device's number of receive queues. An integer in the
286 range 1...4096. When unset, the kernel's default will be used.
287 TransmitQueueLength=
289 Specifies the transmit queue length of the device in number of
290 packets. An unsigned integer in the range 0...4294967294. When
291 unset, the kernel's default will be used.
292 MTUBytes=
294 The maximum transmission unit in bytes to set for the device. The
295 usual suffixes K, M, G are supported and are understood to the base
296 of 1024.
297 BitsPerSecond=
299 The speed to set for the device, the value is rounded down to the
300 nearest Mbps. The usual suffixes K, M, G are supported and are
301 understood to the base of 1000.
302 Duplex=
304 The duplex mode to set for the device. The accepted values are half
305 and full.
306 AutoNegotiation=
308 Takes a boolean. If set to yes, automatic negotiation of
309 transmission parameters is enabled. Autonegotiation is a procedure
310 by which two connected ethernet devices choose common transmission
311 parameters, such as speed, duplex mode, and flow control. When
312 unset, the kernel's default will be used.
313 Note that if autonegotiation is enabled, speed and duplex settings
315 are read-only. If autonegotiation is disabled, speed and duplex
316 settings are writable if the driver supports multiple link modes.
317 WakeOnLan=
319 The Wake-on-LAN policy to set for the device. Takes the special
320 value "off" which disables Wake-on-LAN, or space separated list of
321 the following words:
322 phy
324 Wake on PHY activity.
325 unicast
327 Wake on unicast messages.
328 multicast
330 Wake on multicast messages.
331 broadcast
333 Wake on broadcast messages.
334 arp
336 Wake on ARP.
337 magic
339 Wake on receipt of a magic packet.
340 secureon
342 Enable secureon(tm) password for MagicPacket(tm).
343 Defaults to unset, and the device's default will be used. This
345 setting can be specified multiple times. If an empty string is
346 assigned, then the all previous assignments are cleared.
347 Port=
349 The port option is used to select the device port. The supported
350 values are:
351 tp
353 An Ethernet interface using Twisted-Pair cable as the medium.
354 aui
356 Attachment Unit Interface (AUI). Normally used with hubs.
357 bnc
359 An Ethernet interface using BNC connectors and co-axial cable.
360 mii
362 An Ethernet interface using a Media Independent Interface
363 (MII).
364 fibre
366 An Ethernet interface using Optical Fibre as the medium.
367 Advertise=
369 This sets what speeds and duplex modes of operation are advertised
370 for auto-negotiation. This implies "AutoNegotiation=yes". The
371 supported values are:
372 Table 1. Supported advertise values
374 ┌───────────────────┬──────────────┬─────────────┐
375 │Advertise │ Speed (Mbps) │ Duplex Mode │
376 ├───────────────────┼──────────────┼─────────────┤
377 │10baset-half │ 10 │ half │
378 ├───────────────────┼──────────────┼─────────────┤
379 │10baset-full │ 10 │ full │
380 ├───────────────────┼──────────────┼─────────────┤
381 │100baset-half │ 100 │ half │
382 ├───────────────────┼──────────────┼─────────────┤
383 │100baset-full │ 100 │ full │
384 ├───────────────────┼──────────────┼─────────────┤
385 │1000baset-half │ 1000 │ half │
386 ├───────────────────┼──────────────┼─────────────┤
387 │1000baset-full │ 1000 │ full │
388 ├───────────────────┼──────────────┼─────────────┤
389 │10000baset-full │ 10000 │ full │
390 ├───────────────────┼──────────────┼─────────────┤
391 │2500basex-full │ 2500 │ full │
392 ├───────────────────┼──────────────┼─────────────┤
393 │1000basekx-full │ 1000 │ full │
394 ├───────────────────┼──────────────┼─────────────┤
395 │10000basekx4-full │ 10000 │ full │
396 ├───────────────────┼──────────────┼─────────────┤
397 │10000basekr-full │ 10000 │ full │
398 ├───────────────────┼──────────────┼─────────────┤
399 │10000baser-fec │ 10000 │ full │
400 ├───────────────────┼──────────────┼─────────────┤
401 │20000basemld2-full │ 20000 │ full │
402 ├───────────────────┼──────────────┼─────────────┤
403 │20000basekr2-full │ 20000 │ full │
404 └───────────────────┴──────────────┴─────────────┘
405 By default this is unset, i.e. all possible modes will be
406 advertised. This option may be specified more than once, in which
407 case all specified speeds and modes are advertised. If the empty
408 string is assigned to this option, the list is reset, and all prior
409 assignments have no effect.
410 ReceiveChecksumOffload=
412 Takes a boolean. If set to true, hardware offload for checksumming
413 of ingress network packets is enabled. When unset, the kernel's
414 default will be used.
415 TransmitChecksumOffload=
417 Takes a boolean. If set to true, hardware offload for checksumming
418 of egress network packets is enabled. When unset, the kernel's
419 default will be used.
420 TCPSegmentationOffload=
422 Takes a boolean. If set to true, TCP Segmentation Offload (TSO) is
423 enabled. When unset, the kernel's default will be used.
424 TCP6SegmentationOffload=
426 Takes a boolean. If set to true, TCP6 Segmentation Offload
427 (tx-tcp6-segmentation) is enabled. When unset, the kernel's default
428 will be used.
429 GenericSegmentationOffload=
431 Takes a boolean. If set to true, Generic Segmentation Offload (GSO)
432 is enabled. When unset, the kernel's default will be used.
433 GenericReceiveOffload=
435 Takes a boolean. If set to true, Generic Receive Offload (GRO) is
436 enabled. When unset, the kernel's default will be used.
437 LargeReceiveOffload=
439 Takes a boolean. If set to true, Large Receive Offload (LRO) is
440 enabled. When unset, the kernel's default will be used.
441 RxChannels=
443 Sets the number of receive channels (a number between 1 and
444 4294967295) .
445 TxChannels=
447 Sets the number of transmit channels (a number between 1 and
448 4294967295).
449 OtherChannels=
451 Sets the number of other channels (a number between 1 and
452 4294967295).
453 CombinedChannels=
455 Sets the number of combined set channels (a number between 1 and
456 4294967295).
457 RxBufferSize=
459 Takes an integer. Specifies the maximum number of pending packets
460 in the NIC receive buffer. When unset, the kernel's default will be
461 used.
462 RxMiniBufferSize=
464 Takes an integer. Specifies the maximum number of pending packets
465 in the NIC mini receive buffer. When unset, the kernel's default
466 will be used.
467 RxJumboBufferSize=
469 Takes an integer. Specifies the maximum number of pending packets
470 in the NIC jumbo receive buffer. When unset, the kernel's default
471 will be used.
472 TxBufferSize=
474 Takes an integer. Specifies the maximum number of pending packets
475 in the NIC transmit buffer. When unset, the kernel's default will
476 be used.
477 RxFlowControl=
479 Takes a boolean. When set, enables receive flow control, also known
480 as the ethernet receive PAUSE message (generate and send ethernet
481 PAUSE frames). When unset, the kernel's default will be used.
482 TxFlowControl=
484 Takes a boolean. When set, enables transmit flow control, also
485 known as the ethernet transmit PAUSE message (respond to received
486 ethernet PAUSE frames). When unset, the kernel's default will be
487 used.
488 AutoNegotiationFlowControl=
490 Takes a boolean. When set, auto negotiation enables the interface
491 to exchange state advertisements with the connected peer so that
492 the two devices can agree on the ethernet PAUSE configuration. When
493 unset, the kernel's default will be used.
494 GenericSegmentOffloadMaxBytes=
496 Specifies the maximum size of a Generic Segment Offload (GSO)
497 packet the device should accept. The usual suffixes K, M, G are
498 supported and are understood to the base of 1024. An unsigned
499 integer in the range 1...65536. Defaults to unset.
500 GenericSegmentOffloadMaxSegments=
502 Specifies the maximum number of Generic Segment Offload (GSO)
503 segments the device should accept. An unsigned integer in the range
504 1...65535. Defaults to unset.
505
507 Example 1. /usr/lib/systemd/network/99-default.link
508 The link file 99-default.link that is shipped with systemd defines the
510 default naming policy for links.
511 [Link]
513 NamePolicy=kernel database onboard slot path
514 MACAddressPolicy=persistent
515 Example 2. /etc/systemd/network/10-dmz.link
517 This example assigns the fixed name "dmz0" to the interface with the
519 MAC address 00:a0:de:63:7a:e6:
520 [Match]
522 MACAddress=00:a0:de:63:7a:e6
523 [Link]
525 Name=dmz0
526 NamePolicy= is not set, so Name= takes effect. We use the "10-" prefix
528 to order this file early in the list. Note that it needs to be before
529 "99-link", i.e. it needs a numerical prefix, to have any effect at all.
530 Example 3. Debugging NamePolicy= assignments
532 $ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
534 ...
535 Parsed configuration file /usr/lib/systemd/network/99-default.link
536 Parsed configuration file /etc/systemd/network/10-eth0.link
537 ID_NET_DRIVER=cdc_ether
538 Config file /etc/systemd/network/10-eth0.link applies to device hub0
539 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
540 hub0: Device has name_assign_type=4
541 Using default interface naming scheme 'v240'.
542 hub0: Policies didn't yield a name, using specified Name=hub0.
543 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
544 ID_NET_NAME=hub0
545 ...
546 Explicit Name= configuration wins in this case.
548 sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
550 ...
551 Parsed configuration file /usr/lib/systemd/network/99-default.link
552 Parsed configuration file /etc/systemd/network/10-eth0.link
553 Created link configuration context.
554 ID_NET_DRIVER=e1000e
555 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
556 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
557 enp0s31f6: Device has name_assign_type=4
558 Using default interface naming scheme 'v240'.
559 enp0s31f6: Policy *keep*: keeping existing userspace name
560 enp0s31f6: Device has addr_assign_type=0
561 enp0s31f6: MAC on the device already matches policy *persistent*
562 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
563 ...
564 In this case, the interface was already renamed, so the keep policy
566 specified as the first option in 99-default.link means that the
567 existing name is preserved. If keep was removed, or if were in boot
568 before the renaming has happened, we might get the following instead:
569 enp0s31f6: Policy *path* yields "enp0s31f6".
571 enp0s31f6: Device has addr_assign_type=0
572 enp0s31f6: MAC on the device already matches policy *persistent*
573 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
574 ID_NET_NAME=enp0s31f6
575 ...
576 Please note that the details of output are subject to change.
578 Example 4. /etc/systemd/network/10-internet.link
580 This example assigns the fixed name "internet0" to the interface with
582 the device path "pci-0000:00:1a.0-*":
583 [Match]
585 Path=pci-0000:00:1a.0-*
586 [Link]
588 Name=internet0
589 Example 5. /etc/systemd/network/25-wireless.link
591 Here's an overly complex example that shows the use of a large number
593 of [Match] and [Link] settings.
594 [Match]
596 MACAddress=12:34:56:78:9a:bc
597 Driver=brcmsmac
598 Path=pci-0000:02:00.0-*
599 Type=wlan
600 Virtualization=no
601 Host=my-laptop
602 Architecture=x86-64
603 [Link]
605 Name=wireless0
606 MTUBytes=1450
607 BitsPerSecond=10M
608 WakeOnLan=magic
609 MACAddress=cb:a9:87:65:43:21
610
612 systemd-udevd.service(8), udevadm(8), systemd.netdev(5),
613 systemd.network(5)
614systemd 249 SYSTEMD.LINK(5)