zosstorage/docs/SCHEMA.md

zosstorage Configuration (Deprecated schema)

This schema document is deprecated per docs/adr/0002-defaults-only-no-external-config.md. Runtime now uses defaults-only with a single optional kernel cmdline override. The YAML configuration file is not read at boot.

Active behavior (ADR-0002)

• Defaults-only: all settings are defined in code. No /etc/zosstorage/config.yaml is read.
• Optional kernel cmdline override: zosstorage.topology=VALUE can override only the topology. Legacy alias zosstorage.topo= is accepted.
• CLI: --config and --topology are deprecated and ignored (warnings emitted). Operational flags remain (--apply, --show, --report, --fstab, logging).
• Report path: /run/zosstorage/state.json. Optional log file: /run/zosstorage/zosstorage.log.
• Reserved labels: ZOSBOOT (ESP), ZOSDATA (data). GPT names: zosboot, zosdata, zoscache.

Historical reference (original YAML-based schema, no longer used at runtime) The remainder of this document preserves the previous YAML schema for archival purposes only.

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

• src/types.rs
• src/config/loader.rs
• src/cli/args.rs
• src/orchestrator/run.rs
• src/partition/plan.rs
• src/fs/plan.rs
• src/mount/ops.rs
• src/report/state.rs
• src/idempotency/mod.rs

Change log

• v1: Initial draft of schema and precedence rules

End of document