device: support dynamic "connection.stable-id" in form of text-substitution

Usecase: when connecting to a public Wi-Fi with MAC address randomization
("wifi.cloned-mac-address=random") you get on every re-connect a new
IP address due to the changing MAC address.
"wifi.cloned-mac-address=stable" is the solution for that. But that
means, every time when reconnecting to this network, the same ID will
be reused. We want an ID that is stable for a while, but at a later
point a new ID should e generated when revisiting the Wi-Fi network.

Extend the stable-id to become dynamic and support templates/substitutions.
Currently supported is "${CONNECTION}", "${BOOT}" and "${RANDOM}".
Any unrecognized pattern is treated verbaim/untranslated.

"$$" is treated special to allow escaping the '$' character. This allows
the user to still embed verbatim '$' characters with the guarantee that
future versions of NetworkManager will still generate the same ID.
Of course, a user could just avoid '$' in the stable-id unless using
it for dynamic substitutions.

Later we might want to add more recognized substitutions. For example, it
could be useful to generate new IDs based on the current time. The ${} syntax
is extendable to support arguments like "${PERIODIC:weekly}".

Also allow "connection.stable-id" to be set as global default value.
Previously that made no sense because the stable-id was static
and is anyway strongly tied to the identity of the connection profile.
Now, with dynamic stable-ids it gets much more useful to specify
a global default.

Note that pre-existing stable-ids don't change and still generate
the same addresses -- unless they contain one of the new ${} patterns.

1 files changed, 25 insertions, 6 deletions

diff --git a/libnm-core/nm-setting-connection.c b/libnm-core/nm-setting-connection.c
index d7a0d2fc11..ac8bdf2d2d 100644
--- a/libnm-core/nm-setting-connection.c
+++ b/libnm-core/nm-setting-connection.c
@@ -1432,13 +1432,32 @@ nm_setting_connection_class_init (NMSettingConnectionClass *setting_class)
 	/**
 	 * NMSettingConnection:stable-id:
 	 *
-	 * This token to generate stable IDs for the connection. If unset,
-	 * the UUID will be used instead.
+	 * Token to generate stable IDs for the connection.
 	 *
-	 * The stable-id is used instead of the connection UUID for generating
-	 * IPv6 stable private addresses with ipv6.addr-gen-mode=stable-privacy.
-	 * It is also used to seed the generated cloned MAC address for
-	 * ethernet.cloned-mac-address=stable and wifi.cloned-mac-address=stable.
+	 * The stable-id is used for generating IPv6 stable private addresses
+	 * with ipv6.addr-gen-mode=stable-privacy. It is also used to seed the
+	 * generated cloned MAC address for ethernet.cloned-mac-address=stable
+	 * and wifi.cloned-mac-address=stable. Note that also the interface name
+	 * of the activating connection and a per-host secret key is included
+	 * into the address generation so that the same stable-id on different
+	 * hosts/devices yields different addresses.
+	 *
+	 * If the value is unset, an ID unique for the connection is used.
+	 * Specifing a stable-id allows multiple connections to generate the
+	 * same addresses. Another use is to generate IDs at runtime via
+	 * dynamic substitutions.
+	 *
+	 * The '$' character is treated special to perform dynamic substitutions
+	 * at runtime. Currently supported are "${CONNECTION}", "${BOOT}", "${RANDOM}".
+	 * These effectively create unique IDs per-connection, per-boot, or every time.
+	 * Any unrecognized patterns following '$' are treated verbatim, however
+	 * are reserved for future use. You are thus advised to avoid '$' or
+	 * escape it as "$$".
+	 * For example, set it to "${CONNECTION}/${BOOT}" to create a unique id for
+	 * this connection that changes with every reboot.
+	 *
+	 * Note that two connections only use the same effective id if
+	 * their stable-id is also identical before performing dynamic substitutions.
 	 *
 	 * Since: 1.4
 	 **/