Debian Codegraph @

upstream/debian-trixie/man7/systemd.net-naming-scheme.7

raw
1 '\" t
2 .TH "SYSTEMD\&.NET\-NAMING\-SCHEME" "7" "" "systemd 257.13" "systemd.net-naming-scheme"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd.net-naming-scheme \- Network device naming schemes
24 .SH "DESCRIPTION"
25 .PP
26 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
27 \fBsystemd-udevd.service\fR(8)
28 builtin
29 \fBnet_id\fR
30 and exported as
31 \fBudev\fR(7)
32 properties (\fIID_NET_NAME_ONBOARD=\fR,
33 \fIID_NET_LABEL_ONBOARD=\fR,
34 \fIID_NET_NAME_PATH=\fR,
35 \fIID_NET_NAME_SLOT=\fR)\&.
36 .PP
37 Names and MAC addresses are derived from various stable device metadata attributes\&. Newer versions of
38 \fBsystemd\-udevd\fR
39 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
40 \fInet\&.naming_scheme=\fR
41 kernel command line switch, see
42 \fBsystemd-udevd.service\fR(8)\&. Available naming schemes are described below\&.
43 .PP
44 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
45 \fINamePolicy=\fR
46 and
47 \fIMACAddressPolicy=\fR
48 in
49 \fBsystemd.link\fR(5)\&.
50 .PP
51 Note that while the concept of network interface naming schemes is primarily relevant in the context of
52 systemd\-udevd\&.service, the
53 \fBsystemd-nspawn\fR(1)
54 container manager also takes it into account when naming network interfaces, see below\&.
55 .SH "POLICIES"
56 .PP
57 All names start with a two\-character prefix that signifies the interface type\&.
58 .sp
59 .it 1 an-trap
60 .nr an-no-space-flag 1
61 .nr an-break-flag 1
62 .br
63 .B Table\ \&1.\ \&Two character prefixes based on the type of interface
64 .TS
65 allbox tab(:);
66 lB lB.
67 T{
68 Prefix
69 T}:T{
70 Description
71 T}
72 .T&
73 l l
74 l l
75 l l
76 l l
77 l l.
78 T{
79 \fBen\fR
80 T}:T{
81 Ethernet
82 T}
83 T{
84 \fBib\fR
85 T}:T{
86 InfiniBand
87 T}
88 T{
89 \fBsl\fR
90 T}:T{
91 Serial line IP (slip)
92 T}
93 T{
94 \fBwl\fR
95 T}:T{
96 Wireless local area network (WLAN)
97 T}
98 T{
99 \fBww\fR
100 T}:T{
101 Wireless wide area network (WWAN)
102 T}
103 .TE
104 .sp 1
105 .PP
106 The
107 \fBudev\fR(7)
108 \fBnet_id\fR
109 builtin exports the following device properties:
110 .PP
111 \fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBo\fR\fInumber\fR, \fIID_NET_NAME_ONBOARD=\fR\fIprefix\fR\fBd\fR\fInumber\fR
112 .RS 4
113 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\&.
114 .sp
115 .it 1 an-trap
116 .nr an-no-space-flag 1
117 .nr an-break-flag 1
118 .br
119 .B Table\ \&2.\ \&On\-board naming schemes
120 .TS
121 allbox tab(:);
122 lB lB.
123 T{
124 Format
125 T}:T{
126 Description
127 T}
128 .T&
129 l l
130 l l.
131 T{
132 \fIprefix\fR\fBo\fR\fInumber\fR
133 T}:T{
134 PCI on\-board index
135 T}
136 T{
137 \fIprefix\fR\fBd\fR\fInumber\fR
138 T}:T{
139 DeviceTree alias index
140 T}
141 .TE
142 .sp 1
143 Added in version 243\&.
144 .RE
145 .PP
146 \fIID_NET_LABEL_ONBOARD=\fR\fIlabel\fR
147 .RS 4
148 This property is set based on textual label given by the firmware for on\-board devices\&. This is only available for PCI devices\&.
149 .sp
150 Added in version 243\&.
151 .RE
152 .PP
153 \fIID_NET_NAME_MAC=\fR\fIprefix\fR\fBx\fR\fIAABBCCDDEEFF\fR
154 .RS 4
155 This name consists of the prefix, letter
156 \fBx\fR, 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\&.
157 .sp
158 Added in version 243\&.
159 .RE
160 .PP
161 \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR\fBx\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR], \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBv\fR\fIslot\fR, \fIID_NET_NAME_SLOT=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIport_name\fR|\fBd\fR\fIdev_port\fR]\fBr\fR\fIslot\fR
162 .RS 4
163 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\&.
164 .sp
165 .it 1 an-trap
166 .nr an-no-space-flag 1
167 .nr an-break-flag 1
168 .br
169 .B Table\ \&3.\ \&Slot naming schemes
170 .TS
171 allbox tab(:);
172 lB lB.
173 T{
174 Format
175 T}:T{
176 Description
177 T}
178 .T&
179 l l
180 l l
181 l l
182 l l
183 l l
184 l l
185 l l.
186 T{
187 \fIprefix\fR\ \&[\fBP\fR\fIdomain\fR]\ \&\fBs\fR\fIslot\fR\ \&[\fBf\fR\fIfunction\fR]\ \&[\fBn\fR\fIport_name\fR\ \&|\ \&\fBd\fR\fIdev_port\fR]
188 T}:T{
189 PCI slot number
190 T}
191 T{
192 \fIprefix\fR\ \&\fBv\fR\fIslot\fR
193 T}:T{
194 VIO slot number (IBM PowerVM)
195 T}
196 T{
197 \fIprefix\fR\ \&\fBX\fR\fInumber\fR
198 T}:T{
199 VIF interface number (Xen)
200 T}
201 T{
202 \&...\ \&\fBb\fR\fInumber\fR
203 T}:T{
204 Broadcom bus (BCMA) core number
205 T}
206 T{
207 \&...\ \&\fBu\fR\fIport\fR\&...\ \&[\fBc\fR\fIconfig\fR]\ \&[\fBi\fR\fIinterface\fR]
208 T}:T{
209 USB port number chain
210 T}
211 T{
212 \&...\ \&\fBv\fR\fIslot\fR
213 T}:T{
214 SR\-VIO slot number
215 T}
216 T{
217 \&...\ \&\fBr\fR\fIslot\fR
218 T}:T{
219 SR\-IOV slot number
220 T}
221 .TE
222 .sp 1
223 The PCI domain is only prepended when it is not 0\&. All multi\-function PCI devices will carry the
224 \fBf\fR\fIfunction\fR
225 number in the device name, including the function 0 device\&. For non\-multi\-function devices, the number is suppressed if 0\&. The port name
226 \fIport_name\fR
227 is used, or the port number
228 \fBd\fR\fIdev_port\fR
229 if the name is not known\&.
230 .sp
231 For BCMA devices, the core number is suppressed when 0\&.
232 .sp
233 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\&.
234 .sp
235 SR\-IOV virtual devices are named based on the name of the parent interface, with a suffix of
236 \fBv\fR
237 and the virtual device number, with any leading zeros removed\&. The bus number is ignored\&.
238 .sp
239 SR\-IOV virtual device representors are named based on the name of the physical device interface, with a suffix of
240 \fBr\fR
241 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\&.
242 .sp
243 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\&.
244 .sp
245 Added in version 243\&.
246 .RE
247 .PP
248 \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBc\fR\fIbus_id\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBa\fR\fIvendor\fR\fImodel\fR\fBi\fR\fIinstance\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBi\fR\fIaddress\fR\fBn\fR\fIport_name\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR\fBu\fR\fIport\fR\&..., \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR], \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBb\fR\fInumber\fR, \fIID_NET_NAME_PATH=\fR\fIprefix\fR[\fBP\fR\fIdomain\fR]\fBp\fR\fIbus\fR\fBs\fR\fIslot\fR[\fBf\fR\fIfunction\fR][\fBn\fR\fIphys_port_name\fR|\fBd\fR\fIdev_port\fR]\fBu\fR\fIport\fR\&...[\fBc\fR\fIconfig\fR][\fBi\fR\fIinterface\fR]
249 .RS 4
250 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\&.
251 .sp
252 .it 1 an-trap
253 .nr an-no-space-flag 1
254 .nr an-break-flag 1
255 .br
256 .B Table\ \&4.\ \&Path naming schemes
257 .TS
258 allbox tab(:);
259 lB lB.
260 T{
261 Format
262 T}:T{
263 Description
264 T}
265 .T&
266 l l
267 l l
268 l l
269 l l
270 l l
271 l l.
272 T{
273 \fIprefix\fR\ \&\fBc\fR\fIbus_id\fR
274 T}:T{
275 CCW or grouped CCW device identifier
276 T}
277 T{
278 \fIprefix\fR\ \&\fBa\fR\fIvendor\fR\ \&\fImodel\fR\ \&\fBi\fR\fIinstance\fR
279 T}:T{
280 ACPI path names for ARM64 platform devices
281 T}
282 T{
283 \fIprefix\fR\ \&\fBi\fR\fIaddress\fR\ \&\fBn\fR\fIport_name\fR
284 T}:T{
285 Netdevsim (simulated networking device) device number and port name
286 T}
287 T{
288 \fIprefix\fR\ \&[\fBP\fR\fIdomain\fR]\ \&\fBp\fR\fIbus\fR\ \&\fBs\fR\fIslot\fR\ \&[\fBf\fR\fIfunction\fR]\ \&[\fBn\fR\fIphys_port_name\fR\ \&|\ \&\fBd\fR\fIdev_port\fR]
289 T}:T{
290 PCI geographical location
291 T}
292 T{
293 \&...\ \&\fBb\fR\fInumber\fR
294 T}:T{
295 Broadcom bus (BCMA) core number
296 T}
297 T{
298 \&...\ \&\fBu\fR\fIport\fR\&...\ \&[\fBc\fR\fIconfig\fR]\ \&[\fBi\fR\fIinterface\fR]
299 T}:T{
300 USB port number chain
301 T}
302 .TE
303 .sp 1
304 CCW and grouped CCW devices are found in IBM System Z mainframes\&. Any leading zeros and dots are suppressed\&.
305 .sp
306 For PCI, BCMA, and USB devices, the same rules as described above for slot naming are used\&.
307 .sp
308 Added in version 243\&.
309 .RE
310 .SH "HISTORY"
311 .PP
312 The following "naming schemes" have been defined (which may be chosen at system boot\-up time via the
313 \fInet\&.naming_scheme=\fR
314 kernel command line switch, see above):
315 .PP
316 \fBv238\fR
317 .RS 4
318 This is the naming scheme that was implemented in systemd 238\&.
319 .sp
320 Added in version 243\&.
321 .RE
322 .PP
323 \fBv239\fR
324 .RS 4
325 Naming was changed for virtual network interfaces created with SR\-IOV and NPAR and for devices where the PCI network controller device does not have a slot number associated\&.
326 .sp
327 SR\-IOV virtual devices are named based on the name of the parent interface, with a suffix of
328 "v\fIport\fR", where
329 \fIport\fR
330 is the virtual device number\&. Previously those virtual devices were named as if completely independent\&.
331 .sp
332 The ninth and later NPAR virtual devices are named following the scheme used for the first eight NPAR partitions\&. Previously those devices were not renamed and the kernel default ("eth\fIN\fR") was used\&.
333 .sp
334 Names are also generated for PCI devices where the PCI network controller device does not have an associated slot number itself, but one of its parents does\&. Previously those devices were not renamed and the kernel default was used\&.
335 .sp
336 Added in version 243\&.
337 .RE
338 .PP
339 \fBv240\fR
340 .RS 4
341 The
342 "ib"
343 prefix and stable names for infiniband devices are introduced\&. Previously those devices were not renamed\&.
344 .sp
345 The ACPI index field (used in
346 \fIID_NET_NAME_ONBOARD=\fR) is now also used when 0\&.
347 .sp
348 A new naming policy
349 \fINamePolicy=keep\fR
350 was introduced\&. With this policy, if the network device name was already set by userspace, the device will not be renamed again\&. Previously, this naming policy applied implicitly, and now it must be explicitly requested\&. Effectively, this means that network devices will be renamed according to the configuration, even if they have been renamed already, if
351 \fBkeep\fR
352 is not specified as the naming policy in the
353 \&.link
354 file\&. See
355 \fBsystemd.link\fR(5)
356 for a description of
357 \fINamePolicy=\fR\&.
358 .sp
359 Added in version 243\&.
360 .RE
361 .PP
362 \fBv241\fR
363 .RS 4
364 \fBMACAddressPolicy=persistent\fR
365 was extended to set MAC addresses based on the device name\&. Previously addresses were only based on the
366 \fIID_NET_NAME_*\fR
367 attributes, which meant that interface names would never be generated for virtual devices\&. Now a persistent address will be generated for most devices, including in particular bridges\&.
368 .sp
369 Note: when userspace does not set a MAC address for a bridge device, the kernel will initially assign a random address, and then change it when the first device is enslaved to the bridge\&. With this naming policy change, bridges get a persistent MAC address based on the bridge name instead of the first enslaved device\&.
370 .sp
371 Added in version 243\&.
372 .RE
373 .PP
374 \fBv243\fR
375 .RS 4
376 Support for renaming netdevsim (simulated networking) devices was added\&. Previously those devices were not renamed\&.
377 .sp
378 Previously two\-letter interface type prefix was prepended to
379 \fIID_NET_LABEL_ONBOARD=\fR\&. This is not done anymore\&.
380 .sp
381 Added in version 243\&.
382 .RE
383 .PP
384 \fBv245\fR
385 .RS 4
386 When
387 \fBsystemd-nspawn\fR(1)
388 derives the name for the host side of the network interface created with
389 \fB\-\-network\-veth\fR
390 from the container name it previously simply truncated the result at 15 characters if longer (since that\*(Aqs the maximum length for network interface names)\&. From now on, for any interface name that would be longer than 15 characters the last 4 characters are set to a 24bit hash value of the full interface name\&. This way network interface name collisions between multiple similarly named containers (who only differ in container name suffix) should be less likely (but still possible, since the 24bit hash value is very small)\&.
391 .sp
392 Added in version 245\&.
393 .RE
394 .PP
395 \fBv247\fR
396 .RS 4
397 When a PCI slot is associated with a PCI bridge that has multiple child network controllers, the same value of the
398 \fIID_NET_NAME_SLOT\fR
399 property might be derived for those controllers\&. This would cause a naming conflict if the property is selected as the device name\&. Now, we detect this situation and do not produce the
400 \fIID_NET_NAME_SLOT\fR
401 property\&.
402 .sp
403 Added in version 247\&.
404 .RE
405 .PP
406 \fBv249\fR
407 .RS 4
408 PCI hotplug slot names for the s390 PCI driver are a hexadecimal representation of the
409 function_id
410 device attribute\&. This attribute is now used to build the
411 \fIID_NET_NAME_SLOT\fR\&. Before that, all slot names were parsed as decimal numbers, which could either result in an incorrect value of the
412 \fIID_NET_NAME_SLOT\fR
413 property or none at all\&.
414 .sp
415 Some firmware and hypervisor implementations report unreasonably high numbers for the on\-board index\&. To prevent the generation of bogus on\-board interface names, index numbers greater than 16381 (2\(S1⁴\-1) were ignored\&. For s390 PCI devices index values up to 65535 (2\(S1⁶\-1) are valid\&. To account for that, the limit was increased to 65535\&.
416 .sp
417 The
418 \fBudev\fR(7)
419 rule
420 \fINAME=\fR
421 replaces
422 ":",
423 "/", and
424 "%"
425 with an underscore ("_"), and refuses strings which contain only digits\&.
426 .sp
427 Added in version 249\&.
428 .RE
429 .PP
430 \fBv250\fR
431 .RS 4
432 Added naming scheme for Xen netfront "vif" interfaces based on the guest side VIF number set from the Xen config (or the interface index in AWS EC2)\&.
433 .sp
434 Added in version 250\&.
435 .RE
436 .PP
437 \fBv251\fR
438 .RS 4
439 Since version
440 \fBv247\fR
441 we no longer set
442 \fIID_NET_NAME_SLOT\fR
443 if we detect that a PCI device associated with a slot is a PCI bridge as that would create naming conflict when there are more child devices on that bridge\&. Now, this is relaxed and we will use slot information to generate the name based on it but only if the PCI device has multiple functions\&. This is safe because distinct function number is a part of the device name for multifunction devices\&. Note, this is reverted in
444 \fBv255\fR\&. See below\&.
445 .sp
446 Added in version 251\&.
447 .RE
448 .PP
449 \fBv252\fR
450 .RS 4
451 Added naming scheme for platform devices with devicetree aliases\&.
452 .sp
453 Added in version 252\&.
454 .RE
455 .PP
456 \fBv253\fR
457 .RS 4
458 Set
459 \fIID_NET_NAME_PATH\fR
460 for usb devices not connected via a PCI bus\&.
461 .sp
462 Added in version 253\&.
463 .RE
464 .PP
465 \fBv254\fR
466 .RS 4
467 Naming was changed for SR\-IOV virtual device representors, optionally settable at compilation time\&. The
468 "r\fIslot\fR"
469 suffix was added to differentiate SR\-IOV virtual device representors attached to a single physical device interface\&. Because of a mistake, this scheme was
470 \fInot the default scheme for systemd version 254\fR\&.
471 .sp
472 Added in version 255\&.
473 .RE
474 .PP
475 \fBv255\fR
476 .RS 4
477 Naming was changed for SR\-IOV virtual device representors to enable the change introduced in
478 \fBv254\fR
479 by default\&.
480 .sp
481 If we detect that a PCI device associated with a slot is a PCI bridge, we no longer set
482 \fIID_NET_NAME_SLOT\fR, reverting a change that was introduced in
483 \fBv251\fR\&.
484 .sp
485 Added in version 255\&.
486 .RE
487 .PP
488 \fBv257\fR
489 .RS 4
490 PCI slot number is now read from
491 \fBfirmware_node/sun\fR
492 sysfs file\&.
493 .sp
494 The naming scheme based on devicetree aliases was extended to support aliases for individual interfaces of controllers with multiple ports\&.
495 .sp
496 Added in version 257\&.
497 .RE
498 .PP
499 Note that
500 \fBlatest\fR
501 may be used to denote the latest scheme known (to this particular version of systemd)\&.
502 .SH "LIMITING THE USE OF SPECIFIC SYSFS ATTRIBUTES"
503 .PP
504 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
505 \fBudev\fR(7)
506 is picked, the network card\*(Aqs name can still change when a new kernel version adds a new sysfs attribute\&. For example, if kernel starts setting the
507 \fBphys_port_name\fR,
508 \fBudev\fR
509 will append the "\fBn\fR\fIphys_port_name\fR" suffix to the device name\&.
510 .PP
511 \fIID_NET_NAME_ALLOW=\fR\fIBOOL\fR
512 .RS 4
513 This udev property sets a fallback policy for reading a sysfs attribute\&. If set to
514 \fB0\fR
515 udev will not read any sysfs attribute by default, unless it is explicitly allowlisted, see below\&. If set to
516 \fB1\fR
517 udev can use any sysfs attribute unless it is explicitly forbidden\&. The default value is
518 \fB1\fR\&.
519 .sp
520 Added in version 256\&.
521 .RE
522 .PP
523 \fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=\fR\fI\fIBOOL\fR\fR
524 .RS 4
525 This udev property explicitly states if udev shall use the specified
526 \fIsysfsattr\fR, when composing the device name\&.
527 .sp
528 Added in version 256\&.
529 .RE
530 .PP
531 With these options, users can set an allowlist or denylist for sysfs attributes\&. To create an allowlist, the user needs to set
532 \fIID_NET_NAME_ALLOW=0\fR
533 for the device and then list the allowed attributes with the
534 \fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=1\fR
535 options\&. In case of a denylist, the user needs to provide the list of denied attributes with the
536 \fIID_NET_NAME_ALLOW_\fR\fI\fIsysfsattr\fR\fR\fI=0\fR
537 options\&.
538 .SH "EXAMPLES"
539 .PP
540 \fBExample\ \&1.\ \&Using udevadm test\-builtin to display device properties\fR
541 .sp
542 .if n \{\
543 .RS 4
544 .\}
545 .nf
546 $ udevadm test\-builtin net_id /sys/class/net/enp0s31f6
547 \&.\&.\&.
548 Using default interface naming scheme \*(Aqv243\*(Aq\&.
549 ID_NET_NAMING_SCHEME=v243
550 ID_NET_NAME_MAC=enx54ee75cb1dc0
551 ID_OUI_FROM_DATABASE=Wistron InfoComm(Kunshan)Co\&.,Ltd\&.
552 ID_NET_NAME_PATH=enp0s31f6
553 \&.\&.\&.
554 .fi
555 .if n \{\
556 .RE
557 .\}
558 .PP
559 \fBExample\ \&2.\ \&PCI Ethernet card with firmware index "1"\fR
560 .sp
561 .if n \{\
562 .RS 4
563 .\}
564 .nf
565 ID_NET_NAME_ONBOARD=eno1
566 ID_NET_NAME_ONBOARD_LABEL=Ethernet Port 1
567 .fi
568 .if n \{\
569 .RE
570 .\}
571 .PP
572 \fBExample\ \&3.\ \&PCI Ethernet card in slot with firmware index number\fR
573 .sp
574 .if n \{\
575 .RS 4
576 .\}
577 .nf
578 # /sys/devices/pci0000:00/0000:00:1c\&.3/0000:05:00\&.0/net/ens1
579 ID_NET_NAME_MAC=enx000000000466
580 ID_NET_NAME_PATH=enp5s0
581 ID_NET_NAME_SLOT=ens1
582 .fi
583 .if n \{\
584 .RE
585 .\}
586 .PP
587 \fBExample\ \&4.\ \&PCI Ethernet multi\-function card with 2 ports\fR
588 .sp
589 .if n \{\
590 .RS 4
591 .\}
592 .nf
593 # /sys/devices/pci0000:00/0000:00:1c\&.0/0000:02:00\&.0/net/enp2s0f0
594 ID_NET_NAME_MAC=enx78e7d1ea46da
595 ID_NET_NAME_PATH=enp2s0f0
596
597 # /sys/devices/pci0000:00/0000:00:1c\&.0/0000:02:00\&.1/net/enp2s0f1
598 ID_NET_NAME_MAC=enx78e7d1ea46dc
599 ID_NET_NAME_PATH=enp2s0f1
600 .fi
601 .if n \{\
602 .RE
603 .\}
604 .PP
605 \fBExample\ \&5.\ \&PCI WLAN card\fR
606 .sp
607 .if n \{\
608 .RS 4
609 .\}
610 .nf
611 # /sys/devices/pci0000:00/0000:00:1c\&.1/0000:03:00\&.0/net/wlp3s0
612 ID_NET_NAME_MAC=wlx0024d7e31130
613 ID_NET_NAME_PATH=wlp3s0
614 .fi
615 .if n \{\
616 .RE
617 .\}
618 .PP
619 \fBExample\ \&6.\ \&PCI IB host adapter with 2 ports\fR
620 .sp
621 .if n \{\
622 .RS 4
623 .\}
624 .nf
625 # /sys/devices/pci0000:00/0000:00:03\&.0/0000:15:00\&.0/net/ibp21s0f0
626 ID_NET_NAME_PATH=ibp21s0f0
627
628 # /sys/devices/pci0000:00/0000:00:03\&.0/0000:15:00\&.1/net/ibp21s0f1
629 ID_NET_NAME_PATH=ibp21s0f1
630 .fi
631 .if n \{\
632 .RE
633 .\}
634 .PP
635 \fBExample\ \&7.\ \&USB built\-in 3G modem\fR
636 .sp
637 .if n \{\
638 .RS 4
639 .\}
640 .nf
641 # /sys/devices/pci0000:00/0000:00:1d\&.0/usb2/2\-1/2\-1\&.4/2\-1\&.4:1\&.6/net/wwp0s29u1u4i6
642 ID_NET_NAME_MAC=wwx028037ec0200
643 ID_NET_NAME_PATH=wwp0s29u1u4i6
644 .fi
645 .if n \{\
646 .RE
647 .\}
648 .PP
649 \fBExample\ \&8.\ \&USB Android phone\fR
650 .sp
651 .if n \{\
652 .RS 4
653 .\}
654 .nf
655 # /sys/devices/pci0000:00/0000:00:1d\&.0/usb2/2\-1/2\-1\&.2/2\-1\&.2:1\&.0/net/enp0s29u1u2
656 ID_NET_NAME_MAC=enxd626b3450fb5
657 ID_NET_NAME_PATH=enp0s29u1u2
658 .fi
659 .if n \{\
660 .RE
661 .\}
662 .PP
663 \fBExample\ \&9.\ \&s390 grouped CCW interface\fR
664 .sp
665 .if n \{\
666 .RS 4
667 .\}
668 .nf
669 # /sys/devices/css0/0\&.0\&.0007/0\&.0\&.f5f0/group_device/net/encf5f0
670 ID_NET_NAME_MAC=enx026d3c00000a
671 ID_NET_NAME_PATH=encf5f0
672 .fi
673 .if n \{\
674 .RE
675 .\}
676 .PP
677 \fBExample\ \&10.\ \&Set an allowlist for reading sysfs attributes for network card naming\fR
678 .sp
679 .if n \{\
680 .RS 4
681 .\}
682 .nf
683 /etc/udev/hwdb\&.d/50\-net\-naming\-allowlist\&.hwdb
684 net:naming:drvirtio_net:*
685 ID_NET_NAME_ALLOW=0
686 ID_NET_NAME_ALLOW_ACPI_INDEX=1
687 ID_NET_NAME_ALLOW_ADDR_ASSIGN_TYPE=1
688 ID_NET_NAME_ALLOW_ADDRESS=1
689 ID_NET_NAME_ALLOW_ARI_ENABLED=1
690 ID_NET_NAME_ALLOW_DEV_PORT=1
691 ID_NET_NAME_ALLOW_FUNCTION_ID=1
692 ID_NET_NAME_ALLOW_IFLINK=1
693 ID_NET_NAME_ALLOW_INDEX=1
694 ID_NET_NAME_ALLOW_LABEL=1
695 ID_NET_NAME_ALLOW_PHYS_PORT_NAME=1
696 ID_NET_NAME_ALLOW_TYPE=1
697 .fi
698 .if n \{\
699 .RE
700 .\}
701 .PP
702 \fBExample\ \&11.\ \&Set a denylist so that specified sysfs attribute are ignored\fR
703 .sp
704 .if n \{\
705 .RS 4
706 .\}
707 .nf
708 /etc/udev/hwdb\&.d/50\-net\-naming\-denylist\&.hwdb
709 net:naming:drvirtio_net:*
710 ID_NET_NAME_ALLOW=1
711 ID_NET_NAME_ALLOW_DEV_PORT=0
712 ID_NET_NAME_ALLOW_PHYS_PORT_NAME=0
713 .fi
714 .if n \{\
715 .RE
716 .\}
717 .SH "SEE ALSO"
718 .PP
719 \fBudev\fR(7), \fBudevadm\fR(8), \fBsystemd-udevd.service\fR(8), \m[blue]\fBPredictable Network Interface Names\fR\m[]\&\s-2\u[1]\d\s+2, \fBsystemd-nspawn\fR(1)
720 .SH "NOTES"
721 .IP " 1." 4
722 Predictable Network Interface Names
723 .RS 4
724 \%https://systemd.io/PREDICTABLE_INTERFACE_NAMES
725 .RE