Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
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;. -- JBR with qualifications in linguistics, experience as a Debian sysadmin, and probably no clue about this particular package diff --git a/en/issues.dbk b/en/issues.dbk index 3105a90f..524f2650 100644 --- a/en/issues.dbk +++ b/en/issues.dbk @@ -150,8 +150,7 @@ information mentioned in . The alternative is to switch to a supported mechanism for enforcing the old naming scheme, such as a systemd .link - file (see - systemd.link(5)). + file (see systemd.link(5)). The net.ifnames=0 kernel commandline option might also work for systems with only one network interface (of a given type). @@ -173,9 +172,10 @@ $ udevadm test-builtin net_id /sys/class/net/eth0 2>/ This should give enough information to devise a migration plan. (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.) + udevadm output includes an onboard or + slot name, that takes priority; MAC-based names are + normally treated as a fallback, but may be needed for USB network + hardware.) Once you are ready to carry out the switch, disable @@ -194,9 +194,9 @@ $ sudo update-initramfs -u names. Adjust any remaining configuration files, and test your system. - See the - https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/;>upstream - documentation and the udev + See the wiki, https://www.freedesktop.org/software/systemd/man/systemd.net-naming-scheme.html;>upstream + documentation, and the udev README.Debian for further information.
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
On Mon, 2 Sep 2019 at 22:25, Justin B Rye wrote: > 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. -- ...Bye..Dmitry.
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
Hello Justin, On Thu, 12 Sep 2019 at 16:14, Justin B Rye wrote: > 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. -- ...Bye..Dmitry.
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
Justin B Rye wrote on Sep 02: > 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 -- JBR with qualifications in linguistics, experience as a Debian sysadmin, and probably no clue about this particular package
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
Dmitry Semyonov wrote: > 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). >>> 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. > > 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! >>> * 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. >>> * 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. >> 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." Unfortunately, this takes us right back to what I went on to say: >> 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. > 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"? >> 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
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
Justin, On Mon, 2 Sep 2019 at 14:25, Justin B Rye wrote: > > Dmitry Semyonov wrote: > > "(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. > 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. > > 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. 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). > > 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. 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. > > * 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. > > * 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). > > * 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." > 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. > > 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. > 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? 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
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
Bug#939178: release-notes: Describe name selection rules in the "Migrating from legacy network interface names" section
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! -- ...Bye..Dmitry.
