How to modify boot entries and kernel command-line parameters in Alibaba Cloud Linux 3 AI Extension Edition - Alibaba Cloud Linux

This topic describes how to use the grubby tool to add or delete kernel boot parameters in the Alibaba Cloud Linux 3 AI Extension Edition operating system.

Understand the boot configuration file structure

Boot entry configuration file: All GRUB boot entry configurations are located in the /boot/loader/entries/ directory. The filename is a combination of the machine-id (`/etc/machine-id`) and the kernel version. For example, c8742e47872643a6839300623c28b57c-5.10.134-19.101.al8.x86_64.conf.

Configuration file example:

title Alibaba Cloud Linux (5.10.134-19.101.al8.x86_64) 3 (OpenAnolis Edition)
version 5.10.134-19.101.al8.x86_64
linux /boot/vmlinuz-5.10.134-19.101.al8.x86_64
initrd /boot/initramfs-5.10.134-19.101.al8.x86_64.img $tuned_initrd
options $kernelopts $tuned_params
id alinux-20250707132428-5.10.134-19.101.al8.x86_64
grub_users $grub_users
grub_arg --unrestricted
grub_class kernel

The options line determines the parameters that the kernel accepts at startup. By default, it references a variable named kernelopts. This variable defines common kernel parameters that apply to all boot entries. Its value is stored in the /boot/grub2/grubenv file. By modifying this variable, you can manage parameters globally for all kernel versions.

Recommended tool

Manually editing these configuration files can cause formatting errors that may prevent the system from starting. Use the grubby command line interface to manage kernel boot entries. grubby automatically handles complex configuration file updates to ensure atomicity and correctness.

Prerequisites

Before you begin, ensure that the following conditions are met:

Permissions: Log on to the target ECS instance as a user with root permissions.
Data backup (Recommended): For production environments, create a snapshot for the instance before you perform the operations. This lets you quickly recover data in case of a fault.
Special configuration for AI Extension Edition images: To modify kernel command-line parameters or boot entries in an Alibaba Cloud Linux 3 AI Extension Edition image, you must run the following command once before running any grubby modification commands.
```
efibootmgr -q && test -f /boot/efi/EFI/alinux/grubenv && ln -sf ../efi/EFI/alinux/grubenv /boot/grub2/grubenv # This command only needs to be run once. Running it multiple times has no adverse effects.
```

Important

This operation ensures that the grubenv environment is correctly linked. If it is not linked correctly, your changes will not take effect.

Use grubby to modify boot parameters

This section describes two core methods to modify kernel boot parameters. Select the appropriate method based on your needs.

Globally modify parameters for all boot entries

Use this method when you need to apply a parameter to all installed kernel versions. For example, you can add nvme_core.io_timeout=4294967295 to support specific hardware.

How it works: grubby directly modifies the value of the kernelopts variable in the /boot/grub2/grubenv file. All boot entries that reference this variable are affected.

Commands:

Add a parameter

grubby --update-kernel=ALL --args="<NEW_PARAMETER>"   
# Replace <NEW_PARAMETER> with the parameter that you want to add. For example: "nvme_core.io_timeout=4294967295"

Remove a parameter

grubby --update-kernel=ALL --remove-args="<PARAMETER_TO_REMOVE>" 
 # Replace <PARAMETER_TO_REMOVE> with the parameter that you want to remove. For example: "quiet"

Modify the kernel command-line parameters for a single boot entry

Use this method when you want to add or remove a test parameter for a specific kernel version, such as the currently running kernel, without affecting other kernel versions or future global modifications.

How it works: To modify the kernel command-line parameters for a single boot entry, the kernelopts variable is expanded and its value is saved to the corresponding boot entry configuration file in /boot/loader/entries/<RELEVANT_KERNEL_BOOT_ENTRY.conf>.
Note
To modify the kernel command-line parameters for this boot entry again, you must specify the boot entry. This is because the configuration file for the boot entry no longer contains the kernelopts variable.

Commands:

Add a parameter

grubby --update-kernel=/boot/vmlinuz-$(uname -r) --args="<NEW_PARAMETER>"
# Replace <NEW_PARAMETER> with the parameter that you want to add.

Remove a parameter

grubby --update-kernel=/boot/vmlinuz-$(uname -r) --remove-args="<PARAMETER_TO_REMOVE>"
# Replace <PARAMETER_TO_REMOVE> with the parameter that you want to remove.