Kernel Command Line Configuration

Overview

The kernel command line in postmarketOS is generated by boot-deploy calling generate-kernel-cmdline. This tool combines configuration from multiple sources following a three-tier hierarchy: distro defaults, device maintainer config, and user overrides.

The previous system using deviceinfo variables had several limitations. First, boot-deploy is distro-agnostic, so any defaults there must apply to all supported distros. This limited what could be added (kernel lockdown, plymouth splash, etc). Second, the deviceinfo keys could only add parameters, not remove them. This made it problematic for users to override kernel cmdline params installed by packaging.

The new system addresses these issues by supporting both adding and removing specific kernel parameters, providing a clear configuration hierarchy with well-defined ordering, and allowing packages to define their own cmdline config without modifying shared defaults (similar to how initramfs files are handled).

For details on the configuration file format, see man 5 generate-kernel-cmdline or the online documentation.

Migration from deviceinfo

To migrate a device package from the old system:

1. Remove deviceinfo_kernel_cmdline= from the device’s deviceinfo file

2. Create a kernel-cmdline.conf file in the device package directory listing the parameters (one per line)

3. Add kernel-cmdline.conf to source= in the APKBUILD

For example, if deviceinfo had:

deviceinfo_kernel_cmdline="quiet loglevel=2 clk_ignore_unused"

Create kernel-cmdline.conf:

quiet
loglevel=2
clk_ignore_unused

Device packages with that support multiple kernels should name the file kernel-cmdline.<kernel name>.conf and add it to sources= in the APKBUILD. No other action is needed, this file will be automatically added to the correct subpackage by devicepkg-dev.

Device Package Configuration

Device maintainers can add kernel command line parameters specific to their device by creating a kernel-cmdline.conf file in the device package directory and adding it to source= in the APKBUILD. The devicepkg-dev tool will automatically install this file to /usr/lib/kernel-cmdline.d/50-<device>.conf during package build. This works similarly to how modules-initfs files are handled.

The configuration file lists kernel parameters one per line. Parameters can be added or removed (prefix with - to remove).

Example kernel-cmdline.conf:

console=ttyMSM0,115200
clk_ignore_unused
pd_ignore_unused

User Overrides

Users and system administrators can override kernel command line configuration by creating files in /etc/kernel-cmdline.d/. Files must have a .conf extension and are processed in lexicographic order after distro and device configs.

To add parameters, create a config file:

doas $EDITOR /etc/kernel-cmdline.d/custom.conf

To remove a parameter that was set by distro or device config, prefix it with -:

-quiet
debug

Verification

Users can verify the generated kernel command line by running generate-kernel-cmdline as an unprivileged user:

$ generate-kernel-cmdline
quiet hid_apple.swap_fn_leftctrl=1 splash

Note that this only shows parameters from configuration files. It does not include parameters that boot-deploy injects at install time.

Examples

Base Distro Config

/usr/lib/kernel-cmdline.d/00-base.conf:

quiet
splash

Device Config

/usr/lib/kernel-cmdline.d/50-device-pine64-pinephone.conf:

console=ttyMSM0,115200

Result: quiet splash console=ttyMSM0,115200

User Override for Debugging

/etc/kernel-cmdline.d/debug.conf:

-quiet
debug
loglevel=7

Result: splash console=ttyMSM0,115200 debug loglevel=7

User Hardware Configuration

/etc/kernel-cmdline.d/keyboard.conf:

hid_apple.swap_fn_leftctrl=1

Result: splash console=ttyMSM0,115200 debug loglevel=7 hid_apple.swap_fn_leftctrl=1