zosstorage/docs/SCHEMA.md

# zosstorage Configuration (Deprecated schema)

This schema document is deprecated per [docs/adr/0002-defaults-only-no-external-config.md](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

```yaml
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 | bcachefs-2copy | 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.
- bcachefs-2copy: 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](docs/ARCHITECTURE.md) and the reporting module.

Configuration examples

Minimal single-disk btrfs
```yaml
version: 1
topology:
  mode: btrfs_single
```

Dual independent btrfs (two disks)
```yaml
version: 1
topology:
  mode: dual_independent
filesystem:
  btrfs:
    compression: zstd:5
```

SSD + HDD with bcachefs
```yaml
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/types.rs)
- [src/config/loader.rs](../src/config/loader.rs)
- [src/cli/args.rs](../src/cli/args.rs)
- [src/orchestrator/run.rs](../src/orchestrator/run.rs)
- [src/partition/plan.rs](../src/partition/plan.rs)
- [src/fs/plan.rs](../src/fs/plan.rs)
- [src/mount/ops.rs](../src/mount/ops.rs)
- [src/report/state.rs](../src/report/state.rs)
- [src/idempotency/mod.rs](../src/idempotency/mod.rs)

Change log
- v1: Initial draft of schema and precedence rules

End of document