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