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">
   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>Naming</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 the table below.</para>
 105
 106             <table>
 107               <title>Onboard naming schemes</title>
 108
 109               <tgroup cols='2'>
 110                 <thead>
 111                   <row>
 112                     <entry>Format</entry>
 113                     <entry>Description</entry>
 114                   </row>
 115                 </thead>
 116
 117                 <tbody>
 118                   <row>
 119                     <entry><replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></entry>
 120                     <entry>PCI onboard index</entry>
 121                   </row>
 122
 123                   <row>
 124                     <entry><replaceable>prefix</replaceable><constant>d</constant><replaceable>number</replaceable></entry>
 125                     <entry>Devicetree alias index</entry>
 126                   </row>
 127
 128                 </tbody>
 129               </tgroup>
 130             </table>
 131           </listitem>
 132         </varlistentry>
 133
 134         <varlistentry>
 135           <term><varname>ID_NET_LABEL_ONBOARD=<replaceable>prefix</replaceable> <replaceable>label</replaceable></varname></term>
 136
 137           <listitem><para>This property is set based on textual label given by the firmware for on-board
 138           devices. The name consists of the prefix concatenated with the label. This is only available for
 139           PCI devices.
 140           </para>
 141           </listitem>
 142         </varlistentry>
 143
 144         <varlistentry>
 145           <term><varname>ID_NET_NAME_MAC=<replaceable>prefix</replaceable><constant>x</constant><replaceable>AABBCCDDEEFF</replaceable></varname></term>
 146
 147           <listitem><para>This name consists of the prefix, letter <constant>x</constant>, and 12 hexadecimal
 148           digits of the MAC address. It is available if the device has a fixed MAC address. Because this name
 149           is based on an attribute of the card itself, it remains "stable" when the device is moved (even
 150           between machines), but will change when the hardware is replaced.</para>
 151           </listitem>
 152         </varlistentry>
 153
 154         <varlistentry>
 155           <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>
 156           <term><varname>ID_NET_NAME_SLOT=<replaceable>prefix</replaceable><constant>v</constant><replaceable>slot</replaceable></varname></term>
 157           <term><varname>ID_NET_NAME_SLOT=<replaceable>prefix</replaceable><constant>x</constant><replaceable>slot</replaceable></varname></term>
 158           <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>
 159           <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>
 160           <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>
 161
 162           <listitem><para>This property describes the slot position. Different schemes are used depending on
 163           the bus type, as described in the table below. In case of USB, BCMA, and SR-VIO devices, the full
 164           name consists of the prefix, PCI slot identifier, and USB or BCMA or SR-VIO slot identifier. The
 165           first two parts are denoted as "…" in the table below.</para>
 166
 167           <table>
 168             <title>Slot naming schemes</title>
 169
 170             <tgroup cols='2'>
 171               <thead>
 172                 <row>
 173                   <entry>Format</entry>
 174                   <entry>Description</entry>
 175                 </row>
 176               </thead>
 177
 178               <tbody>
 179                 <row>
 180                   <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>
 181                   <entry>PCI slot number</entry>
 182                 </row>
 183
 184                 <row>
 185                   <entry><replaceable>prefix</replaceable> <constant>v</constant><replaceable>slot</replaceable></entry>
 186                   <entry>VIO slot number (IBM PowerVM)</entry>
 187                 </row>
 188
 189                 <row>
 190                   <entry><replaceable>prefix</replaceable> <constant>X</constant><replaceable>number</replaceable></entry>
 191                   <entry>VIF interface number (Xen)</entry>
 192                 </row>
 193
 194                 <row>
 195                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 196                   <entry>Broadcom bus (BCMA) core number</entry>
 197                 </row>
 198
 199                 <row>
 200                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 201                   <entry>USB port number chain</entry>
 202                 </row>
 203
 204                 <row>
 205                   <entry>… <constant>v</constant><replaceable>slot</replaceable></entry>
 206                   <entry>SR-VIO slot number</entry>
 207                 </row>
 208               </tbody>
 209             </tgroup>
 210           </table>
 211
 212           <para>The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry
 213           the <constant>f<replaceable>function</replaceable></constant> number in the device name, including
 214           the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name
 215           <replaceable>port_name</replaceable> is used, or the port number
 216           <constant>d</constant><replaceable>dev_port</replaceable> if the name is not known.</para>
 217
 218           <para>For BCMA devices, the core number is suppressed when 0.</para>
 219
 220           <para>For USB devices the full chain of port numbers of hubs is composed. If the name gets longer
 221           than the maximum number of 15 characters, the name is not exported. The usual USB configuration
 222           number 1 and interface number 0 values are suppressed.</para>
 223
 224           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 225           <constant>v</constant> and the virtual device number, with any leading zeros removed. The bus
 226           number is ignored.</para>
 227
 228           <para>In some configurations a parent PCI bridge of a given network controller may be associated
 229           with a slot. In such case we don't generate this device property to avoid possible naming conflicts.</para>
 230           </listitem>
 231         </varlistentry>
 232
 233         <varlistentry>
 234           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>c</constant><replaceable>bus_id</replaceable></varname></term>
 235           <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>
 236           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>i</constant><replaceable>address</replaceable><constant>n</constant><replaceable>port_name</replaceable></varname></term>
 237           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>u</constant><replaceable>port</replaceable>…</varname></term>
 238           <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>
 239           <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>
 240           <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>
 241
 242           <listitem><para>This property describes the device installation location. Different schemes are
 243           used depending on the bus type, as described in the table below. For BCMA and USB devices, PCI path
 244           information must known, and the full name consists of the prefix, PCI slot identifier, and USB or
 245           BCMA location. The first two parts are denoted as "…" in the table below.</para>
 246
 247           <table>
 248             <title>Path naming schemes</title>
 249
 250             <tgroup cols='2'>
 251               <thead>
 252                 <row>
 253                   <entry>Format</entry>
 254                   <entry>Description</entry>
 255                 </row>
 256               </thead>
 257
 258               <tbody>
 259                 <row>
 260                   <entry><replaceable>prefix</replaceable> <constant>c</constant><replaceable>bus_id</replaceable></entry>
 261                   <entry>CCW or grouped CCW device identifier</entry>
 262                 </row>
 263
 264                 <row>
 265                   <entry><replaceable>prefix</replaceable> <constant>a</constant><replaceable>vendor</replaceable> <replaceable>model</replaceable> <constant>i</constant><replaceable>instance</replaceable></entry>
 266                   <entry>ACPI path names for ARM64 platform devices</entry>
 267                 </row>
 268
 269                 <row>
 270                   <entry><replaceable>prefix</replaceable> <constant>i</constant><replaceable>address</replaceable> <constant>n</constant><replaceable>port_name</replaceable></entry>
 271                   <entry>Netdevsim (simulated networking device) device number and port name</entry>
 272                 </row>
 273
 274                 <row>
 275                   <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>
 276                   <entry>PCI geographical location</entry>
 277                 </row>
 278
 279                 <row>
 280                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 281                   <entry>Broadcom bus (BCMA) core number</entry>
 282                 </row>
 283
 284                 <row>
 285                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 286                   <entry>USB port number chain</entry>
 287                 </row>
 288
 289               </tbody>
 290             </tgroup>
 291           </table>
 292
 293           <para>CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and
 294           dots are suppressed.</para>
 295
 296           <para>For PCI, BCMA, and USB devices, the same rules as described above for slot naming are
 297           used.</para>
 298           </listitem>
 299         </varlistentry>
 300     </variablelist>
 301   </refsect1>
 302
 303   <refsect1>
 304     <title>History</title>
 305
 306     <para>The following "naming schemes" have been defined (which may be chosen at system boot-up time via
 307     the <varname>net.naming-scheme=</varname> kernel command line switch, see above):</para>
 308
 309     <variablelist>
 310         <varlistentry>
 311           <term><constant>v238</constant></term>
 312
 313           <listitem><para>This is the naming scheme that was implemented in systemd 238.</para></listitem>
 314         </varlistentry>
 315
 316         <varlistentry>
 317           <term><constant>v239</constant></term>
 318
 319           <listitem><para>Naming was changed for virtual network interfaces created with SR-IOV and NPAR and
 320           for devices where the PCI network controller device does not have a slot number associated.</para>
 321
 322           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 323           <literal>v<replaceable>port</replaceable></literal>, where <replaceable>port</replaceable> is the
 324           virtual device number. Previously those virtual devices were named as if completely independent.
 325           </para>
 326
 327           <para>The ninth and later NPAR virtual devices are named following the scheme used for the first
 328           eight NPAR partitions. Previously those devices were not renamed and the kernel default
 329           ("eth<replaceable>N</replaceable>") was used.</para>
 330
 331           <para>Names are also generated for PCI devices where the PCI network controller device does not
 332           have an associated slot number itself, but one of its parents does. Previously those devices were
 333           not renamed and the kernel default was used.</para>
 334           </listitem>
 335         </varlistentry>
 336
 337         <varlistentry>
 338           <term><constant>v240</constant></term>
 339
 340           <listitem><para>The <literal>ib</literal> prefix and stable names for infiniband devices are
 341           introduced. Previously those devices were not renamed.</para>
 342
 343           <para>The ACPI index field (used in <varname>ID_NET_NAME_ONBOARD=</varname>) is now also used when
 344           0.</para>
 345
 346           <para>A new naming policy <varname>NamePolicy=keep</varname> was introduced. With this policy, if
 347           the network device name was already set by userspace, the device will not be renamed
 348           again. Previously, this naming policy applied implicitly, and now it must be explicitly
 349           requested. Effectively, this means that network devices will be renamed according to the
 350           configuration, even if they have been renamed already, if <constant>keep</constant> is not
 351           specified as the naming policy in the <filename index="false">.link</filename> file. See
 352           <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 353           for a description of <varname>NamePolicy=</varname>.</para></listitem>
 354         </varlistentry>
 355
 356         <varlistentry>
 357           <term><constant>v241</constant></term>
 358
 359           <listitem><para><option>MACAddressPolicy=persistent</option> was extended to set MAC addresses
 360           based on the device name. Previously addresses were only based on the
 361           <varname index="false">ID_NET_NAME_*</varname> attributes, which meant that interface names would
 362           never be generated for virtual devices. Now a persistent address will be generated for most
 363           devices, including in particular bridges.</para>
 364
 365           <para>Note: when userspace does not set a MAC address for a bridge device, the kernel will
 366           initially assign a random address, and then change it when the first device is enslaved to the
 367           bridge. With this naming policy change, bridges get a persistent MAC address based on the bridge
 368           name instead of the first enslaved device.</para></listitem>
 369         </varlistentry>
 370
 371         <varlistentry>
 372           <term><constant>v243</constant></term>
 373
 374           <listitem><para>Support for renaming netdevsim (simulated networking) devices was added. Previously
 375           those devices were not renamed.</para>
 376
 377           <para>Previously two-letter interface type prefix was prepended to
 378           <varname>ID_NET_LABEL_ONBOARD=</varname>. This is not done anymore.</para></listitem>
 379         </varlistentry>
 380
 381         <varlistentry>
 382           <term><constant>v245</constant></term>
 383
 384           <listitem><para>When
 385           <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 386           derives the name for the host side of the network interface created with
 387           <option>--network-veth</option> from the container name it previously simply truncated the result
 388           at 15 characters if longer (since that's the maximum length for network interface names). From now
 389           on, for any interface name that would be longer than 15 characters the last 4 characters are set to
 390           a 24bit hash value of the full interface name. This way network interface name collisions between
 391           multiple similarly named containers (who only differ in container name suffix) should be less
 392           likely (but still possible, since the 24bit hash value is very small).</para></listitem>
 393         </varlistentry>
 394
 395         <varlistentry>
 396           <term><constant>v247</constant></term>
 397
 398           <listitem><para>When a PCI slot is associated with a PCI bridge that has multiple child network
 399           controllers, the same value of the <varname>ID_NET_NAME_SLOT</varname> property might be derived
 400           for those controllers. This would cause a naming conflict if the property is selected as the device
 401           name. Now, we detect this situation and don't produce the <varname>ID_NET_NAME_SLOT</varname>
 402           property.</para></listitem>
 403         </varlistentry>
 404
 405         <varlistentry>
 406           <term><constant>v249</constant></term>
 407
 408           <listitem><para>PCI hotplug slot names for the s390 PCI driver are a hexadecimal representation
 409           of the <filename>function_id</filename> device attribute. This attribute is now used to build the
 410           <varname>ID_NET_NAME_SLOT</varname>. Before that, all slot names were parsed as decimal
 411           numbers, which could either result in an incorrect value of the <varname>ID_NET_NAME_SLOT</varname>
 412           property or none at all.</para>
 413
 414           <para>Some firmware and hypervisor implementations report unreasonably high numbers for the onboard
 415           index. To prevent the generation of bogus onbard interface names, index numbers greater than 16381
 416           (2¹⁴-1) were ignored. For s390 PCI devices index values up to 65535 (2¹⁶-1) are valid. To account
 417           for that, the limit was increased to 65535.</para>
 418
 419           <para>The udev rule <varname>NAME=</varname> replaces <literal>:</literal>,
 420           <literal>/</literal>, and <literal>%</literal> with an underscore (<literal>_</literal>), and
 421           refuses strings which contain only numerics.</para>
 422           </listitem>
 423         </varlistentry>
 424
 425         <varlistentry>
 426           <term><constant>v250</constant></term>
 427
 428           <listitem><para>Added naming scheme for Xen netfront "vif" interfaces based on the guest side
 429           VIF number set from the Xen config (or the interface index in AWS EC2).</para>
 430           </listitem>
 431         </varlistentry>
 432
 433         <varlistentry>
 434           <term><constant>v251</constant></term>
 435
 436           <listitem><para>Since version <constant>v247</constant> we no longer set
 437           <varname>ID_NET_NAME_SLOT</varname> if we detect that a PCI device associated with a slot is a PCI
 438           bridge as that would create naming conflict when there are more child devices on that bridge. Now,
 439           this is relaxed and we will use slot information to generate the name based on it but only if
 440           the PCI device has multiple functions. This is safe because distinct function number is a part of
 441           the device name for multifunction devices.</para>
 442           </listitem>
 443         </varlistentry>
 444
 445         <varlistentry>
 446           <term><constant>v252</constant></term>
 447
 448           <listitem><para>Added naming scheme for platform devices with devicetree aliases.</para>
 449           </listitem>
 450         </varlistentry>
 451
 452         <varlistentry>
 453           <term><constant>v253</constant></term>
 454
 455           <listitem><para>Set <varname>ID_NET_NAME_PATH</varname> for usb devices not connected via a PCI bus.</para>
 456           </listitem>
 457         </varlistentry>
 458
 459       </variablelist>
 460
 461     <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
 462     particular version of systemd).</para>
 463   </refsect1>
 464
 465   <refsect1>
 466     <title>Examples</title>
 467
 468     <example>
 469       <title>Using <command>udevadm test-builtin</command> to display device properties</title>
 470
 471       <programlisting>$ udevadm test-builtin net_id /sys/class/net/enp0s31f6
 472 ...
 473 Using default interface naming scheme 'v243'.
 474 ID_NET_NAMING_SCHEME=v243
 475 ID_NET_NAME_MAC=enx54ee75cb1dc0
 476 ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
 477 ID_NET_NAME_PATH=enp0s31f6
 478 ...</programlisting>
 479     </example>
 480
 481     <example>
 482       <title>PCI Ethernet card with firmware index "1"</title>
 483
 484       <programlisting>ID_NET_NAME_ONBOARD=eno1
 485 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
 486       </programlisting>
 487     </example>
 488
 489     <example>
 490       <title>PCI Ethernet card in hotplug slot with firmware index number</title>
 491
 492       <programlisting># /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
 493 ID_NET_NAME_MAC=enx000000000466
 494 ID_NET_NAME_PATH=enp5s0
 495 ID_NET_NAME_SLOT=ens1</programlisting>
 496     </example>
 497
 498     <example>
 499       <title>PCI Ethernet multi-function card with 2 ports</title>
 500
 501       <programlisting># /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
 502 ID_NET_NAME_MAC=enx78e7d1ea46da
 503 ID_NET_NAME_PATH=enp2s0f0
 504
 505 # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
 506 ID_NET_NAME_MAC=enx78e7d1ea46dc
 507 ID_NET_NAME_PATH=enp2s0f1</programlisting>
 508     </example>
 509
 510     <example>
 511       <title>PCI WLAN card</title>
 512
 513       <programlisting># /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
 514 ID_NET_NAME_MAC=wlx0024d7e31130
 515 ID_NET_NAME_PATH=wlp3s0</programlisting>
 516     </example>
 517
 518     <example>
 519       <title>PCI IB host adapter with 2 ports</title>
 520
 521       <programlisting># /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
 522 ID_NET_NAME_PATH=ibp21s0f0
 523
 524 # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
 525 ID_NET_NAME_PATH=ibp21s0f1</programlisting>
 526     </example>
 527
 528     <example>
 529       <title>USB built-in 3G modem</title>
 530
 531       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
 532 ID_NET_NAME_MAC=wwx028037ec0200
 533 ID_NET_NAME_PATH=wwp0s29u1u4i6</programlisting>
 534     </example>
 535
 536     <example>
 537       <title>USB Android phone</title>
 538
 539       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
 540 ID_NET_NAME_MAC=enxd626b3450fb5
 541 ID_NET_NAME_PATH=enp0s29u1u2</programlisting>
 542     </example>
 543
 544     <example>
 545       <title>s390 grouped CCW interface</title>
 546
 547       <programlisting># /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
 548 ID_NET_NAME_MAC=enx026d3c00000a
 549 ID_NET_NAME_PATH=encf5f0</programlisting>
 550     </example>
 551   </refsect1>
 552
 553   <refsect1>
 554     <title>See Also</title>
 555     <para>
 556       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 557       <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 558       <ulink url="https://systemd.io/PREDICTABLE_INTERFACE_NAMES">Predictable Network Interface Names</ulink>,
 559       <citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 560     </para>
 561   </refsect1>
 562
 563 </refentry>