Skip to content

Commit

Permalink
Smart Docs - Kernel Boot Parameters (#373)
Browse files Browse the repository at this point in the history 
* SmartDocs - Kernel Boot Parameters

* trivial changes

* backup

* Content without modified Troubleshooting

* Modified troubleshooting content

* Modified more info

* Revised based on Tanja's feedback and corrected typos

* Editorial fixes based on Daria's suggestion

* More editorial fixes and formatting

* Minor fixes
  • Loading branch information
@sounix000
sounix000 authored Nov 27, 2024
1 parent 74e7785 commit f4ba4fc
Show file tree
Hide file tree
Showing 8 changed files with 1,048 additions and 0 deletions.
19 changes: 19 additions & 0 deletions DC-kernel-boot-parameters-modify
View file
Original file line number Diff line number Diff line change
@@ -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"
209 changes: 209 additions & 0 deletions articles/kernel-boot-parameters-modify.asm.xml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,209 @@
<?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.
</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-->
106 changes: 106 additions & 0 deletions concepts/kernel-boot-parameters-modify-difference-linuxrc-parameters.xml
View file
Original file line number Diff line number Diff line change
@@ -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>
Loading

0 comments on commit f4ba4fc

Please sign in to comment.