Articles

Volumes: data that outlives a jail

A volume is a dataset of a project that jails attach by name. Create it with an owner and a mode, attach it to one or several jails, snapshot it, and delete a jail without touching the data. A mail server and a desktop sharing one mail directory, and a directory of the host as a volume.

The idea

The jail is disposable, the data is not.

A volume is a dataset that belongs to a project, not to a jail. Jails attach it by name. You can delete, rebuild, upgrade or copy a jail and the volume stays exactly as it was, with its files and its snapshots.

Create and attach

The owner is set once, at creation.

The example is a mail server. The mail belongs to one user, so the volume is made for that user with a mode the group can use:

on the host
$ jailops volume create maildir --uid 5000 --gid 5000 --mode 0770 --comment "the mail of every user"
$ jailops create mail --image freebsd-15-1 --network lan --storage default
$ jailops volume attach mail maildir /var/mail/vhosts

The owner and the mode are set on the empty volume when it is made and cannot be changed later, so the files have the same owner wherever the volume is attached. A jail is changed with jailops volume attach and jailops volume detach while it is stopped; the attachment is there at the next start.

Several jails

One volume, many readers.

The same volume can be attached to more than one jail, at different paths:

on the host
$ jailops create desktop --image freebsd-15-1 --network lan --storage default
$ jailops volume attach desktop maildir /home/ann/Mail
$ jailops volume attach backup maildir /srv/mail --ro

JailOps warns when a volume is attached read-write to several jails, because two writers need to agree among themselves. Attach it read-only where you can. An encrypted volume attaches to one jail only.

Snapshots

Before a risky change.

on the host
$ jailops volume snapshot create maildir before-move -m "before the move"
$ jailops volume snapshot list maildir
$ jailops volume snapshot rollback maildir before-move

A rollback discards what was written since, so it asks you to type the name and is refused while a jail that has the volume attached is running.

When a jail goes away

The data stays.

  • Delete a jail: it is detached and the volume stays. jailops volume list still shows it.
  • Snapshot, roll back or upgrade a jail: volumes are never touched. A volume has snapshots of its own.
  • Copy a jail: the copy attaches no volume.
  • Delete a volume: destroys its files and snapshots, and is refused while a jail attaches it.

The apps of the catalog keep their data the same way: an app's data directories are volumes named after the jail, and they stay when the jail is deleted.

A directory of the host

A mounted storage box as a volume.

A directory that is already on the host, such as a storage box mounted over the network, can be a volume too. Only an administrator creates one, and only below the directories the host's operator approved. JailOps watches that the mount is really there:

on the host
$ jailops volume create storagebox --path /mnt/storagebox --watch --on-loss stop
  • --watch checks that the directory is still a mount of its own, and not an empty directory of the host underneath it. --probe write also tries to write.
  • --on-loss stop stops the jails that attach it when the mount goes away, and none only reports it. Either way the jail never sees an empty directory instead of its data.
  • When the mount comes back, JailOps attaches it to the jails again.

See also

More articles

Try it on one server.

Try the console from the screenshots, install on a clean FreeBSD 15.1 machine, or add JailOps to a host you already run.