udev: allow/denylist for reading sysfs attributes when composing a NIC name

[thirdparty/systemd.git] / man / systemd.net-naming-scheme.xml

diff --git a/man/systemd.net-naming-scheme.xml b/man/systemd.net-naming-scheme.xml
index e9c00c935dc9030dc5652c654ce0327dea986d3f..63e7d3cc0bbbbd7ae0b3c0bc082b6de443b1b608 100644 (file)
--- a/man/systemd.net-naming-scheme.xml
+++ b/man/systemd.net-naming-scheme.xml
@@ -531,6 +531,47 @@
     particular version of systemd).</para>
   </refsect1>
 
+  <refsect1>
+    <title>Limiting the use of specific sysfs attributes</title>
+
+    <para>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's name can still change when a new kernel version adds a new sysfs attribute.
+    For example if kernel starts setting the <constant>phys_port_name</constant>, udev will append the
+    "<constant>n</constant><replaceable>phys_port_name</replaceable>" suffix to the device name.</para>
+
+    <variablelist>
+      <varlistentry>
+        <term><varname>ID_NET_NAME_ALLOW=<replaceable>BOOL</replaceable></varname></term>
+
+        <listitem><para>This evironment value sets a fallback policy for reading a sysfs attribute.
+        If set to <constant>0</constant> udev will not read any sysfs attribute by default, unless it is
+        explicitly allowlisted, see below. If set to <constant>1</constant> udev can use any sysfs attribute
+        unless it is explicitly forbidden. The default value is <constant>1</constant>.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry>
+        <term><varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=<replaceable>BOOL</replaceable></varname></term>
+
+        <listitem><para>This evironment value explicitly states if udev shall use the specified
+        <replaceable>sysfsattr</replaceable>, when composing the device name.</para>
+
+        <xi:include href="version-info.xml" xpointer="v256"/>
+        </listitem>
+      </varlistentry>
+    </variablelist>
+
+    <para>With these options, users can set an allowlist or denylist for sysfs attributes. To create
+    an allowlist, the user needs to set <varname>ID_NET_NAME_ALLOW=0</varname> for the device and then list
+    the allowed attributes with the
+    <varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=1</varname>
+    options. In case of a denylist, the user needs to provide the list of denied attributes with
+    the <varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=0</varname> options.</para>
+  </refsect1>
+
   <refsect1>
     <title>Examples</title>
 
@@ -617,6 +658,36 @@ ID_NET_NAME_PATH=enp0s29u1u2</programlisting>
 ID_NET_NAME_MAC=enx026d3c00000a
 ID_NET_NAME_PATH=encf5f0</programlisting>
     </example>
+
+    <example>
+      <title>Set an allowlist for reading sysfs attributes for network card naming</title>
+
+      <programlisting><filename>/etc/udev/hwdb.d/50-net-naming-allowlist.hwdb</filename>
+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</programlisting>
+    </example>
+
+    <example>
+      <title>Set a denylist so that specified sysfs attribute are ignored</title>
+
+      <programlisting><filename>/etc/udev/hwdb.d/50-net-naming-denylist.hwdb</filename>
+net:naming:drvirtio_net:*
+  ID_NET_NAME_ALLOW=1
+  ID_NET_NAME_ALLOW_DEV_PORT=0
+  ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
+      </programlisting>
+    </example>
   </refsect1>
 
   <refsect1>