diff --git a/modules.json b/modules.json index 66afaa8..f4ade7f 100644 --- a/modules.json +++ b/modules.json @@ -10,6 +10,7 @@ "https://raw.githubusercontent.com/blue-build/modules/main/modules/gschema-overrides/module.yml", "https://raw.githubusercontent.com/blue-build/modules/main/modules/justfiles/module.yml", "https://raw.githubusercontent.com/blue-build/modules/main/modules/rpm-ostree/module.yml", + "https://raw.githubusercontent.com/blue-build/modules/main/modules/kargs/module.yml", "https://raw.githubusercontent.com/blue-build/modules/main/modules/initramfs/module.yml", "https://raw.githubusercontent.com/blue-build/modules/main/modules/script/module.yml", "https://raw.githubusercontent.com/blue-build/modules/main/modules/signing/module.yml", diff --git a/modules/kargs/README.md b/modules/kargs/README.md new file mode 100644 index 0000000..d46ba36 --- /dev/null +++ b/modules/kargs/README.md @@ -0,0 +1,14 @@ +# `kargs` + +The `kargs `module injects kernel arguments into the image. Kernel arguments can be used to define how kernel will interact with the hardware or software. + +Instead of modifying & rebuilding the kernel, the module uses `/usr/lib/bootc/kargs.d/` to define the kernel arguments. See the link below for how `bootc` injects kernel arguments: +https://containers.github.io/bootc/building/kernel-arguments.html + +Because the kargs are managed by `bootc`, to use this module, it is required to be have it installed & to be using it for example for updating the image. This means that instead of `rpm-ostree update`, you need to use `bootc update` for kargs to get applied on the next boot. Or in case of changing the image, you need to use `bootc switch` instead of `rpm-ostree rebase`. + +To see which kargs are currently applied, you can issue `rpm-ostree kargs` command in a local terminal. + +To see which kargs are supported in the kernel, you can see [this detailed documentation](https://web.git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Documentation/admin-guide/kernel-parameters.txt). +Switch the branch accordingly to the kernel version your image is on to get the more accurate version of the documentation. +Take a note it's possible that some working kargs are not in the documentation. diff --git a/modules/kargs/kargs.sh b/modules/kargs/kargs.sh new file mode 100644 index 0000000..09338b6 --- /dev/null +++ b/modules/kargs/kargs.sh @@ -0,0 +1,43 @@ +#!/usr/bin/env bash + +set -euo pipefail + +if ! command -v bootc &> /dev/null; then + echo "ERROR: 'bootc' package is not installed, please install it, as it's necessary for injecting kargs." + exit 1 +fi + +KARGS_D="/usr/lib/bootc/kargs.d" +BLUEBUILD_TOML="${KARGS_D}/bluebuild-kargs.toml" + +get_json_array KARGS 'try .["kargs"][]' "${1}" +formatted_kargs=$(printf '"%s", ' "${KARGS[@]}") +formatted_kargs=${formatted_kargs%, } + +ARCH=$(echo "${1}" | jq -r 'try .["arch"]') +formatted_arch=$(echo "${ARCH}" | sed 's/[^, ]\+/"&"/g') + +if [[ ${#KARGS[@]} -gt 0 ]]; then + # Make kargs.d directory in case it doesn't exist + mkdir -p "${KARGS_D}" + # If bluebuild-kargs.toml already exists from the previous module run, append a new suffixed toml file instead + if [[ -f "${BLUEBUILD_TOML}" ]]; then + counter=1 + new_filename="${KARGS_D}/bluebuild-kargs-${counter}.toml" + while [[ -f "${new_filename}" ]]; do + counter=$((counter + 1)) + new_filename="${KARGS_D}/bluebuild-kargs-${counter}.toml" + done + BLUEBUILD_TOML="${new_filename}" + fi + # Write kargs to toml file + echo "Writing following kernel arguments to kargs.d TOML file: ${formatted_kargs}" + echo "kargs = [${formatted_kargs}]" > "${BLUEBUILD_TOML}" + if [[ "${ARCH}" != "null" ]]; then + echo "Those kernel arguments are applied to the following specific OS architecture(s): ${formatted_arch}" + echo "match-architectures = [${formatted_arch}]" >> "${BLUEBUILD_TOML}" + fi +else + echo "ERROR: You did not include any kernel arguments to inject in the image." + exit 1 +fi diff --git a/modules/kargs/kargs.tsp b/modules/kargs/kargs.tsp new file mode 100644 index 0000000..d8b8654 --- /dev/null +++ b/modules/kargs/kargs.tsp @@ -0,0 +1,21 @@ +import "@typespec/json-schema"; +using TypeSpec.JsonSchema; + +@jsonSchema("/modules/kargs-latest.json") +model KargsModuleLatest { + ...KargsModuleV1; +} + +@jsonSchema("/modules/kargs-v1.json") +model KargsModuleV1 { + /** The kargs module injects kernel arguments into the image. + * https://blue-build.org/reference/modules/kargs/ + */ + type: "kargs" | "kargs@v1" | "kargs@latest"; + + /** Defines on which OS architectures are kargs applied. Defaults to all architectures if omitted. */ + `arch`?: string; + + /** Kargs to inject in the image. */ + `kargs`: Array; +} diff --git a/modules/kargs/module.yml b/modules/kargs/module.yml new file mode 100644 index 0000000..218930a --- /dev/null +++ b/modules/kargs/module.yml @@ -0,0 +1,9 @@ +name: kargs +shortdesc: The kargs module injects kernel arguments into the image. +example: | + type: kargs + arch: x86_64, aarch64 # only inject kernel arguments to these specific OS architectures + kargs: + - console=ttyS0,114800n8 + - mitigations=on + - systemd.unified_cgroup_hierarchy=0