MAC Address Spoofing in NetworkManager 1.4.0

The new NetworkManager release 1.4.0 adds new features to change the current MAC address of your Ethernet or Wi-Fi card. This is also called MAC address “spoofing” or “cloning”.

His name is Václav
Václav sleeps better with NetworkManager’s MAC address randomization

Previously NetworkManager 1.2.0 added MAC address randomization for Wi-Fi, as Lubomir explains in his blog post. He also explains why you may want to do that in the first place, so I skip the introduction. Suffice to say, some consider randomizing the MAC address an important feature to protect their privacy. Only be aware that for real™ privacy, more considerations come into play. The Tails distribution and Wikipedia have good reads on the subject.

1.2.0 relies on support from wpa_supplicant to configure a random MAC address. The problem is that it requires API which will only be part of the next major release 2.6 of the supplicant. Such a release does not yet exist to this date and thus virtually nobody is using this feature.

With NetworkManager 1.4.0, changing of the MAC address is done by NetworkManager itself, requiring no support from the supplicant. This allows also for more flexibility to generate “stable” addresses and the “generate-mac-address-mask”. Also, the same options are now available not only for Wi-Fi, but also Ethernet devices.

Tools like macchanger and macchiato are commonly used to change the MAC address of a device. They support flexible mechanisms to generate a random address, most of these options are now also supported by NetworkManager.

Randomization during Wi-Fi scanning

During Wi-Fi scanning, NetworkManager resets the MAC address frequently to a randomly generated address. This was already enabled by default in 1.2.0, but as said, users likely didn’t have the required support from wpa_supplicant.

This default behavior can be disabled with a global configuration option in NetworkManager.conf:


Note that this is a per-device configuration value, because at the time of Wi-Fi scanning, no connection is yet activated. A “connection” in NetworkManager-speak is a profile, a bunch of settings.

Supported Modes

Since long, NetworkManager supports two connection properties “ethernet.cloned-mac-address” and “wifi.cloned-mac-address”. These settings take effect when activating the connection. They got extended in 1.4.0 and support the following values:

  • An explict MAC address: this was already supported before 1.4.0 and allows to spoof a specific MAC address.
  • “permanent”: use the permanent MAC address of the device. Before 1.4.0, the permanent MAC address was used if the “cloned-mac-address” property was left empty, thus it was the default.
  • “preserve”: don’t change the MAC address of the device upon activation.
  • “random”: generate a randomized value upon each connect.
  • “stable”: generate a stable, hashed MAC address.
  • NULL/unset: this is the default value which allows fallback to a globally configured default, see below. In case no global override exists, NetworkManager falls back to “permanent”, like it did before.

Update-2017-01-25: with 1.6 release and newer, the default value changed from “permanent” to “preserve” [commit],[bug].

Note that in the D-Bus API, the “cloned-mac-address” field is not a string and thus could not be extended in a backward compatible way. That is why on D-Bus there are new fields “ethernet.assigned-mac-address” and “wifi.assigned-mac-address” instead. On the other hand, in nmcli,, and keyfile-format the properties are indeed called “cloned-mac-address”.

How to configure it?

It is likely that your favorite NetworkManager client does not expose these options in the UI. In that case, I would suggest to use nmcli to configure the per-connection settings:

$ nmcli connection show
NAME               UUID               TYPE            DEVICE
My Wi-Fi           fca8fc45-c47...    802-11-wireless --

$ nmcli connection show "My Wi-Fi"

$ nmcli connection modify "My Wi-Fi" \
        wifi.cloned-mac-address stable

$ nmcli connection up "My Wi-Fi"

$ ip link show

Stable MAC Address Generation

The “stable” method warrants more explanation. In a way it is similar to “random”, but instead it generates a stable, hashed value. This way every time the connection activates, the same address is generated. However, each connection generates a different address.

This is for example useful so that you get the same IP address from DHCP, which might not be the case with “random”. Or a captive-portal might remember your login-status based on the MAC address. With “random” you may be required to re-authenticate on every connect.

The “stable” mode still makes you easily recognizable when you re-connect to a previous network, but your hardware MAC address is hidden and tracking you across different networks may be harder (YMMV).

The stable address is generated by hashing a private key from /var/lib/NetworkManager/secret_key, the ifname of the device, and a stable-id. The stable-id by default is the UUID of the connection (“connection.uuid”), unless you configure the new property “connection.stable-id“. The latter allows you to have multiple connections that generate the same MAC address. Note that “connection.stable-id” property is also used when generating stable-privacy IPv6 addresses (“ipv6.addr-gen-mode”, RFC 7217).

Format of the MAC Address

The “random” and “stable” modes both generate a MAC address. By default, all 48 bits of the MAC address are scrambled except the following two bits. For one, the LSB of the first octet which must always be cleared to indicate a unicast MAC address. And then, the 2nd-LSB of the first octet is set to indicate a locally administered address — contrary to a burned-in address. This has the same effect as calling macchanger --random with respect to which bits are scrambled.

Which bits are scrambled is configurable by the per-connection properties “ethernet.generate-mac-address-mask” and “wifi.generate-mac-address-mask” [man]. During Wi-Fi scanning, the per-device property “wifi.scan-generate-mac-address-mask” is used instead [man].

The property works as follows. If the mask-setting contains one MAC address, that address is used as a mask. For example “FF:FF:FF:00:00:00” results in randomizing the lower 3 octets and use the vendor OUI of the device’s permanent MAC address. This is similar to macchanger --ending, except that NetworkManager uses the permanent MAC address of the device while macchanger preserves the OUI of the current address.

Update-2016-11-04: it doesn’t use the permanent MAC address, instead the “initial” MAC address, that is the current MAC address that was configured on the device outside of NetworkManager.

If after the initial mask a second MAC address follows, that address is used instead of the device’s permanent address. For example “FF:FF:FF:00:00:00 00:50:E4:00:00:00” sets the OUI to “00:50:E4” but randomizes the last 3 octets. Likewise, “02:00:00:00:00:00 00:00:00:00:00:00” scrambles all bits but clears the second LSB of the first octet, thus creating a burned-in address like macchanger --random --bia.

Actually, there can follow arbitrary many MAC addresses after the mask, in which case one will be chosen randomly. “02:00:00:00:00:00 00:00:00:00:00:00 02:00:00:00:00:00” will scramble all 47 bits — except the unicast bit which must be always cleared. This allows you to specify a list of OUIs.

Global Default Configuration

NetworkManager supports certain per-connection properties to fallback to a globally configured default value. By having “cloned-mac-address” or “generate-mac-address-mask” unset, it allows fallback to a value configured in NetworkManager.conf.

For example, I have a file /etc/NetworkManager/conf.d/30-mac-randomization.conf like:

# "yes" is already the default for scanning


which sets the default fallback to random. Only for a few selected connection profiles I explicitly switch the per-connection setting to “stable”.

Note: distributions and packages are advised to install configuration snippets to /usr/lib/NetworkManager/conf.d directory instead of /etc.

What’s missing?

What feature do you miss?

One idea would be to support some special “connection.stable-id”. This would allow to implement a “change daily” feature like Windows 10 has. Allowing for a stable-id “time: <date> <time> <period>” could have the effect to start at <date>-<time> and generate a new ID each <period> time. Say, “time: 2016-08-22 6:00:00 7d” could mean to generate a new ID every Monday at 6:00 a.m. Of course, the ID only gets re-generated upon activation of a connection.

Update-2017-01-25: since 1.6, NetworkManager supports dynamic stable-ids like "${BOOT}", "${CONNECTION}", "${RANDOM}" or any combination of these. This also affects RFC7217 stable privacy IPv4 addresses [commit], [example].

Another idea would be to allow a special keyword “preserve” in “generate-mac-address-mask”. It could be used to set a value like “FF:FF:FF:00:00:00 preserve” which should have the same effect as macchanger --ending and use the current MAC address instead of the permanent one.

If you have problems, questions or suggestions, meet us on mailing list, IRC (#nm on freenode) or check our documentation and our bugtracker.

Towards NetworkManager 1.2

Since beginning of this year (2016), two beta releases for the upcoming NetworkManager version 1.2 were released [beta1] [beta2] [git-beta1] [git-beta2].

These lead us towards the next stable version which will bring many new features and improvements. Without going into detail, the improvements and fixes are vast [NEWS].

  • A lot of code was refactored and cleaned up. For example the platform code was for large parts rewritten and now implements netlink-route parsing without relying on libnl3-route library. I think it is fair to say, that the code keeps improving.
  •  We also significantly improved our testing. With the help from Red Hat’s QA team we have an extensive suite of integration tests that help us immensely to be confident about the stability of the code. Currently those tests require internal infrastructure and are thus not yet upstream. But that is on our todo list. Also Coverity and valgrind help us to discover bugs.
  • The previous version 1.0 already introduced the new libnm library to replace the legacy libnm-util/libnm-glib pair. The main reason was to move away from the long deprecated dbus-glib library which NetworkManager was using since the early days. This was not really fixable without introducing a new library. Note that the legacy libraries are still there and continue to be available as long as there are users.
    Now with 1.2, we also ported most VPN plugins and nm-applet to the new library. The VPN plugins contain a shared library which can be loaded by clients to import/export VPN configurations. Those VPN libraries are now available in two flavors, for users of libnm and libnm-glib.

Backward compatibility is of the highest priority for us. Optimally, you can update from an older version without running into any regressions. If you happen to encounter a problem it is likely an issue we want to hear about and fix it.

What about 1.0?

The first release of the current stable branch 1.0 happened more than a year ago. Indeed, NetworkManager’s upstream project makes new major releases very infrequently and the project might not look very active. Well, that is not the case.

NetworkManager’s stable branch 1.0 continues to be heavily maintained in parallel. The last minor release 1.0.10 was cut end of December 2015 [1.0.10] [git-1.0.10].

These stable releases contain much more than mere bug fixes for the 1.0 branch. During the past year more than 1400 commits were backported from the development branch, including new features and major refactorings. This was done to let users and downstream benefit from the work on master and to provide important improvements while waiting for version 1.2.

In fact, some of the new features for 1.2 already found their way back to the stable branch and if you are using a recent distribution like Fedora 23, you already have a small taste of what’s coming.

Where and How?

There are still a few things that need to be fixed. Then the first release candidate 1.2-rc1 will happen and the final 1.2.0 release should happen soon after. I think by mid April 2016 NetworkManager 1.2.0 will be out.

If you want to give it a try, you can build it from source [master] [beta2]. Our master branch is in a good shape and close to the final state. Alternatively, a beta is also packaged in Debian testing/unstable and Fedora 24/rawhide.

We love to hear feedback on or #nm on IRC/freenode.