From: Zbigniew Jędrzejewski-Szmek Date: Thu, 9 May 2019 10:34:30 +0000 (+0200) Subject: man: describe naming schemes in a new man page X-Git-Tag: v243-rc1~454^2~2 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0b1e5b6ed8c6b9a2bc53709eb75e381d360f05bf;p=thirdparty%2Fsystemd.git 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 --- diff --git a/man/rules/meson.build b/man/rules/meson.build index 68941584664..13feadc66f3 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -824,6 +824,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 cf8087ccb31..c267bb2b114 100644 --- a/man/systemd-udevd.service.xml +++ b/man/systemd-udevd.service.xml @@ -171,15 +171,12 @@ 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: v238, v239, v240 which each - implement the naming scheme that was the default in the indicated systemd version. In addition, - latest may be used to designate the latest scheme known (to this particular - version of systemd-udevd.service). + 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 @@ -188,9 +185,8 @@ - - + + See Also diff --git a/man/systemd.link.xml b/man/systemd.link.xml index ea744bd2517..b1be32955e5 100644 --- a/man/systemd.link.xml +++ b/man/systemd.link.xml @@ -278,6 +278,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. @@ -287,6 +288,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. @@ -295,7 +297,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. + @@ -303,7 +307,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 00000000000..f86ad8d63a9 --- /dev/null +++ b/man/systemd.net-naming-scheme.xml @@ -0,0 +1,418 @@ + + + + + + + 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 + + + ib + InfiniBand + + + 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 iaddress nport_name + Netdevsim (simulated networking device) device number and port name + + + + 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: + + + + v238 + + This is the naming naming that was implemented in systemd 238. + + + + v239 + + 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. + + + + + v240 + + The ib prefix and stable names for infiniband devices are + introduced. Previously those devices were not renamed. + + The ACPI index field (used in ID_NET_NAME_ONBOARD=) is now also used when + 0. + + A new naming policy NamePolicy=keep was introduced. With this policy, if + the network device name was already set by userspace, the device will not be renamed + again. Previously, this naming policy applied implicitly, and now it must be explicitly + requested. Effectively, this means that network devices will be renamed according to the + configuration, even if they have been renamed already, if keep is not + specified as the naming policy in the .link file. See + systemd.link5 + for a description of NamePolicy=. + + + + v243 + + Support for netdevsim (simulated networking devices) was added. Previously those devices were + not renamed. + + + 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 'v243'. +ID_NET_NAMING_SCHEME=v243 +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 + + + + PCI IB host adapter with 2 ports + + # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0 +ID_NET_NAME_PATH=ibp21s0f0 + +# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1 +ID_NET_NAME_PATH=ibp21s0f1 + + + + 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 2c7dcf7d2a1..4fcde34813f 100644 --- a/src/udev/udev-builtin-net_id.c +++ b/src/udev/udev-builtin-net_id.c @@ -9,86 +9,7 @@ * * http://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames * - * Two character prefixes based on the type of interface: - * en — Ethernet - * ib — InfiniBand - * sl — serial line IP (slip) - * wl — wlan - * ww — wwan - * - * Type of names: - * b — BCMA bus core number - * c — bus id of a grouped CCW or CCW device, - * with all leading zeros stripped [s390] - * o[n|d] - * — on-board device index number - * s[f][n|d] - * — hotplug slot index number - * x — MAC address - * [P]ps[f][n|d] - * — PCI geographical location - * [P]ps[f][u][..][c][i] - * — USB port number chain - * v - VIO slot number (IBM PowerVM) - * ai — Platform bus ACPI instance id - * in — Netdevsim bus address and port name - * - * All multi-function PCI devices will carry the [f] number in the - * device name, including the function 0 device. - * - * SR-IOV virtual devices are named based on the name of the parent interface, - * with a suffix of "v", where is the virtual device number. - * - * When using PCI geography, The PCI domain is only prepended when it is not 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 == 1 and interface == 0 values are suppressed. - * - * PCI Ethernet card with firmware index "1": - * ID_NET_NAME_ONBOARD=eno1 - * ID_NET_NAME_ONBOARD_LABEL=Ethernet 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 - * - * PCI IB host adapter with 2 ports: - * /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0 - * ID_NET_NAME_PATH=ibp21s0f0 - * /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1 - * ID_NET_NAME_PATH=ibp21s0f1 - * - * 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 + * When the code here is changed, man/systemd.net-naming-scheme.xml must be updated too. */ #include