composefs: Support transient /etc, transient root, and volatile /var

Add TOML configuration (setup-root-conf.toml) for composefs mount
behaviour:

- [root] transient = true: wrap the composefs in a tmpfs overlay; all
  writes are discarded on reboot.
- [etc] mount = transient|overlay|bind|none: control how /etc is mounted
  from the deployment state directory.
- [var] mount = none|bind: control whether /var is bind-mounted from
  state. When mount = none, /var is left as an empty composefs directory.

bootc-root-setup also detects the systemd.volatile=state kernel argument
at boot time and automatically skips the /var state bind-mount when it is
set, leaving /var empty for systemd-fstab-generator to mount a fresh tmpfs
there at local-fs.target. This is the recommended way to get an ephemeral
/var: it uses a plain tmpfs rather than overlayfs, which is compatible with
tools like podman that use overlayfs under /var/lib/containers.

Add inject-baseconfig CI helper, a test-baseconfigs CI job, and a
040-test-baseconfigs.nu integration test that boots each configuration in a
VM and validates filesystem types, writability, SELinux labels, and podman
graph driver compatibility.

Assisted-by: OpenCode (claude-sonnet-4-6@default)
Signed-off-by: Colin Walters <walters@verbum.org>

Author: cgwalters

.github/workflows/ci.yml

@@ -220,10 +220,8 @@ jobs:
         bootloader: ["grub", "systemd"]
         boot_type: ["bls", "uki"]
         seal_state: ["sealed", "unsealed"]
-
         exclude:
-          # centos-9 fails with EUCLEAN (https://github.com/bootc-dev/bootc/issues/1812)
-          # See: https://github.com/bootc-dev/bcvk/pull/204
+          # https://github.com/bootc-dev/bootc/issues/1812
           - test_os: centos-9
             variant: composefs
           - seal_state: "sealed"
@@ -385,6 +383,79 @@ jobs:
           name: "tmt-log-${{ matrix.test_os }}-${{ matrix.variant }}-upgrade-${{ env.ARCH }}"
           path: /var/tmp/tmt
 
+  # Test readonly behaviour with baseconfigs (transient mounts) baked into the image.
+  # Composefs-only: setup-root-conf.toml is a composefs concept; ostree uses a
+  # different config format (prepare-root.conf) and is not covered here.
+  # Runs once per distro × baseconfig — no bootloader/filesystem/boot_type matrix.
+  test-baseconfigs:
+    if: needs.compute-ci-level.outputs.run_heavy == 'true'
+    needs: [compute-ci-level, package]
+    strategy:
+      fail-fast: false
+      matrix:
+        test_os: ${{ fromJson(needs.compute-ci-level.outputs.integration_os_matrix) }}
+        baseconfigs: ["etc-transient", "root-transient", "var-volatile"]
+        exclude:
+          # centos-9 ships an older dracut that lacks the auto-install of setup-root-conf.toml
+          - test_os: centos-9
+
+    runs-on: ubuntu-24.04
+
+    steps:
+      - uses: actions/checkout@v6
+      - name: Bootc Ubuntu Setup
+        uses: bootc-dev/actions/bootc-ubuntu-setup@main
+        with:
+          libvirt: true
+      - name: Install tmt
+        run: pip install --user "tmt[provision-virtual]"
+
+      - name: Setup env
+        run: |
+          BASE=$(just pullspec-for-os base ${{ matrix.test_os }})
+          echo "BOOTC_base=${BASE}" >> $GITHUB_ENV
+          echo "BOOTC_variant=composefs" >> $GITHUB_ENV
+          echo "BOOTC_baseconfigs=${{ matrix.baseconfigs }}" >> $GITHUB_ENV
+          echo "RUST_BACKTRACE=full" >> $GITHUB_ENV
+
+      - name: Download package artifacts
+        uses: actions/download-artifact@v8
+        with:
+          name: packages-${{ matrix.test_os }}
+          path: target/packages/
+
+      - name: Build container with baseconfig
+        run: BOOTC_SKIP_PACKAGE=1 just build
+
+      - name: Build upgrade image
+        run: just _build-upgrade-image
+
+      - name: Run TMT readonly tests
+        run: |
+          cargo xtask run-tmt \
+            --env=BOOTC_variant=composefs \
+            --env=BOOTC_baseconfigs=${{ matrix.baseconfigs }} \
+            --composefs-backend --bootloader=grub --filesystem=ext4 \
+            --seal-state=unsealed --boot-type=bls \
+            --upgrade-image=localhost/bootc-upgrade \
+            localhost/bootc readonly
+          just clean-local-images
+
+      - name: Disk usage summary
+        if: always()
+        run: |
+          echo "### Disk usage" >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+          df -h >> "$GITHUB_STEP_SUMMARY"
+          echo '```' >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Archive TMT logs
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: "tmt-log-${{ matrix.test_os }}-composefs-baseconfigs-${{ matrix.baseconfigs }}-${{ env.ARCH }}"
+          path: /var/tmp/tmt
+
   # Test bootc install on Fedora CoreOS (separate job to avoid disk space issues
   # when run in the same job as test-integration).
   # Uses fedora-43 as it's the current stable Fedora release matching CoreOS.
@@ -471,7 +542,7 @@ jobs:
   # Accepts 'skipped' as success so that merge_group-only jobs don't block PRs.
   required-checks:
     if: always()
-    needs: [compute-ci-level, cargo-deny, validate, install-tests, docs, package, test-integration, test-upgrade, test-container-export]
+    needs: [compute-ci-level, cargo-deny, validate, install-tests, docs, package, test-integration, test-upgrade, test-baseconfigs, test-container-export]
     runs-on: ubuntu-latest
     steps:
       - name: Check all jobs

Dockerfile

@@ -222,6 +222,7 @@ FROM base as base-penultimate
 ARG variant
 ARG bootloader
 ARG boot_type
+ARG baseconfigs=""
 
 # Switch to a signed systemd-boot, if configured
 RUN --network=none --mount=type=tmpfs,target=/run --mount=type=tmpfs,target=/tmp \
@@ -251,6 +252,10 @@ ARG rootfs=""
 RUN --network=none --mount=type=tmpfs,target=/run --mount=type=tmpfs,target=/tmp \
     --mount=type=bind,from=packaging,src=/,target=/run/packaging \
     /run/packaging/configure-rootfs "${variant}" "${rootfs}"
+# Inject base configuration (e.g. transient-etc, transient-root) before dracut runs
+RUN --network=none --mount=type=tmpfs,target=/run --mount=type=tmpfs,target=/tmp \
+    --mount=type=bind,from=packaging,src=/,target=/run/packaging \
+    /run/packaging/inject-baseconfig "${variant}" "${baseconfigs}"
 # Override with our built package
 RUN --network=none --mount=type=tmpfs,target=/run --mount=type=tmpfs,target=/tmp \
     --mount=type=bind,from=packaging,src=/,target=/run/packaging \

Justfile

@@ -43,6 +43,8 @@ filesystem := env("BOOTC_filesystem", "ext4")
 boot_type := env("BOOTC_boot_type", "bls")
 # Only used for composefs tests
 seal_state := env("BOOTC_seal_state", "unsealed")
+# Baseconfigs to inject into the image for testing (e.g. "etc-transient" or "root-transient")
+baseconfigs := env("BOOTC_baseconfigs", "")
 # Base container image to build from
 base := env("BOOTC_base", "quay.io/centos-bootc/centos-bootc:stream10")
 # Buildroot base image
@@ -56,18 +58,21 @@ no_auto_local_deps := env("BOOTC_no_auto_local_deps", "")
 # Internal variables
 nocache := env("BOOTC_nocache", "")
 _nocache_arg := if nocache != "" { "--no-cache" } else { "" }
+_baseconfigs_env := if baseconfigs != "" { "--env=BOOTC_baseconfigs=" + baseconfigs } else { "" }
 testimage_label := "bootc.testimage=1"
 lbi_images := "quay.io/curl/curl:latest quay.io/curl/curl-base:latest registry.access.redhat.com/ubi9/podman:latest"
 fedora-coreos := "quay.io/fedora/fedora-coreos:testing-devel"
 generic_buildargs := ""
 _extra_src_args := if extra_src != "" { "-v " + extra_src + ":/run/extra-src:ro --security-opt=label=disable" } else { "" }
+# filesystem arg: required for bootc container ukify to allow missing fsverity
 base_buildargs := generic_buildargs + " " + _extra_src_args \
                   + " --build-arg=base=" + base \
                   + " --build-arg=variant=" + variant \
                   + " --build-arg=bootloader=" + bootloader \
                   + " --build-arg=boot_type=" + boot_type \
                   + " --build-arg=seal_state=" + seal_state \
-                  + " --build-arg=filesystem=" + filesystem # required for bootc container ukify to allow missing fsverity
+                  + " --build-arg=filesystem=" + filesystem \
+                  + " --build-arg=baseconfigs=" + baseconfigs
 buildargs := base_buildargs \
              + " --cap-add=all --security-opt=label=type:container_runtime_t --device /dev/fuse" \
              + " --secret=id=secureboot_key,src=target/test-secureboot/db.key --secret=id=secureboot_cert,src=target/test-secureboot/db.crt"
@@ -266,7 +271,31 @@ test-container-export: build
 # Run tmt tests without rebuilding (for fast iteration)
 [group('testing')]
 test-tmt-nobuild *ARGS:
-    cargo xtask run-tmt --env=BOOTC_variant={{variant}} --upgrade-image={{upgrade_img}} {{base_img}} {{ARGS}}
+    cargo xtask run-tmt --env=BOOTC_variant={{variant}} {{_baseconfigs_env}} --upgrade-image={{upgrade_img}} {{base_img}} {{ARGS}}
+
+# Run readonly tests with a baseconfig baked into the image at build time.
+# Requires composefs variant. Example: just variant=composefs test-tmt-baseconfig root-transient
+[group('testing')]
+test-tmt-baseconfig baseconfig *ARGS:
+    just variant=composefs baseconfigs={{baseconfig}} build
+    just variant=composefs baseconfigs={{baseconfig}} _build-upgrade-image
+    cargo xtask run-tmt \
+        --env=BOOTC_variant=composefs \
+        --env=BOOTC_baseconfigs={{baseconfig}} \
+        --upgrade-image={{upgrade_img}} \
+        --composefs-backend \
+        --bootloader={{bootloader}} \
+        --filesystem={{filesystem}} \
+        --boot-type={{boot_type}} \
+        --seal-state={{seal_state}} \
+        {{base_img}} readonly {{ARGS}}
+
+# Run readonly tests for all standard baseconfigs
+[group('testing')]
+test-baseconfigs *ARGS:
+    just test-tmt-baseconfig etc-transient {{ARGS}}
+    just test-tmt-baseconfig root-transient {{ARGS}}
+    just test-tmt-baseconfig var-volatile {{ARGS}}
 
 # Run tmt tests on Fedora CoreOS
 [group('testing')]

contrib/packaging/inject-baseconfig

@@ -0,0 +1,61 @@
+#!/bin/bash
+# Inject base configuration files for CI testing of transient-root/etc/var configurations.
+# Arguments: $1=variant, $2=baseconfigs (comma-separated, may be empty)
+set -xeuo pipefail
+
+VARIANT="${1:-}"
+BASECONFIGS="${2:-}"
+
+# No-op if no baseconfigs specified
+if [ -z "${BASECONFIGS}" ]; then
+  exit 0
+fi
+
+# setup-root-conf.toml is composefs-specific; ostree uses prepare-root.conf
+# which has a different (INI) format and different option names.
+case "${VARIANT}" in
+  composefs*)
+    TARGET="/usr/lib/composefs/setup-root-conf.toml"
+    ;;
+  *)
+    echo "inject-baseconfig: baseconfigs not supported for variant '${VARIANT}'" >&2
+    exit 1
+    ;;
+esac
+
+mkdir -p "$(dirname "${TARGET}")"
+
+# Split on commas and process each token
+IFS=',' read -ra TOKENS <<< "${BASECONFIGS}"
+for raw_token in "${TOKENS[@]}"; do
+  # Trim leading/trailing spaces
+  token="${raw_token#"${raw_token%%[![:space:]]*}"}"
+  token="${token%"${token##*[![:space:]]}"}"
+
+  [ -z "${token}" ] && continue
+
+  case "${token}" in
+    etc-transient)
+      printf '[etc]\ntransient = true\n' >> "${TARGET}"
+      ;;
+    root-transient)
+      printf '[root]\ntransient = true\n' >> "${TARGET}"
+      ;;
+    var-volatile)
+      # Mount /var as a fresh tmpfs on every boot via systemd.volatile=state.
+      # bootc-root-setup detects this karg in the initramfs and automatically
+      # skips the /var state bind-mount, leaving /var as an empty directory
+      # from the composefs image.  systemd-fstab-generator then mounts a fresh
+      # tmpfs there at local-fs.target.  Using a plain tmpfs avoids the
+      # overlayfs-on-overlayfs restriction that breaks tools like podman which
+      # use overlayfs under /var/lib/containers.
+      mkdir -p /usr/lib/bootc/kargs.d
+      printf 'kargs = ["systemd.volatile=state"]\n' \
+        > /usr/lib/bootc/kargs.d/50-var-volatile.toml
+      ;;
+    *)
+      echo "Unknown baseconfig: ${token}" >&2
+      exit 1
+      ;;
+  esac
+done

crates/initramfs/src/lib.rs

@@ -116,6 +116,8 @@ struct Config {
     #[serde(default)]
     etc: MountConfig,
     #[serde(default)]
+    var: MountConfig,
+    #[serde(default)]
     root: RootConfig,
 }
 
@@ -437,6 +439,30 @@ pub fn setup_root(args: Args) -> Result<()> {
         .cmdline
         .unwrap_or(Cmdline::from_proc().context("Failed to read cmdline")?);
 
+    // Auto-detect systemd.volatile=state: if the kernel cmdline requests a
+    // volatile /var via the systemd fstab-generator, skip our initramfs
+    // bind-mount of /var from the deployment state directory.  This leaves
+    // /var as an empty directory from the composefs image so that
+    // systemd-fstab-generator can mount a fresh tmpfs there at local-fs.target.
+    // An explicit `[var] mount = "none"` in setup-root-conf.toml has the same
+    // effect; the cmdline check is a convenience so users only need the kargs.d
+    // entry without also editing setup-root-conf.toml.
+    let config = {
+        let mut config = config;
+        // value_of returns None for a missing key, Some("") for a bare flag,
+        // or Some("state") / Some("overlay") / Some("yes") for key=value form.
+        let volatile_val = cmdline.value_of("systemd.volatile");
+        let var_volatile = matches!(volatile_val, Some("state") | Some("overlay"));
+        if var_volatile && config.var.mount.is_none() && !config.var.transient {
+            tracing::debug!(
+                "systemd.volatile={} detected; skipping /var state bind-mount",
+                volatile_val.unwrap_or("")
+            );
+            config.var.mount = Some(MountType::None);
+        }
+        config
+    };
+
     let (image, insecure) = get_cmdline_composefs::<Sha512HashValue>(&cmdline)?;
 
     let new_root = match &args.root_fs {
@@ -509,7 +535,12 @@ pub fn setup_root(args: Args) -> Result<()> {
     // etc + var
     let state = open_dir(open_dir(&sysroot, "state/deploy")?, image.to_hex())?;
     mount_subdir(visible_root, &state, "etc", config.etc, MountType::Bind)?;
-    mount_subdir(visible_root, &state, "var", MountConfig::default(), MountType::Bind)?;
+    // /var is bind-mounted from the deployment state directory by default.
+    // The systemd.volatile=state cmdline detection above (or an explicit
+    // [var] mount = "none" in setup-root-conf.toml) can change this to
+    // MountType::None, which skips the bind-mount entirely and leaves /var
+    // as an empty directory from the composefs image for systemd to fill.
+    mount_subdir(visible_root, &state, "var", config.var, MountType::Bind)?;
 
     if cfg!(not(feature = "pre-6.15")) {
         // Replace the /sysroot with the new composed root filesystem.
@@ -540,6 +571,10 @@ mod tests {
                     mount: None,
                     transient: false
                 },
+                var: MountConfig {
+                    mount: None,
+                    transient: false
+                },
                 root: RootConfig { transient: false },
             }
         );
@@ -564,6 +599,14 @@ mod tests {
         assert_eq!(config.etc.mount, None);
     }
 
+    #[test]
+    fn test_var_none() {
+        // mount = "none" skips the state bind-mount; combine with
+        // systemd.volatile=state karg to get a fresh tmpfs on every boot.
+        let config = parse("[var]\nmount = \"none\"");
+        assert_eq!(config.var.mount, Some(MountType::None));
+    }
+
     #[test]
     fn test_root_transient() {
         let config = parse("[root]\ntransient = true");

docs/src/SUMMARY.md

@@ -62,6 +62,7 @@
 - [composefs backend](experimental-composefs.md)
 - [unified storage](experimental-unified-storage.md)
 - [`man bootc-root-setup.service`](man/bootc-root-setup.service.5.md)
+- [`man bootc-setup-root-conf.toml`](man/bootc-setup-root-conf.5.md)
 - [fsck](experimental-fsck.md)
 - [install reset](experimental-install-reset.md)
 - [--progress-fd](experimental-progress-fd.md)