Modifying Kernel Arguments

Kernel arguments changes are managed by rpm-ostree via the rpm-ostree kargs sub command. Changes are applied to a new deployment and a reboot is necessary for those to take effect.

Adding kernel arguments

You can append kernel arguments. This is useful with e.g. console= that can be used multiple times. An empty value for an argument is allowed:

$ sudo rpm-ostree kargs --append=KEY=VALUE
Example: Add reserved memory for Kdump support
$ sudo rpm-ostree kargs --append='crashkernel=256M'

Removing existing kernel arguments

You can delete a specific kernel argument key/value pair or an entire argument with a single key/value pair:

$ sudo rpm-ostree kargs --delete=KEY=VALUE
Example: Remove console parameters to enable kernel auto-detection
$ sudo rpm-ostree kargs --delete 'console=ttyS0,115200n8'
Example: Update an existing system from cgroupsv1 to cgroupsv2 and immediately reboot
$ sudo rpm-ostree kargs --delete=systemd.unified_cgroup_hierarchy --reboot

Replacing existing kernel arguments

You can replace an existing kernel argument with a new value. You can directly use KEY=VALUE if only one value exists for that argument. Otherwise, you can specify the new value using the following format:

$ sudo rpm-ostree kargs --replace=KEY=VALUE=NEWVALUE
Example: Disable all CPU vulnerability mitigations
$ sudo rpm-ostree kargs --replace=mitigations=auto,nosmt=off

This switches mitigations=auto,nosmt to mitigations=off to disable all CPU vulnerability mitigations.

Interactive editing

To use an editor to modify the kernel arguments:

$ sudo rpm-ostree kargs --editor

Modifying Kernel Arguments via Ignition

There are two ways to modify kernel arguments via Ignition. The current Ignition experimental config spec supports specifying kernel arguments via the kernelArguments section. It is also possible to use Ignition to script a systemd service which runs rpm-ostree kargs and then triggers a reboot.

The Ignition kernelArguments section requires Butane spec version 1.4.0-experimental. After spec 1.4.0 is stabilized, version 1.4.0-experimental will no longer be accepted by Butane, so Butane configs will need to be updated to replace 1.4.0-experimental with 1.4.0. In addition, the corresponding Ignition config version will no longer be accepted by Ignition, so Ignition configs will need to be regenerated with a new version of Butane.
The After=systemd-machine-id-commit.service directive is important in the following systemd service examples to avoid some subtle issues. Similarly, any ConditionFirstBoot=true services should use Before=first-boot-complete.target systemd-machine-id-commit.service. See the systemd documentation for more details.

Example: Moving to cgroups v2

cgroups v1 will be the default in the Fedora CoreOS stable stream until June 15, 2021. Here’s an example kernelArguments section which removes the systemd.unified_cgroup_hierarchy=0 kernel argument so that the machine switches to cgroups v2:

variant: fcos
version: 1.4.0-experimental
kernel_arguments:
  should_not_exist:
    - systemd.unified_cgroup_hierarchy=0

Alternatively, here’s an example systemd unit that does the same:

variant: fcos
version: 1.3.0
systemd:
  units:
    - name: cgroups-v2-karg.service
      enabled: true
      contents: |
        [Unit]
        Description=Switch To cgroups v2
        # We run after `systemd-machine-id-commit.service` to ensure that
        # `ConditionFirstBoot=true` services won't rerun on the next boot.
        After=systemd-machine-id-commit.service
        ConditionKernelCommandLine=systemd.unified_cgroup_hierarchy
        ConditionPathExists=!/var/lib/cgroups-v2-karg.stamp

        [Service]
        Type=oneshot
        RemainAfterExit=yes
        ExecStart=/bin/rpm-ostree kargs --delete=systemd.unified_cgroup_hierarchy
        ExecStart=/bin/touch /var/lib/cgroups-v2-karg.stamp
        ExecStart=/bin/systemctl --no-block reboot

        [Install]
        WantedBy=multi-user.target

Example: Staying on cgroups v1

Starting from June 1, 2021, cgroups v2 is the default on Fedora CoreOS on the next and testing streams. Here’s an example kernelArguments section which adds the systemd.unified_cgroup_hierarchy=0 kernel argument so that the machine keeps using cgroups v1:

variant: fcos
version: 1.4.0-experimental
kernel_arguments:
  should_exist:
    - systemd.unified_cgroup_hierarchy=0

Alternatively, here’s an example systemd unit that does the same:

variant: fcos
version: 1.3.0
systemd:
  units:
    - name: cgroups-v1-karg.service
      enabled: true
      contents: |
        [Unit]
        Description=Switch to cgroups v1
        # We run after `systemd-machine-id-commit.service` to ensure that
        # `ConditionFirstBoot=true` services won't rerun on the next boot.
        After=systemd-machine-id-commit.service
        ConditionKernelCommandLine=!systemd.unified_cgroup_hierarchy
        ConditionPathExists=!/var/lib/cgroups-v1-karg.stamp

        [Service]
        Type=oneshot
        RemainAfterExit=yes
        ExecStart=/bin/rpm-ostree kargs --append=systemd.unified_cgroup_hierarchy=0
        ExecStart=/bin/touch /var/lib/cgroups-v1-karg.stamp
        ExecStart=/bin/systemctl --no-block reboot

        [Install]
        WantedBy=multi-user.target

Example: Disabling all CPU vulnerability mitigations

Here’s an example kernelArguments section which switches mitigations=auto,nosmt to mitigations=off to disable all CPU vulnerability mitigations:

variant: fcos
version: 1.4.0-experimental
kernel_arguments:
  should_exist:
    - mitigations=off
  should_not_exist:
    - mitigations=auto,nosmt

Alternatively, here’s an example systemd unit that does the same:

variant: fcos
version: 1.3.0
systemd:
  units:
    - name: cpu-mitigations-karg.service
      enabled: true
      contents: |
        [Unit]
        Description=Disable all CPU vulnerability mitigations
        # We run after `systemd-machine-id-commit.service` to ensure that
        # `ConditionFirstBoot=true` services won't rerun on the next boot.
        After=systemd-machine-id-commit.service
        ConditionKernelCommandLine=!mitigations=off
        ConditionPathExists=!/var/lib/cpu-mitigations-karg.stamp

        [Service]
        Type=oneshot
        RemainAfterExit=yes
        ExecStart=/bin/rpm-ostree kargs --replace=mitigations=auto,nosmt=off
        ExecStart=/bin/touch /var/lib/cpu-mitigations-karg.stamp
        ExecStart=/bin/systemctl --no-block reboot

        [Install]
        WantedBy=multi-user.target