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.2/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=<replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></varname></term>
 101           <term><varname>ID_NET_NAME_ONBOARD=<replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></varname></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=<replaceable>prefix</replaceable> <replaceable>label</replaceable></varname></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=<replaceable>prefix</replaceable><constant>x</constant><replaceable>AABBCCDDEEFF</replaceable></varname></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=<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>]</varname></term>
 163           <term><varname>ID_NET_NAME_SLOT=<replaceable>prefix</replaceable><constant>v</constant><replaceable>slot</replaceable></varname></term>
 164           <term><varname>ID_NET_NAME_SLOT=<replaceable>prefix</replaceable><constant>x</constant><replaceable>slot</replaceable></varname></term>
 165           <term><varname>ID_NET_NAME_SLOT=<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></varname></term>
 166           <term><varname>ID_NET_NAME_SLOT=<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>]</varname></term>
 167           <term><varname>ID_NET_NAME_SLOT=<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></varname></term>
 168           <term><varname>ID_NET_NAME_SLOT=<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></varname></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<replaceable>function</replaceable></constant> 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=<replaceable>prefix</replaceable><constant>c</constant><replaceable>bus_id</replaceable></varname></term>
 255           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>a</constant><replaceable>vendor</replaceable><replaceable>model</replaceable><constant>i</constant><replaceable>instance</replaceable></varname></term>
 256           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>i</constant><replaceable>address</replaceable><constant>n</constant><replaceable>port_name</replaceable></varname></term>
 257           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>u</constant><replaceable>port</replaceable>…</varname></term>
 258           <term><varname>ID_NET_NAME_PATH=<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>]</varname></term>
 259           <term><varname>ID_NET_NAME_PATH=<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></varname></term>
 260           <term><varname>ID_NET_NAME_PATH=<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>]</varname></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. Note, this is reverted in <constant>v255</constant>.
 482           See below.</para>
 483
 484           <xi:include href="version-info.xml" xpointer="v251"/>
 485           </listitem>
 486         </varlistentry>
 487
 488         <varlistentry>
 489           <term><constant>v252</constant></term>
 490
 491           <listitem><para>Added naming scheme for platform devices with devicetree aliases.</para>
 492
 493           <xi:include href="version-info.xml" xpointer="v252"/>
 494           </listitem>
 495         </varlistentry>
 496
 497         <varlistentry>
 498           <term><constant>v253</constant></term>
 499
 500           <listitem><para>Set <varname>ID_NET_NAME_PATH</varname> for usb devices not connected via a PCI bus.</para>
 501
 502           <xi:include href="version-info.xml" xpointer="v253"/>
 503           </listitem>
 504         </varlistentry>
 505
 506         <varlistentry>
 507           <term><constant>v254</constant></term>
 508
 509           <listitem><para>Naming was changed for SR-IOV virtual device representors, optionally settable at
 510           compilation time. The <literal>r<replaceable>slot</replaceable></literal> suffix was added to
 511           differentiate SR-IOV virtual device representors attached to a single physical device interface.
 512           Because of a mistake, this scheme was <emphasis>not the the default scheme for systemd version
 513           254</emphasis>.</para>
 514
 515           <xi:include href="version-info.xml" xpointer="v255"/>
 516           </listitem>
 517         </varlistentry>
 518
 519         <varlistentry>
 520           <term><constant>v255</constant></term>
 521
 522           <listitem><para>Naming was changed for SR-IOV virtual device representors to enable the
 523           change introduced in <constant>v254</constant> by default.</para>
 524
 525           <para>If we detect that a PCI device associated with a slot is a PCI bridge, we no longer set
 526           <varname>ID_NET_NAME_SLOT</varname>, reverting a change that was introduced in v251.</para>
 527
 528           <xi:include href="version-info.xml" xpointer="v255"/>
 529           </listitem>
 530         </varlistentry>
 531
 532       </variablelist>
 533
 534     <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
 535     particular version of systemd).</para>
 536   </refsect1>
 537
 538   <refsect1>
 539     <title>Examples</title>
 540
 541     <example>
 542       <title>Using <command>udevadm test-builtin</command> to display device properties</title>
 543
 544       <programlisting>$ udevadm test-builtin net_id /sys/class/net/enp0s31f6
 545 ...
 546 Using default interface naming scheme 'v243'.
 547 ID_NET_NAMING_SCHEME=v243
 548 ID_NET_NAME_MAC=enx54ee75cb1dc0
 549 ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
 550 ID_NET_NAME_PATH=enp0s31f6
 551 ...</programlisting>
 552     </example>
 553
 554     <example>
 555       <title>PCI Ethernet card with firmware index "1"</title>
 556
 557       <programlisting>ID_NET_NAME_ONBOARD=eno1
 558 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
 559       </programlisting>
 560     </example>
 561
 562     <example>
 563       <title>PCI Ethernet card in hotplug slot with firmware index number</title>
 564
 565       <programlisting># /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
 566 ID_NET_NAME_MAC=enx000000000466
 567 ID_NET_NAME_PATH=enp5s0
 568 ID_NET_NAME_SLOT=ens1</programlisting>
 569     </example>
 570
 571     <example>
 572       <title>PCI Ethernet multi-function card with 2 ports</title>
 573
 574       <programlisting># /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
 575 ID_NET_NAME_MAC=enx78e7d1ea46da
 576 ID_NET_NAME_PATH=enp2s0f0
 577
 578 # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
 579 ID_NET_NAME_MAC=enx78e7d1ea46dc
 580 ID_NET_NAME_PATH=enp2s0f1</programlisting>
 581     </example>
 582
 583     <example>
 584       <title>PCI WLAN card</title>
 585
 586       <programlisting># /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
 587 ID_NET_NAME_MAC=wlx0024d7e31130
 588 ID_NET_NAME_PATH=wlp3s0</programlisting>
 589     </example>
 590
 591     <example>
 592       <title>PCI IB host adapter with 2 ports</title>
 593
 594       <programlisting># /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
 595 ID_NET_NAME_PATH=ibp21s0f0
 596
 597 # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
 598 ID_NET_NAME_PATH=ibp21s0f1</programlisting>
 599     </example>
 600
 601     <example>
 602       <title>USB built-in 3G modem</title>
 603
 604       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
 605 ID_NET_NAME_MAC=wwx028037ec0200
 606 ID_NET_NAME_PATH=wwp0s29u1u4i6</programlisting>
 607     </example>
 608
 609     <example>
 610       <title>USB Android phone</title>
 611
 612       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
 613 ID_NET_NAME_MAC=enxd626b3450fb5
 614 ID_NET_NAME_PATH=enp0s29u1u2</programlisting>
 615     </example>
 616
 617     <example>
 618       <title>s390 grouped CCW interface</title>
 619
 620       <programlisting># /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
 621 ID_NET_NAME_MAC=enx026d3c00000a
 622 ID_NET_NAME_PATH=encf5f0</programlisting>
 623     </example>
 624   </refsect1>
 625
 626   <refsect1>
 627     <title>See Also</title>
 628     <para>
 629       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 630       <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 631       <ulink url="https://systemd.io/PREDICTABLE_INTERFACE_NAMES">Predictable Network Interface Names</ulink>,
 632       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 633     </para>
 634   </refsect1>
 635
 636 </refentry>