network: Rewrite IPv6Token documentation for new modes

This patch provides new documentation for IPv6Token,
reflecting the new modes (and the existing mode), and documents
various caveats users should be aware of when using these
modes.

1 files changed, 32 insertions, 12 deletions

diff --git a/man/systemd.network.xml b/man/systemd.network.xml
index d61e3472c1..a88b6a447d 100644
--- a/man/systemd.network.xml
+++ b/man/systemd.network.xml
@@ -308,18 +308,38 @@
         <varlistentry>
           <term><varname>IPv6Token=</varname></term>
           <listitem>
-            <para>Specifies an optional address generation mechanism and an optional address prefix. If
-            the mechanism is present, the two parts must be separated with a colon
-            <literal><replaceable>type</replaceable>:<replaceable>prefix</replaceable></literal>. The
-            address generation mechanism may be either <constant>prefixstable</constant> or
-            <constant>static</constant>. If not specified, <constant>static</constant> is assumed. When
-            set to <literal>prefixstable</literal> a method for generating IPv6 Interface Identifiers to
-            be used with IPv6 Stateless Address Autocon figuration (SLAAC). See
-            <ulink url="https://tools.ietf.org/html/rfc7217">RFC 7217</ulink>. When IPv6 address is set,
-            indicates the 64-bit interface part of SLAAC IPv6 addresses for this link.</para>
-
-            <para>Note that the token is only ever used for SLAAC, and not for DHCPv6 addresses, even in
-            the case DHCP is requested by router advertisement. By default, the token is autogenerated.
+            <para>Specifies an optional address generation mode and a required IPv6 address. If
+            the mode is present, the two parts must be separated with a colon
+            <literal><replaceable>mode</replaceable>:<replaceable>address</replaceable></literal>. The
+            address generation mode may be either <constant>prefixstable</constant> or
+            <constant>static</constant>. If not specified, <constant>static</constant> is assumed.
+            </para>
+            <para>When the mode is set to <constant>static</constant>, or unspecified, the lower bits of
+            the supplied address are combined with the upper bits of a prefix received in a Router Advertisement
+            message to form a complete address. Note that if multiple prefixes are received in an RA message, or in
+            multiple RA messages, addresses will be formed from each of them using the supplied address. This
+            mode implements SLAAC but uses a static interface identifier instead of an identifier generated
+            using the EUI-64 algorithm. Because the interface identifier is static, if Duplicate Address Detection
+            detects that the computed address is a duplicate (in use by another node on the link), then this
+            mode will fail to provide an address for that prefix.
+
+            Note that if multiple <constant>static</constant> IPv6Token variables are supplied, only the first
+            one will be used to generate addresses.
+            </para>
+            <para>When the mode is set to <literal>prefixstable</literal> the RFC 7217 algorithm for generating
+            interface identifiers will be used, but only when a prefix received in an RA message matches the supplied address.
+            See <ulink url="https://tools.ietf.org/html/rfc7217">RFC 7217</ulink>. Prefix matching will be attempted
+            against each <constant>prefixstable</constant> IPv6Token variable provided in the configuration; if a received
+            prefix does not match any of the provided addresses, then the EUI-64 algorithm will be used to form
+            an interface identifier for that prefix. This mode is also SLAAC, but with a potentially stable interface
+            identifier which does not directly map to the interface's hardware address.
+
+            Note that the <constant>prefixstable</constant> algorithm includes both the interface's name and
+            MAC address in the hash used to compute the interface identifier, so if either of those are changed the resulting
+            interface identifier (and address) will change, even if the prefix received in the RA message has not changed.
+
+            Note that if multiple <constant>prefixstable</constant> IPv6Token variables are supplied with addresses that
+            match a prefix received in an RA message, only the first one will be used to generate addresses.
             </para>
           </listitem>
         </varlistentry>