Bug#881771: release-notes: No mention of "predictable network interface names" in Debian 10

[Justin B Rye <justin.byam.rye@gmail.com>]

Karl O. Pinc wrote:
>> Whether I'm accessing it physically or via ssh, can't I use something
>> like:
>>  udevadm test /sys/class/net/$ETHX 2>/dev/null | grep NET
>> or
>>  udevadm test-builtin net_id /sys/class/net/$ETHX 2>/dev/null
>> ...?  That worked for me even on Jessie machine.
> 
> I don't know.  I just tried both the above on a
> jessie box running on a VM and it did not show me
> an ID_NET_NAME_PATH, which I presume is what
> shows me the new-style interface name?

(By "$ETHX" I mean "eth0 or whatever you've currently got"...)

Is the VM one that supports the ports-and-slots scheme?  Some
apparently don't.  I don't know exactly what happens instead, but
udevadm seems the most reliable way of narrowing that down.
 
> I don't have a stretch box with old-style names to test on.

If I boot a physical stretch box with the net.ifnames=0 option, it
comes up with an eth0 but udevadm says ID_NET_PATH=enp1s0.

I know udevadm worked for me on physical machines running jessie,
since that's how I predicted their names for my own upgrades.  But if
it *is* the officially approved way of predicting predictable names, I
wish the upstream docs would say so.

Okay, here's a significantly trimmed-down version that we might be
able to use if it's bulked out with good external references.

In issues.dbk:

  <section id="migrate-interface-names">
    <title>Migrating from legacy network interface names</title>
    <para>
     If your system was upgraded from an earlier release, and still uses
     the old-style network interface names that were deprecated with
     stretch (such as <literal>eth0</literal> or <literal>wlan</literal>),
     you should be aware that <systemitem role="package">udev</systemitem>
     in buster no longer supports the mechanism of defining their names via
     <filename>/etc/udev/rules.d/70-persistent-net.rules</filename>. To
     avoid the danger of your machine losing networking after the upgrade
     to buster, it is recommended that you migrate in advance to the new
     naming scheme (usually meaning names like <literal>enp0s1</literal> or
     <literal>wlp2s5</literal>, which incorporate PCI bus- and
     slot-numbers). Take care to update any interface names hard-coded in
     configuration for firewalls, <systemitem role="package">ifupdown</systemitem>.
     and so on.
    </para>
    <para>
     The alternative is to switch to a supported mechanism for enforcing
     the old naming scheme, such as the <literal>net.ifname=0</literal>
     kernel commandline option or a systemd <filename>.link</filename>
     file.
    </para>
    <para>
     To find the new-style names that will be used, first find the
     current names of the relevant interfaces:
    </para>
    <screen
     $ echo /sys/class/net/[ew]*
    </screen>
    <para>
     For each one, check whether it is used in configuration files:
    </para>
    <screen>
     $ sudo rgrep -w eth0 /etc
    </screen>
    <para>
     And what name <systemitem role="package">udev</systemitem> would prefer to
     use for it:
    </para>
    <screen>
     $ udevadm test-builtin net_id /sys/class/net/eth0 2>/dev/null
    </screen>
    <para>
     (One of these may be a fallback MAC-based name, sometimes needed
     for USB network hardware.)
    </para>

[Possibly add extra details there for other special cases]

    <para>
     To switch over, disable <filename>70-persistent-net.rules</filename>
     either by renaming it or by commenting out individual lines.
     On virtual machines you will need to remove the files
     <filename>/etc/systemd/network/99-default.link</filename> and
     (if using virtio network devices)
     <filename>/etc/systemd/network/50-virtio-kernel-names.link</filename>.
     Then rebuild the <filename>initrd</filename>:
    </para>
    <screen>
     $ sudo update-initramfs -u
    </screen>
    <para>
     and reboot. Your system should now have new-style network interface
     names. Adjust any remaining configuration files, and test your system.
    </para>

[possibly a paragraph about safe upgrades over SSH]

    <para>
     See the
     <ulink url="https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/";>upstream
     documentation</link> and the <literal>udev</literal>
     <filename>README.Debian</file> for further information.
    </para>
  </section>

And/or maybe a pointer to some useful page in the Debian Wiki, but I
suspect we'd need to write one first.

Then in upgrading.dbk

  <section id="review-interface-names">
    <title>Verify network interface name support</title>
    <para>
     Systems upgraded from older releases that still use network interfaces
     with names like <literal>eth</literal> or <literal>wlan</literal> are
     at risk of losing networking once they switch to buster; see
     <xref linkend="migrate-interface-names"/> for migration instructions.
    </para>
  </section>

-- 
JBR	with qualifications in linguistics, experience as a Debian
	sysadmin, and probably no clue about this particular package