# systemd.net-naming-scheme

## NAME



           systemd.net-naming-scheme - Network device naming schemes
    


## DESCRIPTION



           Network interfaces names and MAC addresses may be generated based
           on certain stable interface attributes. This is possible when
           there is enough information about the device to generate those
           attributes and the use of this information is configured. This
           page describes interface naming, i.e. what possible names may be
           generated. Those names are generated by the
           systemd-udevd.service(8) builtin **net_id** and exported as udev(7)
           properties (_ID_NET_NAME_ONBOARD=_ , _ID_NET_LABEL_ONBOARD=_ ,
           _ID_NET_NAME_PATH=_ , _ID_NET_NAME_SLOT=_).
    
           Names and MAC addresses are derived from various stable device
           metadata attributes. Newer versions of **systemd-udevd** take more of
           these attributes into account, improving (and thus possibly
           changing) the names and addresses used for the same devices.
           Different versions of those generation rules are called "naming
           schemes". The default naming scheme is chosen at compilation time.
           Usually this will be the latest implemented version, but it is
           also possible to set one of the older versions to preserve
           compatibility. This may be useful for example for distributions,
           which may introduce new versions of systemd in stable releases
           without changing the naming scheme. The naming scheme may also be
           overridden using the _net.naming_scheme=_ kernel command line
           switch, see systemd-udevd.service(8). Available naming schemes are
           described below.
    
           After the udev properties have been generated, appropriate udev
           rules may be used to actually rename devices based on those
           properties. See the description of _NamePolicy=_ and
           _MACAddressPolicy=_ in systemd.link(5).
    
           Note that while the concept of network interface naming schemes is
           primarily relevant in the context of systemd-udevd.service, the
           systemd-nspawn(1) container manager also takes it into account
           when naming network interfaces, see below.
    


## POLICIES



           All names start with a two-character prefix that signifies the
           interface type.
    
           **Table 1. Two character prefixes based on the type of interface**
           ┌────────┬───────────────────────┐
           │ **Prefix** │ **Description** │
           ├────────┼───────────────────────┤
           │ **en** │ Ethernet              │
           ├────────┼───────────────────────┤
           │ **ib** │ InfiniBand            │
           ├────────┼───────────────────────┤
           │ **sl** │ Serial line IP (slip) │
           ├────────┼───────────────────────┤
           │ **wl** │ Wireless local area   │
           │        │ network (WLAN)        │
           ├────────┼───────────────────────┤
           │ **ww** │ Wireless wide area    │
           │        │ network (WWAN)        │
           └────────┴───────────────────────┘
    
           The udev(7) **net_id** builtin exports the following device
           properties:
    
           _ID_NET_NAME_ONBOARD=prefix_**o** _number_ ,
           _ID_NET_NAME_ONBOARD=prefix_**d** _number_
               This name is set based on the numeric ordering information
               given by the firmware for on-board devices. Different schemes
               are used depending on the firmware type, as described in the
               table below.
    
               **Table 2. On-board naming schemes**
               ┌───────────────┬────────────────────────┐
               │ **Format** │ **Description** │
               ├───────────────┼────────────────────────┤
               │ _prefix_**o** _number_ │ PCI on-board index     │
               ├───────────────┼────────────────────────┤
               │ _prefix_**d** _number_ │ DeviceTree alias index │
               └───────────────┴────────────────────────┘
    
               Added in version 243.
    
           _ID_NET_LABEL_ONBOARD=label_
               This property is set based on textual label given by the
               firmware for on-board devices. This is only available for PCI
               devices.
    
               Added in version 243.
    
           _ID_NET_NAME_MAC=prefix_**x** _AABBCCDDEEFF_
               This name consists of the prefix, letter **x** , and 12 hexadecimal
               digits of the MAC address. It is available if the device has a
               fixed MAC address. Because this name is based on an attribute
               of the card itself, it remains "stable" when the device is
               moved (even between machines), but will change when the
               hardware is replaced.
    
               Added in version 243.
    
           _ID_NET_NAME_SLOT=prefix_[**P** _domain_]**s** _slot_[**f** _function_][**n** _port_name_ |**d** _dev_port_],
           _ID_NET_NAME_SLOT=prefix_**v** _slot_ , _ID_NET_NAME_SLOT=prefix_**x** _slot_ ,
           _ID_NET_NAME_SLOT=prefix_[**P** _domain_]**s** _slot_[**f** _function_][**n** _port_name_ |**d** _dev_port_]**b** _number_ ,
           _ID_NET_NAME_SLOT=prefix_[**P** _domain_]**s** _slot_[**f** _function_][**n** _port_name_ |**d** _dev_port_]**u** _port_...[**c** _config_][**i** _interface_],
           _ID_NET_NAME_SLOT=prefix_[**P** _domain_]**s** _slot_[**f** _function_][**n** _port_name_ |**d** _dev_port_]**v** _slot_ ,
           _ID_NET_NAME_SLOT=prefix_[**P** _domain_]**s** _slot_[**f** _function_][**n** _port_name_ |**d** _dev_port_]**r** _slot_
               This property describes the slot position. Different schemes
               are used depending on the bus type, as described in the table
               below. In case of USB, BCMA, and SR-VIO devices, the full name
               consists of the prefix, PCI slot identifier, and USB or BCMA
               or SR-VIO slot identifier. The first two parts are denoted as
               "..." in the table below.
    
               **Table 3. Slot naming schemes**
               ┌─────────────────────────────────────────────────────────────┬──────────────────────────┐
               │ **Format** │ **Description** │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ [**P** _domain_] **s** _slot_ [**f** _function_] [**n** _port_name_ | **d** _dev_port_] │ PCI slot number          │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ **v** _slot_                                                │ VIO slot number (IBM     │
               │                                                             │ PowerVM)                 │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ **X** _number_                                              │ VIF interface number     │
               │                                                             │ (Xen)                    │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **b** _number_                                                 │ Broadcom bus (BCMA) core │
               │                                                             │ number                   │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **u** _port_... [**c** _config_] [**i** _interface_]                         │ USB port number chain    │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **v** _slot_                                                   │ SR-VIO slot number       │
               ├─────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **r** _slot_                                                   │ SR-IOV slot number       │
               └─────────────────────────────────────────────────────────────┴──────────────────────────┘
    
               The PCI domain is only prepended when it is not 0. All
               multi-function PCI devices will carry the **f** _function_ number in
               the device name, including the function 0 device. For
               non-multi-function devices, the number is suppressed if 0. The
               port name _port_name_ is used, or the port number **d** _dev_port_ if
               the name is not known.
    
               For BCMA devices, the core number is suppressed when 0.
    
               For USB devices the full chain of port numbers of hubs is
               composed. If the name gets longer than the maximum number of
               15 characters, the name is not exported. The usual USB
               configuration number 1 and interface number 0 values are
               suppressed.
    
               SR-IOV virtual devices are named based on the name of the
               parent interface, with a suffix of **v** and the virtual device
               number, with any leading zeros removed. The bus number is
               ignored.
    
               SR-IOV virtual device representors are named based on the name
               of the physical device interface, with a suffix of **r** and the
               number of the virtual device that is linked to the particular
               representor, with any leading zeros removed. The physical port
               name and the bus number are ignored.
    
               In some configurations a parent PCI bridge of a given network
               controller may be associated with a slot. In such case we do
               not generate this device property to avoid possible naming
               conflicts.
    
               Added in version 243.
    
           _ID_NET_NAME_PATH=prefix_**c** _bus_id_ ,
           _ID_NET_NAME_PATH=prefix_**a** _vendormodel_**i** _instance_ ,
           _ID_NET_NAME_PATH=prefix_**i** _address_**n** _port_name_ ,
           _ID_NET_NAME_PATH=prefix_**u** _port_...,
           _ID_NET_NAME_PATH=prefix_[**P** _domain_]**p** _bus_**s** _slot_[**f** _function_][**n** _phys_port_name_ |**d** _dev_port_],
           _ID_NET_NAME_PATH=prefix_[**P** _domain_]**p** _bus_**s** _slot_[**f** _function_][**n** _phys_port_name_ |**d** _dev_port_]**b** _number_ ,
           _ID_NET_NAME_PATH=prefix_[**P** _domain_]**p** _bus_**s** _slot_[**f** _function_][**n** _phys_port_name_ |**d** _dev_port_]**u** _port_...[**c** _config_][**i** _interface_]
               This property describes the device installation location.
               Different schemes are used depending on the bus type, as
               described in the table below. For BCMA and USB devices, PCI
               path information must known, and the full name consists of the
               prefix, PCI slot identifier, and USB or BCMA location. The
               first two parts are denoted as "..." in the table below.
    
               **Table 4. Path naming schemes**
               ┌───────────────────────────────────────────────────────────────────────┬──────────────────────────┐
               │ **Format** │ **Description** │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ **c** _bus_id_                                                        │ CCW or grouped CCW       │
               │                                                                       │ device identifier        │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ **a** _vendor model_ **i** _instance_                                        │ ACPI path names for      │
               │                                                                       │ ARM64 platform devices   │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ **i** _address_ **n** _port_name_                                            │ Netdevsim (simulated     │
               │                                                                       │ networking device)       │
               │                                                                       │ device number and port   │
               │                                                                       │ name                     │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ _prefix_ [**P** _domain_] **p** _bus_ **s** _slot_ [**f** _function_] [**n** _phys_port_name_ | **d** _dev_port_] │ PCI geographical         │
               │                                                                       │ location                 │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **b** _number_                                                           │ Broadcom bus (BCMA) core │
               │                                                                       │ number                   │
               ├───────────────────────────────────────────────────────────────────────┼──────────────────────────┤
               │ ... **u** _port_... [**c** _config_] [**i** _interface_]                                   │ USB port number chain    │
               └───────────────────────────────────────────────────────────────────────┴──────────────────────────┘
    
               CCW and grouped CCW devices are found in IBM System Z
               mainframes. Any leading zeros and dots are suppressed.
    
               For PCI, BCMA, and USB devices, the same rules as described
               above for slot naming are used.
    
               Added in version 243.
    


## LIMITING THE USE OF SPECIFIC SYSFS ATTRIBUTES



           When creating names for network cards, some naming schemes use
           data from sysfs populated by the kernel. This means that although
           a specific naming scheme in udev(7) is picked, the network card's
           name can still change when a new kernel version adds a new sysfs
           attribute. For example, if kernel starts setting the
           **phys_port_name** , **udev** will append the "**n** _phys_port_name_ " suffix to
           the device name.
    
           _ID_NET_NAME_ALLOW=BOOL_
               This udev property sets a fallback policy for reading a sysfs
               attribute. If set to **0** udev will not read any sysfs attribute
               by default, unless it is explicitly allowlisted, see below. If
               set to **1** udev can use any sysfs attribute unless it is
               explicitly forbidden. The default value is **1**.
    
               Added in version 256.
    
           _ID_NET_NAME_ALLOW_sysfsattr=BOOL_
               This udev property explicitly states if udev shall use the
               specified _sysfsattr_ , when composing the device name.
    
               Added in version 256.
    
           With these options, users can set an allowlist or denylist for
           sysfs attributes. To create an allowlist, the user needs to set
           _ID_NET_NAME_ALLOW=0_ for the device and then list the allowed
           attributes with the _ID_NET_NAME_ALLOW_sysfsattr=1_ options. In case
           of a denylist, the user needs to provide the list of denied
           attributes with the _ID_NET_NAME_ALLOW_sysfsattr=0_ options.
    


## EXAMPLES



           **Example 1. Using udevadm test-builtin to display device properties**
    
               $ udevadm test-builtin net_id /sys/class/net/enp0s31f6
               ...
               Using default interface naming scheme 'v243'.
               ID_NET_NAMING_SCHEME=v243
               ID_NET_NAME_MAC=enx54ee75cb1dc0
               ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.
               ID_NET_NAME_PATH=enp0s31f6
               ...
    
           **Example 2. PCI Ethernet card with firmware index "1"**
    
               ID_NET_NAME_ONBOARD=eno1
               ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
    
           **Example 3. PCI Ethernet card in slot with firmware index number**
    
               # /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1
               ID_NET_NAME_MAC=enx000000000466
               ID_NET_NAME_PATH=enp5s0
               ID_NET_NAME_SLOT=ens1
    
           **Example 4. PCI Ethernet multi-function card with 2 ports**
    
               # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0
               ID_NET_NAME_MAC=enx78e7d1ea46da
               ID_NET_NAME_PATH=enp2s0f0
    
               # /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1
               ID_NET_NAME_MAC=enx78e7d1ea46dc
               ID_NET_NAME_PATH=enp2s0f1
    
           **Example 5. PCI WLAN card**
    
               # /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0
               ID_NET_NAME_MAC=wlx0024d7e31130
               ID_NET_NAME_PATH=wlp3s0
    
           **Example 6. PCI IB host adapter with 2 ports**
    
               # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0
               ID_NET_NAME_PATH=ibp21s0f0
    
               # /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1
               ID_NET_NAME_PATH=ibp21s0f1
    
           **Example 7. USB built-in 3G modem**
    
               # /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6
               ID_NET_NAME_MAC=wwx028037ec0200
               ID_NET_NAME_PATH=wwp0s29u1u4i6
    
           **Example 8. USB Android phone**
    
               # /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2
               ID_NET_NAME_MAC=enxd626b3450fb5
               ID_NET_NAME_PATH=enp0s29u1u2
    
           **Example 9. s390 grouped CCW interface**
    
               # /sys/devices/css0/0.0.0007/0.0.f5f0/group_device/net/encf5f0
               ID_NET_NAME_MAC=enx026d3c00000a
               ID_NET_NAME_PATH=encf5f0
    
           **Example 10. Set an allowlist for reading sysfs attributes for**
           **network card naming**
    
               /etc/udev/hwdb.d/50-net-naming-allowlist.hwdb
               net:naming:drvirtio_net:*
                 ID_NET_NAME_ALLOW=0
                 ID_NET_NAME_ALLOW_ACPI_INDEX=1
                 ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1
                 ID_NET_NAME_ALLOW_ADDRESS=1
                 ID_NET_NAME_ALLOW_ARI_ENABLED=1
                 ID_NET_NAME_ALLOW_DEV_PORT=1
                 ID_NET_NAME_ALLOW_FUNCTION_ID=1
                 ID_NET_NAME_ALLOW_IFLINK=1
                 ID_NET_NAME_ALLOW_INDEX=1
                 ID_NET_NAME_ALLOW_LABEL=1
                 ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1
                 ID_NET_NAME_ALLOW_TYPE=1
    
           **Example 11. Set a denylist so that specified sysfs attribute are**
           **ignored**
    
               /etc/udev/hwdb.d/50-net-naming-denylist.hwdb
               net:naming:drvirtio_net:*
                 ID_NET_NAME_ALLOW=1
                 ID_NET_NAME_ALLOW_DEV_PORT=0
                 ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
    


## NOTES



            1. Predictable Network Interface Names
               https://systemd.io/PREDICTABLE_INTERFACE_NAMES
    


* * *