Host storage
Initialize and mount an explicit device for snapshots and ZeroFS caches.
- Choose a whole block device by a stable path. Check it with
lsblk -f. - Add
[host_storage]toconfig.toml:
[host_storage]
device = "/dev/disk/by-id/nvme-instance-store"
mount_point = "/data"
filesystem = "xfs"- Set
paths.snapshot_dirbeneath the mount point, such as/data/nibrunner-vm. With ZeroFS, also setvolumes.zerofs.cache_dirandvolumes.zerofs.checkpoint_cache_dirbeneath it, in separate directories. - Run
nibrunnerd startas root.
The device path above is a placeholder: supply the device on your host. nibrunner does not
discover instance stores or select disks by cloud provider. Omit [host_storage] to keep
managing mounts yourself.
What happens
| Device or mount | Result |
|---|---|
| No filesystem signatures | Format with the configured filesystem, then mount. |
Existing matching ext4 or xfs filesystem | Mount without formatting; preserve its contents. |
| Other signatures, partition tables, partitions, RAID, LVM, child devices or read-only devices | Refuse startup. |
| Device mounted elsewhere, wrong device at the mount point, nested mounts or a read-only mount | Refuse startup. |
| Unmounted, nonempty mount point or symlinked storage paths | Refuse startup without hiding or moving files. |
filesystem is required and accepts ext4 or xfs. An existing filesystem must match it.
Configuring [host_storage] authorizes initialization when no signatures are detected, including
discarding unrecognized raw contents. Use a dedicated device. Cryptographically erased disks can
contain nonzero bytes, so initialization does not require a zero-filled device.
--force never authorizes reformatting an existing filesystem.
New ext4 filesystems have the verity feature enabled so individual snapshot files can use
fs-verity.
Existing ext4 filesystems are preserved without changing their features.
Install util-linux, mount, and the filesystem's tools (e2fsprogs or xfsprogs); the release
installer includes them. The managed device and mount point must use normalized absolute paths
with letters, digits, /, _, ., : or -. The mount point cannot be /.
Boot and repeated starts
Installation mounts storage before writing any host directories. At boot, systemd prepares the device, mounts it, and creates directories before starting the daemon or ZeroFS. A replacement blank ephemeral device is initialized through the same checks. Neither service starts if the mount is unavailable, and both are stopped if systemd observes the mount going away. Starting the daemon directly also checks the mount before creating directories.
The mount point is traversable (0755). Snapshot and checkpoint-cache directories belong to
root (0700); the live cache belongs to the zerofs account (0700). Existing contents are not
recursively changed. Repeated starts reuse the mounted filesystem and restore directory ownership
and permissions.
Ephemeral storage
Keep the host database and configuration on persistent storage. A replacement device has no previous snapshots or caches. Durable tenant volumes require the ZeroFS backend and its object store.
Replace a custom initializer
- Disable the old disk-initialization unit and remove its dependency drop-ins. Leave the existing filesystem mounted.
- Configure the same device, mount point and filesystem in
[host_storage]. - Run
nibrunnerd start.
An existing matching mount is reused. If files were written beneath the mount point on the root filesystem, move them aside yourself while the device is unmounted; startup refuses to hide them.
To return to manual mounting, arrange the replacement boot dependencies, remove [host_storage],
and run nibrunnerd start. The generated storage units and dependencies are removed; the filesystem stays
mounted.