{{Header}}
{{title|title=
grub bootloader Configuration Changes
}}
{{#seo:
|description=Kernel Boot Parameter Changes
|image=Live-mode-promo.jpg
}}
{{troubleshooting_mininav}}
[[File:kicksecure-persistent-mode-user-session.png|thumb|GRUB boot menu]]
{{intro|
Kernel Boot Parameter Changes
}}
__TOC__
= Introduction =
TODO: Expand introduction.

'''Figure:''' ''GRUB boot menu''

[[File:kicksecure-persistent-mode-user-session.png|GRUB boot menu|500px]]

= Kernel Boot Parameters =
{{mbox
| type    = notice
| image   = [[File:Ambox_notice.png|40px|alt=Info]]
| text    = This is a grub, not a {{project_name_long}} feature. [[Unspecific|Unspecific to {{project_name_long}}.]] Therefore [[Self_Support_First_Policy|Self Support First Policy]] applies.
}}

Before trying specific kernel boot parameters, it is advisable to first add them temporarily for testing or troubleshooting purposes. When the parameters have the intended effect, they can then be added permanently.

Kernel boot parameters are text strings that disable/enable certain features or change specific system behaviors. To achieve the desired change, note kernel boot parameters: <ref>
https://wiki.ubuntu.com/Kernel/KernelBootParameters
</ref>

* <u>Keyword parameters:</u> Kernel boot parameters can be simple keywords (like "<code>splash</code>" or "<code>noapic</code>").
* <u>Case sensitivity:</u> Kernel boot parameters are case-sensitive (for example "<code>Noapic</code>" would not have any effect but "<code>noapic</code>" would take effect).
* <u>Value parameters:</u> Kernel boot parameters might have an <code>=</code> sign to denote values (like "<code>acpi_backlight=vendor</code>").
* <u>Punctuation:</u> Kernel boot parameters might include punctuation (like "<code>i8042.noloop</code>").
* <u>Exact matching:</u> Kernel boot parameters have no effect unless entered exactly as advised.
* <u>No error messages:</u> Spelling or formatting errors, or invalid values, are silently ignored and do not result in an error message.

= Temporary Kernel Boot Parameter Change =
{{Anchor|Kernel Boot Parameter Change}}
Follow these steps to temporarily add and/or remove kernel boot parameters. Example use cases include:

* {{IconSet|h4|A}} Enabling verbose boot messages for the purpose of debugging boot failures.
* {{IconSet|h4|B}} Booting into [[Recovery#Recovery_Mode|Recovery Mode]] (single user mode).
* {{IconSet|h4|C}} Testing kernel parameters temporarily before making them accessible through [[#Permanent Configuration Changes|Permanent Configuration Changes]].
* {{IconSet|h4|D}} This list is far from exhaustive.

{{Box|text=
{{IconSet|h1|1}} Restart the system. <ref>
Or shut it down and power it on again.
</ref> The GRUB menu will automatically appear. <ref> If the menu does not appear, repeatedly press the {{IconSet|keyboard|ESC}} key until the grub menu appears. Alternatively, the {{IconSet|keyboard|shift}} key can be held down continuously for BIOS-mode (not UEFI-mode) until the menu appears.<br />
<br />
The system might hang when holding down the {{IconSet|keyboard|shift}} key. If that happens, just briefly release the {{IconSet|keyboard|shift}} key and hold it down again until the grub menu appears.
</ref>

{{IconSet|h1|2}} Change the GRUB keyboard layout.

<u>Note:</u> Optional.

{{box|text=
{{IconSet|h2|1}} Scroll to <code>Keyboard layout options</code>.

Scroll all the way down using the {{IconSet|keyboard|↓}} key until you reach <code>Keyboard layout options</code>, then press {{IconSet|keyboard|enter}}.

{{IconSet|h2|2}} Select your keyboard layout.

Navigate using the arrow keys ({{IconSet|keyboard|↑}} or {{IconSet|keyboard|↓}}) until you find your keyboard layout, then press {{IconSet|keyboard|enter}}.

{{IconSet|h2|3}} Read the notice.

<pre>
Switching keyboard layouts may cause the keyboard to malfunction or
become unresponsive. If this occurs, force-reboot the machine to
fix this.

Keyboard layout `..` loaded. Press enter to continue.
</pre>

{{IconSet|h2|4}} Confirm and return to the main menu.

Press {{IconSet|keyboard|enter}} to continue, then press {{IconSet|keyboard|ESC}} to go back to the main menu.

{{IconSet|h2|5}} Done.

Keyboard layout change complete.
}}

{{IconSet|h1|3}} Select the relevant entry to edit.

Use the arrow keys ({{IconSet|keyboard|↑}} or {{IconSet|keyboard|↓}}) to highlight the relevant entry and then press the {{IconSet|keyboard|e}} key to enter edit mode.

{{IconSet|h1|4}} Go to the end of the line.

Use the arrow keys to move down to the line that contains boot arguments: <ref>
https://web.archive.org/web/20220312140233/https://docs.fedoraproject.org/en-US/Fedora/22/html/Multiboot_Guide/GRUB-runtime.html
</ref> The line will begin with <code>linux</code>.

Press the {{IconSet|keyboard|end}} key to move the cursor to the end of that line.

{{IconSet|h1|5}} Add or remove kernel boot parameter changes.

* {{IconSet|false|A}} <u>Removing kernel parameters:</u>
** Optional.
** For example, removing the following kernel parameters can be very useful for debugging: <code>loglevel=0</code> <code>quiet</code> <code>rd.shell=0</code> <code>rd.emergency=halt</code>
* <u>And/or,</u>
* {{IconSet|false|B}} <u>Add kernel parameters:</u> Press the {{IconSet|keyboard|space}} and carefully type in kernel boot parameter(s).
** Optional.
** For example, to enable [[Recovery#Recovery_Mode|Recovery Mode]] (single user mode), type: {{CodeSelect|inline=true|code=single}}
** <u>Note:</u> Replace <code>single</code> with the actual kernel parameter.

{{IconSet|h1|6}} Notes:

* Multiple parameters are separated with a <code>space</code>.
* No <code>space</code>s are added before or after any <code>=</code> (equals) signs or for punctuation in parameters.

{{IconSet|h1|7}} Boot the system.

Press {{IconSet|keyboard|ctrl}} + {{IconSet|keyboard|X}} to boot the system with the new, temporary parameters.

{{IconSet|h1|8}} Done.

The effect will only last for this boot session; once the system is restarted, they will no longer have any effect.
}}

= Permanent Configuration Changes =
{{Box|text=
{{IconSet|h1|1}} Learn how to configure permanent changes.

Inspect the following resources:

* folder <code>/etc/default/grub.d</code>
* file <code>/etc/default/grub.d/40_kernel_hardening.cfg</code>

{{IconSet|h1|2}} Create a new configuration file.

{{Open with root rights|
filename=/etc/default/grub.d/50_user.cfg
}}

{{IconSet|h1|3}} Paste the necessary GRUB configuration change such as adding or removing kernel parameters.

<u>Notes:</u>

* The following example uses kernel parameter <code>nomodeset</code>.
* Replace only <code>nomodeset</code> with the actual kernel parameters you want to add.
* Do not remove the leading text (underlined): <code><u>GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX</u> nomodeset"</code>.
* Do not remove the trailing quote (<code>'''"'''</code>; marked in bold): <code>GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX nomodeset'''"'''</code>.

{{CodeSelect|code=
GRUB_CMDLINE_LINUX="$GRUB_CMDLINE_LINUX nomodeset"
}}

{{IconSet|h1|4}} Save.

{{IconSet|h1|5}} Regenerate grub configuration.

{{CodeSelect|code=
sudo update-grub
}}

{{IconSet|h1|6}} Done.

The process of adding a kernel parameter is complete.

{{IconSet|h1|7}} Verification of GRUB configuration file.

Optional.

Inspect <code>/boot/grub/grub.cfg</code> because that is the generated file which is actually used during the boot process.

{{CodeSelect|code=
sudoedit /boot/grub/grub.cfg
}}

{{IconSet|h1|8}} Reboot.

A reboot is required for changes to take effect.

{{CodeSelect|code=
reboot
}}

{{IconSet|h1|9}} Verification of kernel command line.

Inspect the virtual file <code>/proc/cmdline</code>.

{{CodeSelect|code=
cat /proc/cmdline
}}
}}

= Inspect Grub Configuration Changes =
{{IconSet|h1|1}} Put folder <code>/boot/grub</code> under git version control.

Git is a useful tool to record which files in a folder changed and how.

{{box|text=
Git setup for folder <code>/boot/grub</code>.

{{Git version control
|sudo_maybe=sudo
|folder=/boot/grub
}}
}}

{{IconSet|h1|2}} Change grub configuration.

Make changes according to [[#Permanent Configuration Changes|Permanent Configuration Changes]].

{{IconSet|h1|3}} See which files were modified by <code>update-grub</code>.

From the same folder.

{{CodeSelect|code=
git status
}}

{{IconSet|h1|4}} Inspect the changes.

Using command line with the default diff viewer <code>diff</code> can be difficult to read, but an alternative is presented in the next step.

{{CodeSelect|code=
git diff
}}

{{IconSet|h1|5}} Optional: Use a graphical diff viewer.

A graphical diff viewer can be used. [[Unspecific]]. [[Undocumented]].

{{CodeSelect|code=
git difftool
}}

= Inspect Kernel Command Line =
{{IconSet|h1|1}} Display the kernel command line.

To view the kernel command line of the currently booted kernel, run:

{{CodeSelect|code=
cat /proc/cmdline
}}

{{IconSet|h1|2}} <u>Optional:</u> Filter for a specific parameter.

If there is too much output, use <code>grep</code> to filter.

<u>Note:</u> Replace <code>parameter</code> with the actual kernel parameter you are looking for.

{{CodeSelect|code=
cat /proc/cmdline {{!}} grep --color parameter
}}

{{IconSet|h1|3}} Done.

The current kernel command line has been inspected.

= Goodies =
* https://packages.debian.org/{{Stable_project_version_based_on_Debian_codename}}/grub-image-boot
* https://packages.debian.org/{{Stable_project_version_based_on_Debian_codename}}/grub-customizer

= Boot with Manual Commands =
TODO: document

https://forums.kicksecure.com/t/kicksecure-no-password-prompt-on-gnu-grub/483/3

= Boot Related Screenshots =
TODO: document

== GRUB Bootloader Authentication Password Prompt ==
<u>Notes:</u>

* This is an authentication password for the GRUB bootloader, providing basic protection against unauthorized access. It is unrelated to [[Full Disk Encryption]].
* This is for protecting GRUB menu and settings from unauthorized changes.

Refer to:

* [[Protection_Against_Physical_Attacks#Bootloader_Password|Bootloader Password]]
* [[Protection_Against_Physical_Attacks#How_to_set_a_bootloader_password|How to set a bootloader password]].

'''Figure:''' ''GRUB Bootloader Authentication Password Prompt''

[[File:grub_bootloader_password.jpg]]

== Legacy BIOS - GRUB Bootloader Disk Decryption Password Prompt  ==

'''Figure:''' ''GRUB Bootloader Disk Decryption Password Prompt for (Legacy BIOS)''

[[File:Grubpass.png|600px]]

== EFI - GRUB Bootloader Disk Decryption Password Prompt ==

'''Figure:''' ''GRUB Bootloader Disk Decryption Password Prompt (EFI)''

[[File:EFIGrubpass.png|600px]]

== EFI - SecureBoot - Boot Error Message ==

This is a known issue. No bug report is required.

'''Figure:''' ''EFI SecureBoot Boot Error Message''

[[File:EFIDracutpass.png|600px]]

To resolve this issue, refer to [[Secure Boot]].

== initramfs (initramfs-tools or dracut) Based Encryption Password Prompt ==
Initramfs-based encryption password prompts are not directly related to GRUB. They are created by the initramfs generation tool, such as <code>initramfs-tools</code> or <code>dracut</code>. These prompts are mentioned on this page for completeness, to avoid confusing a prompt generated by the initramfs with a prompt generated by GRUB.

{{quotation
|quote=Please enter passphrase for disk ... (press TAB for no echo)
}}

'''Figure:''' ''initramfs (initramfs-tools or dracut) Based Encryption Password [[Full_Disk_Encryption#Pre-Boot_Authentication|Pre-Boot Authentication]] Prompt - Example (cropped)''

[[File:Dracutpass-cropped.png|frameless|1200px|alt={{project_name_short}} GRUB|initramfs (dracut) Based Encryption Password Prompt]]

'''Figure:''' ''initramfs (initramfs-tools or dracut) Based Encryption Password Prompt - Example (full)''

[[File:dracutpass.png|600px]]

This is related to [[Full Disk Encryption|{{fde}}]].

{{quotation
|quote=The installer currently requires that you set a disk encryption passphrase when you’re on the “Partitions” screen. Whatever passphrase you set at that point, type that in and press “Enter”. If you don’t remember entering a passphrase, but do remember entering a password at some point, type in that password.
|context=[https://forums.kicksecure.com/t/please-enter-passphrase-for-disk-rootfs-message/984 "Please enter passphrase for disk rootfs" message]
}}

= Kicksecure Specific =
== Screenshots ==
<gallery>
File:kicksecure-live-mode-sysmaint-session.png
File:kicksecure-live-mode-user-session.png
File:kicksecure-persistent-mode-sysmaint-session.png
File:kicksecure-persistent-mode-user-session.png
File:kicksecure-remove-user-sysmaint-split.png
</gallery>

== /etc/default/grub.d/20_dist-base-files.cfg ==
File {{CodeSelect|inline=true|code=
/etc/default/grub.d/20_dist-base-files.cfg
}}

<u>Technical information:</u>

<u>For advanced users only.</u> Laymen users an skip this additional explanation. See [[Dev/boot#.2Fetc.2Fdefault.2Fgrub.d.2F20_dist-base-files.cfg|<code>/etc/default/grub.d/20_dist-base-files.cfg</code>]].

= See Also =
* [[Configuration Files]]
* [[grub-live]]
* [[Recovery]]

= Footnotes =
{{reflist|close=1}}
{{Footer}}
[[Category:Documentation]]