Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section

[Dmitry Semyonov]

Package: release-notes
Severity: important

The 5.1.5 section of the document[1] contains the following text:
[1]https://www.debian.org/releases/stable/amd64/release-notes/ch-information.en.html#migrate-interface-names

"(If the udevadm output includes an “onboard” name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)"

This text should be changed to something like this:

udevadm may list several potential names for a single interface. In this
case the final name is assigned according to the following list of
decreasing priorities:
* ID_NET_NAME_FROM_DATABASE
* ID_NET_NAME_ONBOARD
* ID_NET_NAME_SLOT
* ID_NET_NAME_PATH
* ID_NET_NAME_MAC

(MAC-based names are normally used only for USB network hardware.)

It is important to make the right choice when migrating interface names
on a remote system!

[Justin B Rye]

Post by Dmitry Semyonov
Package: release-notes
Severity: important
[1]https://www.debian.org/releases/stable/amd64/release-notes/ch-information.en.html#migrate-interface-names
"(If the udevadm output includes an “onboard” name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)"

(Notice that this is a parenthetical note. If it needs to be inflated
into an in-depth paragraph of explanations, the surrounding context
will also need to be changed to allow it to fit. The previous
sentence that this is an aside to was

This should give enough information to devise a migration plan.

which was intended to make it clear that readers need to think
carefully about what they're doing.)
Can you elaborate on why you think it needs to be changed? You never
state exactly what you think the important bug is here.

Post by Dmitry Semyonov
udevadm may list several potential names for a single interface.

(As I understand it, it will *always* list at least three
ID_NET_NAMEs, not all of which are potential names for interfaces.)

Post by Dmitry Semyonov
In this
case the final name is assigned according to the following list of
* ID_NET_NAME_FROM_DATABASE

This would mean that (on my current system) "ASUSTek COMPUTER INC."
would take priority - no. Mentioning this one at all is probably a
bad idea.

Post by Dmitry Semyonov
* ID_NET_NAME_ONBOARD

This is the one the Release Notes already warn will take priority if
present (on my system, it isn't).

Post by Dmitry Semyonov
* ID_NET_NAME_SLOT

This is the one it doesn't mention. If it's present, readers who are
following instructions will see it in the output and need to find out
for themselves what it means before they can construct their migration
plan - it's explained in the docs we point at* - but I've never seen
one and have no idea how common they are.

(* PS: or at least, it used to be - see below.)

Post by Dmitry Semyonov
* ID_NET_NAME_PATH
* ID_NET_NAME_MAC
(MAC-based names are normally used only for USB network hardware.)

There's an extra complication here that your order-of-priority list
doesn't account for. Given that it's possible to use MAC-based names
instead of the hardware-path-based, it must be possible (I've
forgotten the details) for udev to decide to use them even though
they're at the lowest priority level. Users of such USB hardware will
need to look up how that works.

The problem with giving too many details is that readers may assume
these are *all* the details they need to know, and for a topic like
this with its myriad corner-cases, I can't believe we're ever going to
be able to provide that One True Complete HOWTO Guide.

Post by Dmitry Semyonov
It is important to make the right choice when migrating interface names
on a remote system!

Well, yes - the fact that it's an important thing to get right is
already implied by the fact that the Release Notes go to the trouble
of offering instructions in the first place.

If the central point you're trying to make is that we need to warn
people about the possibility of ID_NET_NAME_SLOT taking priority over
ID_NET_NAME_PATH, we might be able to do that just by adding a few
extra words in the parenthesised text:

This should give enough information to devise a migration plan. (If
- the udevadm output includes an "onboard" name, that takes priority;
+ the udevadm output includes an "onboard" name or a "slot" name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)

But just how common are slot names? Is it in fact possible for a NIC
to have both an onboard name and a slot name? What we need is a guide
written by the people who actually understand all this that we can
point at. Hang on... in fact, now that I check the references, I
remember that the freedesktop.org docs that we point at used to
delegate the actually informative parts to a further "read the source"
link, and that sourcecode seems to have thrown away most of its
explanatory header:

https://github.com/systemd/systemd/blob/eefe36e64c1a583bb9470884ed92115e0ce4647e/src/udev/udev-builtin-net_id.c

...sigh.

It's looking as though the only workable solution for highly technical
problems like this is always going to be the one I adopted for
boottime entropy starvation: don't try to cram a complete explanation
into the Release Notes, just point at both an external source and a
Debian Wiki page where the people who care can document the issues.

The tricky part is probably going to be making sure it doesn't
degenerate into an everybody-hates-udev page.

[Dmitry Semyonov]

Justin,

Post by Justin B Rye

Post by Dmitry Semyonov
"(If the udevadm output includes an “onboard” name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)"

(Notice that this is a parenthetical note. If it needs to be inflated
into an in-depth paragraph of explanations, the surrounding context
will also need to be changed to allow it to fit. The previous
sentence that this is an aside to was
This should give enough information to devise a migration plan.

It would probably be enough for a local system but is clearly not
enough for a *safe* remote migration plan.

Post by Justin B Rye
which was intended to make it clear that readers need to think
carefully about what they're doing.)

To me this was just some vague sentence that didn't give any useful
information or warned about any pitfall, and thus was mostly ignored.

Post by Justin B Rye
Can you elaborate on why you think it needs to be changed? You never
state exactly what you think the important bug is here.

The existing text creates an impression that what you should pay
attention to is only the "onboard" name. Since all this was new to me,
there was no ONBOARD name, and there was the usual PATH name there, I
just assumed it was safe to use it without paying attention to the
presence of a SLOT name, (which non-intuitively was listed between the
lowest priority MAC and the lower priority PATH names).

Post by Justin B Rye

Post by Dmitry Semyonov
the final name is assigned according to the following list of
* ID_NET_NAME_FROM_DATABASE

This would mean that (on my current system) "ASUSTek COMPUTER INC."
would take priority - no.

You probably mixed it with the ID_OUI_FROM_DATABASE variable. The
ID_NET_NAME_FROM_DATABASE is very rare according to some documentation
I read while investigating the issue.

Post by Justin B Rye

Post by Dmitry Semyonov
* ID_NET_NAME_ONBOARD

This is the one the Release Notes already warn will take priority if
present (on my system, it isn't).

It would be a stretch to call parenthesized side note a warning.

Post by Justin B Rye

Post by Dmitry Semyonov
* ID_NET_NAME_SLOT

This is the one it doesn't mention. If it's present, readers who are
following instructions will see it in the output and need to find out
for themselves what it means before they can construct their migration
plan - it's explained in the docs we point at*

Somehow, it was not so obvious to me, and the referenced docs are also
not very clear about the name selection process, (not to mention a
bunch of unrelated information there you need to read through before
arriving at the important bits).

Post by Justin B Rye

Post by Dmitry Semyonov
* ID_NET_NAME_PATH
* ID_NET_NAME_MAC
(MAC-based names are normally used only for USB network hardware.)

There's an extra complication here that your order-of-priority list
doesn't account for.

Indeed, a USB-to-Ethernet dongle lists both MAC and PATH names but
uses the lower priority MAC name by default.
So, my last note should probably be:
"Warning: MAC names are normally preferred over PATH ones for USB
network hardware."

Post by Justin B Rye
The problem with giving too many details is that readers may assume
these are *all* the details they need to know, and for a topic like
this with its myriad corner-cases, I can't believe we're ever going to
be able to provide that One True Complete HOWTO Guide.

We can provide the most important information, (which hopefully I was
able to distill with your help), and clearly warn about potential
corner cases that will require a whole lot more reading and
understanding if one wants to be on the safe side while performing the
migration on a remote system.

Post by Justin B Rye

Post by Dmitry Semyonov
It is important to make the right choice when migrating interface names
on a remote system!

Well, yes - the fact that it's an important thing to get right is
already implied by the fact that the Release Notes go to the trouble
of offering instructions in the first place.

The problem is that the current instructions miss important details,
and do not clearly warn about potential pitfalls.

Post by Justin B Rye
If the central point you're trying to make is that we need to warn
people about the possibility of ID_NET_NAME_SLOT taking priority over
ID_NET_NAME_PATH, we might be able to do that just by adding a few
This should give enough information to devise a migration plan. (If
- the udevadm output includes an "onboard" name, that takes priority;
+ the udevadm output includes an "onboard" name or a "slot" name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)
But just how common are slot names? Is it in fact possible for a NIC
to have both an onboard name and a slot name?

Since I do not know the answers I included the full prioritized list
into my suggestion.
Your proposed change would be enough in my case but I still think it
is not visible enough as a warning.

[Justin B Rye]

Post by Dmitry Semyonov
The existing text creates an impression that what you should pay
attention to is only the "onboard" name. Since all this was new to me,
there was no ONBOARD name, and there was the usual PATH name there, I
just assumed it was safe to use it without paying attention to the
presence of a SLOT name, (which non-intuitively was listed between the
lowest priority MAC and the lower priority PATH names).

So you would have benefitted from the addition of "or slot name" (but
we still haven't heard from anybody who would need to be told that
onboard names outrank slot names).

Post by Dmitry Semyonov

Post by Justin B Rye

Post by Dmitry Semyonov
the final name is assigned according to the following list of
* ID_NET_NAME_FROM_DATABASE

This would mean that (on my current system) "ASUSTek COMPUTER INC."
would take priority - no.

You probably mixed it with the ID_OUI_FROM_DATABASE variable. The
ID_NET_NAME_FROM_DATABASE is very rare according to some documentation
I read while investigating the issue.

Hmm... I can't see anyone on the Internet claiming to have seen this
in the wild - and it isn't mentioned in the Freedesktop guide, the old
net-id.c comments, or the udev README. The one source I can find that
does seem to recognise it as existing is systemd.link(5). Odd!

Post by Dmitry Semyonov

Post by Justin B Rye

Post by Dmitry Semyonov
* ID_NET_NAME_ONBOARD

This is the one the Release Notes already warn will take priority if
present (on my system, it isn't).

It would be a stretch to call parenthesized side note a warning.

A side note presenting facts that you might need to be aware of in
order to devise a migration plan, presented in the section "issues".
Admittedly, "stretch" does come into this, but mostly as the release
when the Release Notes started including warnings about this.

Post by Dmitry Semyonov

Post by Justin B Rye

Post by Dmitry Semyonov
* ID_NET_NAME_SLOT

This is the one it doesn't mention. If it's present, readers who are
following instructions will see it in the output and need to find out
for themselves what it means before they can construct their migration
plan - it's explained in the docs we point at*

Somehow, it was not so obvious to me, and the referenced docs are also
not very clear about the name selection process, (not to mention a
bunch of unrelated information there you need to read through before
arriving at the important bits).

Yes. the whole process of trying to predict "predictable names" is a
massive pain. And yes, we *could* have filled the Release Notes with
huge red-block-capital warnings - but the deprecation of
/etc/udev/rules.d/70-persistent-net.rules that all this was intended
to warn about (first announced in a udev NEWS.Debian file in mid-2015)
turned out to have been backed out again at the last minute! So we
were already navigating a fine line between the developers who insist
that the old system's unsupported and the users who consider this
unnecessary scaremongering.

And now the nearest thing anybody's written to a HOWTO is suffering
from linkrot, so we'll need to come up with a replacement.

Post by Dmitry Semyonov

Post by Justin B Rye
There's an extra complication here that your order-of-priority list
doesn't account for.

Indeed, a USB-to-Ethernet dongle lists both MAC and PATH names but
uses the lower priority MAC name by default.
"Warning: MAC names are normally preferred over PATH ones for USB
network hardware."

Post by Justin B Rye
The problem with giving too many details is that readers may assume
these are *all* the details they need to know, and for a topic like
this with its myriad corner-cases, I can't believe we're ever going to
be able to provide that One True Complete HOWTO Guide.

We can provide the most important information, (which hopefully I was
able to distill with your help), and clearly warn about potential
corner cases that will require a whole lot more reading and
understanding if one wants to be on the safe side while performing the
migration on a remote system.

I don't know if we can even afford to claim we've got a complete list
of corner-cases; I'd never heard of ID_NET_NAME_FROM_DATABASE, and we
haven't even touched the question of VMs.

Post by Dmitry Semyonov
The problem is that the current instructions miss important details,
and do not clearly warn about potential pitfalls.

So what did actually go wrong on your systems? You disabled
/etc/udev/rules.d/70-persistent-net.rules and they started using an
unpredictable slot-based "predictable name"?

Post by Dmitry Semyonov

Post by Justin B Rye
This should give enough information to devise a migration plan. (If
- the udevadm output includes an "onboard" name, that takes priority;
+ the udevadm output includes an "onboard" name or a "slot" name, that takes priority;
MAC-based names are normally treated as a fallback, but may be needed
for USB network hardware.)
But just how common are slot names? Is it in fact possible for a NIC
to have both an onboard name and a slot name?

Since I do not know the answers I included the full prioritized list
into my suggestion.
Your proposed change would be enough in my case but I still think it
is not visible enough as a warning.

It may be that what we most need is a clear statement that the
information here is *not complete*, and that people devising a
migration plan for a remote system need to read a proper detailed
HOWTO. Unfortunately, the nearest thing to an official guide is bad
and getting worse.

If I start trying to assemble a Debian Wiki page that the Release
Notes could point at, can you help? (Criticising it counts as help.)

[Justin B Rye]

Post by Justin B Rye
If I start trying to assemble a Debian Wiki page that the Release
Notes could point at, can you help? (Criticising it counts as help.)

Slightly delayed by a badly timed broadband outage, here at last is my
first draft:

https://wiki.debian.org/NetworkInterfaceNames

[Dmitry Semyonov]

Hello Justin,

Post by Justin B Rye
https://wiki.debian.org/NetworkInterfaceNames

Thank you! Some notes on the page as I read it, (feel free to apply or
ignore; unfortunately I won't have time and energy to discuss this
topic further):

* I'm glad to see the clear warning near the top, (as well as
additional gentle reminders about the dangers later, and subtle pushes
into the right direction).

THE ORIGINAL SIMPLE SCHEME / How to get it back:
* "booting with the net.ifnames mechanism deactivated" may not mean
anything without googling. A link would not harm here, or at least a
bit more background information on the subsystem this parameter is
handled by, and how it is passed there. (To be fair, the latter is
explained a few sections down. The explanation should probably be
moved to where the net.ifnames option is mentioned first.)

THE "PERSISTENT NAMES" SCHEME / How to cling to it for now
* "Then deactivate the replacement scheme" sentence presumes the
replacement scheme has been discussed above but it hasn't... It is
also not clear at this point whether deactivation is needed if you've
just upgraded to Buster from Stretch, and want to keep using the older
scheme. (I suspect, keeping the 75-persistent-net.rules file should be
enough without passing the net.ifnames=0 option to the kernel.)
But if you installed Buster from scratch the rules file will not be
there, I guess. In this case, it is probably better to recommend using
the .link files as described by the ALTERNATIVE SCHEMES section.
* "be ready to switch to a different system" - I would replace the
last word with "scheme" since system is often used as a synonym for
PC.

Complications and corner cases / MISTERY PRIORITIES:
* just a vertical spacing issue.

Note that I'm now in a different position compared to when I first
faced this topic. A fresh look from an unenlightened person could
reveal additional pitfalls. On the other hand, it feels like you've
nailed everything, and even spiced it up with a bit of humor here and
there (thanks!), so I'll consider this bug report closed as soon as
the official release notes (starting from Buster if possible) point to
the new page.

Regarding several questions you ask on the wiki page, I do not have
answers to them. I can only confirm that two different laptops, and 4
different servers, (all running Buster by this time), fit into current
udev-based network interface name selection scheme as described on the
page.

[Justin B Rye]

Here's a patch for the Release Notes adding another common corner-case
to the list of things to beware of, plus an updated set of external
links including "https://wiki.debian.org/NetworkInterfaceNames".

[Dmitry Semyonov]

Post by Justin B Rye
So what did actually go wrong on your systems? You disabled
/etc/udev/rules.d/70-persistent-net.rules and they started using an
unpredictable slot-based "predictable name"?

Yes, the interfaces file was updated to use PATH-based names but udev
booted with SLOT-based ones.

[Debian Bug Tracking System]

Your message dated Sun, 15 Sep 2019 20:21:47 +0200
with message-id <f07ab660-1f5e-96c1-353f-***@debian.org>
and subject line Re: Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
has caused the Debian Bug report #939178,
regarding release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
Bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact ***@bugs.debian.org
immediately.)