Bug#881771: release-notes: No mention of "predictable network interface names" in Debian 10
On Sat, 6 Apr 2019 21:31:42 +0300
Andrei POPESCU <andreimpopescu@gmail.com> wrote:
> On Sb, 06 apr 19, 10:28:15, Karl O. Pinc wrote:
> > C) Actual upgrade instructions. This is in-progress.
> >
> > There are really 2 paths for manual migration of
> > interface names: one for when you have console/physical
> > access and another when you don't. In the first case,
> > you can try the new names, see what name you get, and
> > migrate /etc/. Without console access you need to
> > calculate the new interface name, migrate, and hope
> > you got the right name after reboot. To calculate
> > the right interface name you need additional background
> > information. I've whacked up a teeny script, with
> > no dependencies, to compute the common case. But it
> > does require the pciid as input, and I suggest installing
> > pciutils to get lspci to find pciids.
>
> According to [1] here are two other options:
>
> 3. assign own names (e.g. internet0, dmz0, lan0, etc.) by creating a
> .link file in /etc/systemd/network/ and migrate your configuration
> accordingly.
This I was not thinking of, although I'd skimmed [1].
This is sort of like choice 2, in that it requires digging
into hardware identifiers. But being able to use, say, a
MAC address instead of digging into the intricacies of the bus
makes this a simpler approach. It would also be nice
to use this approach to keep the old eth* name and not
have to change the rest of /etc/ at all.
On the other hand, it does
not really help in migrating to the new naming scheme.
> 4. disable the naming policy (via kernel parameter or udev) and
> optionally migrate later (e.g. when one has console access to the
> system).
>
> It should be possible to use the kernel parameter in combination with
> a "boot once" grub entry to both get the new name and test the new
> configuration for remote systems.
Humm. Yes. [2] says this will work. For some reason I thought
it said this approach was going away, but it does not say that.
This might be simplest when updating remote systems. Although
it would require an "at" job to reboot after the "boot once". Right?
At least if trying to migrate remotely.
> Wouldn't it make sense to ask also the udev/systemd maintainers for
> input?
Absolutely. But it might be best to wait and let them review something
already written. From my experience with [3] they don't seem
particularly interested in coming up with specific procedures
when console access is not available. All that got added
to the udev/systemd instructions was a warning that you'd
better have console access when migrating to the new interface
names.
I am using [2] and [3] as my starting point for the instructions
on migrating to the new network interface naming scheme.
I don't feel I'm an expert here. But something needs to be done
or a lot of people's networking is going to break on upgrading
to buster.
I'm attaching new_if_names_v1.patch, so you can see what I have.
(The upgrading.dbk file is not even close to valid.)
The patch may also give you URLs to other useful resources.
> [1]
> https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/
[2]
https://sources.debian.org/src/systemd/241-2/debian/udev.README.Debian/
https://salsa.debian.org/systemd-team/systemd/blob/master/debian/udev.README.Debian
[3]
https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=881769
Karl <kop@meme.com>
Free Software: "You don't pay back, you pay forward."
-- Robert A. Heinlein
diff --git a/en/issues.dbk b/en/issues.dbk
index 35841ee6..6d831f62 100644
--- a/en/issues.dbk
+++ b/en/issues.dbk
@@ -1,3 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
<?xml version='1.0' encoding='utf-8'?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"; [
@@ -39,6 +40,196 @@ information mentioned in <xref linkend="morereading"/>.
</para>
</section>
+ <section id="migrate-interface-names">
+ <title>Migrating from legacy <literal>eth</literal> and
+ <literal>wlan</literal> style network interface names</title>
+
+ <para>Debian buster requires the new network interface naming
+ scheme. Legacy network interface names, names beginning with
+ <literal>eth</literal> or <literal>wlan</literal> are no longer
+ supported.</para>
+
+ <tip>
+ <para>This section applies only to systems upgraded to stretch,
+ Debian 9. Systems installed as stretch, using the stretch
+ installer, already use the new naming scheme.</para>
+ </tip>
+
+ <para>Interface names must be be manually migrated to the new
+ naming scheme before upgrading to Debian 10. If you rely on the
+ old names in custom ifupdown stanzas, firewall scripts, or other
+ networking configuration, these will also need to be updated to
+ the new names.</para>
+
+ <warning>
+ <para>This process may render your machine inaccessible through
+ ssh. Be sure to have physical or console access to the machine,
+ or a way to revert to your existing configuration.</para>
+ </warning>
+
+ <para>First, determine all relevant network interface names: those
+ in <literal>/etc/udev/rules.d/70-persistent-net.rules</literal>,
+ or if that does not exist (in the case of virtual machines), in
+ <literal>ip link</literal> or
+ <literal>/sys/class/net/</literal>.</para>
+
+ <para>The following command may be helpful</para>
+
+ <screen>
+# ls /sys/class/net | egrep '^[0-9]+: (eth)|(wlan)[0-9]+'
+ </screen>
+
+ <para>Then for every interface name use a command like</para>
+
+ <screen>
+# grep -rlF eth0 /etc
+ </screen>
+
+ <para>to find out where it is being used.</para>
+
+ <para>Then on "real hardware" machines, rename the file to
+ <literal>70-persistent-net.rules.old</literal>; alternately, if
+ you have multiple interfaces, instead of renaming you may wish to
+ comment out specific lines to convert a single interface at a
+ time.</para>
+
+<para>On VMs remove the files /etc/systemd/network/99-default.link and
+/etc/systemd/network/50-virtio-kernel-names.link (the latter only exists on VMs
+that use virtio network devices).
+
+Rebuild the initrd with
+
+ update-initramfs -u
+
+and reboot. Then your system should have a new network interface name (or
+names). Adjust configuration files as discovered with the grep above, and test
+your system.
+
+Repeat for each network interface name, as necessary.
+
+--- README.Debian 2017-11-14 15:17:27.811548233 -0600
++++ README.Debian.new 2017-11-14 16:41:13.417161455 -0600
+
++Migration to the current network interface naming scheme
+
+<para>On a typical mass-market computer the new interface naming
+scheme for network interfaces on a PCI bus is based on the PCI bus and
+slot number. Ethernet interfaces are prefixed with
+<literal>en</literal> and wireless interfaces with
+<literal>wl</literal>. The bus and slot portion of an interface's PCI
+identifier can be found in <literal>dmesg</literal> output, the
+system's boot logs, or with the <literal>lspci</literal> command,
+found in the <literal>pciutils</literal> package. The logs and
+<literal>dmesg</literal> will display a typical pciid in the form
+<literal>0000:PP:SS.0</literal>. The <literal>lspci</literal> command
+displays pciids in the form <literal>[PP:SS]</literal>. In all cases
+pciids are shown in hexidecimal.</para>
+
+<para>The new name of a <emphasis>typical</emphasis> ethernet
+interface on a PCI bus is <literal>enpPPsSS</literal>, where
+<literal>PP</literal> is the (base 10) PCI bus number and
+<literal>SS</literal> is the (base 10) PCI slot number. The following
+script prints the new name of a typical ethernet interface. The
+(hexidecimal) pciid is given on the first line.</para>
+
+<screen>
+printf '0A:30' \
+ | perl -e 'while (<>)
+ {printf("enp%ss%s\n",
+ oct("0x".substr($_,0,2)),
+ oct("0x".substr($_,3,2)));};'
+</screen>
+
+<para>The new name of a <emphasis>typical</emphasis> wireless
+interface on a PCI bus is <literal>enpPPsSS</literal>, where
+<literal>PP</literal> is the (base 10) PCI bus number and
+<literal>SS</literal> is the (base 10) PCI slot number. The following
+script prints the new name of a typical ethernet interface. The
+(hexidecimal) pciid is given on the first line.</para>
+
+<screen>
+printf '0A:30' \
+ | perl -e 'while (<>)
+ {printf("wlp%ss%s\n",
+ oct("0x".substr($_,0,2)),
+ oct("0x".substr($_,3,2)));};'
+</screen>
+
+<para>Determining the name of an <emphasis>atypical</emphasis> network
+interface can be done by examining <ulink
+url="https://github.com/systemd/systemd/blob/master/src/udev/udev-builtin-net_id.c#L4";>the
+specifications</ulink>.</para>
+
+
++Begin by discovering the mapping between the new name(s) of your interface(s)
++and the old.
++
++There appears to be no tool available to report the new, automatically
++determined, predictable network interface names. The approach taken here is
++to de-configure the existing interfaces and discover the new interface names
++by observation after reboot. Because the new naming scheme is predictable it
++is also possible, if you know enough about your hardware configuration, to
++manually construct the new names. This is generally more laborious and error
++prone than simply seeing what the system does.
++
++WARNING: This process will disconnect your interface(s) from the network. Be
++sure to have physical access to the machine or a way to revert to your
++existing configuration. If you have multiple interfaces it may be prudent to
++work with only a single interface at a time -- this will also assist in
++mapping the old names to the new. If you have a single interface you could
++instead construct a custom initramfs, reboot into it after installing and
++testing an automated reboot into the default initramfs, and then examining
++the system logs to discover the new interface name. This latter approach is
++not discussed in this document.
++
++Determine all relevant network interface names: look in
++/etc/udev/rules.d/70-persistent-net.rules, or if that does not exist (in the
++case of virtual machines), in "ip link", or in /sys/class/net/.
++
++On "real hardware" machines, rename the file to 70-persistent-net.rules.old;
++on VMs remove the file /etc/udev/rules.d/80-net-setup-link.rules instead.
++Alternately, if you have multiple interfaces, instead of renaming you may
++wish to comment out specific lines in these files so as to work with a single
++interface at a time.
++
++Construct a new (default) initramfs with:
++
++ update-initramfs -u
+
+-Then for every interface name use a command like
++Reboot.
++
++After reboot your system should have a new network interface name (or names).
++Repeat for each network interface name, as necessary.
++
++The new names must replace all occurences of the old in configuration files.
++
++For every interface name use a command like:
+
+ grep -r eth0 /etc
+
+ to find out where it is being used.
+
+-Then on "real hardware" machines, rename the file to
+-70-persistent-net.rules.old; on VMs remove the file
+-/etc/udev/rules.d/80-net-setup-link.rules instead.
+-
+-Reboot, adjust configuration files, and test your system.
++Adjust configuration files, run `update-initramfs -u`, reboot, and test your
++system.
+
+ Custom net interface naming
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
+</para>
+
+ <para>For further information, including options available for
+ custom network interface naming, see</para>
+
+ <screen>
+# zless /usr/share/doc/udev/README.Debian.gz
+ </screen>
+ </section>
+
<section id="noteworthy-obsolete-packages" condition="fixme">
<title>Noteworthy obsolete packages</title>
<para>
diff --git a/en/upgrading.dbk b/en/upgrading.dbk
index b779789f..9c6d4eb8 100644
--- a/en/upgrading.dbk
+++ b/en/upgrading.dbk
@@ -275,6 +275,23 @@ $ apt-forktracer | sort
instructions in <xref linkend="old-upgrade"/>.
</para>
+ <section id="review-interface-names">
+ <title>Verify network interface name support</title>
+
+ <para>Network interface names beginning with
+ <literal>eth</literal> or <literal>wlan</literal> are not
+ supported in buster. Check for the existence of legacy interface
+ names with</para>
+
+ <screen>
+# ls /sys/class/net | egrep '^[0-9]+: (eth)|(wlan)[0-9]+'
+ </screen>
+
+ <para>If legacy network interface names are found the instructions
+ in <xref linkend="migrate-interface-names"/> must be followed.
+ Otherwise the interfaces will become unusable.</para>
+ </section>
+
<section id="review-actions">
<title>Review actions pending in aptitude if you use that package manager</title>
<programlisting condition="fixme">
diff --git a/en/whats-new.dbk b/en/whats-new.dbk
index 9965419f..f650324a 100644
--- a/en/whats-new.dbk
+++ b/en/whats-new.dbk
@@ -363,6 +363,62 @@ Among many others, this release also includes the following software updates:
TODO: (JFS) List other server software? RADIUS? Streaming ?
</programlisting>
+<section id="new-netnames">
+ <title>New network interface names</title>
+ <para>Starting with buster, Debian now requires the <ulink
+ url="https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/";>assignment
+ of fixed network interface names</ulink> based on
+ firmware/topology/bus location information.</para>
+
+ <!-- Put the important information up-front. People must upgrade! -->
+ <warning>
+ <para>Network interface names beginning with <literal>eth</literal>
+ or <literal>wlan</literal> are no longer supported. Debian systems
+ installed before stretch (Debian 9.0) and later upgraded to stretch
+ require manual migration of their network interface names to the new
+ naming scheme. See: <xref linkend="migrate-interface-names"/></para>
+ </warning>
+
+ <para>The <ulink
+ url="https://github.com/systemd/systemd/blob/master/src/udev/udev-builtin-net_id.c#L4";>specifications</ulink>
+ for the new interface naming scheme is found in the code.</para>
+
+ <!-- Give people a reason to be happy. -->
+ <!-- List from the freedesktop.org URL above. -->
+ <para>Some advantages of the new scheme are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Stable interface names when kernels or drivers are
+ updated/changed</para>
+ </listitem>
+ <listitem>
+ <para>Applicability to both x86 and non-x86 machines</para>
+ </listitem>
+ <listitem>
+ <para>Uniformity across all distributions that use
+ systemd/udev</para>
+ </listitem>
+ <listitem>
+ <para>Interface names that are predictable, based on PCI slot
+ number<footnote>
+
+ <para>This is also a disadvantage. It can be harder to upgrade
+ hardware by moving the hard drives of an old computer to a new
+ computer. Unless the network cards in both machines use the
+ same PCI slot numbers, the names of the network interfaces will
+ change.</para>
+
+ </footnote></para>
+ </listitem>
+ <listitem>
+ <para>Stable interface names when broken Ethernet cards are
+ replaced, so long as the new card is fitted into the bus in the
+ old card's slot</para>
+ </listitem>
+ </itemizedlist>
+</section>
+
<section id="cd">
<title>CDs, DVDs, and BDs</title>
<para>
Reply to: