SYSTEMD.LINK(5) | systemd.link | SYSTEMD.LINK(5) |
NAME
systemd.link - Network device configuration
SYNOPSIS
link.link
DESCRIPTION
A plain ini-style text file that encodes configuration for matching network devices, used by systemd-udevd(8) and in particular its net_setup_link builtin. See systemd.syntax(7) for a general description of the syntax.
The .link files are read from the files located in the system network directory /usr/lib/systemd/network and /usr/local/lib/systemd/network [1], the volatile runtime network directory /run/systemd/network, and the local administration network directory /etc/systemd/network. All configuration files are collectively sorted and processed in alphanumeric order, regardless of the directories in which they live. However, files with identical filenames replace each other. It is recommended that each filename is prefixed with a number smaller than "70" (e.g. 10-eth0.link). Otherwise, the default .link files or those generated by systemd-network-generator.service(8) may take precedence over user configured files. Files in /etc/ have the highest priority, files in /run/ take precedence over files with the same name in /usr/lib/. This can be used to override a system-supplied link file with a local file if needed. As a special case, an empty file (file size 0) or symlink with the same name pointing to /dev/null disables the configuration file entirely (it is "masked").
Along with the link file foo.link, a "drop-in" directory foo.link.d/ may exist. All files with the suffix ".conf" from this directory will be merged in the alphanumeric order and parsed after the main file itself has been parsed. This is useful to alter or add configuration settings, without having to modify the main configuration file. Each drop-in file must have appropriate section headers.
In addition to /etc/systemd/network, drop-in ".d" directories can be placed in /usr/lib/systemd/network or /run/systemd/network directories. Drop-in files in /etc/ take precedence over those in /run/ which in turn take precedence over those in /usr/lib/. Drop-in files under any of these directories take precedence over the main link file wherever located.
The link file contains a [Match] section, which determines if a given link file may be applied to a given device, as well as a [Link] section specifying how the device should be configured. The first (in lexical order) of the link files that matches a given device is applied. Note that a default file 99-default.link is shipped by the system. Any user-supplied .link should hence have a lexically earlier name to be considered at all.
See udevadm(8) for diagnosing problems with .link files.
[MATCH] SECTION OPTIONS
A link file is said to match an interface if all matches specified by the [Match] section are satisfied. When a link file does not contain valid settings in [Match] section, then the file will match all interfaces and systemd-udevd warns about that. Hint: to avoid the warning and to make it clear that all interfaces shall be matched, add the following:
OriginalName=*
The first (in alphanumeric order) of the link files that matches a given interface is applied, all later files are ignored, even if they match as well. The following keys are accepted:
MACAddress=
colon-delimited hexadecimal
Added in version 250.
hyphen-delimited hexadecimal
Added in version 250.
dot-delimited hexadecimal
Added in version 250.
IPv4 address format
Added in version 250.
IPv6 address format
Added in version 250.
The total length of each MAC address must be 4 (for IPv4 tunnel), 6 (for Ethernet), 16 (for IPv6 tunnel), or 20 (for InfiniBand). This option may appear more than once, in which case the lists are merged. If the empty string is assigned to this option, the list of hardware addresses defined prior to this is reset. Defaults to unset.
Added in version 211.
PermanentMACAddress=
Added in version 245.
Path=
Added in version 211.
Driver=
Added in version 211.
Type=
Added in version 211.
Kind=
Added in version 251.
Property=
Example: if a .link file has the following:
Property=ID_MODEL_ID=9999 "ID_VENDOR_FROM_DATABASE=vendor name" "KEY=with \"quotation\""
then, the .link file matches only when an interface has all the above three properties.
Added in version 243.
OriginalName=
Added in version 218.
Host=
Added in version 211.
Virtualization=
Added in version 211.
KernelCommandLine=
Added in version 211.
KernelVersion=
Added in version 237.
Credential=
Added in version 252.
Architecture=
Added in version 211.
Firmware=
Added in version 249.
[LINK] SECTION OPTIONS
The [Link] section accepts the following keys:
Description=
Added in version 211.
Property=
Property=HOGE=foo BAR=baz
This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared.
This setting is useful to configure the "ID_NET_MANAGED_BY=" property which declares which network management service shall manage the interface, which is respected by systemd-networkd and others. Use
Property=ID_NET_MANAGED_BY=io.systemd.Network
to declare explicitly that systemd-networkd shall manage the interface, or set the property to something else to declare explicitly it shall not do so. See systemd.network(5) for details how this property is used to match interface names.
Added in version 256.
ImportProperty=
ImportProperty=HOGE BAR
This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared.
If the same property is also set in Property= in the above, then the imported property value will be overridden by the value specified in Property=.
Added in version 256.
UnsetProperty=
ImportProperty=HOGE BAR
This option supports simple specifier expansion, see the Specifiers section below. This option can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared.
This setting is applied after ImportProperty= and Property= are applied. Hence, if the same property is specified in ImportProperty= or Property=, then the imported or specified property value will be ignored, and the property will be unset.
Added in version 256.
Alias=
Added in version 211.
MACAddressPolicy=
persistent
Added in version 211.
random
Added in version 211.
none
Added in version 227.
An empty string assignment is equivalent to setting "none".
Added in version 211.
MACAddress=
Added in version 211.
NamePolicy=
kernel
Added in version 216.
database
Added in version 211.
onboard
Added in version 211.
slot
Added in version 211.
path
Added in version 211.
mac
Added in version 211.
keep
Added in version 241.
Added in version 211.
Name=
Note that specifying a name that the kernel might use for another interface (for example "eth0") is dangerous because the name assignment done by udev will race with the assignment done by the kernel, and only one interface may use the name. Depending on the order of operations, either udev or the kernel will win, making the naming unpredictable. It is best to use some different prefix, for example "internal0"/"external0" or "lan0"/"lan1"/"lan3".
Interface names must have a minimum length of 1 character and a maximum length of 15 characters, and may contain any 7bit ASCII character, with the exception of control characters, ":", "/" and "%". While "." is an allowed character, it's recommended to avoid it when naming interfaces as various tools (such as resolvconf(1)) use it as separator character. Also, fully numeric interface names are not allowed (in order to avoid ambiguity with interface specification by numeric indexes), nor are the special strings ".", "..", "all" and "default".
Added in version 211.
AlternativeNamesPolicy=
Added in version 245.
AlternativeName=
Alternative interface names may be used to identify interfaces in various tools. In contrast to the primary name (as configured with Name= above) there may be multiple alternative names referring to the same interface. Alternative names may have a maximum length of 127 characters, in contrast to the 15 allowed for the primary interface name, but otherwise are subject to the same naming constraints.
Added in version 245.
TransmitQueues=
Added in version 248.
ReceiveQueues=
Added in version 248.
TransmitQueueLength=
Added in version 248.
MTUBytes=
Added in version 211.
BitsPerSecond=
Added in version 211.
Duplex=
Added in version 211.
AutoNegotiation=
Note that if autonegotiation is enabled, speed and duplex settings are read-only. If autonegotiation is disabled, speed and duplex settings are writable if the driver supports multiple link modes.
Added in version 233.
WakeOnLan=
phy
Added in version 211.
unicast
Added in version 235.
multicast
Added in version 235.
broadcast
Added in version 235.
arp
Added in version 235.
magic
Added in version 211.
secureon
Added in version 235.
Defaults to unset, and the device's default will be used. This setting can be specified multiple times. If an empty string is assigned, then the all previous assignments are cleared.
Added in version 211.
WakeOnLanPassword=
Added in version 250.
Port=
tp
Added in version 234.
aui
Added in version 234.
bnc
Added in version 234.
mii
Added in version 234.
fibre
Added in version 234.
Added in version 234.
Advertise=
Table 1. Supported advertise values
Advertise | Speed (Mbps) | Duplex Mode |
10baset-full | 10 | full |
10baset1l-full | 10 | full |
10baset-half | 10 | half |
100basefx-full | 100 | full |
100baset-full | 100 | full |
100baset1-full | 100 | full |
100basefx-half | 100 | half |
100baset-half | 100 | half |
1000basekx-full | 1000 | full |
1000baset-full | 1000 | full |
1000baset1-full | 1000 | full |
1000basex-full | 1000 | full |
1000baset-half | 1000 | half |
2500baset-full | 2500 | full |
2500basex-full | 2500 | full |
5000baset-full | 5000 | full |
10000baser-fec | 10000 | |
10000basecr-full | 10000 | full |
10000baseer-full | 10000 | full |
10000basekr-full | 10000 | full |
10000basekx4-full | 10000 | full |
10000baselr-full | 10000 | full |
10000baselrm-full | 10000 | full |
10000basesr-full | 10000 | full |
10000baset-full | 10000 | full |
20000basekr2-full | 20000 | full |
20000basemld2-full | 20000 | full |
25000basecr-full | 25000 | full |
25000basekr-full | 25000 | full |
25000basesr-full | 25000 | full |
40000basecr4-full | 40000 | full |
40000basekr4-full | 40000 | full |
40000baselr4-full | 40000 | full |
40000basesr4-full | 40000 | full |
50000basecr-full | 50000 | full |
50000basecr2-full | 50000 | full |
50000basedr-full | 50000 | full |
50000basekr-full | 50000 | full |
50000basekr2-full | 50000 | full |
50000baselr-er-fr-full | 50000 | full |
50000basesr-full | 50000 | full |
50000basesr2-full | 50000 | full |
56000basecr4-full | 56000 | full |
56000basekr4-full | 56000 | full |
56000baselr4-full | 56000 | full |
56000basesr4-full | 56000 | full |
100000basecr-full | 100000 | full |
100000basecr2-full | 100000 | full |
100000basecr4-full | 100000 | full |
100000basedr-full | 100000 | full |
100000basedr2-full | 100000 | full |
100000basekr-full | 100000 | full |
100000basekr2-full | 100000 | full |
100000basekr4-full | 100000 | full |
100000baselr-er-fr-full | 100000 | full |
100000baselr2-er2-fr2-full | 100000 | full |
100000baselr4-er4-full | 100000 | full |
100000basesr-full | 100000 | full |
100000basesr2-full | 100000 | full |
100000basesr4-full | 100000 | full |
200000basecr2-full | 200000 | full |
200000basecr4-full | 200000 | full |
200000basedr2-full | 200000 | full |
200000basedr4-full | 200000 | full |
200000basekr2-full | 200000 | full |
200000basekr4-full | 200000 | full |
200000baselr2-er2-fr2-full | 200000 | full |
200000baselr4-er4-fr4-full | 200000 | full |
200000basesr2-full | 200000 | full |
200000basesr4-full | 200000 | full |
400000basecr4-full | 400000 | full |
400000basecr8-full | 400000 | full |
400000basedr4-full | 400000 | full |
400000basedr8-full | 400000 | full |
400000basekr4-full | 400000 | full |
400000basekr8-full | 400000 | full |
400000baselr4-er4-fr4-full | 400000 | full |
400000baselr8-er8-fr8-full | 400000 | full |
400000basesr4-full | 400000 | full |
400000basesr8-full | 400000 | full |
800000basecr8-full | 800000 | full |
800000basedr8-2-full | 800000 | full |
800000basedr8-full | 800000 | full |
800000basekr8-full | 800000 | full |
800000basesr8-full | 800000 | full |
800000basevr8-full | 800000 | full |
asym-pause | ||
aui | ||
autonegotiation | ||
backplane | ||
bnc | ||
fec-baser | ||
fec-llrs | ||
fec-none | ||
fec-rs | ||
fibre | ||
mii | ||
pause | ||
tp |
By default this is unset, i.e. all possible modes will be advertised. This option may be specified more than once, in which case all specified speeds and modes are advertised. If the empty string is assigned to this option, the list is reset, and all prior assignments have no effect.
Added in version 240.
ReceiveChecksumOffload=
Added in version 245.
TransmitChecksumOffload=
Added in version 245.
TCPSegmentationOffload=
Added in version 232.
TCP6SegmentationOffload=
Added in version 235.
GenericSegmentationOffload=
Added in version 232.
GenericReceiveOffload=
Added in version 232.
GenericReceiveOffloadHardware=
Added in version 250.
LargeReceiveOffload=
Added in version 232.
ReceivePacketSteeringCPUMask=
Added in version 256.
ReceiveVLANCTAGHardwareAcceleration=
Added in version 250.
TransmitVLANCTAGHardwareAcceleration=
Added in version 250.
ReceiveVLANCTAGFilter=
Added in version 250.
TransmitVLANSTAGHardwareAcceleration=
Added in version 250.
NTupleFilter=
Added in version 250.
RxChannels=, TxChannels=, OtherChannels=, CombinedChannels=
Added in version 239.
RxBufferSize=, RxMiniBufferSize=, RxJumboBufferSize=, TxBufferSize=
Added in version 244.
RxFlowControl=
Added in version 246.
TxFlowControl=
Added in version 246.
AutoNegotiationFlowControl=
Added in version 246.
GenericSegmentOffloadMaxBytes=
Added in version 248.
GenericSegmentOffloadMaxSegments=
Added in version 248.
UseAdaptiveRxCoalesce=, UseAdaptiveTxCoalesce=
Added in version 250.
RxCoalesceSec=, RxCoalesceIrqSec=, RxCoalesceLowSec=, RxCoalesceHighSec=, TxCoalesceSec=, TxCoalesceIrqSec=, TxCoalesceLowSec=, TxCoalesceHighSec=
Added in version 250.
RxMaxCoalescedFrames=, RxMaxCoalescedIrqFrames=, RxMaxCoalescedLowFrames=, RxMaxCoalescedHighFrames=, TxMaxCoalescedFrames=, TxMaxCoalescedIrqFrames=, TxMaxCoalescedLowFrames=, TxMaxCoalescedHighFrames=
Added in version 250.
CoalescePacketRateLow=, CoalescePacketRateHigh=
Added in version 250.
CoalescePacketRateSampleIntervalSec=
Added in version 250.
StatisticsBlockCoalesceSec=
Added in version 250.
MDI=
Added in version 251.
SR-IOVVirtualFunctions=
Added in version 251.
[SR-IOV] SECTION OPTIONS
The [SR-IOV] section accepts the following keys. Specify several [SR-IOV] sections to configure several SR-IOVs. SR-IOV provides the ability to partition a single physical PCI resource into virtual PCI functions which can then be injected into a VM. In the case of network VFs, SR-IOV improves north-south network performance (that is, traffic with endpoints outside the host machine) by allowing traffic to bypass the host machine’s network stack.
VirtualFunction=
Added in version 251.
VLANId=
Added in version 251.
QualityOfService=
Added in version 251.
VLANProtocol=
Added in version 251.
MACSpoofCheck=
Added in version 251.
QueryReceiveSideScaling=
Added in version 251.
Trust=
Added in version 251.
LinkState=
Added in version 251.
MACAddress=
Added in version 251.
SPECIFIERS
Some settings resolve specifiers which may be used to write generic unit files referring to runtime or unit parameters that are replaced when the unit files are loaded. Specifiers must be known and resolvable for the setting to be valid. The following specifiers are understood:
Table 2. Specifiers available in unit files
Specifier | Meaning | Details |
"%a" | Architecture | A short string identifying the architecture of the local system. A string such as x86, x86-64 or arm64. See the architectures defined for ConditionArchitecture= in systemd.unit(5) for a full list. |
"%A" | Operating system image version | The operating system image version identifier of the running system, as read from the IMAGE_VERSION= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%b" | Boot ID | The boot ID of the running system, formatted as string. See random(4) for more information. |
"%B" | Operating system build ID | The operating system build identifier of the running system, as read from the BUILD_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%H" | Host name | The hostname of the running system. |
"%l" | Short host name | The hostname of the running system, truncated at the first dot to remove any domain component. |
"%m" | Machine ID | The machine ID of the running system, formatted as string. See machine-id(5) for more information. |
"%M" | Operating system image identifier | The operating system image identifier of the running system, as read from the IMAGE_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%o" | Operating system ID | The operating system identifier of the running system, as read from the ID= field of /etc/os-release. See os-release(5) for more information. |
"%q" | Pretty host name | The pretty hostname of the running system, as read from the PRETTY_HOSTNAME= field of /etc/machine-info. If not set, resolves to the short hostname. See machine-info(5) for more information. |
"%T" | Directory for temporary files | This is either /tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.) |
"%v" | Kernel release | Identical to uname -r output. |
"%V" | Directory for larger and persistent temporary files | This is either /var/tmp or the path "$TMPDIR", "$TEMP" or "$TMP" are set to. (Note that the directory may be specified without a trailing slash.) |
"%w" | Operating system version ID | The operating system version identifier of the running system, as read from the VERSION_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
"%W" | Operating system variant ID | The operating system variant identifier of the running system, as read from the VARIANT_ID= field of /etc/os-release. If not set, resolves to an empty string. See os-release(5) for more information. |
EXAMPLES
Example 1. /usr/lib/systemd/network/99-default.link
The link file 99-default.link that is shipped with systemd defines the default policies for the interface name, alternative names, and MAC address of links.
[Match] OriginalName=* [Link] NamePolicy=keep kernel database onboard slot path AlternativeNamesPolicy=database onboard slot path MACAddressPolicy=persistent
Example 2. /etc/systemd/network/10-dmz.link
This example assigns the fixed name "dmz0" to the interface with the MAC address 00:a0:de:63:7a:e6:
[Match] MACAddress=00:a0:de:63:7a:e6 [Link] Name=dmz0
NamePolicy= is not set, so Name= takes effect. We use the "10-" prefix to order this file early in the list. Note that it needs to be before 99-default.link, i.e. it needs a numerical prefix, to have any effect at all.
Example 3. (Re-)applying a .link file to an interface
After a new .link file has been created, or an existing .link file modified, the new settings may be applied to the matching interface with the following commands:
$ sudo udevadm control --reload $ sudo ip link set eth0 down $ sudo udevadm trigger --verbose --settle --action add /sys/class/net/eth0
You may also need to stop the service that manages the network interface, e.g. systemd-networkd.service(8) or NetworkManager.service before the above operation, and then restart the service after that. For more details about udevadm command, see udevadm(8).
Example 4. Debugging NamePolicy= assignments
$ sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/hub0 ... Parsed configuration file /usr/lib/systemd/network/99-default.link Parsed configuration file /etc/systemd/network/10-eth0.link ID_NET_DRIVER=cdc_ether Config file /etc/systemd/network/10-eth0.link applies to device hub0 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable. hub0: Device has name_assign_type=4 Using default interface naming scheme 'v240'. hub0: Policies didn't yield a name, using specified Name=hub0. ID_NET_LINK_FILE=/etc/systemd/network/10-eth0.link ID_NET_NAME=hub0 ...
Explicit Name= configuration wins in this case.
sudo SYSTEMD_LOG_LEVEL=debug udevadm test-builtin net_setup_link /sys/class/net/enp0s31f6 ... Parsed configuration file /usr/lib/systemd/network/99-default.link Parsed configuration file /etc/systemd/network/10-eth0.link Created link configuration context. ID_NET_DRIVER=e1000e Config file /usr/lib/systemd/network/99-default.link applies to device enp0s31f6 link_config: autonegotiation is unset or enabled, the speed and duplex are not writable. enp0s31f6: Device has name_assign_type=4 Using default interface naming scheme 'v240'. enp0s31f6: Policy *keep*: keeping existing userspace name enp0s31f6: Device has addr_assign_type=0 enp0s31f6: MAC on the device already matches policy *persistent* ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link ...
In this case, the interface was already renamed, so the keep policy specified as the first option in 99-default.link means that the existing name is preserved. If keep was removed, or if were in boot before the renaming has happened, we might get the following instead:
enp0s31f6: Policy *path* yields "enp0s31f6". enp0s31f6: Device has addr_assign_type=0 enp0s31f6: MAC on the device already matches policy *persistent* ID_NET_LINK_FILE=/usr/lib/systemd/network/99-default.link ID_NET_NAME=enp0s31f6 ...
Please note that the details of output are subject to change.
Example 5. /etc/systemd/network/10-internet.link
This example assigns the fixed name "internet0" to the interface with the device path "pci-0000:00:1a.0-*":
[Match] Path=pci-0000:00:1a.0-* [Link] Name=internet0
Example 6. /etc/systemd/network/25-wireless.link
Here's an overly complex example that shows the use of a large number of [Match] and [Link] settings.
[Match] MACAddress=12:34:56:78:9a:bc Driver=brcmsmac Path=pci-0000:02:00.0-* Type=wlan Virtualization=no Host=my-laptop Architecture=x86-64 [Link] Name=wireless0 MTUBytes=1450 BitsPerSecond=10M WakeOnLan=magic MACAddress=cb:a9:87:65:43:21
SEE ALSO
systemd-udevd.service(8), udevadm(8), systemd.netdev(5), systemd.network(5), systemd-network-generator.service(8)
NOTES
- 1.
- 💣💥🧨💥💥💣 Please note that those configuration files must be available at all times. If /usr/local/ is a separate partition, it may not be available during early boot, and must not be used for configuration.
- 2.
- System and Service Credentials
systemd 256.6 |