Articles

The life of a jail

What happens to a JailOps jail from create to delete, why a running jail does not come back after a reboot unless you said so with --autostart, how the boot order is decided and shown, and why the host keeps what you declared and nothing else.

The states

What jailops list shows.

A jail is stopped, starting, running, stopping or in error. A stopped jail whose encrypted volumes wait for their passphrase is locked. You move a jail between the first ones with jailops start, stop and restart, and jailops create --start makes one and starts it in one step.

what is there
$ jailops list -c name,state,autostart

The list is the jails of the project you work in. jailops info JAIL says more about one of them.

Declared, not remembered

Why a running jail does not come back by itself.

It is natural to expect that a jail that was running when the host went down is running when the host is back. JailOps does not do that, on purpose.

  • Running is an event, not a declaration. A jail was running because someone started it, maybe an hour ago to try something. A reboot that brings back whatever happened to be running would also bring back the experiment, the half-finished migration and the jail somebody stopped to keep it quiet.
  • What you declared is what you can read. The jail's specification says whether it starts at boot. Anyone who reviews a host reads boot.autostart and knows what will be there after a reboot, without asking what was running at the time.
  • It is the same after a crash and after a planned reboot. The result does not depend on how the host went down.

So you say it once, when you create the jail, and it stays true. A jail that jailops app install makes already has it: installing a service is the declaration that it should run, so an app comes back after every boot.

Autostart

Say it when you create the jail.

Most jails you want back after every boot. Put it in the command that creates them:

create a jail that starts at boot
$ jailops create web --image freebsd-15-1 --network lan --storage default --start --autostart

--start starts it now and --autostart starts it every time the host boots. A jail without --autostart stays stopped after a reboot, also when it was running before. For a jail that exists:

turn it on later
$ jailops config set web boot.autostart true

The host side is jailopsd_enable="YES" in rc.conf: the daemon starts at boot and its first pass starts the jails that declared boot.autostart.

The boot order

Dependencies first, then priority, then the name.

Most hosts need no order. When a jail needs another to be running first, say so: boot.depends names the jails that must start before it, and a dependency that is not running is started first, even if it has no autostart of its own. Among the jails that are ready, a lower boot.priority starts first, then the name. A cycle or a dependency that does not exist leaves the jails involved out, and says so; nothing is guessed around.

You do not have to work the order out in your head. jailops boot prints it the way the daemon will compute it, for the whole host, and lists the jails that will not start with the reason:

the plan
$ jailops boot

Read it before a planned reboot, and again after you change a dependency.

Encrypted jails after a boot

They wait for you, on purpose.

After every boot of the host the keys of encrypted volumes are not loaded. The jail is locked, and the boot skips it and remembers that it was due. jailops volume unlock NAME asks for the passphrase of the volume and, for a jail that had autostart, starts it right after. A jail that depends on a locked jail does not start at boot either; start it after the unlock. The reason shows in jailops boot.

This is the one place where the host waits for a person instead of acting alone, and it is the same rule as everywhere else: nothing starts that you did not declare, and nothing is decrypted that you did not unlock.

Changing a jail without losing it

Snapshots, rollback, upgrade.

The rest of the lifecycle follows the same habit: you ask, the host does exactly that, and what it did is recorded.

  • jailops jail snapshot create JAIL takes a consistent ZFS snapshot across all datasets of a jail; it costs almost nothing until data changes.
  • jailops jail rollback JAIL returns the root, the data or both to a snapshot, and shows how much it discards before it asks you to type the name.
  • jailops jail upgrade JAIL moves a jail to a newer generation of its image, keeps the application data and merges /etc; --dry-run shows the move first. How the generations come about is in jail updates without cron.

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.