Document how to modify kargs via rpm-ostree

Closes: coreos#88

modules/ROOT/nav.adoc

@@ -27,6 +27,7 @@
 *** xref:hostname.adoc[Setting a Hostname]
 *** xref:customize-nic.adoc[How to Customize a NIC Name]
 *** xref:sysconfig-configure-swaponzram.adoc[Configuring SwapOnZRAM]
+*** xref:kernel-args.adoc[Modifying Kernel Arguments]
 ** OS updates
 *** xref:update-streams.adoc[Update Streams]
 *** xref:auto-updates.adoc[Auto-Updates]

modules/ROOT/pages/kernel-args.adoc

@@ -0,0 +1,72 @@
+= Modifying Kernel Arguments
+
+Currently to change kernel arguments, you must script a systemd service which runs `rpm-ostree kargs --reboot`. The command supports appending kernel arguments (via `--append KEY[=VAL]`), deleting them (via `--delete KEY[=VAL]`), and replacing them (via `--replace KEY[=VALUE]`).
+
+NOTE: In the future, we will have a more Ignition-friendly method of doing this with stronger guarantees. See https://github.com/coreos/ignition/issues/1051 for more information.
+
+Here's an example which drops the default `systemd.unified_cgroup_hierarchy=0` kernel argument so that the machine uses cgroups v2:
+
+.Removing systemd.unified_cgroup_hierarchy=0 to switch to cgroups v2
+[source,yaml]
+----
+variant: fcos
+version: 1.1.0
+passwd:
+  users:
+    - name: core
+      ssh_authorized_keys:
+        - $pubkey
+systemd:
+  units:
+    - name: cgroups-v2-karg.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Switch To cgroups v2
+        After=systemd-machine-id-commit.service
+        ConditionKernelCommandLine=systemd.unified_cgroup_hierarchy
+
+        [Service]
+        Type=oneshot
+        RemainAfterExit=yes
+        ExecStart=/bin/rpm-ostree kargs --reboot --delete=systemd.unified_cgroup_hierarchy
+
+        [Install]
+        WantedBy=multi-user.target
+----
+
+NOTE: Make sure to use `After=systemd-machine-id-commit.service`. Otherwise there is a chance that systemd services with `ConditionFirstBoot=true` will rerun on the next boot.
+
+The systemd service above will execute on every boot. This means that e.g. manually re-adding the kernel argument later on will cause the service to kick in again on reboot. If this is a concern, you can additionally use a stamp file:
+
+.Removing systemd.unified_cgroup_hierarchy=0 to switch to cgroups v2 with a stamp file
+[source,yaml]
+----
+variant: fcos
+version: 1.1.0
+passwd:
+  users:
+    - name: core
+      ssh_authorized_keys:
+        - $pubkey
+systemd:
+  units:
+    - name: cgroups-v2-karg.service
+      enabled: true
+      contents: |
+        [Unit]
+        Description=Switch To cgroups v2
+        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
+----