Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 12. Managing kernel arguments in bootc systems

You can customize the boot process of your Red Hat Enterprise Linux bootc systems by managing kernel arguments. By configuring these parameters, you can tune performance and ensure hardware compatibility by applying settings during the image build or installation phase.

You can use bootc to configure kernel arguments. By default, bootc uses the boot loader configuration files stored in /boot/loader/entries. This directory defines arguments provided to the Linux kernel. The set of kernel arguments is machine-specific state, but you can also manage the kernel arguments by using container updates. The boot loader menu entries are shared between multiple operating systems, and boot loaders are installed on one device.

Note

Currently, the boot loader entries are written by an OSTree backend.

The bootc tool uses generic operating system kernels. You can add support to inject kernel arguments by adding a custom configuration, in the TOML format, in /usr/lib/bootc/kargs.d.

Prerequisites

  • You created a container image.

Procedure

  • Add support to inject kernels, for example: 

    # /usr/lib/bootc/kargs.d/10-example.toml
kargs = ["mitigations=auto,nosmt"]
  • Optional: You can also make these kernel arguments architecture-specific by using the match-architectures key. For example: 
# /usr/lib/bootc/kargs.d/00-console.toml
kargs = ["console=ttyS0,115200n8"]
match-architectures = ["x86_64"]

To modify kernel arguments by using the bootc install configurations, you can customize the startup behavior of your Red Hat Enterprise Linux deployments. These parameters enable specific hardware settings or performance optimizations that persist through system updates and reboots.

You can use the bootc install command with the --karg option to inject kernel arguments during installation time in the following ways:

  • Adding kernel arguments into the container image.
  • Adding kernel arguments by using the bootc install --karg command.

Use the kernel arguments on Day 2 operations, by adding the arguments and applying them on a switch, upgrade, or edit.

Prerequisites

  • You created a container image.

Procedure

  1. Create files within /usr/lib/bootc/kargs.d with kernel arguments. 

    $ sudo tee /usr/lib/bootc/kargs.d/console.kargs << EOF
console=tty0 console=ttyS0,115200n8
EOF

  2. Fetch the container image to get the OSTree commit. 

    $ podman pull quay.io/<your_org>/<your_bootc_image>:latest

  3. Use the OSTree commit to return the file tree. 

    # bootc install to-filesystem --karg=root=<UUID>=<uuid of /mnt> --imgref $self /mnt

  4. Navigate to the /usr/lib/bootc/kargs.d kernel arguments directory. 

    cd /usr/lib/bootc/kargs.d

  5. Read each file within the kernel arguments directory. 

    $ find /usr/lib/bootc/kargs.d -name ".kargs" -exec cat {} \;*

  6. Push the contents of each kargs file into a file containing all the needed kargs. 

    $ CONSOLIDATED_KARGS="/tmp/all-kargs.txt"

  7. Pass the kargs to the stage() function. 

    $ bootc kargs --append="$KARGS_STRING"

  8. Apply the kernel arguments to switch, upgrade, or edit during operations. 

    $ bootc switch --transport=registry quay.io/<your_org>/<your_bootc_image>:latest

Inject kernel arguments into your Red Hat Enterprise Linux Containerfile to configure boot parameters during the image build process. Embedding these settings ensures that specific kernel options are consistently applied to any system provisioned from the container image, eliminating the need for post-deployment configuration.

Prerequisites

  • You created a container image.

Procedure

  • Inject kernel arguments: 

    FROM registry.redhat.io/rhel10/rhel-bootc:latest

RUN mkdir -p /usr/lib/bootc/kargs.d
RUN cat <<EOF >> /usr/lib/bootc/kargs.d/console.toml
kargs = ["console=ttyS0,115200n8"]
match-architectures = ["x86_64"]
EOF

RUN cat <<EOF >> /usr/lib/bootc/kargs.d/01-mitigations.toml
kargs = ["mitigations=on", "systemd.unified_cgroup_hierarchy=0"]
match-architectures = ["x86_64", "aarch64"]
EOF

You can use boot install with the --karg to inject kernel arguments during installation time. As a result, the kernel arguments become the machine-local state, that is, they became the persistent configuration unique to that specific machine.

Prerequisites

  • You created a container image.

Procedure

  • Inject kernel arguments: 

    # bootc install to-filesystem --karg=root=<UUID>=<uuid of /mnt> --imgref $self /mnt

Use the bootc-image-builder to add install-time kernel arguments to Red Hat Enterprise Linux bootc images. Defining the kernel parameters by using the customizations.kernel.append to configure hardware-specific settings or console outputs required during the initial povisioning process.

Prerequisites

  • You created a container image.

Procedure

  • Add kernel arguments with bootc-image-builder by using the following customization: 

    {
  "customizations": {
    "kernel": {
      "append": "mitigations=auto,nosmt"
    }
  }
}

The changes that you make to kargs.d files and include in a container build are applied after the installation, and the difference between the set of kernel arguments is applied to the current boot loader configuration. This preserves any machine-local kernel arguments.

You can use any tool to edit the /boot/loader/entries files, which are in a standardized format. The /boot file has read-only access to limit the set of tools that can write to this filesystem.

12.7. Editing kernel arguments in bootc systems
Copy link

To perform machine local changes, you also can edit kernel arguments on a bootc system or an rpm-ostree system, by using the rpm-ostree kargs command. The changes are made through the user/lib/bootc/kargs.d path, which also handles Day 2 changes, besides the first boot changes.

Prerequisites

  • You created a container image.

Procedure

  • Append a kernel argument, for example: 

    # rpm-ostree kargs --append debug
Staging deployment... done
Freed: 40.1 MB (pkgcache branches: 0)
Changes queued for next boot. Run "systemctl reboot" to start a reboot

  • Check the help for more information: 

    # rpm-ostree kargs --help

    The following are the options that you can use to add, modify or remove kernel arguments.

    rpm-ostree kargs

    --append=KEY=VALUE
    Appends a kernel argument. It is useful with, for example, console= that can be used multiple times. You can use an empty value for an argument.
    --replace=KEY=VALUE=NEWVALUE
    Replaces an existing kernel argument. You can replace an argument with KEY=VALUE only if one value already exists for that argument.
    --delete=KEY=VALUE
    Deletes a specific kernel key-value pair argument or an entire argument with a single key-value pair.
    --append-if-missing=KEY=VALUE
    Appends a kernel argument. Does nothing if the key is already present.
    --delete-if-present=KEY=VALUE
    Deletes a specific kernel key-value pair argument. Does nothing if the key is missing.
    --editor
    Uses an editor to modify the kernel arguments.

To ensure that drivers persist across updates, include your third-party kernel modules directly in the container build process. This way, networking and security drivers remain available across image updates, upgrades, and reboots.

To use filesystem, networking, or security modules not included in the default RHEL kernel, you can use the image mode for the RHEL workflow. Unlike the traditional package mode, where drivers are installed on a live system by using dnf, image mode treats the filesystem as immutable.

To include your custom drivers, you can use a multi-stage build. Use the rhel-bootc image as your builder stage to install your third-party kernel modules and compile your source code. This guarantees the driver is compatible with the kernel in the resulting bootable image.

Prerequisites

  • You wrapped your .ko file in an RPM to handle dependency mapping by automatically using depmod during the container build.

Procedure

  1. On your build host, compile your driver and build the RPM package.

    1. Verify the spec and build the package: 

      $ cat SPECS/hello.spec

    2. Build the driver RPM: 

      $ rpmbuild -ba SPECS/hello.spec

  2. Create the Containerfile to append the driver into the operating system image. Use the rhel-bootc base image. The following is an example: 

    # Copy the pre-built RPM into the build context
COPY rpms/hello-<version>-<release>.el10.<arch>.rpm /tmp/

    Alternatively, you can fetch it from a network location. 

    # Install the RPM.
# The %post scripts in the RPM triggers 'depmod' automatically inside the image.
RUN dnf install -y /tmp/hello-<version>-<release>.el10.<arch>.rpm && \
   	dnf clean all && \
    	rm /tmp/hello-<version>-<release>.el10.<arch>.rpm
  3. Build and run your container image. See Building a container.

Verification

  1. Reboot the system: 

    $ sudo reboot

  2. Confirm the kernel module is available on the system: 

    $ sudo uname -r
<kernel_version>

$ sudo ls -l /lib/modules/<kernel_version>/extra/
total 12
-rwxr-xr-x. 1 root root 8512 Jan  1  1970 hello.ko

  3. Ensure that the module dependencies are calculated before the image is finalized, otherwise modprobe might fail on the first boot. 

    $ sudo depmod -a <kernel-version>

  4. Confirm that you can load the module: 

    $ sudo modprobe /lib/modules/<kernel_version>/extra/hello.ko
$ sudo lsmod | grep hello
   hello        12288  0
$ sudo rmmod hello
$ sudo dmesg
 ..snip..
[   84.738633] hello: loading out-of-tree module taints kernel.
[   84.738684] hello: module verification failed: signature and/or required key missing -tainting kernel.
[   84.740548] Hello, world!
[  138.206978] Goodbye!
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2026 Red HatBack to top