systemd.link(5)

systemd.link5

Network device configuration

Usage

link.link

Overview

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.

Note that some distributions may incorporate .link files in their early boot facilities (e.g. by including copies of the .link files in initramfs). As such it may be necessary to take manual steps to ensure that any local changes are consistent with early-boot storage facilities. The relevant distribution-specific documentation should be consulted.

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 lexicographic 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 lexicographically 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=

A whitespace-separated list of hardware addresses. The acceptable formats are:

colon-delimited hexadecimal

Each field must be one byte. E.g. "12:34:56:78:90:ab" or "AA:BB:CC:DD:EE:FF".

Added in version 250.

hyphen-delimited hexadecimal

Each field must be one byte. E.g. "12-34-56-78-90-ab" or "AA-BB-CC-DD-EE-FF".

Added in version 250.

dot-delimited hexadecimal

Each field must be two bytes. E.g. "1234.5678.90ab" or "AABB.CCDD.EEFF".

Added in version 250.

IPv4 address format

E.g. "127.0.0.1" or "192.168.0.1".

Added in version 250.

IPv6 address format

E.g. "2001:0db8:85a3::8a2e:0370:7334" or "::1".

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=

A whitespace-separated list of hardware's permanent addresses. While MACAddress= matches the device's current MAC address, this matches the device's permanent MAC address, which may be different from the current one. Use full colon-, hyphen- or dot-delimited hexadecimal, or IPv4 or IPv6 address format. 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 245.

Path=

A whitespace-separated list of shell-style globs matching the persistent path, as exposed by the udev property ID_PATH.

Added in version 211.

Driver=

A whitespace-separated list of shell-style globs matching the driver currently bound to the device, as exposed by the udev property ID_NET_DRIVER of its parent device, or if that is not set, the driver as exposed by ethtool -i of the device itself. If the list is prefixed with a "!", the test is inverted.

Added in version 211.

Type=

A whitespace-separated list of shell-style globs matching the device type, as exposed by networkctl list. If the list is prefixed with a "!", the test is inverted. Some valid values are "ether", "loopback", "wlan", "wwan". Valid types are named either from the udev "DEVTYPE" attribute, or "ARPHRD_" macros in linux/if_arp.h, so this is not comprehensive.

Added in version 211.

Kind=

A whitespace-separated list of shell-style globs matching the device kind, as exposed by networkctl status INTERFACE or ip -d link show INTERFACE. If the list is prefixed with a "!", the test is inverted. Some valid values are "bond", "bridge", "gre", "tun", "veth". Valid kinds are given by netlink's "IFLA_INFO_KIND" attribute, so this is not comprehensive.

Added in version 251.

Property=

A whitespace-separated list of udev property names with their values after equals sign ("="). If multiple properties are specified, the test results are ANDed. If the list is prefixed with a "!", the test is inverted. If a value contains white spaces, then please quote whole key and value pair. If a value contains quotation, then please escape the quotation with "\".

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=

A whitespace-separated list of shell-style globs matching the device name, as exposed by the udev property "INTERFACE". This cannot be used to match on names that have already been changed from userspace. Caution is advised when matching on kernel-assigned names, as they are known to be unstable between reboots.

Added in version 218.

Host=

Matches against the hostname or machine ID of the host. See ConditionHost= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 211.

Virtualization=

Checks whether the system is executed in a virtualized environment and optionally test whether it is a specific implementation. See ConditionVirtualization= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 211.

KernelCommandLine=

Checks whether a specific kernel command line option is set. See ConditionKernelCommandLine= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 211.

KernelVersion=

Checks whether the kernel version (as reported by uname -r) matches a certain expression. See ConditionKernelVersion= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 237.

Version=

Checks whether a software version matches a certain expression. See ConditionVersion= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 258.

Credential=

Checks whether the specified credential was passed to the systemd-udevd.service service. See System and Service Credentials[2] for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 252.

Architecture=

Checks whether the system is running on a specific architecture. See ConditionArchitecture= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 211.

Firmware=

Checks whether the system is running on a machine with the specified firmware. See ConditionFirmware= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 249.

MachineTag=

Matches against the tags assigned to the local machine. See ConditionMachineTag= in systemd.unit(5) for details. When prefixed with an exclamation mark ("!"), the result is negated. If an empty string is assigned, the previously assigned value is cleared.

Added in version 262.

[SR-iov] section options

SR-IOV provides the ability to partition a single physical PCI resource into virtual PCI functions which can then be e.g. injected into a VM. In the case of network VFs, SR-IOV reduces latency and CPU utilisation for north-south network traffic (that is, traffic with endpoints outside the host machine), by allowing traffic to bypass the host machine’s network stack.

The presence of an [SR-IOV] section in a .link file will cause the creation and configuration of the specified virtual function. Within a .network file, the specified virtual function will be configured, but must already exist. Specify several [SR-IOV] sections to configure several SR-IOVs.

The [SR-IOV] section accepts the following keys.

VirtualFunction=

Specifies a Virtual Function (VF), lightweight PCIe function designed solely to move data in and out. Takes an integer in the range 0...2147483646. This option is compulsory.

Added in version 251.

VLANId=

Specifies VLAN ID of the virtual function. Takes an integer in the range 1...4095.

Added in version 251.

QualityOfService=

Specifies quality of service of the virtual function. Takes an integer in the range 1...4294967294.

Added in version 251.

VLANProtocol=

Specifies VLAN protocol of the virtual function. Takes "802.1Q" or "802.1ad".

Added in version 251.

MACSpoofCheck=

Takes a boolean. Controls the MAC spoof checking. When unset, the kernel's default will be used.

Added in version 251.

QueryReceiveSideScaling=

Takes a boolean. Toggle the ability of querying the receive side scaling (RSS) configuration of the virtual function (VF). The VF RSS information like RSS hash key may be considered sensitive on some devices where this information is shared between VF and the physical function (PF). When unset, the kernel's default will be used.

Added in version 251.

Trust=

Takes a boolean. Allows one to set trust mode of the virtual function (VF). When set, VF users can set a specific feature which may impact security and/or performance. When unset, the kernel's default will be used.

Added in version 251.

LinkState=

Allows one to set the link state of the virtual function (VF). Takes a boolean or a special value "auto". Setting to "auto" means a reflection of the physical function (PF) link state, "yes" lets the VF to communicate with other VFs on this host even if the PF link state is down, "no" causes the hardware to drop any packets sent by the VF. When unset, the kernel's default will be used.

Added in version 251.

MACAddress=

Specifies the MAC address for the virtual function.

Added in version 251.

[energyefficientethernet] section options

The [EnergyEfficientEthernet] section controls the Energy Efficient Ethernet (EEE) feature of the interface, and accepts the following keys.

Enable=

Takes a boolean argument. When true, the Energy Efficient Ethernet (EEE) feature will be enabled on the interface. Defaults to unset, and the enablement of EEE will be unchanged.

Added in version 258.

TxLowPowerIdle=

Takes a boolean argument. When true, the transmit Low Power Idle (Tx-LPI) mode of the Energy Efficient Ethernet feature will be enabled on the interface. Defaults to unset, and the enablement of the mode will be unchanged.

Added in version 258.

TxLowPowerIdleSec=

Takes a timespan. This configures how long the interface should not enter the Low Power Idle mode after transmission. If it is too short, may decrease performance. If it is too long, may not gain energy saving. Defaults to unset, and the timespan will be unchanged.

Added in version 258.

LinkMode=

Takes a list of link modes, e.g. "1000baset-full". See the table for Advertise= setting in [Link] section in the above for possible values. This configures the Energy Efficient Ethernet capable connection modes to be advertised. Defaults to unset, and the advertised modes will be unchanged.

Added in version 258.

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

SpecifierMeaningDetails
"%a"ArchitectureA 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 versionThe 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 IDThe boot ID of the running system, formatted as string. See random(4) for more information.
"%B"Operating system build IDThe 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 nameThe hostname of the running system.
"%l"Short host nameThe hostname of the running system, truncated at the first dot to remove any domain component.
"%m"Machine IDThe machine ID of the running system, formatted as string. See machine-id(5) for more information.
"%M"Operating system image identifierThe 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 IDThe 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 nameThe 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 filesThis 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 releaseIdentical to uname -r output.
"%V"Directory for larger and persistent temporary filesThis 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 IDThe 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 IDThe 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 did not 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

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

https://systemd.io/CREDENTIALS

3.

Partial Generic Segmentation Offload

https://docs.kernel.org/networking/segmentation-offloads.html#partial-generic-segmentation-offload

Releases

7 releases since Debian 8 (Jessie); the text changed 6 times.

  1. 8
  2. 9
  3. 10
  4. 11
  5. 12
  6. 13
  7. Arch

From systemd 262.1-1 in Arch Linux 2026-11-07. Parsed by carta from the page's man source.