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 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 valid
44 settings in [Match] section, then the file will match all devices and
45 systemd-udevd warns about that. Hint: to avoid the warning and to make
46 it clear that all interfaces shall be matched, add the following:
47 OriginalName=*
49 The following keys are accepted:
51 MACAddress=
53 A whitespace-separated list of hardware addresses. Use full colon-,
54 hyphen- or dot-delimited hexadecimal. See the example below. This
55 option may appear more than once, in which case the lists are
56 merged. If the empty string is assigned to this option, the list of
57 hardware addresses defined prior to this is reset.
58 Example:
60 MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF
62 PermanentMACAddress=
64 A whitespace-separated list of hardware's permanent addresses.
65 While MACAddress= matches the device's current MAC address, this
66 matches the device's permanent MAC address, which may be different
67 from the current one. Use full colon-, hyphen- or dot-delimited
68 hexadecimal. This option may appear more than once, in which case
69 the lists are merged. If the empty string is assigned to this
70 option, the list of hardware addresses defined prior to this is
71 reset.
72 Path=
74 A whitespace-separated list of shell-style globs matching the
75 persistent path, as exposed by the udev property ID_PATH.
76 Driver=
78 A whitespace-separated list of shell-style globs matching the
79 driver currently bound to the device, as exposed by the udev
80 property ID_NET_DRIVER of its parent device, or if that is not set,
81 the driver as exposed by ethtool -i of the device itself. If the
82 list is prefixed with a "!", the test is inverted.
83 Type=
85 A whitespace-separated list of shell-style globs matching the
86 device type, as exposed by networkctl status. If the list is
87 prefixed with a "!", the test is inverted.
88 Property=
90 A whitespace-separated list of udev property name with its value
91 after a equal ("="). If multiple properties are specified, the test
92 results are ANDed. If the list is prefixed with a "!", the test is
93 inverted. If a value contains white spaces, then please quote whole
94 key and value pair. If a value contains quotation, then please
95 escape the quotation with "\".
96 Example: if a .link file has the following:
98 Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""
100 then, the .link file matches only when an interface has all the
102 above three properties.
103 OriginalName=
105 A whitespace-separated list of shell-style globs matching the
106 device name, as exposed by the udev property "INTERFACE". This
107 cannot be used to match on names that have already been changed
108 from userspace. Caution is advised when matching on kernel-assigned
109 names, as they are known to be unstable between reboots.
110 Host=
112 Matches against the hostname or machine ID of the host. See
113 ConditionHost= in systemd.unit(5) for details. When prefixed with
114 an exclamation mark ("!"), the result is negated. If an empty
115 string is assigned, then previously assigned value is cleared.
116 Virtualization=
118 Checks whether the system is executed in a virtualized environment
119 and optionally test whether it is a specific implementation. See
120 ConditionVirtualization= in systemd.unit(5) for details. When
121 prefixed with an exclamation mark ("!"), the result is negated. If
122 an empty string is assigned, then previously assigned value is
123 cleared.
124 KernelCommandLine=
126 Checks whether a specific kernel command line option is set. See
127 ConditionKernelCommandLine= in systemd.unit(5) for details. When
128 prefixed with an exclamation mark ("!"), the result is negated. If
129 an empty string is assigned, then previously assigned value is
130 cleared.
131 KernelVersion=
133 Checks whether the kernel version (as reported by uname -r) matches
134 a certain expression. See ConditionKernelVersion= in
135 systemd.unit(5) for details. When prefixed with an exclamation mark
136 ("!"), the result is negated. If an empty string is assigned, then
137 previously assigned value is cleared.
138 Architecture=
140 Checks whether the system is running on a specific architecture.
141 See ConditionArchitecture= in systemd.unit(5) for details. When
142 prefixed with an exclamation mark ("!"), the result is negated. If
143 an empty string is assigned, then previously assigned value is
144 cleared.
145
147 The [Link] section accepts the following keys:
148 Description=
150 A description of the device.
151 Alias=
153 The ifalias interface property is set to this value.
154 MACAddressPolicy=
156 The policy by which the MAC address should be set. The available
157 policies are:
158 persistent
160 If the hardware has a persistent MAC address, as most hardware
161 should, and if it is used by the kernel, nothing is done.
162 Otherwise, a new MAC address is generated which is guaranteed
163 to be the same on every boot for the given machine and the
164 given device, but which is otherwise random. This feature
165 depends on ID_NET_NAME_* properties to exist for the link. On
166 hardware where these properties are not set, the generation of
167 a persistent MAC address will fail.
168 random
170 If the kernel is using a random MAC address, nothing is done.
171 Otherwise, a new address is randomly generated each time the
172 device appears, typically at boot. Either way, the random
173 address will have the "unicast" and "locally administered" bits
174 set.
175 none
177 Keeps the MAC address assigned by the kernel.
178 MACAddress=
180 The MAC address to use, if no MACAddressPolicy= is specified.
181 NamePolicy=
183 An ordered, space-separated list of policies by which the interface
184 name should be set. NamePolicy= may be disabled by specifying
185 net.ifnames=0 on the kernel command line. Each of the policies may
186 fail, and the first successful one is used. The name is not set
187 directly, but is exported to udev as the property ID_NET_NAME,
188 which is, by default, used by a udev(7), rule to set NAME. The
189 available policies are:
190 kernel
192 If the kernel claims that the name it has set for a device is
193 predictable, then no renaming is performed.
194 database
196 The name is set based on entries in the udev's Hardware
197 Database with the key ID_NET_NAME_FROM_DATABASE.
198 onboard
200 The name is set based on information given by the firmware for
201 on-board devices, as exported by the udev property
202 ID_NET_NAME_ONBOARD. See systemd.net-naming-scheme(7).
203 slot
205 The name is set based on information given by the firmware for
206 hot-plug devices, as exported by the udev property
207 ID_NET_NAME_SLOT. See systemd.net-naming-scheme(7).
208 path
210 The name is set based on the device's physical location, as
211 exported by the udev property ID_NET_NAME_PATH. See
212 systemd.net-naming-scheme(7).
213 mac
215 The name is set based on the device's persistent MAC address,
216 as exported by the udev property ID_NET_NAME_MAC. See
217 systemd.net-naming-scheme(7).
218 keep
220 If the device already had a name given by userspace (as part of
221 creation of the device or a rename), keep it.
222 Name=
224 The interface name to use. This option has lower precedence than
225 NamePolicy=, so for this setting to take effect, NamePolicy= must
226 either be unset, empty, disabled, or all policies configured there
227 must fail. Also see the example below with "Name=dmz0".
228 Note that specifying a name that the kernel might use for another
230 interface (for example "eth0") is dangerous because the name
231 assignment done by udev will race with the assignment done by the
232 kernel, and only one interface may use the name. Depending on the
233 order of operations, either udev or the kernel will win, making the
234 naming unpredictable. It is best to use some different prefix, for
235 example "internal0"/"external0" or "lan0"/"lan1"/"lan3".
236 AlternativeNamesPolicy=
238 A space-separated list of policies by which the interface's
239 alternative names should be set. Each of the policies may fail, and
240 all successful policies are used. The available policies are
241 "database", "onboard", "slot", "path", and "mac". If the kernel
242 does not support the alternative names, then this setting will be
243 ignored.
244 AlternativeName=
246 The alternative interface name to use. This option can be specified
247 multiple times. If the empty string is assigned to this option, the
248 list is reset, and all prior assignments have no effect. If the
249 kernel does not support the alternative names, then this setting
250 will be ignored.
251 MTUBytes=
253 The maximum transmission unit in bytes to set for the device. The
254 usual suffixes K, M, G, are supported and are understood to the
255 base of 1024.
256 BitsPerSecond=
258 The speed to set for the device, the value is rounded down to the
259 nearest Mbps. The usual suffixes K, M, G, are supported and are
260 understood to the base of 1000.
261 Duplex=
263 The duplex mode to set for the device. The accepted values are half
264 and full.
265 AutoNegotiation=
267 Takes a boolean. If set to yes, automatic negotiation of
268 transmission parameters is enabled. Autonegotiation is a procedure
269 by which two connected ethernet devices choose common transmission
270 parameters, such as speed, duplex mode, and flow control. When
271 unset, the kernel's default will be used.
272 Note that if autonegotiation is enabled, speed and duplex settings
274 are read-only. If autonegotiation is disabled, speed and duplex
275 settings are writable if the driver supports multiple link modes.
276 WakeOnLan=
278 The Wake-on-LAN policy to set for the device. The supported values
279 are:
280 phy
282 Wake on PHY activity.
283 unicast
285 Wake on unicast messages.
286 multicast
288 Wake on multicast messages.
289 broadcast
291 Wake on broadcast messages.
292 arp
294 Wake on ARP.
295 magic
297 Wake on receipt of a magic packet.
298 secureon
300 Enable secureon(tm) password for MagicPacket(tm).
301 off
303 Never wake.
304 Defaults to off.
306 Port=
308 The port option is used to select the device port. The supported
309 values are:
310 tp
312 An Ethernet interface using Twisted-Pair cable as the medium.
313 aui
315 Attachment Unit Interface (AUI). Normally used with hubs.
316 bnc
318 An Ethernet interface using BNC connectors and co-axial cable.
319 mii
321 An Ethernet interface using a Media Independent Interface
322 (MII).
323 fibre
325 An Ethernet interface using Optical Fibre as the medium.
326 Advertise=
328 This sets what speeds and duplex modes of operation are advertised
329 for auto-negotiation. This implies "AutoNegotiation=yes". The
330 supported values are:
331 Table 1. Supported advertise values
333 ┌───────────────────┬──────────────┬─────────────┐
334 │Advertise │ Speed (Mbps) │ Duplex Mode │
335 ├───────────────────┼──────────────┼─────────────┤
336 │10baset-half │ 10 │ half │
337 ├───────────────────┼──────────────┼─────────────┤
338 │10baset-full │ 10 │ full │
339 ├───────────────────┼──────────────┼─────────────┤
340 │100baset-half │ 100 │ half │
341 ├───────────────────┼──────────────┼─────────────┤
342 │100baset-full │ 100 │ full │
343 ├───────────────────┼──────────────┼─────────────┤
344 │1000baset-half │ 1000 │ half │
345 ├───────────────────┼──────────────┼─────────────┤
346 │1000baset-full │ 1000 │ full │
347 ├───────────────────┼──────────────┼─────────────┤
348 │10000baset-full │ 10000 │ full │
349 ├───────────────────┼──────────────┼─────────────┤
350 │2500basex-full │ 2500 │ full │
351 ├───────────────────┼──────────────┼─────────────┤
352 │1000basekx-full │ 1000 │ full │
353 ├───────────────────┼──────────────┼─────────────┤
354 │10000basekx4-full │ 10000 │ full │
355 ├───────────────────┼──────────────┼─────────────┤
356 │10000basekr-full │ 10000 │ full │
357 ├───────────────────┼──────────────┼─────────────┤
358 │10000baser-fec │ 10000 │ full │
359 ├───────────────────┼──────────────┼─────────────┤
360 │20000basemld2-full │ 20000 │ full │
361 ├───────────────────┼──────────────┼─────────────┤
362 │20000basekr2-full │ 20000 │ full │
363 └───────────────────┴──────────────┴─────────────┘
364 By default this is unset, i.e. all possible modes will be
365 advertised. This option may be specified more than once, in which
366 case all specified speeds and modes are advertised. If the empty
367 string is assigned to this option, the list is reset, and all prior
368 assignments have no effect.
369 ReceiveChecksumOffload=
371 Takes a boolean. If set to true, the hardware offload for
372 checksumming of ingress network packets is enabled. When unset, the
373 kernel's default will be used.
374 TransmitChecksumOffload=
376 Takes a boolean. If set to true, the hardware offload for
377 checksumming of egress network packets is enabled. When unset, the
378 kernel's default will be used.
379 TCPSegmentationOffload=
381 Takes a boolean. If set to true, the TCP Segmentation Offload (TSO)
382 is enabled. When unset, the kernel's default will be used.
383 TCP6SegmentationOffload=
385 Takes a boolean. If set to true, the TCP6 Segmentation Offload
386 (tx-tcp6-segmentation) is enabled. When unset, the kernel's default
387 will be used.
388 GenericSegmentationOffload=
390 Takes a boolean. If set to true, the Generic Segmentation Offload
391 (GSO) is enabled. When unset, the kernel's default will be used.
392 GenericReceiveOffload=
394 Takes a boolean. If set to true, the Generic Receive Offload (GRO)
395 is enabled. When unset, the kernel's default will be used.
396 LargeReceiveOffload=
398 Takes a boolean. If set to true, the Large Receive Offload (LRO) is
399 enabled. When unset, the kernel's default will be used.
400 RxChannels=
402 Sets the number of receive channels (a number between 1 and
403 4294967295) .
404 TxChannels=
406 Sets the number of transmit channels (a number between 1 and
407 4294967295).
408 OtherChannels=
410 Sets the number of other channels (a number between 1 and
411 4294967295).
412 CombinedChannels=
414 Sets the number of combined set channels (a number between 1 and
415 4294967295).
416 RxBufferSize=
418 Takes an integer. Specifies the maximum number of pending packets
419 in the NIC receive buffer. When unset, the kernel's default will be
420 used.
421 RxMiniBufferSize=
423 Takes an integer. Specifies the maximum number of pending packets
424 in the NIC mini receive buffer. When unset, the kernel's default
425 will be used.
426 RxJumboBufferSize=
428 Takes an integer. Specifies the maximum number of pending packets
429 in the NIC jumbo receive buffer. When unset, the kernel's default
430 will be used.
431 TxBufferSize=
433 Takes an integer. Specifies the maximum number of pending packets
434 in the NIC transmit buffer. When unset, the kernel's default will
435 be used.
436 RxFlowControl=
438 Takes a boolean. When set, enables the receive flow control, also
439 known as the ethernet receive PAUSE message (generate and send
440 ethernet PAUSE frames). When unset, the kernel's default will be
441 used.
442 TxFlowControl=
444 Takes a boolean. When set, enables the transmit flow control, also
445 known as the ethernet transmit PAUSE message (respond to received
446 ethernet PAUSE frames). When unset, the kernel's default will be
447 used.
448 AutoNegotiationFlowControl=
450 Takes a boolean. When set, the auto negotiation enables the
451 interface to exchange state advertisements with the connected peer
452 so that the two devices can agree on the ethernet PAUSE
453 configuration. When unset, the kernel's default will be used.
454
456 Example 1. /usr/lib/systemd/network/99-default.link
457 The link file 99-default.link that is shipped with systemd defines the
459 default naming policy for links.
460 [Link]
462 NamePolicy=kernel database onboard slot path
463 MACAddressPolicy=persistent
464 Example 2. /etc/systemd/network/10-dmz.link
466 This example assigns the fixed name "dmz0" to the interface with the
468 MAC address 00:a0:de:63:7a:e6:
469 [Match]
471 MACAddress=00:a0:de:63:7a:e6
472 [Link]
474 Name=dmz0
475 NamePolicy= is not set, so Name= takes effect. We use the "10-" prefix
477 to order this file early in the list. Note that it needs to be before
478 "99-link", i.e. it needs a numerical prefix, to have any effect at all.
479 Example 3. Debugging NamePolicy= assignments
481 $ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0
483 ...
484 Parsed configuration file /usr/lib/systemd/network/99-default.link
485 Parsed configuration file /etc/systemd/network/10-eth0.link
486 ID_NET_DRIVER=cdc_ether
487 Config file /etc/systemd/network/10-eth0.link applies to device hub0
488 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
489 hub0: Device has name_assign_type=4
490 Using default interface naming scheme 'v240'.
491 hub0: Policies didn't yield a name, using specified Name=hub0.
492 ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link
493 ID_NET_NAME=hub0
494 ...
495 Explicit Name= configuration wins in this case.
497 sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6
499 ...
500 Parsed configuration file /usr/lib/systemd/network/99-default.link
501 Parsed configuration file /etc/systemd/network/10-eth0.link
502 Created link configuration context.
503 ID_NET_DRIVER=e1000e
504 Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6
505 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable.
506 enp0s31f6: Device has name_assign_type=4
507 Using default interface naming scheme 'v240'.
508 enp0s31f6: Policy *keep*: keeping existing userspace name
509 enp0s31f6: Device has addr_assign_type=0
510 enp0s31f6: MAC on the device already matches policy *persistent*
511 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
512 ...
513 In this case, the interface was already renamed, so the keep policy
515 specified as the first option in 99-default.link means that the
516 existing name is preserved. If keep was removed, or if were in boot
517 before the renaming has happened, we might get the following instead:
518 enp0s31f6: Policy *path* yields "enp0s31f6".
520 enp0s31f6: Device has addr_assign_type=0
521 enp0s31f6: MAC on the device already matches policy *persistent*
522 ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link
523 ID_NET_NAME=enp0s31f6
524 ...
525 Please note that the details of output are subject to change.
527 Example 4. /etc/systemd/network/10-internet.link
529 This example assigns the fixed name "internet0" to the interface with
531 the device path "pci-0000:00:1a.0-*":
532 [Match]
534 Path=pci-0000:00:1a.0-*
535 [Link]
537 Name=internet0
538 Example 5. /etc/systemd/network/25-wireless.link
540 Here's an overly complex example that shows the use of a large number
542 of [Match] and [Link] settings.
543 [Match]
545 MACAddress=12:34:56:78:9a:bc
546 Driver=brcmsmac
547 Path=pci-0000:02:00.0-*
548 Type=wlan
549 Virtualization=no
550 Host=my-laptop
551 Architecture=x86-64
552 [Link]
554 Name=wireless0
555 MTUBytes=1450
556 BitsPerSecond=10M
557 WakeOnLan=magic
558 MACAddress=cb:a9:87:65:43:21
559
561 systemd-udevd.service(8), udevadm(8), systemd.netdev(5),
562 systemd.network(5)
563systemd 246 SYSTEMD.LINK(5)