Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Smart Docs - Kernel Boot Parameters #373

Merged
merged 10 commits into from
Nov 27, 2024
Merged

Smart Docs - Kernel Boot Parameters #373

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
afe13e3
SmartDocs - Kernel Boot Parameters
sounix000 Sep 23, 2024
5a5e5a0
trivial changes
sounix000 Oct 25, 2024
0169977
backup
sounix000 Oct 25, 2024
5b40dcc
Content without modified Troubleshooting
sounix000 Nov 19, 2024
79af59e
Modified troubleshooting content
sounix000 Nov 19, 2024
7eabf72
Modified more info
sounix000 Nov 19, 2024
21c0b92
Revised based on Tanja's feedback and corrected typos
sounix000 Nov 21, 2024
2762598
Editorial fixes based on Daria's suggestion
sounix000 Nov 26, 2024
53037f7
More editorial fixes and formatting
sounix000 Nov 27, 2024
edfd739
Minor fixes
sounix000 Nov 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions DC-kernel-boot-parameters-modify
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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