SUSE · sounix000 · Nov 27, 2024 · Sep 23, 2024 · Oct 25, 2024 · Oct 25, 2024
diff --git a/DC-kernel-boot-parameters-modify b/DC-kernel-boot-parameters-modify
@@ -0,0 +1,19 @@
+# This file originates from the project https://github.com/openSUSE/doc-kit
+# This file can be edited downstream.
+
+MAIN="kernel-boot-parameters-modify.asm.xml"
+# Point to the ID of the <structure> of your assembly
+SRC_DIR="articles"
+ROOTID="kernel-boot-parameters-modify"
+IMG_SRC_DIR="images"
+
+## Profiling
+PROFOS="PRODUCT"
+#PROFCONDITION="PRODUCTNUMBER"
+#STRUCTID="STRUCTURE-ID"
+#PROFARCH="x86_64;zseries;power;aarch64"
+
+DOCBOOK5_RNG_URI="urn:x-suse:rng:v2:geekodoc-flat"
+
+STYLEROOT="/usr/share/xml/docbook/stylesheet/suse2022-ns"
+FALLBACK_STYLEROOT="/usr/share/xml/docbook/stylesheet/suse-ns"
diff --git a/articles/kernel-boot-parameters-modify.asm.xml b/articles/kernel-boot-parameters-modify.asm.xml
@@ -0,0 +1,210 @@
+<?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 -->
+  <!-- Glue files -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-more-info" href="../glues/kernel-boot-parameters-modify-more-info.xml">
+      <description>For more information</description>
+    </resource>
+  </resources>
+  <!-- Concept files -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-introduction" href="../concepts/kernel-boot-parameters-modify-introduction.xml">
+      <description>Introduction to kernel boot parameters</description>
+    </resource>
+    <resource xml:id="_kernel-boot-parameters-modify-difference-linuxrc-parameters" href="../concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml">
+      <description>Difference between kernel boot parameters and linuxrc parameters</description>
+    </resource>
+  </resources>
+  <!-- Tasks -->
+  <resources>
+    <resource xml:id="_kernel-boot-parameters-modify-temporary" href="../tasks/kernel-boot-parameters-modify-temporary.xml">
+      <description>Temporarily modify kernel boot parameters</description>
+    </resource>
+    <resource xml:id="_kernel-boot-parameters-modify-permanent" href="../tasks/kernel-boot-parameters-modify-permanent.xml">
+      <description>Permanently modify kernel boot parameters</description>
+    </resource>
+    <resource xml:id="_kernel-boot-parameters-modify-troubleshoot" href="../tasks/kernel-boot-parameters-modify-troubleshoot.xml">
+      <description>Troubleshooting modified kernel boot parameters</description>
+    </resource>
+  </resources>
+  <!-- Legal -->
+  <resources>
+    <resource href="../common/legal.xml" xml:id="_legal">
+      <description>Legal Notice</description>
+    </resource>
+    <resource href="../common/license_gfdl1.2.xml" xml:id="_gfdl">
+      <description>GNU Free Documentation License</description>
+    </resource>
+  </resources>
+  <!-- S T R U C T U R E -->
+  <structure renderas="article" xml:id="kernel-boot-parameters-modify" xml:lang="en">
+    <merge>
+      <title>Modifying Kernel Boot Parameters</title>
+      <!--subtitle>Subtitle if necessary</subtitle-->
+      <!-- Create changelog to enable versioning; add most recent entries at the top. -->
+      <revhistory xml:id="rh-kernel-boot-parameters-modify">
+        <revision><date>2024-11-28</date>
+          <revdescription>
+            <para>
+              Initial version
+            </para>
+          </revdescription>
+        </revision>
+      </revhistory>
+      <!-- TODO: provide a listing of possible and validatable meta entry values. Maybe in our geekodoc repo? -->
+      <!-- add author's e-mail -->
+      <meta name="maintainer" content="[email protected]" its:translate="no"/>
+      <!-- ISO date of last update as YYYY-MM-DD -->
+      <meta name="updated" content="2024-11-28" 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" its:translate="no"/>
+      <meta name="productname" its:translate="no"><productname version="15 SP6">&sles;</productname>
+      </meta>
+      <meta name="title" its:translate="yes">Modifying kernel boot parameters</meta>
+      <meta name="description" its:translate="yes">How to modify kernel boot parameters for customizing the boot process</meta>
+      <meta name="social-descr" its:translate="yes">Modify kernel boot parameters</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:product>SUSE Linux Enterprise Server 16.0</dm:product>
+          <dm:component>Documentation</dm:component>
+          <dm:assignee>[email protected]</dm:assignee>
+        </dm:bugtracker>
+        <dm:translation>yes</dm:translation>
+      </dm:docmanager>
+      <abstract>
+        <variablelist>
+          <varlistentry>
+            <term>WHAT?</term>
+            <listitem>
+              <para>
+                This article introduces the concepts, examples and modification process for kernel
+                boot parameters to customize the boot process and optimize the resulting
+                environment.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>WHY?</term>
+            <listitem>
+              <para>
+                Modifying kernel boot parameters is essential for achieving specific system
+                configurations and addressing several scenarios, including performance
+                optimization, better hardware compatibility, and troubleshooting issues such as
+                graphics drivers.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>EFFORT</term>
+            <listitem>
+              <para>
+                It takes 15 minutes to fully understand the concepts and the process, and five
+                minutes to modify kernel boot parameters and observe their effect after a reboot.
+                modify kernel boot parameters and observe their effect after a reboot.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>GOAL</term>
+            <listitem>
+              <para>
+                Modify kernel parameters to customize the boot process and the subsequent
+                environment.
+              </para>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>REQUIREMENTS</term>
+            <listitem>
+              <para>
+                Depending on whether you want to apply changes in kernel boot parameters to the
+                upcoming boot process, or all subsequent boot processes, the requirements are as
+                follows:
+              </para>
+              <itemizedlist>
+                <listitem>
+                  <para>
+                    To change kernel boot parameters on an experimental basis only for the upcoming
+                    boot process, there are no requirements.
+                  </para>
+                </listitem>
+                <listitem>
+                  <para>
+                    To change kernel boot parameters for all subsequent boot processes, you should
+                    have <literal>root</literal> or equivalent administrative privileges.
+                  </para>
+                </listitem>
+              </itemizedlist>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </abstract>
+    </merge>
+    <!-- pull in all the topic files you need -->
+    <!-- pick the appropriate type of include to match your needs -->
+    <!-- pull in a topic as is -->
+    <!--concept-->
+    <module resourceref="_kernel-boot-parameters-modify-introduction" renderas="section"/>
+    <!--concept-->
+    <module resourceref="_kernel-boot-parameters-modify-difference-linuxrc-parameters" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-temporary" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-permanent" renderas="section"/>
+    <!--task-->
+    <module resourceref="_kernel-boot-parameters-modify-troubleshoot" renderas="section">
+      <merge>
+        <title>Troubleshooting and FAQs</title>
+      </merge>
+    </module>
+    <!--glue-more-info-->
+    <module resourceref="_kernel-boot-parameters-modify-more-info" renderas="section">
+      <merge>
+        <title>For more information</title>
+      </merge>
+    </module>
+    <!--common-->
+    <module resourceref="_legal"/>
+    <!--common-->
+    <module resourceref="_gfdl">
+      <output renderas="appendix"/>
+    </module>
+  </structure>
+</assembly>
+<!--Delete later; adding just for the sake of testing a push-->
diff --git a/concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml b/concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml
@@ -0,0 +1,106 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- This file originates from the project https://github.com/openSUSE/doc-kit -->
+<!-- This file can be edited downstream. -->
+<!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="kernel-boot-parameters-modify-difference-linuxrc-parameters"
+ 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>Difference between kernel boot parameters and linuxrc parameters</title>
+    <!-- can be changed via merge in the assembly -->
+    <!--add author's email address-->
+    <meta name="maintainer" content="[email protected]" its:translate="no"/>
+    <abstract>
+      <!-- can be changed via merge in the assembly -->
+      <para>
+        Kernel boot parameters and linuxrc parameters are often similar in appearance, but
+        conceptually they are entirely different. It is important that you do not confuse them and
+        understand their basic difference.
+      </para>
+    </abstract>
+  </info>
+  <section xml:id="kernel-boot-parameters-modify-linuxrc-parameter-introduction">
+    <title>What are linuxrc parameters and why are they different from kernel boot parameters?</title>
+    <para>
+      In &sle;, the <literal>linuxrc</literal> script is executed during the boot process before
+      the system's root file system is mounted. It acts as the initial RAM disk (initrd) entry
+      point and sets up the environment needed for the kernel to load the root file system.
+      <literal>linuxrc</literal> parameters are used to pass configurations that affect this early
+      stage of the boot process, such as driver loading, debugging options, or hardware
+      initialization.
+    </para>
+    <para>
+      In contrast, kernel boot parameters are passed to the kernel by the boot loader (such as
+      &grub;) after the initial RAM disk has handed control to the kernel. The kernel boot
+      parameters directly influence how the kernel operates and manages system features such as
+      power management, debugging and hardware interaction after the root file system is mounted.
+    </para>
+    <para>
+      The distinction is critical because <literal>linuxrc</literal> parameters are used to
+      configure the environment before the kernel fully initializes, whereas kernel boot parameters
+      control the behavior of the kernel after this point. Misinterpreting or interchanging the two
+      can lead to improper configurations and boot failures.
+    </para>
+    <para>
+      To learn more about the <literal>linuxrc</literal> parameters and their usage, refer to
+      <link xlink:href="https://documentation.suse.com/sles/html/SLES-all/appendix-linuxrc.html"></link>.
+    </para>
+  </section>
+  <section xml:id="kernel-boot-parameters-modify-linuxrc-parameter-examples">
+    <title>Examples of linuxrc parameters</title>
+    <para>
+      The following examples highlight common <literal>linuxrc</literal> parameters and their use
+      cases to configure the environment before the kernel initializes:
+    </para>
+    <itemizedlist>
+      <listitem>
+        <para>
+          <literal>rd.driver.blacklist=</literal>: Specifies drivers to be blocked in the initrd.
+          For example, <literal>rd.driver.blacklist=nouveau</literal> prevents the
+          <literal>nouveau</literal> graphics driver from loading during the early stages of boot.
+          This can be useful when troubleshooting driver-related boot issues.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.break</literal>: Interrupts the boot process and drops the system to a shell
+          within the initrd for debugging purposes. This parameter is helpful for diagnosing issues
+          related to the early boot process, such as driver loading or file system mounting errors.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.retry=</literal>: Specifies the number of retries for device scanning in the
+          initrd. For example, <literal>rd.retry=3</literal> configures the system to retry
+          scanning devices three times before giving up, which can be critical for resolving
+          transient hardware initialization issues.
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          <literal>rd.luks=1</literal>: Enables support for encrypted devices in the initrd. This
+          parameter is essential for systems that use encrypted root file systems, ensuring that
+          decryption takes place during the initial boot stage.
+        </para>
+      </listitem>
+    </itemizedlist>
+    <para>
+      By contrast, equivalent kernel boot parameters such as <parameter>quiet</parameter> or
+      <parameter>nomodeset</parameter> are not used in the initrd phase but take effect after the
+      kernel is fully initialized. This reinforces the need to distinguish between these two types
+      of parameters.
+    </para>
+  </section>
+</topic>