Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

Chapter 11. Managing kernel arguments in bootc systems

You can use bootc to configure kernel arguments. By default, bootc uses the boot loader configuration files that are stored in /boot/loader/entries. This directory defines arguments provided to the Linux kernel. While kernel arguments are machine-specific, you can manage them through 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. For example: 

# /usr/lib/bootc/kargs.d/10-example.toml
kargs = ["mitigations=auto,nosmt"]
Copy to Clipboard Toggle word wrap

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,114800n8"]
match-architectures = ["x86_64"]
Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

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

    $ podman pull quay.io/<your_org>/<your_bootc_image>:latest
    Copy to Clipboard Toggle word wrap

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

    # bootc install to-filesystem --karg=root=<UUID>=<uuid of /mnt> --imgref $self /mnt
    Copy to Clipboard Toggle word wrap

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

    cd /usr/lib/bootc/kargs.d
    Copy to Clipboard Toggle word wrap

  5. Read each file within the kernel arguments directory. 

    $ find /usr/lib/bootc/kargs.d -name ".kargs" -exec cat {} \;*
    Copy to Clipboard Toggle word wrap

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

    $ CONSOLIDATED_KARGS="/tmp/all-kargs.txt"
    Copy to Clipboard Toggle word wrap

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

    $ bootc kargs --append="$KARGS_STRING"
    Copy to Clipboard Toggle word wrap

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

    $ bootc switch --transport=registry quay.io/<your_org>/<your_bootc_image>:latest
    Copy to Clipboard Toggle word wrap

To add kernel arguments into a container image, use a Containerfile. The following is an example: 

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,114800n8"]
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
Copy to Clipboard Toggle word wrap

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
    Copy to Clipboard Toggle word wrap

The bootc-image-builder tool supports the customizations.kernel.append during the installation time.

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"
    }
  }
}
    Copy to Clipboard Toggle word wrap

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.

11.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.

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.

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
    Copy to Clipboard Toggle word wrap

  • Check the help for more information: 

    # rpm-ostree kargs --help
    Copy to Clipboard Toggle word wrap
Back to top
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

© 2025 Red Hat