# 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](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
1. Start from built-in defaults documented here.
2. Merge in the on-disk config file if present at /etc/zosstorage/config.yaml.
3. Merge CLI flags next; these override file values.
4. Merge kernel cmdline last; zosstorage.config= overrides CLI and file.
5. 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

```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: single               # single | dual_independent | ssd_hdd_bcachefs | btrfs_raid1 (optional)
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: Two 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 eligible disks. Create data partitions on both, then create a single multi-device bcachefs labeled ZOSDATA spanning the data partitions (two-copies semantics to be tuned via mkfs options in a follow-up).
- 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
- base_dir: default /var/cache.
- scheme:
  - per_uuid: mount data filesystems at /var/cache/<FS-UUID>
  - custom: reserved for future mapping-by-config, not yet implemented.
- fstab.enabled: default false. When true, zosstorage will generate fstab entries in deterministic order.

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: 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