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
