Bug#881769: udev: Docs on upgrading to predictable network interface names don't work

[Karl O. Pinc]

On Wed, 15 Nov 2017 01:08:06 +0100
Michael Biebl <biebl at debian.org> wrote:

> Am 14.11.2017 um 23:46 schrieb Karl O. Pinc:

> > The stretch README.Debian.gz for udev omits mention that
> > update-initramfs -u must be run after changing configuration files
> > when converting to the new "predictable network interface names".
> >   
> 
> Well, we already mention it earlier:
> 
> 
>   - Disable the default *.link rules with
>     "ln -s /dev/null /etc/systemd/network/99-default.link"
>     and rebuild the initrd with "update-initramfs -u".

Sure.  But the README is organized into sections.  You don't
mention the initramfs in the section that's telling you how
to convert your pre Debian 9 systems into something suitable
for Debian 10.

I should be able to follow the instructions given in the
migration section and, well, migrate.  I should not 
have to carefully read the whole document.
But if I follow the document as written
my interface name never changes (until I somehow figure out
that I need to update the initramfs to make this happen.)

So, the "migration" section needs mention of update-initramfs.

> Besides, your patch seems to contain a lot of other changes.
> Please elaborate

A few goals of the patch:

Improve random sentences.  (Without re-writing the entire
document.)  Generally this falls along the lines of changing
"will", as in "always must", to "may", as in "are allowed to".
This isn't perfect.  There could remain potentially unanswered questions
in the reader's mind as to what happens automatically and what
must be done manually.  If you think this is a problem
I think it should be addressed with specificity in a sentence
like: "Software upgrades do not automatically change network interface
names."

Likewise, add caveats to overly definitive statements where
awkward surprises can result if the statements are taken
at face value.  E.g. "replacing a broken network card does
not change the name".  Well, if you replace a broken network
card and put the new card in a different PCI slot the names
of the system's interfaces likely change.  Caveats lengthen
the README, but it's harder to (re)craft a good, accurate,
short sentence than to add an additional qualifying sentence,
so that's what I did.

Finally, the main goal was to make the section on
"migration" closer to a procedure which could be followed
step-by-step.  The old document told you to go through your
config files and find all places where the old interface
names occurred _before_ it told you how to find the new
interface names which which to replace the old.

Once I started down the road toward a step-by-step
procedure it became clear that blindly following some
of the steps could lead to a dangerous place.  Like
having a remotely accessible system which is no longer
remotely accessible -- what you get when you delete
the 70-persistent-net.rules files and reboot without
thinking through the consequences.  This led to a lot 
of problem mitigation verbiage.

I didn't do an awesome job.  Writing good sentences
is hard.  And in my opinion there's a lot to
be done by a good editor almost everywhere in the document. I think 
that, overall, the patch is an improvement.  
A step forward.  If you don't think so that's ok.
Or take the hunks you like.  Or apply it and then edit
over what you don't care for.

I patched because I think that it's entirely unacceptable to
have a document that looks like a step by step
procedure and leave out the critical step of generating
a new initramfs.  Once I started it was hard to stop
banging out the dents and applying some polish to the 
rough spots.

See also: Bug#881771

Regards,

Karl <kop at meme.com>
Free Software:  "You don't pay back, you pay forward."
                 -- Robert A. Heinlein