man: clean up naming scheme description a bit
authorZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Mon, 17 Jun 2019 07:21:57 +0000 (09:21 +0200)
committerZbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl>
Mon, 17 Jun 2019 11:42:27 +0000 (13:42 +0200)
This is in preparation for later changes.  Let's change the documentation of
net.naming-scheme= to also say that it applies to MAC addresses. This commit
doesn't actually implement that though.

man/systemd.net-naming-scheme.xml
src/udev/net/naming-scheme.h

index eb8faad..69d8ee9 100644 (file)
   <refsect1>
     <title>Description</title>
 
-    <para>Network interfaces may be renamed to give them predictable names when there's enough information to
-    generate appropriate names and the use of certain types of names is configured. This page describes the
-    first part, i.e. what possible names may be generated. Those names are generated by the
+    <para>Network interfaces names and MAC addresses may be generated based on certain stable interface
+    attributes. This is possible when there is enough information about the device to generate those
+    attributes and the use of this information is configured. This page describes interface naming, i.e. what
+    possible names may be generated. Those names are generated by the
     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
     builtin <command>net_id</command> and exported as udev properties
     (<varname>ID_NET_NAME_ONBOARD=</varname>, <varname>ID_NET_LABEL_ONBOARD=</varname>,
     <varname>ID_NET_NAME_PATH=</varname>, <varname>ID_NET_NAME_SLOT=</varname>).</para>
 
-    <para>Names are derived from various device metadata attributes. Newer versions of udev take more of
-    these attributes into account, improving (and thus possibly changing) the names used for the same
-    devices. Differents version of the naming rules are called "naming schemes". The default naming scheme is
-    chosen at compilation time. Usually this will be the latest implemented version, but it is also possible
-    to set one of the older versions to preserve compatibility. This may be useful for example for
-    distributions, which may introduce new versions of systemd in stable releases without changing the naming
-    scheme. The naming scheme may also be overriden using the <varname>net.naming-scheme=</varname> kernel
-    command line switch, see
+    <para>Names and MAC addresses are derived from various stable device metadata attributes. Newer versions
+    of udev take more of these attributes into account, improving (and thus possibly changing) the names and
+    addresses used for the same devices. Different versions of those generation rules are called "naming
+    schemes". The default naming scheme is chosen at compilation time. Usually this will be the latest
+    implemented version, but it is also possible to set one of the older versions to preserve
+    compatibility. This may be useful for example for distributions, which may introduce new versions of
+    systemd in stable releases without changing the naming scheme. The naming scheme may also be overriden
+    using the <varname>net.naming-scheme=</varname> kernel command line switch, see
     <citerefentry><refentrytitle>systemd-udevd.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
     Available naming schemes are described below.</para>
 
     <para>After the udev proprties have been generated, appropriate udev rules may be used to actually rename
-    devices based on those properties. See the description of <varname>NamePolicy=</varname> in
-    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.
-    </para>
+    devices based on those properties. See the description of <varname>NamePolicy=</varname> and
+    <varname>MACAddressPolicy=</varname> in
+    <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
   </refsect1>
 
   <refsect1>
         <varlistentry>
           <term><constant>v240</constant></term>
 
-          <para>The <literal>ib</literal> prefix and stable names for infiniband devices are
+          <listitem><para>The <literal>ib</literal> prefix and stable names for infiniband devices are
           introduced. Previously those devices were not renamed.</para>
 
           <para>The ACPI index field (used in <varname>ID_NET_NAME_ONBOARD=</varname>) is now also used when
           configuration, even if they have been renamed already, if <constant>keep</constant> is not
           specified as the naming policy in the <filename noindex='true'>.link</filename> file. See
           <citerefentry><refentrytitle>systemd.link</refentrytitle><manvolnum>5</manvolnum></citerefentry>
-          for a description of <varname>NamePolicy=</varname>.</para>
+          for a description of <varname>NamePolicy=</varname>.</para></listitem>
         </varlistentry>
 
         <varlistentry>
           <term><constant>v243</constant></term>
 
-          <para>Support for netdevsim (simulated networking devices) was added. Previously those devices were
-          not renamed.</para>
+          <listitem><para>Support for renaming netdevsim (simulated networking) devices was added. Previously
+          those devices were not renamed.</para>
 
           <para>Previously two-letter interface type prefix was prepended to
-          <varname>ID_NET_LABEL_ONBOARD=</varname>. This is not done anymore.</para>
+          <varname>ID_NET_LABEL_ONBOARD=</varname>. This is not done anymore.</para></listitem>
         </varlistentry>
-
-        <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
-        particular version of systemd.</para>
     </variablelist>
+
+    <para>Note that <constant>latest</constant> may be used to denote the latest scheme known (to this
+    particular version of systemd.</para>
   </refsect1>
 
   <refsect1>
index 4061eec..584fea8 100644 (file)
  * OS versions, but not fully stabilize them. */
 typedef enum NamingSchemeFlags {
         /* First, the individual features */
-        NAMING_SR_IOV_V        = 1 << 0, /* Use "v" suffix for SR-IOV, see 609948c7043a40008b8299529c978ed8e11de8f6*/
-        NAMING_NPAR_ARI        = 1 << 1, /* Use NPAR "ARI", see 6bc04997b6eab35d1cb9fa73889892702c27be09 */
-        NAMING_INFINIBAND      = 1 << 2, /* Use "ib" prefix for infiniband, see 938d30aa98df887797c9e05074a562ddacdcdf5e */
-        NAMING_ZERO_ACPI_INDEX = 1 << 3, /* Use zero acpi_index field, see d81186ef4f6a888a70f20a1e73a812d6acb9e22f */
-        NAMING_ALLOW_RERENAMES = 1 << 4, /* Allow re-renaming of devices, see #9006 */
-        NAMING_NETDEVSIM       = 1 << 5, /* Generate names for netdevsim devices, see eaa9d507d85509c8bf727356e3884ec54b0fc646 */
-        NAMING_LABEL_NOPREFIX  = 1 << 6, /* Don't prepend ID_NET_LABEL_ONBOARD with interface type prefix */
+        NAMING_SR_IOV_V            = 1 << 0, /* Use "v" suffix for SR-IOV, see 609948c7043a */
+        NAMING_NPAR_ARI            = 1 << 1, /* Use NPAR "ARI", see 6bc04997b6ea */
+        NAMING_INFINIBAND          = 1 << 2, /* Use "ib" prefix for infiniband, see 938d30aa98df */
+        NAMING_ZERO_ACPI_INDEX     = 1 << 3, /* Use zero acpi_index field, see d81186ef4f6a */
+        NAMING_ALLOW_RERENAMES     = 1 << 4, /* Allow re-renaming of devices, see #9006 */
+        NAMING_NETDEVSIM           = 1 << 5, /* Generate names for netdevsim devices, see eaa9d507d855 */
+        NAMING_LABEL_NOPREFIX      = 1 << 6, /* Don't prepend ID_NET_LABEL_ONBOARD with interface type prefix */
 
         /* And now the masks that combine the features above */
         NAMING_V238 = 0,