Volumes¶

Sistemo provides persistent block storage through volumes. Every machine gets a root volume automatically, and you can create additional data volumes that persist independently of machines.

All volumes are tracked in SQLite and stored as sparse ext4 files on the host.

Root volumes¶

When you deploy a machine, sistemo automatically creates a root volume named {machine-name}-root. This volume holds the operating system and is sized by the --storage flag (default 2 GB).

sistemo machine deploy debian --name webserver --storage 10G
# or: sistemo vm deploy debian --name webserver --storage 10G
# Creates root volume "webserver-root" (10 GB)

Root volumes are managed automatically — you don't need to create, attach, or format them.

Creating data volumes¶

Create a named volume for persistent data that should outlive any single machine:

sistemo volume create 5G --name pgdata

Size accepts human-readable units: 512M, 1G, 5G, 10GB. The volume is created as a sparse ext4 file, so it only uses disk space as data is written.

Tip

Name your volumes after what they store (pgdata, uploads, redis-data) rather than after the machine that uses them. Volumes outlive machines.

Listing volumes¶

sistemo volume list

Example output:

ID                                     NAME          SIZE    STATUS      ATTACHED TO
a1b2c3d4-5678-9abc-def0-123456789abc   pgdata        5 GB    attached    webserver
b2c3d4e5-6789-abcd-ef01-23456789abcd   redis-data    1 GB    available   —
c3d4e5f6-789a-bcde-f012-3456789abcde   webserver-root 10 GB  attached    webserver

attached — the volume is connected to a running or stopped machine
available — the volume is free and can be attached to any machine

Attaching to a stopped machine¶

Attach an existing volume to a stopped machine:

sistemo machine volume attach myvm pgdata

Warning

The machine must be stopped before attaching or detaching volumes. Stop it first with sistemo machine stop myvm.

Detaching from a stopped machine¶

Remove a volume from a machine without deleting it:

sistemo machine volume detach myvm pgdata

The volume keeps all its data and can be attached to another machine.

Booting from an existing volume¶

If you already have a volume with an OS (e.g. from a previous machine with --preserve-storage), you can boot directly from it:

sistemo machine deploy --volume web-root --name web2

This skips the image entirely and uses the volume as the root disk.

Attaching at deploy time¶

The simplest way to use a data volume is to attach it when deploying a machine:

sistemo volume create 5G --name pgdata
sistemo machine deploy debian --attach pgdata

The volume appears as an extra block device inside the machine (e.g. /dev/vdb). Format and mount it on first use:

# Inside the machine (first time only — skip mkfs if already formatted)
mkfs.ext4 /dev/vdb
mkdir -p /mnt/data
mount /dev/vdb /mnt/data

Note

Only run mkfs.ext4 the first time you use a volume. If the volume already has data, just mount it.

Multiple volumes¶

A machine can have its root volume plus multiple data volumes attached:

sistemo volume create 5G --name pgdata
sistemo volume create 2G --name uploads
sistemo machine deploy debian --attach pgdata,uploads

Volumes appear as block devices in order:

Device	Volume
`/dev/vda`	Root volume (automatic)
`/dev/vdb`	First attached volume (`pgdata`)
`/dev/vdc`	Second attached volume (`uploads`)

Resizing a volume¶

Grow a volume while the machine is stopped:

sistemo machine stop myvm
sistemo volume resize pgdata 10GB
sistemo machine start myvm

Warning

Volumes can only be grown, not shrunk. The machine must be stopped before resizing.

After starting the machine, the filesystem will need to be expanded to use the new space:

# Inside the machine
resize2fs /dev/vdb

Deleting volumes¶

Delete a volume that is not attached to any machine:

sistemo volume delete pgdata

Warning

A volume must not be attached to any machine before it can be deleted. Detach it first with sistemo machine volume detach.

Preserving storage on machine delete¶

By default, sistemo machine delete removes the machine and its root volume. To keep data volumes for reuse with another machine:

sistemo machine delete myvm --preserve-storage

This deletes the machine and its root volume but keeps all attached data volumes. Their status changes to available so they can be attached to a new machine.

Where files live¶

All volume data is stored on the host filesystem:

~/.sistemo/volumes/
├── a1b2c3d4-5678-9abc-def0-123456789abc.ext4   # pgdata
├── b2c3d4e5-6789-abcd-ef01-23456789abcd.ext4   # redis-data
└── c3d4e5f6-789a-bcde-f012-3456789abcde.ext4   # webserver-root

Volumes are sparse ext4 files passed to Firecracker as additional block devices. Metadata (names, sizes, attachments) is tracked in SQLite.

Example workflow¶

A typical workflow for persistent database storage:

# 1. Create a volume for PostgreSQL data
sistemo volume create 5G --name pgdata

# 2. Deploy a machine with the volume attached
sistemo machine deploy debian --name db1 --attach pgdata

# 3. Inside the machine: format, mount, install PostgreSQL
sistemo machine ssh db1
# mkfs.ext4 /dev/vdb
# mkdir -p /var/lib/postgresql
# mount /dev/vdb /var/lib/postgresql
# apt install postgresql

# 4. Later: stop the machine and grow the volume
sistemo machine stop db1
sistemo volume resize pgdata 10GB
sistemo machine start db1
# Inside machine: resize2fs /dev/vdb

# 5. Replace the machine but keep the data
sistemo machine delete db1 --preserve-storage

# 6. Attach the volume to a new machine
sistemo machine deploy debian --name db2 --attach pgdata
# Inside machine: mount /dev/vdb /var/lib/postgresql (no mkfs — data is preserved)

The volume survives across machine deletes, upgrades, and reattachments. Your data stays safe.

JSON output¶

Use -o json for scripting and automation:

sistemo volume list -o json