{ "content": [ { "type": "text", "text": "# SYSTEMD.NET-NAMING-SCHEME (info)\n\n## NAME\n\nsystemd.net-naming-scheme - Network device naming schemes\n\n## DESCRIPTION\n\nNetwork interfaces names and MAC addresses may be generated based on\ncertain stable interface attributes. This is possible when there is\nenough information about the device to generate those attributes and\nthe use of this information is configured. This page describes\ninterface naming, i.e. what possible names may be generated. Those\nnames are generated by the systemd-udevd.service(8) builtin netid and\nexported as udev properties (IDNETNAMEONBOARD=,\nIDNETLABELONBOARD=, IDNETNAMEPATH=, IDNETNAMESLOT=).\n\n## Sections\n\n- **NAME**\n- **DESCRIPTION**\n- **NAMING**\n- **HISTORY**\n- **EXAMPLES**\n- **SEE ALSO**\n- **NOTES**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "SYSTEMD.NET-NAMING-SCHEME", "section": "", "mode": "info", "summary": "systemd.net-naming-scheme - Network device naming schemes", "synopsis": null, "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [ "Example 1. Using udevadm test-builtin to display device properties", "$ udevadm test-builtin netid /sys/class/net/enp0s31f6", "...", "Using default interface naming scheme 'v243'.", "IDNETNAMINGSCHEME=v243", "IDNETNAMEMAC=enx54ee75cb1dc0", "IDOUIFROMDATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.", "IDNETNAMEPATH=enp0s31f6", "...", "Example 2. PCI Ethernet card with firmware index \"1\"", "IDNETNAMEONBOARD=eno1", "IDNETNAMEONBOARDLABEL=Ethernet Port 1", "Example 3. PCI Ethernet card in hotplug slot with firmware index number", "# /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1", "IDNETNAMEMAC=enx000000000466", "IDNETNAMEPATH=enp5s0", "IDNETNAMESLOT=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", "IDNETNAMEMAC=enx78e7d1ea46da", "IDNETNAMEPATH=enp2s0f0", "# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1", "IDNETNAMEMAC=enx78e7d1ea46dc", "IDNETNAMEPATH=enp2s0f1", "Example 5. PCI WLAN card", "# /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0", "IDNETNAMEMAC=wlx0024d7e31130", "IDNETNAMEPATH=wlp3s0", "Example 6. PCI IB host adapter with 2 ports", "# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0", "IDNETNAMEPATH=ibp21s0f0", "# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1", "IDNETNAMEPATH=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", "IDNETNAMEMAC=wwx028037ec0200", "IDNETNAMEPATH=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", "IDNETNAMEMAC=enxd626b3450fb5", "IDNETNAMEPATH=enp0s29u1u2", "Example 9. s390 grouped CCW interface", "# /sys/devices/css0/0.0.0007/0.0.f5f0/groupdevice/net/encf5f0", "IDNETNAMEMAC=enx026d3c00000a", "IDNETNAMEPATH=encf5f0" ], "see_also": [ { "name": "udev", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/udev/7/json" }, { "name": "udevadm", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/udevadm/8/json" }, { "name": "nspawn", "section": "1", "url": "https://www.chedong.com/phpMan.php/man/nspawn/1/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 32, "subsections": [] }, { "name": "NAMING", "lines": 130, "subsections": [] }, { "name": "HISTORY", "lines": 103, "subsections": [] }, { "name": "EXAMPLES", "lines": 65, "subsections": [] }, { "name": "SEE ALSO", "lines": 3, "subsections": [] }, { "name": "NOTES", "lines": 4, "subsections": [] } ], "sections": { "NAME": { "content": "systemd.net-naming-scheme - Network device naming schemes\n", "subsections": [] }, "DESCRIPTION": { "content": "Network interfaces names and MAC addresses may be generated based on\ncertain stable interface attributes. This is possible when there is\nenough information about the device to generate those attributes and\nthe use of this information is configured. This page describes\ninterface naming, i.e. what possible names may be generated. Those\nnames are generated by the systemd-udevd.service(8) builtin netid and\nexported as udev properties (IDNETNAMEONBOARD=,\nIDNETLABELONBOARD=, IDNETNAMEPATH=, IDNETNAMESLOT=).\n\nNames and MAC addresses are derived from various stable device metadata\nattributes. Newer versions of udev take more of these attributes into\naccount, improving (and thus possibly changing) the names and addresses\nused for the same devices. Different versions of those generation rules\nare called \"naming schemes\". The default naming scheme is chosen at\ncompilation time. Usually this will be the latest implemented version,\nbut it is also possible to set one of the older versions to preserve\ncompatibility. This may be useful for example for distributions, which\nmay introduce new versions of systemd in stable releases without\nchanging the naming scheme. The naming scheme may also be overridden\nusing the net.naming-scheme= kernel command line switch, see systemd-\nudevd.service(8). Available naming schemes are described below.\n\nAfter the udev properties have been generated, appropriate udev rules\nmay be used to actually rename devices based on those properties. See\nthe description of NamePolicy= and MACAddressPolicy= in\nsystemd.link(5).\n\nNote that while the concept of network interface naming schemes is\nprimarily relevant in the context of systemd-udevd.service, the\nsystemd-nspawn(1) container manager also takes it into account when\nnaming network interfaces, see below.\n", "subsections": [] }, "NAMING": { "content": "All names start with a two-character prefix that signifies the\ninterface type.\n\nTable 1. Two character prefixes based on the type of interface\n+-------+----------------------------+\n|Prefix | Description |\n+-------+----------------------------+\n|en | Ethernet |\n+-------+----------------------------+\n|ib | InfiniBand |\n+-------+----------------------------+\n|sl | Serial line IP (slip) |\n+-------+----------------------------+\n|wl | Wireless local area |\n| | network (WLAN) |\n+-------+----------------------------+\n|ww | Wireless wide area network |\n| | (WWAN) |\n+-------+----------------------------+\n\nThe udev netid builtin exports the following udev device properties:\n\nIDNETNAMEONBOARD=prefixonumber\nThis name is set based on the numeric ordering information given by\nthe firmware for on-board devices. The name consists of the prefix,\nletter o, and a number specified by the firmware. This is only\navailable for PCI devices.\n\nIDNETLABELONBOARD=prefix label\nThis property is set based on textual label given by the firmware\nfor on-board devices. The name consists of the prefix concatenated\nwith the label. This is only available for PCI devices.\n\nIDNETNAMEMAC=prefixxAABBCCDDEEFF\nThis name consists of the prefix, letter x, and 12 hexadecimal\ndigits of the MAC address. It is available if the device has a\nfixed MAC address. Because this name is based on an attribute of\nthe card itself, it remains \"stable\" when the device is moved (even\nbetween machines), but will change when the hardware is replaced.\n\nIDNETNAMESLOT=prefix[Pdomain]sslot[ffunction][nportname|ddevport],\nIDNETNAMESLOT=prefixvslot,\nIDNETNAMESLOT=prefix[Pdomain]sslot[ffunction][nportname|ddevport]bnumber,\nIDNETNAMESLOT=prefix[Pdomain]sslot[ffunction][nportname|ddevport]uport...[cconfig][iinterface],\nIDNETNAMESLOT=prefix[Pdomain]sslot[ffunction][nportname|ddevport]vslot\nThis property describes the slot position. Different schemes are\nused depending on the bus type, as described in the table below. In\ncase of USB, BCMA, and SR-VIO devices, the full name consists of\nthe prefix, PCI slot identifier, and USB or BCMA or SR-VIO slot\nidentifier. The first two parts are denoted as \"...\" in the table\nbelow.\n\nTable 2. Slot naming schemes\n+------------------------------------------------------------+--------------------------+\n|Format | Description |\n+------------------------------------------------------------+--------------------------+\n|prefix [Pdomain] sslot [ffunction] [nportname | ddevport] | PCI slot number |\n+------------------------------------------------------------+--------------------------+\n|prefix vslot | VIO slot number (IBM |\n| | PowerVM) |\n+------------------------------------------------------------+--------------------------+\n|... bnumber | Broadcom bus (BCMA) core |\n| | number |\n+------------------------------------------------------------+--------------------------+\n|... uport... [cconfig] [iinterface] | USB port number chain |\n+------------------------------------------------------------+--------------------------+\n|... vslot | SR-VIO slot number |\n+------------------------------------------------------------+--------------------------+\nThe PCI domain is only prepended when it is not 0. All\nmulti-function PCI devices will carry the ffunction number in the\ndevice name, including the function 0 device. For\nnon-multi-function devices, the number is suppressed if 0. The port\nname portname is used, or the port number ddevport if the name is\nnot known.\n\nFor BCMA devices, the core number is suppressed when 0.\n\nFor USB devices the full chain of port numbers of hubs is composed.\nIf the name gets longer than the maximum number of 15 characters,\nthe name is not exported. The usual USB configuration number 1 and\ninterface number 0 values are suppressed.\n\nSR-IOV virtual devices are named based on the name of the parent\ninterface, with a suffix of v and the virtual device number, with\nany leading zeros removed. The bus number is ignored.\n\nIn some configurations a parent PCI bridge of a given network\ncontroller may be associated with a slot. In such case we don't\ngenerate this device property to avoid possible naming conflicts.\n\nIDNETNAMEPATH=prefixcbusid,\nIDNETNAMEPATH=prefixavendormodeliinstance,\nIDNETNAMEPATH=prefixiaddressnportname,\nIDNETNAMEPATH=prefix[Pdomain]pbussslot[ffunction][nphysportname|ddevport],\nIDNETNAMEPATH=prefix[Pdomain]pbussslot[ffunction][nphysportname|ddevport]bnumber,\nIDNETNAMEPATH=prefix[Pdomain]pbussslot[ffunction][nphysportname|ddevport]uport...[cconfig][iinterface]\nThis property describes the device installation location. Different\nschemes are used depending on the bus type, as described in the\ntable below. For BCMA and USB devices, PCI path information must\nknown, and the full name consists of the prefix, PCI slot\nidentifier, and USB or BCMA location. The first two parts are\ndenoted as \"...\" in the table below.\n\nTable 3. Path naming schemes\n+----------------------------------------------------------------------+---------------------------+\n|Format | Description |\n+----------------------------------------------------------------------+---------------------------+\n|prefix cbusid | CCW or grouped CCW device |\n| | identifier |\n+----------------------------------------------------------------------+---------------------------+\n|prefix avendor model iinstance | ACPI path names for ARM64 |\n| | platform devices |\n+----------------------------------------------------------------------+---------------------------+\n|prefix iaddress nportname | Netdevsim (simulated |\n| | networking device) device |\n| | number and port name |\n+----------------------------------------------------------------------+---------------------------+\n|prefix [Pdomain] pbus sslot [ffunction] [nphysportname | ddevport] | PCI geographical location |\n+----------------------------------------------------------------------+---------------------------+\n|... bnumber | Broadcom bus (BCMA) core |\n| | number |\n+----------------------------------------------------------------------+---------------------------+\n|... uport... [cconfig] [iinterface] | USB port number chain |\n+----------------------------------------------------------------------+---------------------------+\nCCW and grouped CCW devices are found in IBM System Z mainframes.\nAny leading zeros and dots are suppressed.\n\nFor PCI, BCMA, and USB devices, the same rules as described above\nfor slot naming are used.\n", "subsections": [] }, "HISTORY": { "content": "The following \"naming schemes\" have been defined (which may be chosen\nat system boot-up time via the net.naming-scheme= kernel command line\nswitch, see above):\n\nv238\nThis is the naming scheme that was implemented in systemd 238.\n\nv239\nNaming was changed for virtual network interfaces created with\nSR-IOV and NPAR and for devices where the PCI network controller\ndevice does not have a slot number associated.\n\nSR-IOV virtual devices are named based on the name of the parent\ninterface, with a suffix of \"vport\", where port is the virtual\ndevice number. Previously those virtual devices were named as if\ncompletely independent.\n\nThe ninth and later NPAR virtual devices are named following the\nscheme used for the first eight NPAR partitions. Previously those\ndevices were not renamed and the kernel default (\"ethN\") was used.\n\nNames are also generated for PCI devices where the PCI network\ncontroller device does not have an associated slot number itself,\nbut one of its parents does. Previously those devices were not\nrenamed and the kernel default was used.\n\nv240\nThe \"ib\" prefix and stable names for infiniband devices are\nintroduced. Previously those devices were not renamed.\n\nThe ACPI index field (used in IDNETNAMEONBOARD=) is now also\nused when 0.\n\nA new naming policy NamePolicy=keep was introduced. With this\npolicy, if the network device name was already set by userspace,\nthe device will not be renamed again. Previously, this naming\npolicy applied implicitly, and now it must be explicitly requested.\nEffectively, this means that network devices will be renamed\naccording to the configuration, even if they have been renamed\nalready, if keep is not specified as the naming policy in the .link\nfile. See systemd.link(5) for a description of NamePolicy=.\n\nv241\nMACAddressPolicy=persistent was extended to set MAC addresses based\non the device name. Previously addresses were only based on the\nIDNETNAME* attributes, which meant that interface names would\nnever be generated for virtual devices. Now a persistent address\nwill be generated for most devices, including in particular\nbridges.\n\nNote: when userspace does not set a MAC address for a bridge\ndevice, the kernel will initially assign a random address, and then\nchange it when the first device is enslaved to the bridge. With\nthis naming policy change, bridges get a persistent MAC address\nbased on the bridge name instead of the first enslaved device.\n\nv243\nSupport for renaming netdevsim (simulated networking) devices was\nadded. Previously those devices were not renamed.\n\nPreviously two-letter interface type prefix was prepended to\nIDNETLABELONBOARD=. This is not done anymore.\n\nv245\nWhen systemd-nspawn(1) derives the name for the host side of the\nnetwork interface created with --network-veth from the container\nname it previously simply truncated the result at 15 characters if\nlonger (since that's the maximum length for network interface\nnames). From now on, for any interface name that would be longer\nthan 15 characters the last 4 characters are set to a 24bit hash\nvalue of the full interface name. This way network interface name\ncollisions between multiple similarly named containers (who only\ndiffer in container name suffix) should be less likely (but still\npossible, since the 24bit hash value is very small).\n\nv247\nWhen a PCI slot is associated with a PCI bridge that has multiple\nchild network controllers, the same value of the IDNETNAMESLOT\nproperty might be derived for those controllers. This would cause a\nnaming conflict if the property is selected as the device name.\nNow, we detect this situation and don't produce the\nIDNETNAMESLOT property.\n\nv249\nPCI hotplug slot names for the s390 PCI driver are a hexadecimal\nrepresentation of the functionid device attribute. This attribute\nis now used to build the IDNETNAMESLOT. Before that, all slot\nnames were parsed as decimal numbers, which could either result in\nan incorrect value of the IDNETNAMESLOT property or none at all.\n\nSome firmware and hypervisor implementations report unreasonable\nhigh numbers for the onboard index. To prevent the generation of\nbogus onbard interface names, index numbers greater than 16381\n(2^14-1) were ignored. For s390 PCI devices index values up to\n65535 (2^16-1) are valid. To account for that, the limit is\nincreased to now 65535.\n\nThe udev rule NAME= replaces \":\", \"/\", and \"%\" with an underscore\n(\"\"), and refuses strings which contain only numerics.\n\nNote that latest may be used to denote the latest scheme known (to this\nparticular version of systemd).\n", "subsections": [] }, "EXAMPLES": { "content": "Example 1. Using udevadm test-builtin to display device properties\n\n$ udevadm test-builtin netid /sys/class/net/enp0s31f6\n...\nUsing default interface naming scheme 'v243'.\nIDNETNAMINGSCHEME=v243\nIDNETNAMEMAC=enx54ee75cb1dc0\nIDOUIFROMDATABASE=Wistron InfoComm(Kunshan)Co.,Ltd.\nIDNETNAMEPATH=enp0s31f6\n...\n\nExample 2. PCI Ethernet card with firmware index \"1\"\n\nIDNETNAMEONBOARD=eno1\nIDNETNAMEONBOARDLABEL=Ethernet Port 1\n\nExample 3. PCI Ethernet card in hotplug slot with firmware index number\n\n# /sys/devices/pci0000:00/0000:00:1c.3/0000:05:00.0/net/ens1\nIDNETNAMEMAC=enx000000000466\nIDNETNAMEPATH=enp5s0\nIDNETNAMESLOT=ens1\n\nExample 4. PCI Ethernet multi-function card with 2 ports\n\n# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.0/net/enp2s0f0\nIDNETNAMEMAC=enx78e7d1ea46da\nIDNETNAMEPATH=enp2s0f0\n\n# /sys/devices/pci0000:00/0000:00:1c.0/0000:02:00.1/net/enp2s0f1\nIDNETNAMEMAC=enx78e7d1ea46dc\nIDNETNAMEPATH=enp2s0f1\n\nExample 5. PCI WLAN card\n\n# /sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/wlp3s0\nIDNETNAMEMAC=wlx0024d7e31130\nIDNETNAMEPATH=wlp3s0\n\nExample 6. PCI IB host adapter with 2 ports\n\n# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.0/net/ibp21s0f0\nIDNETNAMEPATH=ibp21s0f0\n\n# /sys/devices/pci0000:00/0000:00:03.0/0000:15:00.1/net/ibp21s0f1\nIDNETNAMEPATH=ibp21s0f1\n\nExample 7. USB built-in 3G modem\n\n# /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.4/2-1.4:1.6/net/wwp0s29u1u4i6\nIDNETNAMEMAC=wwx028037ec0200\nIDNETNAMEPATH=wwp0s29u1u4i6\n\nExample 8. USB Android phone\n\n# /sys/devices/pci0000:00/0000:00:1d.0/usb2/2-1/2-1.2/2-1.2:1.0/net/enp0s29u1u2\nIDNETNAMEMAC=enxd626b3450fb5\nIDNETNAMEPATH=enp0s29u1u2\n\nExample 9. s390 grouped CCW interface\n\n# /sys/devices/css0/0.0.0007/0.0.f5f0/groupdevice/net/encf5f0\nIDNETNAMEMAC=enx026d3c00000a\nIDNETNAMEPATH=encf5f0\n", "subsections": [] }, "SEE ALSO": { "content": "udev(7), udevadm(8), Predictable Network Interface Names[1], systemd-\nnspawn(1)\n", "subsections": [] }, "NOTES": { "content": "1. Predictable Network Interface Names\nhttps://systemd.io/PREDICTABLEINTERFACENAMES\n\nsystemd 249 SYSTEMD.NET-NAMING-SCHEME(7)", "subsections": [] } } } }