Sunday, August 20, 2017

Raspbian Stretch Renames Network Interfaces

As we are all aware by now, Raspbian released their latest version named Stretch a few days ago on August 16th, 2017.  So this weekend, when I was about to start a new project, I went to the Raspbian download page and downloaded a new image of Raspbian Stretch Lite.  While I waited on the download I skimmed the release notes, which unfortunately fail to mention an important change to the new operating system version: Predictable Network Interface Names.

Once I finished downloading and the image was written to the SD card, I proceeded to do the initial set-up of the Pi for this particular project, which in this case included setting a static IP address.  As usual, I opened /etc/dhcpcd.conf and edited the file with the IP information for eth0.  After rebooting, I was surprised to find that I was still issued the same dhcp address instead of the static ip address I specified.  After over an hour of troubleshooting and searching through forums, I finally found my problem: my network interface is no longer named eth0.  This should have been evident after my first ifconfig, but since I wasn't expecting a change to the interface name, my eyes just skimmed over that information and went straight to the ip address.  I'm hoping that by publishing this I can save someone else the same frustration and waste of time.

Predictable Network Interface Names are not new, but prior to Stretch they were not used by default in Raspbian.  The new naming scheme no longer uses the traditional interface names such as eth0, eth1, wlan0, etc, and instead uses hardware address based names to avoid ambiguity and prevent the accidental changing of interface names.  On the Raspberry Pi, since the Ethernet interface is connected through the usb bus, the mac address is used to identify the interface.  Specifically, the interface names will start with "en" for Ethernet or "wl" for wireless, followed by an "x" to indicate that it will be followed by the mac address, and then predictably the mac address.  For example, if an Ethernet port has a mac address of b827eb123456, then the interface name will be enxb827eb123456.  It is straight forward enough, but if you weren't aware of the change, it could certainly catch you off guard, and leave you wondering why configuring eth0 has no effect on the configuration of your Ethernet port.

In order to find the new name of your interface, simply use ifconfig and check the available interfaces.  If you would rather not use the new naming scheme, you can revert to the old naming scheme by adding net.ifnames=0 to /boot/cmdline.txt.  However, this is quickly becoming the new normal, as more and more Linux distributions switch to using predictable network interface names, so I highly recommend sticking with and getting used to using the new naming scheme, as it will soon be ubiquitous.

Here is a link to the forum post where I found the initial information regarding Raspbian Stretch and the change to predictable network interface names.

EDIT: Apparently the interface names are only affected on new installations of Stretch, and not on systems that are upgraded from Jessie to Stretch.  I assume the reason for this is so that every system with a static IP that gets upgraded to Stretch won't immediately lose their static IP.

EDIT: As of the latest version of Raspbian Stretch, released on Nov 29th, 2017, Raspbian no longer defaults to using Predictable Network Interface Names.  Instead it uses the old naming scheme of eth0, wlan0, etc.  They have also added a new option to raspi-config to allow you turn on Predictable Network Interface Names if you would prefer to use the new naming scheme.


  1. I did an upgrade to stretch and had no static configuration problems. Here is the ifconfig output minus the gt and lt symbols:

    eth0: flags=4163 UP,BROADCAST,RUNNING,MULTICAST mtu 1500
    inet netmask broadcast
    inet6 fe80::346d:ff2a:2d15:423a prefixlen 64 scopeid 0x20 link
    ether b8:27:eb:7a:fd:60 txqueuelen 1000 (Ethernet)
    RX packets 1933516 bytes 2421907229 (2.2 GiB)
    RX errors 0 dropped 1 overruns 0 frame 0
    TX packets 1016956 bytes 142035640 (135.4 MiB)
    TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0

    lo: flags=73 UP,LOOPBACK,RUNNING mtu 65536
    inet netmask
    inet6 ::1 prefixlen 128 scopeid 0x10
    loop txqueuelen 1 (Local Loopback)
    RX packets 100 bytes 13031 (12.7 KiB)
    RX errors 0 dropped 0 overruns 0 frame 0
    TX packets 100 bytes 13031 (12.7 KiB)
    TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0

    wlan0: flags=4163 UP,BROADCAST,RUNNING,MULTICAST mtu 1500
    inet netmask broadcast
    inet6 fe80::9d81:6cf9:1e4c:692a prefixlen 64 scopeid 0x20 link
    ether b8:27:eb:2f:a8:35 txqueuelen 1000 (Ethernet)
    RX packets 16532 bytes 2233937 (2.1 MiB)
    RX errors 0 dropped 0 overruns 0 frame 0
    TX packets 521 bytes 40669 (39.7 KiB)
    TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0

    1. Thanks for the info. I just found out earlier today that apparently the change does not take effect on systems that are updated from Jessie to Stretch, only on new installations of Stretch. I'm curious to know, can you check your /boot/cmdline.txt file and see if there is a "net.ifnames=0"

    2. I did not see it in the command line file. No reference to ifnames at all

    3. Thank you for taking the time to look into that. I find it bizarre that Raspbian would issue two different versions of their operating system, one for people who upgrade and one for people who do a fresh install. I get that they don't want to break people's network interface with an upgrade, but there had to be a better way to do this. No disrespect to the people at Raspberry Pi and the community, what you have accomplished is amazing, but the handling of the roll out of Predictable Network Interface Names is somewhat disappointing. Even now information is scarce.

  2. I clean-installed Stretch on three Pis a few days ago, and here are my results of `ifconfig` command ('lo' omitted):

    1. 3B:
    - enx[mac-address]
    - wlan0 <= on board Wifi, not in use right now

    2. Zero W
    - wlan0 <= on board WiFi, in use

    3. Zero
    - wlx[mac-address] <= USB WiFi dongle, in use

    I didn't set `net.ifnames=0` in /boot/cmdline.txt.

    There's some inconsistency in the naming of network interfaces (at least) in my case.

    1. That's very interesting. On my 3B my on-board wifi was also listed as wlan0, but I assumed that it may be because it was never in use. I'm surprised to find that your Zero W list the wifi as wlan0, but your Zero lists it as wlx[mac]. I can live with either naming scheme, but it needs to be consistent. I have a spare of all three models you listed as well as a 2B lying around. I'll do some testing this evening and report back. Thank you very much for your information.

    2. So I've been doing some testing, and it look like the Predictable Network Interface Names are failing for the built-in wifi on the Pi3 and Zero W. They work for the Ethernet ports on the 2B and 3B, and on USB Wifi adapters, but not for the on-board Wifi on the 3B and Zero W. I'm still looking for the cause of the failure, but I haven't found it yet.

  3. It would also be nice to include instructions/information on what you did to actually fix/make-it-work for those that find this post.

    1) Find out what your interface name is (will be something like 'enxb827ec3f7f60'

    2) Edit your config by running: sudo nano /etc/dhcpcd.conf

    3) Add the following lines (near the bottom):

    inferface enxb827ec3f7f60
    static ip_address=
    static routers=
    static domain_name_servers=

    4) Close/save the file and reboot

    1. I take your point. This was less of a post about setting a static IP address, and more about a major operating system change I stumbled across while setting a static IP. I wasn't planning on writing this post, but there was very little available information about this change at the time, so I just did a quick write-up and put it out there. But you're right, it never hurts to include as much information as possible. Thanks for posting the steps for others that might need that guidance.

  4. The change is not properly documented, I had to revert back from stretch to jessie for a non-essential raspberry pi server (new installation).

    for those who wonder where to find old installation:

    1. I agree that Raspbian did a poor (really nonexistent) job of documenting this fairly major change. If you want to see the proper documentation for Persistent Network Interface Names see the release notes for the most recent LTS version of Debian, where it is properly documented.

      Also, thanks for giving a link to older Raspbian images. I always save copies of old disk images for any operating system I download, but I'm sure not everyone does that.

  5. I've just done a clean install of the latest Raspbian Stretch Lite 2017-09-07 from scratch and the normal changes to fixed IP in dhcpcd.conf (using eth0) worked OK for me. Weird?

  6. Sorry not quite the same as before as I used the wording in the new dhcpcd.conf as mentioned above.

  7. nother change was the output of ifconfig. For each network link the line for address when from
    inet address:
    causing other scripting issues.

  8. I just installed Raspbian Stretch from the 2017-11-29-raspbian-stretch.img image, and it seems to default to the old method of representing interfaces. (My ifconfig lists eth0, lo, usb0, and wlan0.)

    1. That's very interesting. I would be surprised if they changed it back, since most distributions are moving towards predictable network interface names, but there was a bit of an uproar when Raspbian made the change without much announcement, so maybe they did change it back. I'll have to do some looking into this and report back. Thanks for the info.

    2. My fresh install and completely patched Raspbian Stretch seems to also keep using default interface names.

      I used etcher and the following image:

      raspi-config allows to Enable/Disable predictable network interface names but it seems disabled by default.

    3. Fitz and Anonymous, thank you both for the updated information. I have verified that using the 2017-11-29 disk image, Raspbian defaults to NOT using Predictable Network Interface Names, and uses the old naming scheme for both the on-board Ethernet and WiFi, as well as for any network adapters that are added. This can be changed using raspi-config, but I have not found what exactly raspi-config alters to make this change. I will update my original post after a little more experimenting. Thanks again.