zosstorage/README.md

# zosstorage

One-shot disk provisioning utility intended for initramfs. It discovers eligible disks, plans a GPT layout based on a chosen topology, creates filesystems, mounts them under a predictable scheme, and emits a machine-readable report. Safe-by-default with a non-destructive preview mode.

Status: first-draft preview capable. Partition apply, mkfs, and mounts are gated until the planning is validated in your environment.

Key modules
- CLI and entrypoint:
  - [src/cli/args.rs](src/cli/args.rs)
  - [src/main.rs](src/main.rs)
- Orchestration and preview JSON:
  - [src/orchestrator/run.rs](src/orchestrator/run.rs)
- Configuration loader, overlays, defaults:
  - [src/config/loader.rs](src/config/loader.rs)
- Device discovery (sysfs + regex filters, removable policy):
  - [src/device/discovery.rs](src/device/discovery.rs)
- Idempotency detection and emptiness checks:
  - [src/idempotency/mod.rs](src/idempotency/mod.rs)
- Partition planning (topology-aware):
  - [src/partition/plan.rs](src/partition/plan.rs)
- Filesystem planning/creation and mkfs integration:
  - [src/fs/plan.rs](src/fs/plan.rs)
- Mount planning and application (skeleton):
  - [src/mount/ops.rs](src/mount/ops.rs)

Features at a glance
- Topology-driven planning with built-in defaults: Single, DualIndependent, BtrfsRaid1, SsdHddBcachefs
- Non-destructive preview: --show/--report outputs JSON summary (disks, partition plan, filesystems, planned mountpoints)
- Safe discovery: excludes removable media by default (USB sticks) unless explicitly allowed
- Config-optional: the tool runs without any YAML; sensible defaults are always present and may be overridden/merged by config

Requirements
- Linux with /proc and /sys mounted (initramfs friendly)
- External tools discovered at runtime:
  - blkid (for probing UUIDs and signatures)
  - sgdisk (for GPT application) — planned
  - mkfs.vfat, mkfs.btrfs, bcachefs (for formatting) — invoked by fs/plan when enabled in execution phase
- Tracing/logging to stderr by default; optional file at /run/zosstorage/zosstorage.log

Install and build
- System Rust toolchain:
  cargo build --release

Binary is target/release/zosstorage.

CLI usage
- Topology selection (config optional):
  -t, --topology single|dual-independent|btrfs-raid1|ssd-hdd-bcachefs
- Preview (non-destructive):
  --show                      Print JSON summary to stdout
  --report PATH               Write JSON summary to a file
- Discovery policy:
  --allow-removable           Include removable devices (USB) during discovery
- Tracing/logging:
  -l, --log-level LEVEL       error|warn|info|debug (default: info)
  -L, --log-to-file           Also write logs to /run/zosstorage/zosstorage.log
- Other:
  -c, --config PATH           Merge a YAML config file (overrides defaults)
  -s, --fstab                 Enable writing /etc/fstab entries (when mounts are applied)
  -f, --force                 Present but not implemented (returns an error)

Examples
- Single disk plan with debug logs:
  sudo ./zosstorage --show -t single -l debug
- RAID1 btrfs across two disks; print and write summary:
  sudo ./zosstorage --show --report /run/zosstorage/plan.json -t btrfs-raid1 -l debug -L
- SSD+HDD bcachefs plan, include removable devices (for lab cases):
  sudo ./zosstorage --show -t ssd-hdd-bcachefs --allow-removable -l debug
- Quiet plan to file:
  sudo ./zosstorage --report /run/zosstorage/plan.json -t dual-independent

Preview JSON shape (examples)
1) Already provisioned (idempotency success):
{
  "version": "v1",
  "timestamp": "2025-09-26T12:34:56Z",
  "status": "already_provisioned",
  "state": { ... full StateReport JSON ... }
}

2) Planned (not yet provisioned):
{
  "version": "v1",
  "timestamp": "2025-09-26T12:34:56Z",
  "status": "planned",
  "topology": "btrfs_raid1",
  "alignment_mib": 1,
  "require_empty_disks": true,
  "disks": [
    { "path": "/dev/nvme0n1", "size_bytes": 1000204886016, "rotational": false, "model": "...", "serial": "..." },
    { "path": "/dev/nvme1n1", "size_bytes": 1000204886016, "rotational": false, "model": "...", "serial": "..." }
  ],
  "partition_plan": [
    {
      "disk": "/dev/nvme0n1",
      "parts": [
        { "role": "bios_boot", "size_mib": 1, "gpt_name": "zosboot" },
        { "role": "esp", "size_mib": 512, "gpt_name": "zosboot" },
        { "role": "data", "size_mib": null, "gpt_name": "zosdata" }
      ]
    },
    {
      "disk": "/dev/nvme1n1",
      "parts": [
        { "role": "data", "size_mib": null, "gpt_name": "zosdata" }
      ]
    }
  ],
  "filesystems_planned": [
    { "kind": "vfat", "from_roles": ["esp"], "label": "ZOSBOOT", "planned_mountpoint": null },
    { "kind": "btrfs", "from_roles": ["data"], "devices_planned": 2, "label": "ZOSDATA", "planned_mountpoint_template": "/var/cache/{UUID}" }
  ],
  "mount": {
    "scheme": "per_uuid",
    "base_dir": "/var/cache",
    "fstab_enabled": false,
    "target_template": "/var/cache/{UUID}"
  }
}

Defaults and policies
- Device selection defaults (see [src/config/loader.rs](src/config/loader.rs)):
  include_patterns: ^/dev/sd\w+$, ^/dev/nvme\w+n\d+$, ^/dev/vd\w+$
  exclude_patterns: ^/dev/ram\d+$, ^/dev/zram\d+$, ^/dev/loop\d+$, ^/dev/fd\d+$
  allow_removable: false (USB excluded unless --allow-removable)
  min_size_gib: 10
- Partitioning defaults:
  alignment_mib: 1
  bios_boot: enabled (1 MiB), gpt_name: zosboot
  esp: 512 MiB, label: ZOSBOOT, gpt_name: zosboot
  data: gpt_name: zosdata
  cache: gpt_name: zoscache (only used in SSD+HDD topology)
- Filesystem defaults:
  vfat (ESP) label: ZOSBOOT
  btrfs (data) label: ZOSDATA
  bcachefs (data/cache) label: ZOSDATA
- Mount scheme:
  per-UUID under /var/cache/{UUID}
  /etc/fstab generation is disabled by default

Tracing and logs
- stderr logging level controlled by -l/--log-level (info by default)
- optional file logging with -L/--log-to-file at /run/zosstorage/zosstorage.log
- Debug spans provide insight into discovery, idempotency, planning, and tool invocations

Extending and execution plan
- Near-term:
  - Implement sgdisk partition apply and udev settle
  - Pass btrfs raid profile flags -m/-d from config (raid1, none) to mkfs
  - Create per-UUID mount targets; persist fstab when enabled
  - Atomic report write via tempfile+rename
- Longer-term:
  - Dry-run mode with richer diffs
  - Richer schema for disks/partitions/filesystems in the report
  - Additional filesystem and tuning support

Safety model
- Preview mode never mutates block devices
- Emptiness checks guard destructive actions (skipped only in preview)
- Reserved labels and GPT names validated to reduce risk

Troubleshooting
- No eligible disks found: adjust include/exclude patterns or use --allow-removable for test media
- Removable media excluded: either add --allow-removable or exclude it explicitly via config patterns
- blkid missing: install util-linux; preview can still plan but cannot capture UUIDs for mkfs outputs
- bcachefs command missing: install bcachefs-tools or skip the SSD+HDD topology

License
- TBD (add your preferred license)