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+ -->
   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 may be renamed to give them predictable names when there's enough information to
  26     generate appropriate names and the use of certain types of names is configured. This page describes the
  27     first part, i.e. what possible names may be generated. Those names are generated by the
  28     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
  29     builtin <command>net_id</command> and exported as udev properties
  30     (<varname>ID_NET_NAME_ONBOARD=</varname>, <varname>ID_NET_LABEL_ONBOARD=</varname>,
  31     <varname>ID_NET_NAME_PATH=</varname>, <varname>ID_NET_NAME_SLOT=</varname>).</para>
  32
  33     <para>Names are derived from various device metadata attributes. Newer versions of udev take more of
  34     these attributes into account, improving (and thus possibly changing) the names used for the same
  35     devices. Differents version of the naming rules are called "naming schemes". The default naming scheme is
  36     chosen at compilation time. Usually this will be the latest implemented version, but it is also possible
  37     to set one of the older versions to preserve compatibility. This may be useful for example for
  38     distributions, which may introduce new versions of systemd in stable releases without changing the naming
  39     scheme. The naming scheme may also be overriden using the <varname>net.naming-scheme=</varname> kernel
  40     command line switch, see
  41     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  42     Available naming schemes are described below.</para>
  43
  44     <para>After the udev proprties have been generated, appropriate udev rules may be used to actually rename
  45     devices based on those properties. See the description of <varname>NamePolicy=</varname> in
  46     <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
  47     </para>
  48   </refsect1>
  49
  50   <refsect1>
  51     <title>Naming</title>
  52
  53     <para>All names start with a two-character prefix that signifies the interface type.</para>
  54
  55     <table>
  56       <title>Two character prefixes based on the type of interface</title>
  57
  58       <tgroup cols='2'>
  59         <thead>
  60           <row>
  61             <entry>Prefix</entry>
  62             <entry>Description</entry>
  63           </row>
  64         </thead>
  65         <tbody>
  66           <row>
  67             <entry><constant>en</constant></entry>
  68             <entry>Ethernet</entry>
  69           </row>
  70           <row>
  71             <entry><constant>ib</constant></entry>
  72             <entry>InfiniBand</entry>
  73           </row>
  74           <row>
  75             <entry><constant>sl</constant></entry>
  76             <entry>serial line IP (slip)</entry>
  77           </row>
  78           <row>
  79             <entry><constant>wl</constant></entry>
  80             <entry>Wireless local area network (WLAN)</entry>
  81           </row>
  82           <row>
  83             <entry><constant>ww</constant></entry>
  84             <entry>Wireless wide area network (WWAN)</entry>
  85           </row>
  86         </tbody>
  87       </tgroup>
  88     </table>
  89
  90     <para>The udev <command>net_id</command> builtin exports the following udev device properties:</para>
  91
  92     <variablelist>
  93         <varlistentry>
  94           <term><varname>ID_NET_NAME_ONBOARD=<replaceable>prefix</replaceable><constant>o</constant><replaceable>number</replaceable></varname></term>
  95
  96           <listitem><para>This name is set based on the ordering information given by the firmware for
  97           on-board devices. The name consists of the prefix, letter <constant>o</constant>, and a number
  98           specified by the firmware. This is only available for PCI devices.</para>
  99           </listitem>
 100         </varlistentry>
 101
 102         <varlistentry>
 103           <term><varname>ID_NET_LABEL_ONBOARD=<replaceable>prefix</replaceable> <replaceable>label</replaceable></varname></term>
 104
 105           <listitem><para>This property is set based on label given by the firmware for on-board devices. The
 106           name consists of the prefix concatenated with the label. This is only available for PCI devices.
 107           </para>
 108           </listitem>
 109         </varlistentry>
 110
 111         <varlistentry>
 112           <term><varname>ID_NET_NAME_MAC=<replaceable>prefix</replaceable><constant>x</constant><replaceable>AABBCCDDEEFF</replaceable></varname></term>
 113
 114           <listitem><para>This name consists of the prefix, letter <constant>x</constant>, and 12 hexadecimal
 115           digits of the MAC address. It is available if the device has a fixed MAC address. Because this name
 116           is based on an attribute of the card itself, it remains "stable" when the device is moved (even
 117           between machines), but will change when the hardware is replaced.</para>
 118           </listitem>
 119         </varlistentry>
 120
 121         <varlistentry>
 122           <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>
 123           <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>
 124           <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>
 125           <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>
 126
 127           <listitem><para>This property describes the slot position. Different schemes are used depending on
 128           the bus type, as described in the table below. In all cases, PCI slot information must be known. In
 129           case of USB, BCMA, and SR-VIO devices, the full name consists of the prefix, PCI slot identifier,
 130           and USB or BCMA or SR-VIO slot identifier. The first two parts are denoted as "…" in the table
 131           below.</para>
 132
 133           <table>
 134             <title>Slot naming schemes</title>
 135
 136             <tgroup cols='2'>
 137               <thead>
 138                 <row>
 139                   <entry>Format</entry>
 140                   <entry>Description</entry>
 141                 </row>
 142               </thead>
 143
 144               <tbody>
 145                 <row>
 146                   <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>
 147                   <entry>PCI slot number</entry>
 148                 </row>
 149
 150                 <row>
 151                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 152                   <entry>Broadcom bus (BCMA) core number</entry>
 153                 </row>
 154
 155                 <row>
 156                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 157                   <entry>USB port number chain</entry>
 158                 </row>
 159
 160                 <row>
 161                   <entry>… <constant>v</constant><replaceable>slot</replaceable></entry>
 162                   <entry>SR-VIO slot number</entry>
 163                 </row>
 164               </tbody>
 165             </tgroup>
 166           </table>
 167
 168           <para>The PCI domain is only prepended when it is not 0. All multi-function PCI devices will carry
 169           the <constant>f<replaceable>function</replaceable></constant> number in the device name, including
 170           the function 0 device. For non-multi-function devices, the number is suppressed if 0. The port name
 171           <replaceable>port_name</replaceable> is used, or the port number
 172           <constant>d</constant><replaceable>dev_port</replaceable> if the name is not known.</para>
 173
 174           <para>For BCMA devices, the core number is suppressed when 0.</para>
 175
 176           <para>For USB devices the full chain of port numbers of hubs is composed. If the name gets longer
 177           than the maximum number of 15 characters, the name is not exported. The usual USB configuration
 178           number 1 and interface number 0 values are suppressed.</para>
 179           </listitem>
 180
 181           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 182           <constant>v</constant> and the virtual device number, with any leading zeros removed. The bus
 183           number is ignored. This device type is found in IBM PowerVMs.</para>
 184         </varlistentry>
 185
 186         <varlistentry>
 187           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>c</constant><replaceable>bus_id</replaceable></varname></term>
 188           <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>
 189           <term><varname>ID_NET_NAME_PATH=<replaceable>prefix</replaceable><constant>i</constant><replaceable>address</replaceable><constant>n</constant><replaceable>port_name</replaceable></varname></term>
 190           <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>
 191           <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>
 192           <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>
 193
 194           <listitem><para>This property describes the device installation location. Different schemes are
 195           used depending on the bus type, as described in the table below. For BCMA and USB devices, PCI path
 196           information must known, and the full name consists of the prefix, PCI slot identifier, and USB or
 197           BCMA location. The first two parts are denoted as "…" in the table below.</para>
 198
 199           <table>
 200             <title>Path naming schemes</title>
 201
 202             <tgroup cols='2'>
 203               <thead>
 204                 <row>
 205                   <entry>Format</entry>
 206                   <entry>Description</entry>
 207                 </row>
 208               </thead>
 209
 210               <tbody>
 211                 <row>
 212                   <entry><replaceable>prefix</replaceable> <constant>c</constant><replaceable>bus_id</replaceable></entry>
 213                   <entry>CCW or grouped CCW device identifier</entry>
 214                 </row>
 215
 216                 <row>
 217                   <entry><replaceable>prefix</replaceable> <constant>a</constant><replaceable>vendor</replaceable> <replaceable>model</replaceable> <constant>i</constant><replaceable>instance</replaceable></entry>
 218                   <entry>ACPI path names for ARM64 platform devices</entry>
 219                 </row>
 220
 221                 <row>
 222                   <entry><replaceable>prefix</replaceable> <constant>i</constant><replaceable>address</replaceable> <constant>n</constant><replaceable>port_name</replaceable></entry>
 223                   <entry>Netdevsim (simulated networking device) device number and port name</entry>
 224                 </row>
 225
 226                 <row>
 227                   <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>
 228                   <entry>PCI geographical location</entry>
 229                 </row>
 230
 231                 <row>
 232                   <entry>… <constant>b</constant><replaceable>number</replaceable></entry>
 233                   <entry>Broadcom bus (BCMA) core number</entry>
 234                 </row>
 235
 236                 <row>
 237                   <entry>… <constant>u</constant><replaceable>port</replaceable>… [<constant>c</constant><replaceable>config</replaceable>] [<constant>i</constant><replaceable>interface</replaceable>]</entry>
 238                   <entry>USB port number chain</entry>
 239                 </row>
 240
 241               </tbody>
 242             </tgroup>
 243           </table>
 244
 245           <para>CCW and grouped CCW devices are found in IBM System Z mainframes. Any leading zeros and
 246           dots are suppressed.</para>
 247
 248           <para>For PCI, BCMA, and USB devices, the same rules as described above for slot naming are
 249           used.</para>
 250           </listitem>
 251         </varlistentry>
 252     </variablelist>
 253   </refsect1>
 254
 255   <refsect1>
 256     <title>History</title>
 257
 258     <para>The following "naming schemes" have been defined:</para>
 259
 260     <variablelist>
 261         <varlistentry>
 262           <term><constant>v238</constant></term>
 263
 264           <listitem><para>This is the naming naming that was implemented in systemd 238.</para></listitem>
 265         </varlistentry>
 266
 267         <varlistentry>
 268           <term><constant>v239</constant></term>
 269
 270           <listitem><para>Naming was changed for virtual network interfaces created with SR-IOV and NPAR and
 271           for devices where the PCI network controller device does not have a slot number associated.</para>
 272
 273           <para>SR-IOV virtual devices are named based on the name of the parent interface, with a suffix of
 274           <literal>v<replaceable>port</replaceable></literal>, where <replaceable>port</replaceable> is the
 275           virtual device number. Previously those virtual devices were named as if completely independent.
 276           </para>
 277
 278           <para>The ninth and later NPAR virtual devices are named following the scheme used for the first
 279           eight NPAR partitions. Previously those devices were not renamed and the kernel default
 280           ("eth<replaceable>N</replaceable>") was used.</para>
 281
 282           <para>Names are also generated for PCI devices where the PCI network controller device does not
 283           have an associated slot number itself, but one of its parents does. Previously those devices were
 284           not renamed and the kernel default was used.</para>
 285           </listitem>
 286         </varlistentry>
 287
 288         <varlistentry>
 289           <term><constant>v240</constant></term>
 290
 291           <para>The <literal>ib</literal> prefix and stable names for infiniband devices are
 292           introduced. Previously those devices were not renamed.</para>
 293
 294           <para>The ACPI index field (used in <varname>ID_NET_NAME_ONBOARD=</varname>) is now also used when
 295           0.</para>
 296
 297           <para>A new naming policy <varname>NamePolicy=keep</varname> was introduced. With this policy, if
 298           the network device name was already set by userspace, the device will not be renamed
 299           again. Previously, this naming policy applied implicitly, and now it must be explicitly
 300           requested. Effectively, this means that network devices will be renamed according to the
 301           configuration, even if they have been renamed already, if <constant>keep</constant> is not
 302           specified as the naming policy in the <filename noindex='true'>.link</filename> file. See
 303           <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
 304           for a description of <varname>NamePolicy=</varname>.</para>
 305         </varlistentry>
 306
 307         <varlistentry>
 308           <term><constant>v243</constant></term>
 309
 310           <para>Support for netdevsim (simulated networking devices) was added. Previously those devices were
 311           not renamed.</para>
 312
 313           <para>Previously two-letter interface type prefix was prepended to
 314           <varname>ID_NET_LABEL_ONBOARD=</varname>. This is not done anymore.</para>
 315         </varlistentry>
 316
 317         <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
 318         particular version of systemd.</para>
 319     </variablelist>
 320   </refsect1>
 321
 322   <refsect1>
 323     <title>Examples</title>
 324
 325     <example>
 326       <title>Using <command>udevadm test-builtin</command> to display device properties</title>
 327
 328       <programlisting>$ udevadm test-builtin net_id /sys/class/net/enp0s31f6
 329 ...
 330 Using default interface naming scheme 'v243'.
 331 ID_NET_NAMING_SCHEME=v243
 332 ID_NET_NAME_MAC=enx54ee75cb1dc0
 333 ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
 334 ID_NET_NAME_PATH=enp0s31f6
 335 ...</programlisting>
 336     </example>
 337
 338     <example>
 339       <title>PCI Ethernet card with firmware index "1"</title>
 340
 341       <programlisting>ID_NET_NAME_ONBOARD=eno1
 342 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
 343       </programlisting>
 344     </example>
 345
 346     <example>
 347       <title>PCI Ethernet card in hotplug slot with firmware index number</title>
 348
 349       <programlisting># /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
 350 ID_NET_NAME_MAC=enx000000000466
 351 ID_NET_NAME_PATH=enp5s0
 352 ID_NET_NAME_SLOT=ens1</programlisting>
 353     </example>
 354
 355     <example>
 356       <title>PCI Ethernet multi-function card with 2 ports</title>
 357
 358       <programlisting># /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
 359 ID_NET_NAME_MAC=enx78e7d1ea46da
 360 ID_NET_NAME_PATH=enp2s0f0
 361
 362 # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
 363 ID_NET_NAME_MAC=enx78e7d1ea46dc
 364 ID_NET_NAME_PATH=enp2s0f1</programlisting>
 365     </example>
 366
 367     <example>
 368       <title>PCI WLAN card</title>
 369
 370       <programlisting># /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
 371 ID_NET_NAME_MAC=wlx0024d7e31130
 372 ID_NET_NAME_PATH=wlp3s0</programlisting>
 373     </example>
 374
 375     <example>
 376       <title>PCI IB host adapter with 2 ports</title>
 377
 378       <programlisting># /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
 379 ID_NET_NAME_PATH=ibp21s0f0
 380
 381 # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
 382 ID_NET_NAME_PATH=ibp21s0f1</programlisting>
 383     </example>
 384
 385     <example>
 386       <title>USB built-in 3G modem</title>
 387
 388       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
 389 ID_NET_NAME_MAC=wwx028037ec0200
 390 ID_NET_NAME_PATH=wwp0s29u1u4i6</programlisting>
 391     </example>
 392
 393     <example>
 394       <title>USB Android phone</title>
 395
 396       <programlisting># /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
 397 ID_NET_NAME_MAC=enxd626b3450fb5
 398 ID_NET_NAME_PATH=enp0s29u1u2</programlisting>
 399     </example>
 400
 401     <example>
 402       <title>s390 grouped CCW interface</title>
 403
 404       <programlisting># /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
 405 ID_NET_NAME_MAC=enx026d3c00000a
 406 ID_NET_NAME_PATH=encf5f0</programlisting>
 407     </example>
 408   </refsect1>
 409
 410   <refsect1>
 411     <title>See Also</title>
 412     <para>
 413       <citerefentry><refentrytitle>udev</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
 414       <citerefentry><refentrytitle>udevadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 415       <ulink url="https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames">the
 416       original page describing stable interface names</ulink>
 417     </para>
 418   </refsect1>
 419
 420 </refentry>