Get Started
REFERENCE

Volume

Reference for the persistent disks a box can own in addition to its root file system.

A Volume is a writable, persistent disk that belongs to one box and is mounted at a fixed directory inside it. A box has a root file system at / and zero to nine Volumes. Each disk is forked on its own.

For the reasons to use one, see Keep Data Separate from the Environment and Back Up and Restore Data.

Create

Volumes are declared on box create, with any source for the root file system. Repeat the flag for each disk.

--volume <mount-path>
--volume <mount-path>,uid=<n>,gid=<n>,mode=<octal>
--volume <mount-path>,from=<snap-id>

--volume-mount-path <mount-path> is the older spelling of the first form.

Mount path

  • An absolute directory inside the box, written without a trailing slash and without . or .. parts.
  • Not /, and not a path the system manages for itself.
  • Absent or empty in the root file system, and not reached through a symlink.
  • Two Volumes of one box cannot use the same path or sit inside each other.

Owner and mode

A new empty Volume belongs to root with mode 0755. uid, gid, and mode change that for the top directory:

  • uid and gid are numeric ids inside the box, from 0 to 4294967294. Each defaults to 0. User names are not looked up.
  • mode is three or four octal digits from 0000 to 7777, including sticky, setgid, and setuid bits.
  • The values are applied once, at creation, to the top directory only. Later chmod and chown changes are stored like any other change and are not reset by stop or wake.
  • Directories above the mount path are not changed; they must already let the user through.

Starting from existing data

from=<snap-id> creates the Volume as a writable copy of an existing disk. The source is not changed.

A source can be:

  • a saved snap,
  • the root file system or a Volume of a stopped box,
  • the root file system or a Volume of a running box, which pauses briefly while it is captured.

Take the snap id of a box’s disk from the Storage table of box inspect.

  • The copy keeps the source’s contents, owners, and modes, so from= cannot be combined with uid, gid, or mode.
  • One box create can read from at most one running box. Saved snaps and empty Volumes can be mixed in freely.
  • Disks from a running box are captured one after another, not at one shared instant.
  • The box appears only when every disk is ready. If one fails, nothing is created. Stopping or removing a running source cancels the preparation.

Lifecycle

  • Kept through box stop, sleep, and every wake-up.
  • Removed by box rm together with the box. There is no separate way to recover it afterwards; snaps forked from it earlier are kept.
  • Not included in a fork of the root file system: neither the data nor the mount.
  • Fixed at creation. Volumes cannot be added, removed, replaced, or moved to another box.

A box accepts commands and file access only when its root file system and all Volumes are ready.

Fork

sys9 run snap fork --from-box <box-id> --volume <mount-path>

--volume must be the exact mount path of an existing Volume. A subdirectory, /, or an unknown path is rejected; the command never falls back to the root file system.

The result is an ordinary saved snap that holds only that Volume. It follows the same rules as any fork, may not contain an operating system, and is kept when the box is removed.

Files

Inside the box and through box exec, box cp, and box file, a Volume appears at its mount path, whether the box is running or stopped. There are no Volume-specific file commands.

Through its own snap id, a Volume is read with its top directory as /:

sys9 run box file ls <box-id> /state
sys9 run snap file ls <state-snap-id> /

Find the disks of a box

box create and box inspect print a Storage table:

Storage
MOUNT PATH  SNAP ID          ROLE
/           <root-snap-id>   Attached Snap
/state      <state-snap-id>  Volume

snap ls --attached true lists the disks of every box with the owning box and mount path. In JSON, a box carries volumes with snap_id and mount_path for each one.

Not available

  • Standalone Volumes that exist without a box, and attaching or detaching them.
  • One Volume shared by several boxes.
  • One snapshot that covers several disks at the same instant.
  • A separate size tier or bill. Volume data counts toward normal storage usage.