Adding upstream version 4.23.0.upstream/4.23.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 85 insertions, 14 deletions

diff --git a/upstream/debian-unstable/man7/systemd.net-naming-scheme.7 b/upstream/debian-unstable/man7/systemd.net-naming-scheme.7
index b0d4fe7b..28ef2fa9 100644
--- a/upstream/debian-unstable/man7/systemd.net-naming-scheme.7
+++ b/upstream/debian-unstable/man7/systemd.net-naming-scheme.7
@@ -1,5 +1,5 @@
 '\" t
-.TH "SYSTEMD\&.NET\-NAMING\-SCHEME" "7" "" "systemd 255" "systemd.net-naming-scheme"
+.TH "SYSTEMD\&.NET\-NAMING\-SCHEME" "7" "" "systemd 256~rc3" "systemd.net-naming-scheme"
 .\" -----------------------------------------------------------------
 .\" * Define some portability stuff
 .\" -----------------------------------------------------------------
@@ -33,7 +33,7 @@ and exported as udev properties (\fIID_NET_NAME_ONBOARD=\fR,
 \fIID_NET_NAME_SLOT=\fR)\&.
 .PP
 Names and MAC addresses are derived from various stable device metadata attributes\&. Newer versions of udev take more of these attributes into account, improving (and thus possibly changing) the names and addresses used for the same devices\&. Different versions of those generation 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 overridden using the
-\fInet\&.naming\-scheme=\fR
+\fInet\&.naming_scheme=\fR
 kernel command line switch, see
 \fBsystemd-udevd.service\fR(8)\&. Available naming schemes are described below\&.
 .PP
@@ -103,7 +103,7 @@ The udev
 \fBnet_id\fR
 builtin exports the following udev device properties:
 .PP
-\fIID_NET_NAME_ONBOARD=\fR\fI\fIprefix\fR\fR\fI\fBo\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_ONBOARD=\fR\fI\fIprefix\fR\fR\fI\fBd\fR\fR\fI\fInumber\fR\fR
+\fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBo\fR\fInumber\fR, \fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBd\fR\fInumber\fR
 .RS 4
 This name is set based on the numeric ordering information given by the firmware for on\-board devices\&. Different schemes are used depending on the firmware type, as described in the table below\&.
 .sp
@@ -138,14 +138,14 @@ T}
 Added in version 243\&.
 .RE
 .PP
-\fIID_NET_LABEL_ONBOARD=\fR\fI\fIprefix\fR\fR\fI \fR\fI\fIlabel\fR\fR
+\fIID_NET_LABEL_ONBOARD=\fR\fIprefix\fR \fIlabel\fR
 .RS 4
 This property is set based on textual 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\&.
 .sp
 Added in version 243\&.
 .RE
 .PP
-\fIID_NET_NAME_MAC=\fR\fI\fIprefix\fR\fR\fI\fBx\fR\fR\fI\fIAABBCCDDEEFF\fR\fR
+\fIID_NET_NAME_MAC=\fR\fIprefix\fR\fBx\fR\fIAABBCCDDEEFF\fR
 .RS 4
 This name consists of the prefix, letter
 \fBx\fR, 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\&.
@@ -153,7 +153,7 @@ This name consists of the prefix, letter
 Added in version 243\&.
 .RE
 .PP
-\fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI\fBv\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI\fBx\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBb\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...[\fR\fI\fBc\fR\fR\fI\fIconfig\fR\fR\fI][\fR\fI\fBi\fR\fR\fI\fIinterface\fR\fR\fI]\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBv\fR\fR\fI\fIslot\fR\fR, \fIID_NET_NAME_SLOT=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBr\fR\fR\fI\fIslot\fR\fR
+\fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBx\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBr\fR\fIslot\fR
 .RS 4
 This property describes the slot position\&. Different schemes are used depending on the bus type, as described in the table below\&. 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\&.
 .sp
@@ -216,7 +216,7 @@ T}
 .TE
 .sp 1
 The PCI domain is only prepended when it is not 0\&. All multi\-function PCI devices will carry the
-\fBf\fR\fB\fIfunction\fR\fR
+\fBf\fR\fIfunction\fR
 number in the device name, including the function 0 device\&. For non\-multi\-function devices, the number is suppressed if 0\&. The port name
 \fIport_name\fR
 is used, or the port number
@@ -240,7 +240,7 @@ In some configurations a parent PCI bridge of a given network controller may be
 Added in version 243\&.
 .RE
 .PP
-\fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBc\fR\fR\fI\fIbus_id\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBa\fR\fR\fI\fIvendor\fR\fR\fI\fImodel\fR\fR\fI\fBi\fR\fR\fI\fIinstance\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBi\fR\fR\fI\fIaddress\fR\fR\fI\fBn\fR\fR\fI\fIport_name\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBb\fR\fR\fI\fInumber\fR\fR, \fIID_NET_NAME_PATH=\fR\fI\fIprefix\fR\fR\fI[\fR\fI\fBP\fR\fR\fI\fIdomain\fR\fR\fI]\fR\fI\fBp\fR\fR\fI\fIbus\fR\fR\fI\fBs\fR\fR\fI\fIslot\fR\fR\fI[\fR\fI\fBf\fR\fR\fI\fIfunction\fR\fR\fI][\fR\fI\fBn\fR\fR\fI\fIphys_port_name\fR\fR\fI|\fR\fI\fBd\fR\fR\fI\fIdev_port\fR\fR\fI]\fR\fI\fBu\fR\fR\fI\fIport\fR\fR\fI\&...[\fR\fI\fBc\fR\fR\fI\fIconfig\fR\fR\fI][\fR\fI\fBi\fR\fR\fI\fIinterface\fR\fR\fI]\fR
+\fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBc\fR\fIbus_id\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBa\fR\fIvendor\fR\fImodel\fR\fBi\fR\fIinstance\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBi\fR\fIaddress\fR\fBn\fR\fIport_name\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBu\fR\fIport\fR\&..., \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR]
 .RS 4
 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\&.
 .sp
@@ -305,7 +305,7 @@ Added in version 243\&.
 .SH "HISTORY"
 .PP
 The following "naming schemes" have been defined (which may be chosen at system boot\-up time via the
-\fInet\&.naming\-scheme=\fR
+\fInet\&.naming_scheme=\fR
 kernel command line switch, see above):
 .PP
 \fBv238\fR
@@ -459,7 +459,7 @@ Added in version 253\&.
 Naming was changed for SR\-IOV virtual device representors, optionally settable at compilation time\&. The
 "r\fIslot\fR"
 suffix was added to differentiate SR\-IOV virtual device representors attached to a single physical device interface\&. Because of a mistake, this scheme was
-\fInot the the default scheme for systemd version 254\fR\&.
+\fInot the default scheme for systemd version 254\fR\&.
 .sp
 Added in version 255\&.
 .RE
@@ -476,6 +476,38 @@ Added in version 255\&.
 Note that
 \fBlatest\fR
 may be used to denote the latest scheme known (to this particular version of systemd)\&.
+.SH "LIMITING THE USE OF SPECIFIC SYSFS ATTRIBUTES"
+.PP
+When creating names for network cards, some naming schemes use data from sysfs populated by the kernel\&. This means that although a specific naming scheme in udev is picked, the network card\*(Aqs name can still change when a new kernel version adds a new sysfs attribute\&. For example if kernel starts setting the
+\fBphys_port_name\fR, udev will append the "\fBn\fR\fIphys_port_name\fR" suffix to the device name\&.
+.PP
+\fIID_NET_NAME_ALLOW=\fR\fIBOOL\fR
+.RS 4
+This udev property sets a fallback policy for reading a sysfs attribute\&. If set to
+\fB0\fR
+udev will not read any sysfs attribute by default, unless it is explicitly allowlisted, see below\&. If set to
+\fB1\fR
+udev can use any sysfs attribute unless it is explicitly forbidden\&. The default value is
+\fB1\fR\&.
+.sp
+Added in version 256\&.
+.RE
+.PP
+\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=\fR\fI\fIBOOL\fR\fR
+.RS 4
+This udev property explicitly states if udev shall use the specified
+\fIsysfsattr\fR, when composing the device name\&.
+.sp
+Added in version 256\&.
+.RE
+.PP
+With these options, users can set an allowlist or denylist for sysfs attributes\&. To create an allowlist, the user needs to set
+\fIID_NET_NAME_ALLOW=0\fR
+for the device and then list the allowed attributes with the
+\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=1\fR
+options\&. In case of a denylist, the user needs to provide the list of denied attributes with the
+\fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=0\fR
+options\&.
 .SH "EXAMPLES"
 .PP
 \fBExample\ \&1.\ \&Using udevadm test\-builtin to display device properties\fR
@@ -615,12 +647,51 @@ ID_NET_NAME_PATH=encf5f0
 .if n \{\
 .RE
 .\}
+.PP
+\fBExample\ \&10.\ \&Set an allowlist for reading sysfs attributes for network card naming\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+/etc/udev/hwdb\&.d/50\-net\-naming\-allowlist\&.hwdb
+net:naming:drvirtio_net:*
+  ID_NET_NAME_ALLOW=0
+  ID_NET_NAME_ALLOW_ACPI_INDEX=1
+  ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1
+  ID_NET_NAME_ALLOW_ADDRESS=1
+  ID_NET_NAME_ALLOW_ARI_ENABLED=1
+  ID_NET_NAME_ALLOW_DEV_PORT=1
+  ID_NET_NAME_ALLOW_FUNCTION_ID=1
+  ID_NET_NAME_ALLOW_IFLINK=1
+  ID_NET_NAME_ALLOW_INDEX=1
+  ID_NET_NAME_ALLOW_LABEL=1
+  ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1
+  ID_NET_NAME_ALLOW_TYPE=1
+.fi
+.if n \{\
+.RE
+.\}
+.PP
+\fBExample\ \&11.\ \&Set a denylist so that specified sysfs attribute are ignored\fR
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+/etc/udev/hwdb\&.d/50\-net\-naming\-denylist\&.hwdb
+net:naming:drvirtio_net:*
+  ID_NET_NAME_ALLOW=1
+  ID_NET_NAME_ALLOW_DEV_PORT=0
+  ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
+      
+.fi
+.if n \{\
+.RE
+.\}
 .SH "SEE ALSO"
 .PP
-\fBudev\fR(7),
-\fBudevadm\fR(8),
-\m[blue]\fBPredictable Network Interface Names\fR\m[]\&\s-2\u[1]\d\s+2,
-\fBsystemd-nspawn\fR(1)
+\fBudev\fR(7), \fBudevadm\fR(8), \m[blue]\fBPredictable Network Interface Names\fR\m[]\&\s-2\u[1]\d\s+2, \fBsystemd-nspawn\fR(1)
 .SH "NOTES"
 .IP " 1." 4
 Predictable Network Interface Names