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