From 2cb7e0aaedad73b076ea18c6900b0e86c5760d79 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 27 Apr 2024 15:00:47 +0200 Subject: Adding upstream version 247.3. Signed-off-by: Daniel Baumann --- man/systemd.link.xml | 889 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 889 insertions(+) create mode 100644 man/systemd.link.xml (limited to 'man/systemd.link.xml') diff --git a/man/systemd.link.xml b/man/systemd.link.xml new file mode 100644 index 0000000..24271ea --- /dev/null +++ b/man/systemd.link.xml @@ -0,0 +1,889 @@ + + + + + + + systemd.link + systemd + + + + systemd.link + 5 + + + + systemd.link + Network device configuration + + + + link.link + + + + Description + + A plain ini-style text file that encodes configuration for matching network devices, used by + systemd-udevd8 and in + particular its net_setup_link builtin. See + systemd.syntax7 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, + the volatile runtime network directory + /run/systemd/network, and the local + administration network directory + /etc/systemd/network. Link files must have + the extension .link; other extensions are + ignored. All link files are collectively sorted and processed in + lexical order, regardless of the directories in which they live. + However, files with identical filenames replace each other. 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"). + + 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 udevadm8 for + diagnosing problems with .link files. + + + + [Match] Section Options + + A link file is said to match a device 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 devices 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 following keys are accepted: + + + + + + MACAddress= + + A whitespace-separated list of hardware addresses. Use full colon-, hyphen- or dot-delimited hexadecimal. See the example below. + 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. + + Example: + MACAddress=01:23:45:67:89:ab 00-11-22-33-44-55 AABB.CCDD.EEFF + + + + + 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. 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. + + + + + Path= + + A whitespace-separated list of shell-style globs matching + the persistent path, as exposed by the udev property + ID_PATH. + + + + + 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. + + + + + Type= + + A whitespace-separated list of shell-style globs matching the device type, as exposed by + networkctl status. If the list is prefixed with a "!", the test is inverted. + + + + + + Property= + + A whitespace-separated list of udev property name with its value after a equal + (=). 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. + + + + + + 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. + + + + + Host= + + Matches against the hostname or machine ID of the host. See ConditionHost= in + systemd.unit5 + for details. When prefixed with an exclamation mark (!), the result is negated. + If an empty string is assigned, then previously assigned value is cleared. + + + + + + Virtualization= + + Checks whether the system is executed in a virtualized environment and optionally test + whether it is a specific implementation. See ConditionVirtualization= in + systemd.unit5 + for details. When prefixed with an exclamation mark (!), the result is negated. + If an empty string is assigned, then previously assigned value is cleared. + + + + + + KernelCommandLine= + + Checks whether a specific kernel command line option is set. See + ConditionKernelCommandLine= in + systemd.unit5 + for details. When prefixed with an exclamation mark (!), the result is negated. + If an empty string is assigned, then previously assigned value is cleared. + + + + + + KernelVersion= + + Checks whether the kernel version (as reported by uname -r) matches a certain + expression. See ConditionKernelVersion= in + systemd.unit5 for + details. When prefixed with an exclamation mark (!), the result is negated. + If an empty string is assigned, then previously assigned value is cleared. + + + + + + Architecture= + + Checks whether the system is running on a specific architecture. See + ConditionArchitecture= in + systemd.unit5 + for details. When prefixed with an exclamation mark (!), the result is negated. + If an empty string is assigned, then previously assigned value is cleared. + + + + + + + + + [Link] Section Options + + The [Link] section accepts the following + keys: + + + + Description= + + A description of the device. + + + + Alias= + + The ifalias interface property is set to this value. + + + + MACAddressPolicy= + + The policy by which the MAC address should be set. The + available policies are: + + + + + + + If the hardware has a persistent MAC address, as + most hardware should, and if it is used by the kernel, + nothing is done. Otherwise, a new MAC address is + generated which is guaranteed to be the same on every + boot for the given machine and the given device, but + which is otherwise random. This feature depends on ID_NET_NAME_* + properties to exist for the link. On hardware where these + properties are not set, the generation of a persistent MAC address + will fail. + + + + + + If the kernel is using a random MAC address, + nothing is done. Otherwise, a new address is randomly + generated each time the device appears, typically at + boot. Either way, the random address will have the + unicast and + locally administered bits set. + + + + + + Keeps the MAC address assigned by the kernel. Or use the MAC address specified in + MACAddress=. + + + + + An empty string assignment is equivalent to setting none. + + + + MACAddress= + + The interface MAC address to use. For this setting to take effect, + MACAddressPolicy= must either be unset, empty, or none. + + + + + NamePolicy= + + An ordered, space-separated list of policies by which the interface name should be set. + NamePolicy= may be disabled by specifying on the + kernel command line. Each of the policies may fail, and the first successful one is used. The name + is not set directly, but is exported to udev as the property , which + is, by default, used by a + udev7, + rule to set NAME. The available policies are: + + + + + + + If the kernel claims that the name it has set + for a device is predictable, then no renaming is + performed. + + + + + + The name is set based on entries in the udev's + Hardware Database with the key + ID_NET_NAME_FROM_DATABASE. + + + + + + + The name is set based on information given by + the firmware for on-board devices, as exported by the + udev property ID_NET_NAME_ONBOARD. + See systemd.net-naming-scheme7. + + + + + + + The name is set based on information given by + the firmware for hot-plug devices, as exported by the + udev property ID_NET_NAME_SLOT. + See systemd.net-naming-scheme7. + + + + + + + The name is set based on the device's physical + location, as exported by the udev property + ID_NET_NAME_PATH. + See systemd.net-naming-scheme7. + + + + + + + The name is set based on the device's persistent + MAC address, as exported by the udev property + ID_NET_NAME_MAC. + See systemd.net-naming-scheme7. + + + + + + + If the device already had a name given by userspace (as part of creation of the device + or a rename), keep it. + + + + + + + Name= + + The interface name to use. This option has lower precedence than + NamePolicy=, so for this setting to take effect, NamePolicy= + must either be unset, empty, disabled, or all policies configured there must fail. Also see the + example below with Name=dmz0. + + 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. + + + + + AlternativeNamesPolicy= + + A space-separated list of policies by which the interface's alternative names + should be set. Each of the policies may fail, and all successful policies are used. The + available policies are database, onboard, + slot, path, and mac. If the + kernel does not support the alternative names, then this setting will be ignored. + + + + + AlternativeName= + + The alternative interface name to use. This option can be specified multiple times. + If the empty string is assigned to this option, the list is reset, and all prior assignments + have no effect. If the kernel does not support the alternative names, then this setting will + be ignored. + + + + MTUBytes= + + The maximum transmission unit in bytes to set for the + device. The usual suffixes K, M, G, are supported and are + understood to the base of 1024. + + + + BitsPerSecond= + + The speed to set for the device, the value is rounded + down to the nearest Mbps. The usual suffixes K, M, G, are + supported and are understood to the base of 1000. + + + + Duplex= + + The duplex mode to set for the device. The accepted values are and + . + + + + AutoNegotiation= + + Takes a boolean. If set to yes, automatic negotiation of transmission parameters is enabled. + Autonegotiation is a procedure by which two connected ethernet devices choose + common transmission parameters, such as speed, duplex mode, and flow control. + When unset, the kernel's default will be used. + + 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. + + + + WakeOnLan= + + The Wake-on-LAN policy to set for the device. The + supported values are: + + + + + + Wake on PHY activity. + + + + + + Wake on unicast messages. + + + + + + Wake on multicast messages. + + + + + + Wake on broadcast messages. + + + + + + Wake on ARP. + + + + + + Wake on receipt of a magic packet. + + + + + + + Enable secureon(tm) password for MagicPacket(tm). + + + + + + + Never wake. + + + + + Defaults to . + + + + Port= + + The port option is used to select the device port. The + supported values are: + + + + + + An Ethernet interface using Twisted-Pair cable as the medium. + + + + + + Attachment Unit Interface (AUI). Normally used with hubs. + + + + + + + An Ethernet interface using BNC connectors and co-axial cable. + + + + + + An Ethernet interface using a Media Independent Interface (MII). + + + + + + An Ethernet interface using Optical Fibre as the medium. + + + + + + + Advertise= + + This sets what speeds and duplex modes of operation are advertised for auto-negotiation. + This implies AutoNegotiation=yes. The supported values are: + + + Supported advertise values + + + + + + + Advertise + Speed (Mbps) + Duplex Mode + + + + 10half + + + 10full + + + 100half + + + 100full + + + 1000half + + + 1000full + + + 10000full + + + 2500full + + + 1000full + + + 10000full + + + 10000full + + + 10000full + + + 20000full + + + 20000full + + +
+ + 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. + + + + + ReceiveChecksumOffload= + + Takes a boolean. If set to true, the hardware offload for checksumming of ingress + network packets is enabled. When unset, the kernel's default will be used. + + + + TransmitChecksumOffload= + + Takes a boolean. If set to true, the hardware offload for checksumming of egress + network packets is enabled. When unset, the kernel's default will be used. + + + + TCPSegmentationOffload= + + Takes a boolean. If set to true, the TCP Segmentation Offload (TSO) is enabled. + When unset, the kernel's default will be used. + + + + TCP6SegmentationOffload= + + Takes a boolean. If set to true, the TCP6 Segmentation Offload (tx-tcp6-segmentation) is enabled. + When unset, the kernel's default will be used. + + + + GenericSegmentationOffload= + + Takes a boolean. If set to true, the Generic Segmentation Offload (GSO) is enabled. + When unset, the kernel's default will be used. + + + + GenericReceiveOffload= + + Takes a boolean. If set to true, the Generic Receive Offload (GRO) is enabled. + When unset, the kernel's default will be used. + + + + LargeReceiveOffload= + + Takes a boolean. If set to true, the Large Receive Offload (LRO) is enabled. + When unset, the kernel's default will be used. + + + + RxChannels= + + Sets the number of receive channels (a number between 1 and 4294967295) . + + + + TxChannels= + + Sets the number of transmit channels (a number between 1 and 4294967295). + + + + OtherChannels= + + Sets the number of other channels (a number between 1 and 4294967295). + + + + CombinedChannels= + + Sets the number of combined set channels (a number between 1 and 4294967295). + + + + RxBufferSize= + + Takes an integer. Specifies the maximum number of pending packets in the NIC receive buffer. + When unset, the kernel's default will be used. + + + + RxMiniBufferSize= + + Takes an integer. Specifies the maximum number of pending packets in the NIC mini receive buffer. + When unset, the kernel's default will be used. + + + + RxJumboBufferSize= + + Takes an integer. Specifies the maximum number of pending packets in the NIC jumbo receive buffer. + When unset, the kernel's default will be used. + + + + TxBufferSize= + + Takes an integer. Specifies the maximum number of pending packets in the NIC transmit buffer. + When unset, the kernel's default will be used. + + + + RxFlowControl= + + Takes a boolean. When set, enables the receive flow control, also known as the ethernet + receive PAUSE message (generate and send ethernet PAUSE frames). When unset, the kernel's + default will be used. + + + + TxFlowControl= + + Takes a boolean. When set, enables the transmit flow control, also known as the ethernet + transmit PAUSE message (respond to received ethernet PAUSE frames). When unset, the kernel's + default will be used. + + + + AutoNegotiationFlowControl= + + Takes a boolean. When set, the auto negotiation enables the interface to exchange state + advertisements with the connected peer so that the two devices can agree on the ethernet + PAUSE configuration. When unset, the kernel's default will be used. + + + + + + + + Examples + + + /usr/lib/systemd/network/99-default.link + + The link file 99-default.link that is + shipped with systemd defines the default naming policy for + links. + + [Link] +NamePolicy=kernel database onboard slot path +MACAddressPolicy=persistent + + + + /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-link, i.e. it needs a numerical prefix, to have any effect at all. + + + + Debugging <varname>NamePolicy=</varname> 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 policy specified as + the first option in 99-default.link means that the existing name is + preserved. If 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. + + + + /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 + + + + /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.service8 + , + + udevadm8 + , + + systemd.netdev5 + , + + systemd.network5 + + + + + -- cgit v1.2.3