feat: kargs module (#388)

* feat: `kargs` module

* fix: ARCH conditions

* docs: Explain arch in module.yml

* docs: Refine kargs documentation

Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com>

* chore: Add `kargs` to `modules.json`

* docs: Add info about discovering possible kargs

* docs: Use master branch link for kargs

* docs: Some grammar style fix

* docs: Add note about `bootc switch` for kargs to get applied

* chore: slight grammar change

* chore: small grammar change

---------

Co-authored-by: xyny <60004820+xynydev@users.noreply.github.com>

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",

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.

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

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<string>;
+}

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