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>
+
We should probably start by pointing back at the deprecation stage in
the Stretch release-notes. Make this "issues" file the primary one
explaining the situation, with just a cross-reference in the
"upgrading" file, and introduce this in terms of "if your system was
upgraded from Jessie without migrating away from the network interface
naming scheme deprecated in the Stretch release, and depends on
/e/u/r/70-persistent-network-blah.txt to maintain these legacy names,
you should be aware that udev on Buster no longer recognises that
file. To avoid the danger of your machine losing networking after the
upgrade to Buster, it is recommended that you switch to the new naming
scheme in advance, updating any interface names hardcoded in
configuration files."
+ <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>
That's not quite true; the change isn't that they're unsupported (if
you set up an appropriate .link file or something), it's that the
legacy support for configuring them in /etc/udev/rules.d/ has gone.
+
+ <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>
The <tip> element isn't used anywhere else in the release-notes.
I suppose it's also technically not true that the change in udev
behaviour applies only to upgraded systems; it's entirely possible to
set up a freshly installed Stretch box with an /e/u/r/ file.
+
+ <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>
(For people with only a single wireless connection, handled by
network-manager, is there in fact any "manual" work that they need to
do? Or will nm just bring up whatever wireless card it finds?)
+
+ <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>
Again, <warning> isn't currently used in release-notes.
(It seems to me the simplest safety net would be a grub entry using
the kernel net.ifnames=0 option.)
+
+ <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>
This looks like a halfway-converted "ip link" recipe - the "ls"
invocation will output some string like "eth0 lo wlan0", and the
"grep" won't match it. But if you're listing /sys/net for human
consumption there's not much need for filtering anyway - just:
<para>
First, determine all relevant network interface names by running:
</para>
<screen>
$ echo /sys/class/net/[ew]*
</screen>
I suppose you might want to add here:
<para>
In the legacy system, ethernet cards had names like
<literal>eth0</literal>; wireless cards had ones like
<literal>wlan0</literal>. The new system uses hardware-based
names like <literal>enp1s0</literal> or <literal>wlp2s1</literal>,
where the numbers encode PCI device bus- and slot-numbers.
</para>
(Apparently USB wifi hardware may use a MAC-based name, so that might
need to be mentioned, though on the plus side I think it's a case that
doesn't require any changes in Buster.)
+
+ <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>
The stage at which they need to edit that ifupdown stanza or whatever
is also the stage at which they need the information about "how to
predict predictable names", so put that here.
+
+<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).
Should there be extra </para><para>s here? Does the following apply
to both physical and VM systems?
+
+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
Oh, is this a patch for the udev README.Debian? There's nothing
Debian-specific about how the wlpXsX system works, so maybe it should
just point to some other source.
+
++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
(Less redundantly, "is based on the bus and slot numbers".)
Wait, if this is the README, why is it using markup?
+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,
If this is a udev README we can probably hope to get some reliable
input on the best udevadm invocation for this purpose.
+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>
^
It's "hexa-".
+
+<screen>
+printf '0A:30' \
+ | perl -e 'while (<>)
+ {printf("enp%ss%s\n",
+ oct("0x".substr($_,0,2)),
+ oct("0x".substr($_,3,2)));};'
+</screen>
This seems an overcomplicated way of converting a number from hex to
dec, though I may be biassed due to the fact that for my own hardware
I've never seen a slot or bus number higher than 7. Couldn't you just
use a bash function like:
$ ethname() { echo "enp$((16#$1))s$((16#$2))"; }
$ ethname 0a 30
enp10s48
+
+<para>The new name of a <emphasis>typical</emphasis> wireless
+interface on a PCI bus is <literal>enpPPsSS</literal>, where
^^
Typo. But this whole thing boils down to "and likewise for wireless
interfaces, but with a wl- prefix instead of en-".
+<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.
Wait, what's happening? Why is this text being preincremented?
++
++There appears to be no tool available to report the new, automatically
++determined, predictable network interface names. The approach taken here is
I thought that was what "udevadm test-builtin net_id" was intended
for, but I haven't tried it on a very wide range of machines.
++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/.
It's simpler and more reliable just to standardise on pointing at
/sys/class/net/, and we don't need to do that in every file.
++
++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.
++
++
++ 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.
++
+
+ 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>
What file is this? What file format? I... what...?
+
+ <para>For further information, including options available for
+ custom network interface naming, see</para>
+
+ <screen>
+# zless /usr/share/doc/udev/README.Debian.gz
+ </screen>
(That looks like a useless use of root!)
+ </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>
As above, just use something like "echo /sys/class/net/*". Or
preferably the upgrading file should just have a crossreference and a
warning that you need to fix this *before* dist-upgrading.
+
+ <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>
Is this true for uncustomised network-managerised laptops? (Not that
people usually upgrade those via SSH, I suppose.)
<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
TODO: (JFS) List other server software? RADIUS? Streaming ?
</programlisting>
We don't need to say the same thing over and over again in every
file. The most it needs is cross-references pointing to one HOWTO,
which could even be on the wiki. The what's-new-in-buster list
shouldn't be going into detail on deprecations that were announced for
what's-new-in-stretch.
+<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
^^
Technically it's "Debian 9"; only point releases get two sig-figs.
But why say any more than "Systems upgraded to stretch from an earlier
release"?
+ 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>
Grammar nitpick: the specifications (plural) *are* found there.
+
+ <!-- Give people a reason to be happy. -->
+ <!-- List from the freedesktop.org URL above. -->
+ <para>Some advantages of the new scheme are:</para>
But the *scheme* isn't new... something like this might perhaps have
belonged in the Stretch release-notes, but for Buster the change we
need to explain the advantages of is that it has gone ahead with
deprecating the use of the old /etc/udev/ stuff and now only pays
attention to the kernel commandline and the standard systemd.link(5)
mechanism.
+
+ <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>
An attempt to compress this:
<para>
The old scheme had problems with interfaces changing names after
driver updates; the new scheme provides names that are stable,
uniform across architectures and systemd-using distributions, and
(in principle) predictable.
</para>
But as I say, it's not a new feature added for Buster, so it belongs
somewhere else.
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package