Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
Dmitry Semyonov wrote:
> 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.)"
(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.)
> This text should be changed to something like this:
Can you elaborate on why you think it needs to be changed? You never
state exactly what you think the important bug is here.
> 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.)
> In this
> case the final name is assigned according to the following list of
> decreasing priorities:
> * 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.
> * ID_NET_NAME_ONBOARD
This is the one the Release Notes already warn will take priority if
present (on my system, it isn't).
> * 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.)
> * 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.
> 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.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: