Merge branch 'main' into vlada-cpu-temp

DC-network-interface-predictable-naming

@@ -0,0 +1,18 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="network-interface-predictable-naming.asm.xml"
+# Point to the ID of the <structure> of your assembly
+ROOTID="network-interface-predictable-naming"
+SRC_DIR="articles"
+IMG_SRC_DIR="images"
+
+PROFCONDITION="suse-product"
+#PROFCONDITION="suse-product;beta"
+#PROFCONDITION="community-project"
+
+# Just a test:
+STYLEASSEMBLY="/usr/share/xml/docbook/stylesheet/nwalsh5/current/assembly/assemble.xsl"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"

articles/ALP.asm.xml

@@ -207,7 +207,7 @@
         <dm:bugtracker>
           <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
           <dm:component>Documentation</dm:component>
-          <dm:product>ALP</dm:product>
+          <dm:product>Dolomite</dm:product>
           <dm:assignee>[email protected]</dm:assignee>
         </dm:bugtracker>
         <dm:translation>yes</dm:translation>

articles/cockpit-alp.asm.xml

@@ -177,8 +177,8 @@ type="application/relax-ng-compact-syntax"?>
       <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
         <dm:bugtracker>
           <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
-          <dm:component>Smart Docs</dm:component>
-          <dm:product>Documentation</dm:product>
+          <dm:component>Documentation</dm:component>
+          <dm:product>Dolomite</dm:product>
           <dm:assignee>[email protected]</dm:assignee>
         </dm:bugtracker>
         <dm:translation>yes</dm:translation>

articles/network-interface-predictable-naming.asm.xml

@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- file: templates/articles/assembly.xml -->
+<?xml-model href="https://cdn.docbook.org/schema/5.2/rng/assemblyxi.rnc"
+            type="application/relax-ng-compact-syntax"?>
+<!DOCTYPE assembly
+[
+    <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<assembly version="5.2" xml:lang="en"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:trans="http://docbook.org/ns/transclusion"
+          xmlns:its="http://www.w3.org/2005/11/its"
+          xmlns="http://docbook.org/ns/docbook">
+  <!-- resources section references all topic chunks used in the final article
+    -->
+  <!-- R E S O U R C E S -->
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_concept-network-interface-predictable-naming" href="../concepts/network-interface-predictable-naming.xml"/>
+    <resource xml:id="_task-network-interface-predictable-naming-enable" href="../tasks/network-interface-predictable-naming-enable.xml"/>
+    <resource xml:id="_task-network-interface-predictable-naming-disable" href="../tasks/network-interface-predictable-naming-disable.xml"/>
+    <resource xml:id="_glue-network-interface-predictable-naming-for-more-info" href="../glues/network-interface-predictable-naming-more-info.xml"/>
+    <resource href="../common/legal.xml" xml:id="_legal"/>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl"/>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="network-interface-predictable-naming" xml:lang="en">
+    <merge>
+      <title>Predictable naming scheme for network interfaces</title>
+      <revhistory>
+        <title>Changelog</title>
+        <revision><date>2023-08-02</date>
+          <revdescription>
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>
+      </revhistory>
+      <meta name="maintainer" content="[email protected]" its:translate="no"/>
+      <!-- ISO date of last update as YYYY-MM-DD -->
+      <meta name="updated" content="2023-08-01" its:translate="no"/>
+      <!-- this does not work yet. Use the dm tags listed below for now
+        <meta name="bugtracker" its:translate="no">
+        <phrase role="url">https://bugzilla.suse.com/enter_bug.cgi</phrase>
+        <phrase role="component">Non-product-specific documentation</phrase>
+        <phrase role="product">Smart Docs</phrase>
+        <phrase role="assignee">[email protected]</phrase>
+        </meta>
+        -->
+      <!-- not supported, yet. Use dm: tag for now
+        <meta name="translation" its:translate="no">
+        <phrase role="trans">yes</phrase>
+        <phrase role="language">de-de,cs-cz</phrase>
+        </meta>
+        -->
+      <!-- enter the platform identifier or a list of
+        identifiers, separated by ; -->
+      <meta name="architecture" content="x86;power" its:translate="no"/>
+      <meta name="productname" its:translate="no">
+        <!-- enter product name and version --><productname version="15-SP5">&sles;</productname>
+      </meta>
+      <meta name="title" its:translate="yes">Predictable network interface naming</meta>
+      <meta name="description" its:translate="yes">By using predictable naming
+      scheme, the system automatically provides persistent names for network
+      interfaces that are stable across reboots or hardware changes.</meta>
+      <meta name="social-descr" its:translate="yes">Predictable network
+      interface naming ensures stable names across system reboots or hardware changes.</meta>
+      <!-- suitable category, comma-separated list of categories -->
+      <meta name="category" content="Systems Management" its:translate="no"/>
+      <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
+        <dm:bugtracker>
+          <dm:url>https://bugzilla.suse.com/enter_bug.cgi</dm:url>
+          <dm:component>Smart Docs</dm:component>
+          <dm:product>Documentation</dm:product>
+          <dm:assignee>[email protected]</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>TOPIC</term>
+            <listitem>
+              <para>
+                Predictable naming scheme provides stable and persistent names
+                to system network interfaces. Such names offer more security
+                and can survive system reboots and hardware changes.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>INTENTION</term>
+            <listitem>
+              <para>
+                You can learn what network interface naming schemes are and how
+                to activate and deactivate the predictable naming scheme on
+                your system.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+                It takes 15 minutes to read and understand how to activate the
+                predictable naming scheme for network interfaces on your
+                system.
+              </para>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <module resourceref="_concept-network-interface-predictable-naming">
+      <merge>
+        <title>Introduction</title>
+        <abstract>
+          <para></para>
+        </abstract>
+      </merge>
+    </module>
+    <module resourceref="_task-network-interface-predictable-naming-enable">
+      <merge>
+        <abstract>
+          <para></para>
+        </abstract>
+      </merge>
+    </module>
+    <module resourceref="_task-network-interface-predictable-naming-disable">
+      <merge>
+        <abstract>
+          <para></para>
+        </abstract>
+      </merge>
+    </module>
+    <module resourceref="_glue-network-interface-predictable-naming-for-more-info"/>
+    <module resourceref="_legal"/>
+    <module resourceref="_gfdl" renderas="appendix"/>
+  </structure>
+</assembly>

concepts/network-interface-predictable-naming.xml

@@ -0,0 +1,156 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<!-- refers to legacy doc: <add github link to legacy doc piece, if applicable> -->
+<!-- point back to this document with a similar comment added to your legacy doc piece -->
+<!-- refer to README.md for file and id naming conventions -->
+<!-- metadata is dealt with on the assembly level -->
+<topic xml:id="network-interface-predictable-naming-concept"
+ role="concept" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>Predictable naming scheme for network interfaces</title>
+    <!--add author's email address-->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <abstract>
+      <para>
+        This article describes a naming scheme that assigns more predictable
+        names for system network interfaces.
+      </para>
+    </abstract>
+  </info>
+  <section xml:id="network-interface-predictable-naming-traditional">
+    <title>Traditional naming schemes</title>
+    <para>
+      When &slea; boots, network interface names are assigned. The traditional
+      naming scheme used to assign names beginning with
+      <literal>eth<replaceable>X</replaceable></literal>, where
+      <replaceable>X</replaceable> is the order number of the discovered
+      matching driver of the related network device. Because the driver probing
+      is not predictable, the assigned names may become unstable and on the
+      next boot, <literal>eht0</literal> may become <literal>eth1</literal>,
+      for example. Such behavior has security implications because firewall
+      rules are sensitive to unpredictable changes in network interface names.
+    </para>
+    <para>
+      Another and more recent approach based on the
+      <package>biosdevname</package> package tries to find fixed slot topology
+      information in certain firmware interfaces and uses them to assign fixed
+      names to interfaces that incorporate their physical location on the
+      mainboard.
+    </para>
+  </section>
+  <section xml:id="network-interface-predictable-naming-what-is">
+    <title>What is a predictable naming scheme?</title>
+    <para>
+      To make network interface naming persistent and customizable, you can
+      activate more predictable naming of network interfaces based on
+      &systemd;.
+    </para>
+    <para>
+      &systemd; offers a stable naming scheme closer to kernel-internal device
+      identification. Together with <systemitem>udev</systemitem> rules, they
+      create flexible algorithms for assigning network device names.
+    </para>
+  </section>
+  <section xml:id="network-interface-predictable-naming-how-it-works">
+    <title>How does the predictable naming scheme work?</title>
+    <para>
+      The following is the process of deriving the network interface naming.
+      The priority of steps is top to bottom&mdash;if the device information
+      outlined in a specific step is not available, the next step is a
+      fallback.
+    </para>
+    <procedure>
+      <step>
+        <para>
+          If custom <systemitem>udev</systemitem> rules for assigning network
+          interface names exist, they are used.
+        </para>
+      </step>
+      <step>
+        <para>
+          If the <package>biosdevname</package> package is installed, its
+          <systemitem>udev</systemitem> rules are used.
+        </para>
+      </step>
+      <step>
+        <para>
+          If the device's firmware / BIOS index number for onboard devices is
+          available, it is used. For example, <literal>eno1</literal>.
+        </para>
+      </step>
+      <step>
+        <para>
+          If the device's firmware / BIOS PCI Express hotplug slot index number
+          is available, it is used. For example, <literal>ens1</literal>.
+        </para>
+      </step>
+      <step>
+        <para>
+          If the device's names incorporating physical / geographical location
+          of the connector of the hardware are available, they are used. For
+          example, <literal>enp2s0</literal>.
+        </para>
+      </step>
+      <step>
+        <para>
+          If none of the above information is available, the traditional
+          unpredictable kernel-based naming is applied. For example,
+          <literal>eth0</literal>.
+        </para>
+      </step>
+    </procedure>
+  </section>
+  <section xml:id="network-interface-predictable-naming-benefits">
+    <title>Benefits of the predictable naming scheme</title>
+    <para>
+      If you activate the &systemd;-based network interface naming scheme, you
+      get the following benefits:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          Persistent interface names between reboots.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Persistent interface names even if hardware is added or removed.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Interface names are automatically determined without user
+          configuration.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          The interface names are fully predictable. For example, by looking at
+          the output of the <command>lspci</command> command, you can determine
+          the name of the interface.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Fully stateless operation&mdash;changing the hardware configuration
+          does not modify the content of <filename>/etc</filename>.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          Compatibility with the read-only root <literal>/</literal> file
+          system.
+        </para>
+      </listitem>
+    </itemizedlist>
+  </section>
+</topic>

glues/network-interface-predictable-naming-more-info.xml

@@ -0,0 +1,39 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE topic
+[
+  <!ENTITY % entities SYSTEM "../common/generic-entities.ent">
+    %entities;
+]>
+<topic xml:id="network-interface-predictable-naming-more-info"
+ role="glue" xml:lang="en"
+ xmlns="http://docbook.org/ns/docbook" version="5.2"
+ xmlns:its="http://www.w3.org/2005/11/its"
+ xmlns:xi="http://www.w3.org/2001/XInclude"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:trans="http://docbook.org/ns/transclusion">
+  <info>
+    <title>For more information</title>
+    <!-- can be changed via merge in the
+      assembly -->
+    <!--add author's e-mail address-->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <!-- add an abstract/para here, if you need one -->
+    <!-- can be changed via merge in the assembly -->
+  </info>
+  <itemizedlist>
+    <listitem>
+      <para>
+        For more detailed information about naming customization, read the
+        <literal>systemd.net-naming-scheme</literal> man page (<command>man 7
+        systemd.net-naming-scheme</command>).
+      </para>
+    </listitem>
+    <listitem>
+      <para>
+        A more detailed description and reasoning behind the predictable naming
+        scheme are given in <link
+        xlink:href="https://www.freedesktop.org/wiki/Software/systemd/PredictableNetworkInterfaceNames/"/>.
+      </para>
+    </listitem>
+  </itemizedlist>
+</topic>