zosstorage Configuration Schema

This document defines the YAML configuration for the initramfs-only disk provisioning utility and the exact precedence rules between configuration sources. It complements docs/ARCHITECTURE.md.

Canonical paths and keys

Kernel cmdline key: zosstorage.config=
Default config file path: /etc/zosstorage/config.yaml
JSON state report path: /run/zosstorage/state.json
Optional log file path: /run/zosstorage/zosstorage.log
fstab generation: disabled by default
Reserved filesystem labels: ZOSBOOT (ESP), ZOSDATA (all data filesystems)
GPT partition names: zosboot, zosdata, zoscache

Precedence and merge strategy

Start from built-in defaults documented here.
Merge in the on-disk config file if present at /etc/zosstorage/config.yaml.
Merge CLI flags next; these override file values.
Merge kernel cmdline last; zosstorage.config= overrides CLI and file.
No interactive prompts are permitted.

The kernel cmdline key zosstorage.config= accepts:

A path to a YAML file inside the initramfs root (preferred).
A file: absolute path (e.g., file:/run/config/zos.yaml).
A data: URL containing base64 YAML (optional extension).

Top-level YAML structure

version: 1
logging:
  level: info                # one of: error, warn, info, debug
  to_file: false             # default false; when true, logs to /run/zosstorage/zosstorage.log
device_selection:
  include_patterns:          # default: ["^/dev/sd\\w+$", "^/dev/nvme\\w+n\\d+$", "^/dev/vd\\w+$"]
    - "^/dev/sd\\w+$"
    - "^/dev/nvme\\w+n\\d+$"
    - "^/dev/vd\\w+$"
  exclude_patterns:          # default excludes: ram, zram, loop, fd, dm-crypt mappings not matching include, etc.
    - "^/dev/ram\\d+$"
    - "^/dev/zram\\d+$"
    - "^/dev/loop\\d+$"
    - "^/dev/fd\\d+$"
  allow_removable: false     # future option; default false
  min_size_gib: 10           # ignore devices smaller than this (default 10)
topology:                    # desired overall layout; see values below
  mode: btrfs_single         # btrfs_single | bcachefs_single | dual_independent | bcachefs2_copy | ssd_hdd_bcachefs | btrfs_raid1
partitioning:
  alignment_mib: 1           # GPT alignment in MiB
  require_empty_disks: true  # abort if any partition or FS signatures exist
  bios_boot:
    enabled: true
    size_mib: 1
    gpt_name: zosboot       # name for the tiny BIOS boot partition (non-FS)
  esp:
    size_mib: 512
    label: ZOSBOOT
    gpt_name: zosboot
  data:
    gpt_name: zosdata
  cache:
    gpt_name: zoscache
filesystem:
  btrfs:
    label: ZOSDATA
    compression: zstd:3      # string passed to -O/compress option handling
    raid_profile: none       # none | raid1
  bcachefs:
    label: ZOSDATA
    cache_mode: promote      # promote | writeback (if supported during mkfs; default promote)
    compression: zstd
    checksum: crc32c
  vfat:
    label: ZOSBOOT
mount:
  base_dir: /var/cache
  scheme: per_uuid           # per_uuid | custom
  fstab:
    enabled: false
report:
  path: /run/zosstorage/state.json

Topology modes

btrfs_single: One eligible disk. Create BIOS boot (if enabled), ESP 512 MiB, remainder as data. Create a btrfs filesystem labeled ZOSDATA on the data partition.
bcachefs_single: One eligible disk. Create BIOS boot (if enabled), ESP 512 MiB, remainder as data. Create a bcachefs filesystem labeled ZOSDATA on the data partition.
dual_independent: One or more eligible disks. On each disk, create BIOS boot (if enabled) + ESP + data. Create an independent btrfs filesystem labeled ZOSDATA on each data partition. No RAID by default.
bcachefs2_copy: Two or more eligible disks (minimum 2). Create data partitions and then a single multi-device bcachefs labeled ZOSDATA spanning those data partitions. The mkfs step uses --replicas=2 (data and metadata).
ssd_hdd_bcachefs: One SSD/NVMe and one HDD. Create BIOS boot (if enabled) + ESP on both as required. Create cache (on SSD) and data/backing (on HDD) partitions named zoscache and zosdata respectively. Create a bcachefs labeled ZOSDATA across SSD(HDD) per policy (SSD cache/promote; HDD backing).
btrfs_raid1: Optional mode if explicitly requested. Create mirrored btrfs across two disks for the data role with raid1 profile. Not enabled by default.

Validation rules

Abort if no eligible disks are found after filtering.
Abort if any target disk is not empty when require_empty_disks: true. Emptiness is determined by absence of partitions and known FS signatures.
Never modify devices outside include_patterns or inside exclude_patterns.
Ensure unique GPT partition UUIDs. ESP labels on different disks may be identical (ZOSBOOT), but partition UUIDs must differ.
Filesystem labels must follow reserved semantics: ESP uses ZOSBOOT, all data filesystems use ZOSDATA.

Logging section

logging.level: error | warn | info | debug. Default info.
logging.to_file: when true, logs also go to /run/zosstorage/zosstorage.log. Default false.

Device selection section

include_patterns: array of regex patterns (Rust-style) matched against absolute device paths.
exclude_patterns: array of regex patterns that are removed after inclusion.
allow_removable: future toggle for including removable media. Default false.
min_size_gib: minimum size to consider a disk eligible; default 10 GiB.

Partitioning section

alignment_mib: default 1 (MiB boundaries).
require_empty_disks: true by default to guarantee safety.
bios_boot: enabled true, size_mib 1, gpt_name zosboot. Used for BIOS-bootable GPT where needed.
esp: size_mib 512, label ZOSBOOT, gpt_name zosboot.
data: gpt_name zosdata.
cache: gpt_name zoscache, only created in ssd_hdd_bcachefs mode.

Filesystem section

btrfs: label ZOSDATA; compression string such as zstd:3; raid_profile none|raid1 (only applied when topology permits).
bcachefs: label ZOSDATA; cache_mode promote|writeback; compression; checksum. Exact tuning defaults remain open items.
vfat: label ZOSBOOT used for ESP.

Mount section

Runtime root mounts (all data filesystems):
- Each data filesystem is root-mounted at /var/mounts/{UUID}
- btrfs root mount options: rw,noatime,subvolid=5
- bcachefs root mount options: rw,noatime
Subvolume mounts (from the primary data filesystem only) to final targets:
- Targets: /var/cache/system, /var/cache/etc, /var/cache/modules, /var/cache/vm-meta
- btrfs subvol options: -o rw,noatime,subvol={name}
- bcachefs subdir options: -o rw,noatime,X-mount.subdir={name}
fstab.enabled: default false. When true, zosstorage writes only the four subvolume mount entries, in deterministic target order, using UUID= sources for the filesystem; root mounts under /var/mounts are excluded.

Report section

path: default /run/zosstorage/state.json.
The report content schema is defined separately in docs/ARCHITECTURE.md and the reporting module.

Configuration examples

Minimal single-disk btrfs

version: 1
topology:
  mode: btrfs_single

Dual independent btrfs (two disks)

version: 1
topology:
  mode: dual_independent
filesystem:
  btrfs:
    compression: zstd:5

SSD + HDD with bcachefs

version: 1
topology:
  mode: ssd_hdd_bcachefs
partitioning:
  cache:
    gpt_name: zoscache
filesystem:
  bcachefs:
    cache_mode: promote
    compression: zstd
    checksum: crc32c

CLI flags (to mirror kernel cmdline)

--config PATH: path to YAML config (mirrors zosstorage.config=)
--log-level LEVEL: error|warn|info|debug
--log-to-file: enables logging to /run/zosstorage/zosstorage.log
--fstab: enable writing fstab entries
--force: present but non-functional; returns unimplemented

Kernel cmdline examples

zosstorage.config=/etc/zosstorage/config.yaml
zosstorage.config=file:/run/zos.yaml
zosstorage.config=data:application/x-yaml;base64,PHZlcnNpb246IDEK...

Notes on idempotency

If expected GPT names (zosboot, zosdata, zoscache where applicable) and filesystem labels (ZOSBOOT, ZOSDATA) are found consistent with the chosen topology, zosstorage exits successfully without changes.

Future extensions

Removable media allowlist policies
btrfs RAID profiles beyond raid1
bcachefs extended tuning options
Custom mount mapping schemes
Multiple topology groups on multi-disk systems

Reference modules

Change log

v1: Initial draft of schema and precedence rules

End of document

8.6 KiB Raw Blame History

zosstorage Configuration Schema

8.6 KiB

Raw Blame History