From af528dcffaab1efea760395cc6676fe4b01e89b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Zbigniew=20J=C4=99drzejewski-Szmek?= Date: Thu, 9 May 2019 12:34:30 +0200 Subject: [PATCH] man: describe naming schemes in a new man page I decided to make this a separate man page because it is freakin' long. This content could equally well go in systemd-udevd.service(8), systemd.link(5), or a new man page for the net_id builtin. v2: - rename to systemd.net-naming-scheme - add udevadm test-builtin net_id example (cherry picked from commit 0b1e5b6ed8c6b9a2bc53709eb75e381d360f05bf) Related: #1827462 [msekleta: I've removed parts that describe features which are not available in RHEL-8] --- man/rules/meson.build | 1 + man/systemd-udevd.service.xml | 19 +- man/systemd.link.xml | 10 +- man/systemd.net-naming-scheme.xml | 385 ++++++++++++++++++++++++++++++ src/udev/udev-builtin-net_id.c | 1 + 5 files changed, 402 insertions(+), 14 deletions(-) create mode 100644 man/systemd.net-naming-scheme.xml diff --git a/man/rules/meson.build b/man/rules/meson.build index 7ae94ea265..e6c0a99bbd 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -714,6 +714,7 @@ manpages = [ ['systemd.kill', '5', [], ''], ['systemd.link', '5', [], ''], ['systemd.mount', '5', [], ''], + ['systemd.net-naming-scheme', '7', [], ''], ['systemd.netdev', '5', [], 'ENABLE_NETWORKD'], ['systemd.network', '5', [], 'ENABLE_NETWORKD'], ['systemd.nspawn', '5', [], ''], diff --git a/man/systemd-udevd.service.xml b/man/systemd-udevd.service.xml index b738591c93..f4cdb2f1e7 100644 --- a/man/systemd-udevd.service.xml +++ b/man/systemd-udevd.service.xml @@ -174,15 +174,11 @@ net.naming-scheme= Network interfaces are renamed to give them predictable names when possible (unless - net.ifnames=0 is specified, see above). The names are derived from various - device metadata fields. Newer versions of systemd-udevd.service take more of - these fields into account, improving (and thus possibly changing) the names used for the same - devices. With this kernel command line option it is possible to pick a specific version of this - algorithm. It expects a naming scheme identifier as argument. Currently the following identifiers - are known: rhel-8.0, rhel-8.1, rhel-8.2, - rhel-8.3 which each implement the naming scheme that was the default in the - indicated Red Hat Enterprise Linux minor version. In addition, latest may be - used to designate the latest scheme known (to this particular version of + net.ifnames=0 is specified, see above). With this kernel command line option it + is possible to pick a specific version of this algorithm and override the default chosen at + compilation time. Expects one of the naming scheme identifiers listed in + systemd.net-naming-scheme7, + or latest to select the latest scheme known (to this particular version of systemd-udevd.service). Note that selecting a specific scheme is not sufficient to fully stabilize interface naming: the naming is generally derived from driver attributes exposed by the kernel. As the kernel is @@ -191,9 +187,8 @@ - - + + See Also diff --git a/man/systemd.link.xml b/man/systemd.link.xml index 6708753e82..32657308d0 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -286,6 +286,7 @@ 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. @@ -295,6 +296,7 @@ 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. @@ -303,7 +305,9 @@ The name is set based on the device's physical location, as exported by the udev property - ID_NET_NAME_PATH. + ID_NET_NAME_PATH. + See systemd.net-naming-scheme7. + @@ -311,7 +315,9 @@ The name is set based on the device's persistent MAC address, as exported by the udev property - ID_NET_NAME_MAC. + ID_NET_NAME_MAC. + See systemd.net-naming-scheme7. + diff --git a/man/systemd.net-naming-scheme.xml b/man/systemd.net-naming-scheme.xml new file mode 100644 index 0000000000..a12cc3c460 --- /dev/null +++ b/man/systemd.net-naming-scheme.xml @@ -0,0 +1,385 @@ + + + + + + + systemd.net-naming-scheme + systemd + + + + systemd.net-naming-scheme + 7 + + + + systemd.net-naming-scheme + Network device naming schemes + + + + Description + + Network interfaces may be renamed to give them predictable names when there's enough information to + generate appropriate names and the use of certain types of names is configured. This page describes the + first part, i.e. what possible names may be generated. Those names are generated by the + systemd-udevd.service8 + builtin net_id and exported as udev properties + (ID_NET_NAME_ONBOARD=, ID_NET_LABEL_ONBOARD=, + ID_NET_NAME_PATH=, ID_NET_NAME_SLOT=). + + Names are derived from various device metadata attributes. Newer versions of udev take more of + these attributes into account, improving (and thus possibly changing) the names used for the same + devices. Differents version of the naming rules are called "naming schemes". The default naming scheme is + chosen at compilation time. Usually this will be the latest implemented version, but it is also possible + to set one of the older versions to preserve compatibility. This may be useful for example for + distributions, which may introduce new versions of systemd in stable releases without changing the naming + scheme. The naming scheme may also be overriden using the net.naming-scheme= kernel + command line switch, see + systemd-udevd.service8. + Available naming schemes are described below. + + After the udev proprties have been generated, appropriate udev rules may be used to actually rename + devices based on those properties. See the description of NamePolicy= in + systemd.link5. + + + + + Naming + + All names start with a two-character prefix that signifies the interface type. + + + Two character prefixes based on the type of interface + + + + + Prefix + Description + + + + + en + Ethernet + + + sl + serial line IP (slip) + + + wl + Wireless local area network (WLAN) + + + ww + Wireless wide area network (WWAN) + + + +
+ + The udev net_id builtin exports the following udev device properties: + + + + ID_NET_NAME_ONBOARD=prefixonumber + + This name is set based on the ordering information given by the firmware for + on-board devices. The name consists of the prefix, letter o, and a number + specified by the firmware. This is only available for PCI devices. + + + + + ID_NET_LABEL_ONBOARD=prefix label + + This property is set based on label given by the firmware for on-board devices. The + name consists of the prefix concatenated with the label. This is only available for PCI devices. + + + + + + ID_NET_NAME_MAC=prefixxAABBCCDDEEFF + + This name consists of the prefix, letter x, and 12 hexadecimal + digits of the MAC address. It is available if the device has a fixed MAC address. Because this name + is based on an attribute of the card itself, it remains "stable" when the device is moved (even + between machines), but will change when the hardware is replaced. + + + + + ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port] + ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]bnumber + ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]uport…[cconfig][iinterface] + ID_NET_NAME_SLOT=prefix[Pdomain]sslot[ffunction][nport_name|ddev_port]vslot + + This property describes the slot position. Different schemes are used depending on + the bus type, as described in the table below. In all cases, PCI slot information must be known. In + case of USB, BCMA, and SR-VIO devices, the full name consists of the prefix, PCI slot identifier, + and USB or BCMA or SR-VIO slot identifier. The first two parts are denoted as "…" in the table + below. + + + Slot naming schemes + + + + + Format + Description + + + + + + prefix [Pdomain] sslot [ffunction] [nport_name | ddev_port] + PCI slot number + + + + … bnumber + Broadcom bus (BCMA) core number + + + + … uport… [cconfig] [iinterface] + USB port number chain + + + + … vslot + SR-VIO slot number + + + +
+ + The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry + the ffunction number in the device name, including + the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name + port_name is used, or the port number + ddev_port if the name is not known. + + For BCMA devices, the core number is suppressed when 0. + + For USB devices the full chain of port numbers of hubs is composed. If the name gets longer + than the maximum number of 15 characters, the name is not exported. The usual USB configuration + number 1 and interface number 0 values are suppressed. + + + SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of + v and the virtual device number, with any leading zeros removed. The bus + number is ignored. This device type is found in IBM PowerVMs. + + + + ID_NET_NAME_PATH=prefixcbus_id + ID_NET_NAME_PATH=prefixavendormodeliinstance + ID_NET_NAME_PATH=prefixiaddressnport_name + ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port] + ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port]bnumber + ID_NET_NAME_PATH=prefix[Pdomain]pbussslot[ffunction][nphys_port_name|ddev_port]uport…[cconfig][iinterface] + + This property describes the device installation location. Different schemes are + used depending on the bus type, as described in the table below. For BCMA and USB devices, PCI path + information must known, and the full name consists of the prefix, PCI slot identifier, and USB or + BCMA location. The first two parts are denoted as "…" in the table below. + + + Path naming schemes + + + + + Format + Description + + + + + + prefix cbus_id + CCW or grouped CCW device identifier + + + + prefix avendor model iinstance + ACPI path names for ARM64 platform devices + + + + prefix [Pdomain] pbus sslot [ffunction] [nphys_port_name | ddev_port] + PCI geographical location + + + + … bnumber + Broadcom bus (BCMA) core number + + + + … uport… [cconfig] [iinterface] + USB port number chain + + + + +
+ + CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and + dots are suppressed. + + For PCI, BCMA, and USB devices, the same rules as described above for slot naming are + used. + + + + + + + History + + The following "naming schemes" have been defined: + + + + rhel-8.0 + + Naming was changed for virtual network interfaces created with SR-IOV and NPAR and + for devices where the PCI network controller device does not have a slot number associated. + + SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of + vport, where port is the + virtual device number. Previously those virtual devices were named as if completely independent. + + + The ninth and later NPAR virtual devices are named following the scheme used for the first + eight NPAR partitions. Previously those devices were not renamed and the kernel default + ("ethN") was used. + + Names are also generated for PCI devices where the PCI network controller device does not + have an associated slot number itself, but one of its parents does. Previously those devices were + not renamed and the kernel default was used. + + + + + rhel-8.1 + + Same as naming scheme rhel-8.0. + + + + rhel-8.2 + + Same as naming scheme rhel-8.0. + + + + rhel-8.3 + + Same as naming scheme rhel-8.0. + + + Note that latest may be used to denote the latest scheme known (to this + particular version of systemd. + + + + + Examples + + + Using <command>udevadm test-builtin</command> to display device properties + + $ udevadm test-builtin net_id /sys/class/net/enp0s31f6 +... +Using default interface naming scheme 'rhel-8.3'. +ID_NET_NAMING_SCHEME=rhel-8.3 +ID_NET_NAME_MAC=enx54ee75cb1dc0 +ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd. +ID_NET_NAME_PATH=enp0s31f6 +... + + + + PCI Ethernet card with firmware index "1" + + ID_NET_NAME_ONBOARD=eno1 +ID_NET_NAME_ONBOARD_LABEL=enEthernet Port 1 + + + + + + PCI Ethernet card in hotplug slot with firmware index number + + # /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1 +ID_NET_NAME_MAC=enx000000000466 +ID_NET_NAME_PATH=enp5s0 +ID_NET_NAME_SLOT=ens1 + + + + PCI Ethernet multi-function card with 2 ports + + # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0 +ID_NET_NAME_MAC=enx78e7d1ea46da +ID_NET_NAME_PATH=enp2s0f0 + +# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1 +ID_NET_NAME_MAC=enx78e7d1ea46dc +ID_NET_NAME_PATH=enp2s0f1 + + + + PCI WLAN card + + # /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0 +ID_NET_NAME_MAC=wlx0024d7e31130 +ID_NET_NAME_PATH=wlp3s0 + + + + USB built-in 3G modem + + # /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6 +ID_NET_NAME_MAC=wwx028037ec0200 +ID_NET_NAME_PATH=wwp0s29u1u4i6 + + + + USB Android phone + + # /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2 +ID_NET_NAME_MAC=enxd626b3450fb5 +ID_NET_NAME_PATH=enp0s29u1u2 + + + + s390 grouped CCW interface + + # /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0 +ID_NET_NAME_MAC=enx026d3c00000a +ID_NET_NAME_PATH=encf5f0 + + + + + See Also + + udev7, + udevadm8, + the + original page describing stable interface names + + + + diff --git a/src/udev/udev-builtin-net_id.c b/src/udev/udev-builtin-net_id.c index d85dc2848b..aa553d5ade 100644 --- a/src/udev/udev-builtin-net_id.c +++ b/src/udev/udev-builtin-net_id.c @@ -78,6 +78,7 @@ * /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0 * ID_NET_NAME_MAC=enx026d3c00000a * ID_NET_NAME_PATH=encf5f0 + * When the code here is changed, man/systemd.net-naming-scheme.xml must be updated too. */ #include