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 visible enough as a warning. -- ...Bye..Dmitry.
