Your First Volume

From an empty prefix to a mounted filesystem takes four commands. This page walks through them once by hand, so that the systemd automation in Running Under systemd holds no surprises.

The volume lifecycle

A volume passes through a small number of states, and each flexblock command moves it from one to the next. A command that would skip a state is refused with an exit code that says which state is missing; see Exit Codes.

Command	What it does
`init`	Creates a new, empty volume in object storage. Touches no device unless given `--attach`.
`attach`	Sizes a cache on this host’s device from the volume superblock and claims ownership. Nothing is bulk-copied.
`start`	Runs preflight checks, recovers the cache if needed, brings up `/dev/ublkbN` and serves until interrupted. Also the crash-recovery command.
`detach`	Releases ownership and clears local state. The volume’s data stays in the bucket.
`wipe`	Deletes every object under the prefix and the local cache.

The everyday path is init, attach, start, then stop and start again as needed. detach and attach move a volume between hosts, and wipe destroys it.

Before you begin

This walk-through assumes:

The grant is installed at /etc/flexblock/grant.json; see Install.
Credentials are available, through a platform identity or exported and passed with sudo -E.
The cache partition is /dev/nvme1n1p1.
The volume will hold an XFS filesystem mounted at /mnt/analytics.

Create, serve, mount, stop

If your credentials are exported environment variables, use sudo -E instead of sudo throughout, so they reach flexBlock.

Create the volume and attach the cache

init writes the volume superblock to the prefix. With --attach it also sizes a cache on the local device and claims ownership in the same run. The cache starts empty and warms on demand.
Terminal window
```
sudo flexblock init --device-size 2T --attach /dev/nvme1n1p1
```
The device size may be smaller than the licensed size. It can be grown later, but never shrunk. Other volume settings, such as chunk size and compression, are also chosen here; see flexblock init.

The two halves can also run separately, even on different machines, since creating the volume touches no device:
Terminal window
```
sudo flexblock init --device-size 2T
sudo flexblock attach /dev/nvme1n1p1
```
init refuses a prefix that already holds objects, and attach refuses a cache device that holds unrelated data unless --overwrite is given. Add --dry-run to either command to see the plan without changing anything.
Start serving

start runs the preflight checks, recovers the cache if needed, rebuilds the object index, brings up the block device and serves until interrupted. Pin the device id so the path is stable, and turn on metrics if you have a Prometheus server.
Terminal window
```
sudo flexblock start /dev/nvme1n1p1 --ublk-dev-id 0 --metrics-port 10056
```
The banner prints the volume, cache, serving, flush and license sections, then serving - press Ctrl+C to stop, after which log lines follow. The device appears as /dev/ublkb0.

Without --ublk-dev-id, the daemon reuses the id it last served under since boot, or the kernel assigns the next free one, and the ublk device is live log line names it.
Format and mount

In another shell, format and mount the device as you would any other. The device advertises the chunk size as its optimal I/O size, so mkfs.xfs aligns to it without extra flags.
Terminal window
```
sudo mkfs.xfs /dev/ublkb0
sudo mkdir -p /mnt/analytics
sudo mount /dev/ublkb0 /mnt/analytics
```
Stop cleanly

Unmount first, then interrupt the daemon. It refuses the signal while the device is in use, gives any other process holding it open five seconds to close it, flushes every dirty chunk, finishes pending discard deletes, checkpoints, and marks the cache cleanly stopped.
Terminal window
```
sudo umount /mnt/analytics
sudo kill -INT "$(pidof flexblock)"
```
With more than one volume on the host, signal the PID that show reports instead of using pidof.