man/systemd.net-naming-scheme.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="systemd.net-naming-scheme" xmlns:xi="http://www.w3.org/2001/XInclude">
   7   <refentryinfo>
   8     <title>systemd.net-naming-scheme</title>
   9     <productname>systemd</productname>
  10   </refentryinfo>
  11
  12   <refmeta>
  13     <refentrytitle>systemd.net-naming-scheme</refentrytitle>
  14     <manvolnum>7</manvolnum>
  15   </refmeta>
  16
  17   <refnamediv>
  18     <refname>systemd.net-naming-scheme</refname>
  19     <refpurpose>Network device naming schemes</refpurpose>
  20   </refnamediv>
  21
  22   <refsect1>
  23     <title>Description</title>
  24
  25     <para>Network interfaces names and MAC addresses may be generated based on certain stable interface
  26     attributes. This is possible when there is enough information about the device to generate those
  27     attributes and the use of this information is configured. This page describes interface naming, i.e. what
  28     possible names may be generated. Those names are generated by the
  29     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  30     builtin <command>net_id</command> and exported as udev properties
  31     (<varname>ID_NET_NAME_ONBOARD=</varname>, <varname>ID_NET_LABEL_ONBOARD=</varname>,
  32     <varname>ID_NET_NAME_PATH=</varname>, <varname>ID_NET_NAME_SLOT=</varname>).</para>
  33
  34     <para>Names and MAC addresses are derived from various stable device metadata attributes. Newer versions
  35     of udev take more of these attributes into account, improving (and thus possibly changing) the names and
  36     addresses used for the same devices. Different versions of those generation rules are called "naming
  37     schemes". The default naming scheme is chosen at compilation time. Usually this will be the latest
  38     implemented version, but it is also possible to set one of the older versions to preserve
  39     compatibility. This may be useful for example for distributions, which may introduce new versions of
  40     systemd in stable releases without changing the naming scheme. The naming scheme may also be overridden
  41     using the <varname>net.naming_scheme=</varname> kernel command line switch, see
  42     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  43     Available naming schemes are described below.</para>
  44
  45     <para>After the udev properties have been generated, appropriate udev rules may be used to actually rename
  46     devices based on those properties. See the description of <varname>NamePolicy=</varname> and
  47     <varname>MACAddressPolicy=</varname> in
  48     <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
  49
  50     <para>Note that while the concept of network interface naming schemes is primarily relevant in the
  51     context of <filename>systemd-udevd.service</filename>, the
  52     <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  53     container manager also takes it into account when naming network interfaces, see below.</para>
  54   </refsect1>
  55
  56   <refsect1>
  57     <title>Policies</title>
  58
  59     <para>All names start with a two-character prefix that signifies the interface type.</para>
  60
  61     <table>
  62       <title>Two character prefixes based on the type of interface</title>
  63
  64       <tgroup cols='2'>
  65         <thead>
  66           <row>
  67             <entry>Prefix</entry>
  68             <entry>Description</entry>
  69           </row>
  70         </thead>
  71         <tbody>
  72           <row>
  73             <entry><constant>en</constant></entry>
  74             <entry>Ethernet</entry>
  75           </row>
  76           <row>
  77             <entry><constant>ib</constant></entry>
  78             <entry>InfiniBand</entry>
  79           </row>
  80           <row>
  81             <entry><constant>sl</constant></entry>
  82             <entry>Serial line IP (slip)</entry>
  83           </row>
  84           <row>
  85             <entry><constant>wl</constant></entry>
  86             <entry>Wireless local area network (WLAN)</entry>
  87           </row>
  88           <row>
  89             <entry><constant>ww</constant></entry>
  90             <entry>Wireless wide area network (WWAN)</entry>
  91           </row>
  92         </tbody>
  93       </tgroup>
  94     </table>
  95
  96     <para>The udev <command>net_id</command> builtin exports the following udev device properties:</para>
  97
  98     <variablelist>
  99         <varlistentry>
 100           <term><varname>ID_NET_NAME_ONBOARD=</varname><replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></term>
 101           <term><varname>ID_NET_NAME_ONBOARD=</varname><replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></term>
 102
 103           <listitem><para>This name is set based on the numeric ordering information given by the firmware
 104           for on-board devices. Different schemes are used depending on the firmware type, as described in
 105           the table below.</para>
 106
 107             <table>
 108               <title>On-board naming schemes</title>
 109
 110               <tgroup cols='2'>
 111                 <thead>
 112                   <row>
 113                     <entry>Format</entry>
 114                     <entry>Description</entry>
 115                   </row>
 116                 </thead>
 117
 118                 <tbody>
 119                   <row>
 120                     <entry><replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></entry>
 121                     <entry>PCI on-board index</entry>
 122                   </row>
 123
 124                   <row>
 125                     <entry><replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></entry>
 126                     <entry>Devicetree alias index</entry>
 127                   </row>
 128
 129                 </tbody>
 130               </tgroup>
 131             </table>
 132
 133               <xi:include href="version-info.xml" xpointer="v243"/>
 134           </listitem>
 135         </varlistentry>
 136
 137         <varlistentry>
 138           <term><varname>ID_NET_LABEL_ONBOARD=</varname><replaceable>prefix</replaceable> <replaceable>label</replaceable></term>
 139
 140           <listitem><para>This property is set based on textual label given by the firmware for on-board
 141           devices. The name consists of the prefix concatenated with the label. This is only available for
 142           PCI devices.
 143           </para>
 144
 145           <xi:include href="version-info.xml" xpointer="v243"/>
 146           </listitem>
 147         </varlistentry>
 148
 149         <varlistentry>
 150           <term><varname>ID_NET_NAME_MAC=</varname><replaceable>prefix</replaceable><constant>x</constant><replaceable>AABBCCDDEEFF</replaceable></term>
 151
 152           <listitem><para>This name consists of the prefix, letter <constant>x</constant>, and 12 hexadecimal
 153           digits of the MAC address. It is available if the device has a fixed MAC address. Because this name
 154           is based on an attribute of the card itself, it remains "stable" when the device is moved (even
 155           between machines), but will change when the hardware is replaced.</para>
 156
 157           <xi:include href="version-info.xml" xpointer="v243"/>
 158           </listitem>
 159         </varlistentry>
 160
 161         <varlistentry>
 162           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]</term>
 163           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable><constant>v</constant><replaceable>slot</replaceable></term>
 164           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable><constant>x</constant><replaceable>slot</replaceable></term>
 165           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>b</constant><replaceable>number</replaceable></term>
 166           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>u</constant><replaceable>port</replaceable>…[<constant>c</constant><replaceable>config</replaceable>][<constant>i</constant><replaceable>interface</replaceable>]</term>
 167           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>v</constant><replaceable>slot</replaceable></term>
 168           <term><varname>ID_NET_NAME_SLOT=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>r</constant><replaceable>slot</replaceable></term>
 169
 170           <listitem><para>This property describes the slot position. Different schemes are used depending on
 171           the bus type, as described in the table below. In case of USB, BCMA, and SR-VIO devices, the full
 172           name consists of the prefix, PCI slot identifier, and USB or BCMA or SR-VIO slot identifier. The
 173           first two parts are denoted as "…" in the table below.</para>
 174
 175           <table>
 176             <title>Slot naming schemes</title>
 177
 178             <tgroup cols='2'>
 179               <thead>
 180                 <row>
 181                   <entry>Format</entry>
 182                   <entry>Description</entry>
 183                 </row>
 184               </thead>
 185
 186               <tbody>
 187                 <row>
 188                   <entry><replaceable>prefix</replaceable> [<constant>P</constant><replaceable>domain</replaceable>] <constant>s</constant><replaceable>slot</replaceable> [<constant>f</constant><replaceable>function</replaceable>] [<constant>n</constant><replaceable>port_name</replaceable> | <constant>d</constant><replaceable>dev_port</replaceable>]</entry>
 189                   <entry>PCI slot number</entry>
 190                 </row>
 191
 192                 <row>
 193                   <entry><replaceable>prefix</replaceable> <constant>v</constant><replaceable>slot</replaceable></entry>
 194                   <entry>VIO slot number (IBM PowerVM)</entry>
 195                 </row>
 196
 197                 <row>
 198                   <entry><replaceable>prefix</replaceable> <constant>X</constant><replaceable>number</replaceable></entry>
 199                   <entry>VIF interface number (Xen)</entry>
 200                 </row>
 201
 202                 <row>
 203                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 204                   <entry>Broadcom bus (BCMA) core number</entry>
 205                 </row>
 206
 207                 <row>
 208                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 209                   <entry>USB port number chain</entry>
 210                 </row>
 211
 212                 <row>
 213                   <entry>… <constant>v</constant><replaceable>slot</replaceable></entry>
 214                   <entry>SR-VIO slot number</entry>
 215                 </row>
 216
 217                 <row>
 218                   <entry>… <constant>r</constant><replaceable>slot</replaceable></entry>
 219                   <entry>SR-IOV slot number</entry>
 220                 </row>
 221               </tbody>
 222             </tgroup>
 223           </table>
 224
 225           <para>The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry
 226           the <constant>f</constant><replaceable>function</replaceable> number in the device name, including
 227           the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name
 228           <replaceable>port_name</replaceable> is used, or the port number
 229           <constant>d</constant><replaceable>dev_port</replaceable> if the name is not known.</para>
 230
 231           <para>For BCMA devices, the core number is suppressed when 0.</para>
 232
 233           <para>For USB devices the full chain of port numbers of hubs is composed. If the name gets longer
 234           than the maximum number of 15 characters, the name is not exported. The usual USB configuration
 235           number 1 and interface number 0 values are suppressed.</para>
 236
 237           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 238           <constant>v</constant> and the virtual device number, with any leading zeros removed. The bus
 239           number is ignored.</para>
 240
 241           <para>SR-IOV virtual device representors are named based on the name of the physical device
 242           interface, with a suffix of <constant>r</constant> and the number of the virtual device that
 243           is linked to the particular representor, with any leading zeros removed. The physical port
 244           name and the bus number are ignored.</para>
 245
 246           <para>In some configurations a parent PCI bridge of a given network controller may be associated
 247           with a slot. In such case we don't generate this device property to avoid possible naming conflicts.</para>
 248
 249           <xi:include href="version-info.xml" xpointer="v243"/>
 250           </listitem>
 251         </varlistentry>
 252
 253         <varlistentry>
 254           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable><constant>c</constant><replaceable>bus_id</replaceable></term>
 255           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable><constant>a</constant><replaceable>vendor</replaceable><replaceable>model</replaceable><constant>i</constant><replaceable>instance</replaceable></term>
 256           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable><constant>i</constant><replaceable>address</replaceable><constant>n</constant><replaceable>port_name</replaceable></term>
 257           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable><constant>u</constant><replaceable>port</replaceable>…</term>
 258           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>p</constant><replaceable>bus</replaceable><constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>phys_port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]</term>
 259           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>p</constant><replaceable>bus</replaceable><constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>phys_port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>b</constant><replaceable>number</replaceable></term>
 260           <term><varname>ID_NET_NAME_PATH=</varname><replaceable>prefix</replaceable>[<constant>P</constant><replaceable>domain</replaceable>]<constant>p</constant><replaceable>bus</replaceable><constant>s</constant><replaceable>slot</replaceable>[<constant>f</constant><replaceable>function</replaceable>][<constant>n</constant><replaceable>phys_port_name</replaceable>|<constant>d</constant><replaceable>dev_port</replaceable>]<constant>u</constant><replaceable>port</replaceable>…[<constant>c</constant><replaceable>config</replaceable>][<constant>i</constant><replaceable>interface</replaceable>]</term>
 261
 262           <listitem><para>This property describes the device installation location. Different schemes are
 263           used depending on the bus type, as described in the table below. For BCMA and USB devices, PCI path
 264           information must known, and the full name consists of the prefix, PCI slot identifier, and USB or
 265           BCMA location. The first two parts are denoted as "…" in the table below.</para>
 266
 267           <table>
 268             <title>Path naming schemes</title>
 269
 270             <tgroup cols='2'>
 271               <thead>
 272                 <row>
 273                   <entry>Format</entry>
 274                   <entry>Description</entry>
 275                 </row>
 276               </thead>
 277
 278               <tbody>
 279                 <row>
 280                   <entry><replaceable>prefix</replaceable> <constant>c</constant><replaceable>bus_id</replaceable></entry>
 281                   <entry>CCW or grouped CCW device identifier</entry>
 282                 </row>
 283
 284                 <row>
 285                   <entry><replaceable>prefix</replaceable> <constant>a</constant><replaceable>vendor</replaceable> <replaceable>model</replaceable> <constant>i</constant><replaceable>instance</replaceable></entry>
 286                   <entry>ACPI path names for ARM64 platform devices</entry>
 287                 </row>
 288
 289                 <row>
 290                   <entry><replaceable>prefix</replaceable> <constant>i</constant><replaceable>address</replaceable> <constant>n</constant><replaceable>port_name</replaceable></entry>
 291                   <entry>Netdevsim (simulated networking device) device number and port name</entry>
 292                 </row>
 293
 294                 <row>
 295                   <entry><replaceable>prefix</replaceable> [<constant>P</constant><replaceable>domain</replaceable>] <constant>p</constant><replaceable>bus</replaceable> <constant>s</constant><replaceable>slot</replaceable> [<constant>f</constant><replaceable>function</replaceable>] [<constant>n</constant><replaceable>phys_port_name</replaceable> | <constant>d</constant><replaceable>dev_port</replaceable>]</entry>
 296                   <entry>PCI geographical location</entry>
 297                 </row>
 298
 299                 <row>
 300                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 301                   <entry>Broadcom bus (BCMA) core number</entry>
 302                 </row>
 303
 304                 <row>
 305                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 306                   <entry>USB port number chain</entry>
 307                 </row>
 308
 309               </tbody>
 310             </tgroup>
 311           </table>
 312
 313           <para>CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and
 314           dots are suppressed.</para>
 315
 316           <para>For PCI, BCMA, and USB devices, the same rules as described above for slot naming are
 317           used.</para>
 318
 319           <xi:include href="version-info.xml" xpointer="v243"/>
 320           </listitem>
 321         </varlistentry>
 322     </variablelist>
 323   </refsect1>
 324
 325   <refsect1>
 326     <title>History</title>
 327
 328     <para>The following "naming schemes" have been defined (which may be chosen at system boot-up time via
 329     the <varname>net.naming_scheme=</varname> kernel command line switch, see above):</para>
 330
 331     <variablelist>
 332         <varlistentry>
 333           <term><constant>v238</constant></term>
 334
 335           <listitem><para>This is the naming scheme that was implemented in systemd 238.</para>
 336
 337           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 338         </varlistentry>
 339
 340         <varlistentry>
 341           <term><constant>v239</constant></term>
 342
 343           <listitem><para>Naming was changed for virtual network interfaces created with SR-IOV and NPAR and
 344           for devices where the PCI network controller device does not have a slot number associated.</para>
 345
 346           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 347           <literal>v<replaceable>port</replaceable></literal>, where <replaceable>port</replaceable> is the
 348           virtual device number. Previously those virtual devices were named as if completely independent.
 349           </para>
 350
 351           <para>The ninth and later NPAR virtual devices are named following the scheme used for the first
 352           eight NPAR partitions. Previously those devices were not renamed and the kernel default
 353           ("eth<replaceable>N</replaceable>") was used.</para>
 354
 355           <para>Names are also generated for PCI devices where the PCI network controller device does not
 356           have an associated slot number itself, but one of its parents does. Previously those devices were
 357           not renamed and the kernel default was used.</para>
 358
 359           <xi:include href="version-info.xml" xpointer="v243"/>
 360           </listitem>
 361         </varlistentry>
 362
 363         <varlistentry>
 364           <term><constant>v240</constant></term>
 365
 366           <listitem><para>The <literal>ib</literal> prefix and stable names for infiniband devices are
 367           introduced. Previously those devices were not renamed.</para>
 368
 369           <para>The ACPI index field (used in <varname>ID_NET_NAME_ONBOARD=</varname>) is now also used when
 370           0.</para>
 371
 372           <para>A new naming policy <varname>NamePolicy=keep</varname> was introduced. With this policy, if
 373           the network device name was already set by userspace, the device will not be renamed
 374           again. Previously, this naming policy applied implicitly, and now it must be explicitly
 375           requested. Effectively, this means that network devices will be renamed according to the
 376           configuration, even if they have been renamed already, if <constant>keep</constant> is not
 377           specified as the naming policy in the <filename index="false">.link</filename> file. See
 378           <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 379           for a description of <varname>NamePolicy=</varname>.</para>
 380
 381           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 382         </varlistentry>
 383
 384         <varlistentry>
 385           <term><constant>v241</constant></term>
 386
 387           <listitem><para><option>MACAddressPolicy=persistent</option> was extended to set MAC addresses
 388           based on the device name. Previously addresses were only based on the
 389           <varname index="false">ID_NET_NAME_*</varname> attributes, which meant that interface names would
 390           never be generated for virtual devices. Now a persistent address will be generated for most
 391           devices, including in particular bridges.</para>
 392
 393           <para>Note: when userspace does not set a MAC address for a bridge device, the kernel will
 394           initially assign a random address, and then change it when the first device is enslaved to the
 395           bridge. With this naming policy change, bridges get a persistent MAC address based on the bridge
 396           name instead of the first enslaved device.</para>
 397
 398           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 399         </varlistentry>
 400
 401         <varlistentry>
 402           <term><constant>v243</constant></term>
 403
 404           <listitem><para>Support for renaming netdevsim (simulated networking) devices was added. Previously
 405           those devices were not renamed.</para>
 406
 407           <para>Previously two-letter interface type prefix was prepended to
 408           <varname>ID_NET_LABEL_ONBOARD=</varname>. This is not done anymore.</para>
 409
 410           <xi:include href="version-info.xml" xpointer="v243"/></listitem>
 411         </varlistentry>
 412
 413         <varlistentry>
 414           <term><constant>v245</constant></term>
 415
 416           <listitem><para>When
 417           <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 418           derives the name for the host side of the network interface created with
 419           <option>--network-veth</option> from the container name it previously simply truncated the result
 420           at 15 characters if longer (since that's the maximum length for network interface names). From now
 421           on, for any interface name that would be longer than 15 characters the last 4 characters are set to
 422           a 24bit hash value of the full interface name. This way network interface name collisions between
 423           multiple similarly named containers (who only differ in container name suffix) should be less
 424           likely (but still possible, since the 24bit hash value is very small).</para>
 425
 426           <xi:include href="version-info.xml" xpointer="v245"/></listitem>
 427         </varlistentry>
 428
 429         <varlistentry>
 430           <term><constant>v247</constant></term>
 431
 432           <listitem><para>When a PCI slot is associated with a PCI bridge that has multiple child network
 433           controllers, the same value of the <varname>ID_NET_NAME_SLOT</varname> property might be derived
 434           for those controllers. This would cause a naming conflict if the property is selected as the device
 435           name. Now, we detect this situation and don't produce the <varname>ID_NET_NAME_SLOT</varname>
 436           property.</para>
 437
 438           <xi:include href="version-info.xml" xpointer="v247"/></listitem>
 439         </varlistentry>
 440
 441         <varlistentry>
 442           <term><constant>v249</constant></term>
 443
 444           <listitem><para>PCI hotplug slot names for the s390 PCI driver are a hexadecimal representation
 445           of the <filename>function_id</filename> device attribute. This attribute is now used to build the
 446           <varname>ID_NET_NAME_SLOT</varname>. Before that, all slot names were parsed as decimal
 447           numbers, which could either result in an incorrect value of the <varname>ID_NET_NAME_SLOT</varname>
 448           property or none at all.</para>
 449
 450           <para>Some firmware and hypervisor implementations report unreasonably high numbers for the
 451           on-board index. To prevent the generation of bogus on-board interface names, index numbers greater
 452           than 16381 (2¹⁴-1) were ignored. For s390 PCI devices index values up to 65535 (2¹⁶-1) are valid.
 453           To account for that, the limit was increased to 65535.</para>
 454
 455           <para>The udev rule <varname>NAME=</varname> replaces <literal>:</literal>,
 456           <literal>/</literal>, and <literal>%</literal> with an underscore (<literal>_</literal>), and
 457           refuses strings which contain only numerics.</para>
 458
 459           <xi:include href="version-info.xml" xpointer="v249"/>
 460           </listitem>
 461         </varlistentry>
 462
 463         <varlistentry>
 464           <term><constant>v250</constant></term>
 465
 466           <listitem><para>Added naming scheme for Xen netfront "vif" interfaces based on the guest side
 467           VIF number set from the Xen config (or the interface index in AWS EC2).</para>
 468
 469           <xi:include href="version-info.xml" xpointer="v250"/>
 470           </listitem>
 471         </varlistentry>
 472
 473         <varlistentry>
 474           <term><constant>v251</constant></term>
 475
 476           <listitem><para>Since version <constant>v247</constant> we no longer set
 477           <varname>ID_NET_NAME_SLOT</varname> if we detect that a PCI device associated with a slot is a PCI
 478           bridge as that would create naming conflict when there are more child devices on that bridge. Now,
 479           this is relaxed and we will use slot information to generate the name based on it but only if
 480           the PCI device has multiple functions. This is safe because distinct function number is a part of
 481           the device name for multifunction devices.</para>
 482
 483           <xi:include href="version-info.xml" xpointer="v251"/>
 484           </listitem>
 485         </varlistentry>
 486
 487         <varlistentry>
 488           <term><constant>v252</constant></term>
 489
 490           <listitem><para>Added naming scheme for platform devices with devicetree aliases.</para>
 491
 492           <xi:include href="version-info.xml" xpointer="v252"/>
 493           </listitem>
 494         </varlistentry>
 495
 496         <varlistentry>
 497           <term><constant>v253</constant></term>
 498
 499           <listitem><para>Set <varname>ID_NET_NAME_PATH</varname> for usb devices not connected via a PCI bus.</para>
 500
 501           <xi:include href="version-info.xml" xpointer="v253"/>
 502           </listitem>
 503         </varlistentry>
 504
 505         <varlistentry>
 506           <term><constant>v254</constant></term>
 507
 508           <listitem><para>Naming was changed for SR-IOV virtual device representors, optionally settable at
 509           compilation time. The <literal>r<replaceable>slot</replaceable></literal> suffix was added to
 510           differentiate SR-IOV virtual device representors attached to a single physical device interface.
 511           Because of a mistake, this scheme was <emphasis>not the the default scheme for systemd version
 512           254</emphasis>.</para>
 513
 514           <xi:include href="version-info.xml" xpointer="v255"/>
 515           </listitem>
 516         </varlistentry>
 517
 518         <varlistentry>
 519           <term><constant>v255</constant></term>
 520
 521           <listitem><para>Naming was changed for SR-IOV virtual device representors to enable the
 522           change introduced in <constant>v254</constant> by default.</para>
 523
 524           <xi:include href="version-info.xml" xpointer="v255"/>
 525           </listitem>
 526         </varlistentry>
 527
 528       </variablelist>
 529
 530     <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
 531     particular version of systemd).</para>
 532   </refsect1>
 533
 534   <refsect1>
 535     <title>Limiting the use of specific sysfs attributes</title>
 536
 537     <para>When creating names for network cards, some naming schemes use data from sysfs populated
 538     by the kernel. This means that although a specific naming scheme in udev is picked,
 539     the network card's name can still change when a new kernel version adds a new sysfs attribute.
 540     For example if kernel starts setting the <constant>phys_port_name</constant>, udev will append the
 541     "<constant>n</constant><replaceable>phys_port_name</replaceable>" suffix to the device name.</para>
 542
 543     <variablelist>
 544       <varlistentry>
 545         <term><varname>ID_NET_NAME_ALLOW=</varname><replaceable>BOOL</replaceable></term>
 546
 547         <listitem><para>This udev property sets a fallback policy for reading a sysfs attribute.
 548         If set to <constant>0</constant> udev will not read any sysfs attribute by default, unless it is
 549         explicitly allowlisted, see below. If set to <constant>1</constant> udev can use any sysfs attribute
 550         unless it is explicitly forbidden. The default value is <constant>1</constant>.</para>
 551
 552         <xi:include href="version-info.xml" xpointer="v256"/>
 553         </listitem>
 554       </varlistentry>
 555
 556       <varlistentry>
 557         <term><varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=<replaceable>BOOL</replaceable></varname></term>
 558
 559         <listitem><para>This udev property explicitly states if udev shall use the specified
 560         <replaceable>sysfsattr</replaceable>, when composing the device name.</para>
 561
 562         <xi:include href="version-info.xml" xpointer="v256"/>
 563         </listitem>
 564       </varlistentry>
 565     </variablelist>
 566
 567     <para>With these options, users can set an allowlist or denylist for sysfs attributes. To create
 568     an allowlist, the user needs to set <varname>ID_NET_NAME_ALLOW=0</varname> for the device and then list
 569     the allowed attributes with the
 570     <varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=1</varname>
 571     options. In case of a denylist, the user needs to provide the list of denied attributes with
 572     the <varname>ID_NET_NAME_ALLOW_<replaceable>sysfsattr</replaceable>=0</varname> options.</para>
 573   </refsect1>
 574
 575   <refsect1>
 576     <title>Examples</title>
 577
 578     <example>
 579       <title>Using <command>udevadm test-builtin</command> to display device properties</title>
 580
 581       <programlisting>$ udevadm test-builtin net_id /sys/class/net/enp0s31f6
 582 ...
 583 Using default interface naming scheme 'v243'.
 584 ID_NET_NAMING_SCHEME=v243
 585 ID_NET_NAME_MAC=enx54ee75cb1dc0
 586 ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
 587 ID_NET_NAME_PATH=enp0s31f6
 588 ...</programlisting>
 589     </example>
 590
 591     <example>
 592       <title>PCI Ethernet card with firmware index "1"</title>
 593
 594       <programlisting>ID_NET_NAME_ONBOARD=eno1
 595 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
 596       </programlisting>
 597     </example>
 598
 599     <example>
 600       <title>PCI Ethernet card in hotplug slot with firmware index number</title>
 601
 602       <programlisting># /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
 603 ID_NET_NAME_MAC=enx000000000466
 604 ID_NET_NAME_PATH=enp5s0
 605 ID_NET_NAME_SLOT=ens1</programlisting>
 606     </example>
 607
 608     <example>
 609       <title>PCI Ethernet multi-function card with 2 ports</title>
 610
 611       <programlisting># /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
 612 ID_NET_NAME_MAC=enx78e7d1ea46da
 613 ID_NET_NAME_PATH=enp2s0f0
 614
 615 # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
 616 ID_NET_NAME_MAC=enx78e7d1ea46dc
 617 ID_NET_NAME_PATH=enp2s0f1</programlisting>
 618     </example>
 619
 620     <example>
 621       <title>PCI WLAN card</title>
 622
 623       <programlisting># /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
 624 ID_NET_NAME_MAC=wlx0024d7e31130
 625 ID_NET_NAME_PATH=wlp3s0</programlisting>
 626     </example>
 627
 628     <example>
 629       <title>PCI IB host adapter with 2 ports</title>
 630
 631       <programlisting># /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
 632 ID_NET_NAME_PATH=ibp21s0f0
 633
 634 # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
 635 ID_NET_NAME_PATH=ibp21s0f1</programlisting>
 636     </example>
 637
 638     <example>
 639       <title>USB built-in 3G modem</title>
 640
 641       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
 642 ID_NET_NAME_MAC=wwx028037ec0200
 643 ID_NET_NAME_PATH=wwp0s29u1u4i6</programlisting>
 644     </example>
 645
 646     <example>
 647       <title>USB Android phone</title>
 648
 649       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
 650 ID_NET_NAME_MAC=enxd626b3450fb5
 651 ID_NET_NAME_PATH=enp0s29u1u2</programlisting>
 652     </example>
 653
 654     <example>
 655       <title>s390 grouped CCW interface</title>
 656
 657       <programlisting># /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
 658 ID_NET_NAME_MAC=enx026d3c00000a
 659 ID_NET_NAME_PATH=encf5f0</programlisting>
 660     </example>
 661
 662     <example>
 663       <title>Set an allowlist for reading sysfs attributes for network card naming</title>
 664
 665       <programlisting><filename>/etc/udev/hwdb.d/50-net-naming-allowlist.hwdb</filename>
 666 net:naming:drvirtio_net:*
 667   ID_NET_NAME_ALLOW=0
 668   ID_NET_NAME_ALLOW_ACPI_INDEX=1
 669   ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1
 670   ID_NET_NAME_ALLOW_ADDRESS=1
 671   ID_NET_NAME_ALLOW_ARI_ENABLED=1
 672   ID_NET_NAME_ALLOW_DEV_PORT=1
 673   ID_NET_NAME_ALLOW_FUNCTION_ID=1
 674   ID_NET_NAME_ALLOW_IFLINK=1
 675   ID_NET_NAME_ALLOW_INDEX=1
 676   ID_NET_NAME_ALLOW_LABEL=1
 677   ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1
 678   ID_NET_NAME_ALLOW_TYPE=1</programlisting>
 679     </example>
 680
 681     <example>
 682       <title>Set a denylist so that specified sysfs attribute are ignored</title>
 683
 684       <programlisting><filename>/etc/udev/hwdb.d/50-net-naming-denylist.hwdb</filename>
 685 net:naming:drvirtio_net:*
 686   ID_NET_NAME_ALLOW=1
 687   ID_NET_NAME_ALLOW_DEV_PORT=0
 688   ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
 689       </programlisting>
 690     </example>
 691   </refsect1>
 692
 693   <refsect1>
 694     <title>See Also</title>
 695     <para><simplelist type="inline">
 696       <member><citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
 697       <member><citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
 698       <member><ulink url="https://systemd.io/PREDICTABLE_INTERFACE_NAMES">Predictable Network Interface Names</ulink></member>
 699       <member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 700     </simplelist></para>
 701   </refsect1>
 702
 703 </refentry>