Jail updates without cron
How JailOps keeps FreeBSD jails up to date without a cron script: one image per release, the patch levels as generations, and a nightly upgrade you turn on, with a health check, a rollback and a record of every run. What it leaves alone, and what was tested.
Updating FreeBSD jails with a cron script
It works until the night it does not.
Many hosts with jails have one: a script that cron starts at night. It upgrades the base system of each jail, runs pkg upgrade in every jail, maybe restarts a service or two, and mails its output to someone.
It does the work, and it leaves out the three things that matter on the night something breaks:
- No health check. The script finishes when the commands return, not when the services answer. A jail whose service no longer starts looks like every other jail.
- No rollback. When an upgrade breaks a jail, the way back is whatever you prepared by hand, if you did.
- No record. What changed, in which jail, and what failed lives in a mail, if the mail arrived and someone read it.
And it rolls the same change over every jail, the broken ones included. JailOps replaces such a script with a nightly upgrade per image, which the daemon runs itself. Before it, the model it rests on.
pkgbase jails: one image, one release
Patch levels are generations.
A thin jail's root is a ZFS clone of an image generation: an immutable pkgbase userland. What must survive an upgrade (/etc, /usr/local, /var/db, /home, /root and the jail's volumes) lives on datasets of its own. Upgrading a jail swaps the root for a clone of a newer generation and keeps those datasets.
- An image is one FreeBSD release and is named after it:
freebsd-15-1is 15.1-RELEASE. - Its generations are the patch levels of that release. Each upgrade builds the next one, with the release's current patches and packages.
- A new release is a new image (
freebsd-15-2), never a generation of the old one. Nothing upgrades a jail from one release to the next in place. - The host first. A jail runs on the host's kernel, so the host must run a release at least as new as the image's.
A jail made with --image freebsd-15-1 follows the image's newest generation. The commands are the same whether you run them by hand or let the nightly run do them:
$ jailops image upgrade freebsd-15-1 --dry-run # the plan, and which jails would move $ jailops image upgrade freebsd-15-1 # the next generation, then every thin jail, one at a time $ jailops image generation list freebsd-15-1 # which jail is on which generation
Each jail move is the same as jailops jail upgrade: an atomic snapshot of the jail, the new root, a three-way merge of /etc, the swap, and the jail's health check. A jail that fails it is swapped back to its old root. The run stops at the first jail that fails, so a bad generation is not rolled across the host.
Automatic jail upgrades, every night
Off until you turn it on.
The nightly auto upgrade is set per image. Nothing is upgraded unless you turned it on: not when you create an image, not in the first-run wizard, where the box is unticked.
$ jailops image set freebsd-15-1 --auto-upgrade --upgrade-at 03:00 # --upgrade-packages=false leaves the packages in the jails alone $ jailops image show freebsd-15-1 # the next run and the latest runs $ jailops image set freebsd-15-1 --auto-upgrade=false
In the console it is the checkbox Upgrade automatically every night on the image's card of the Images page, with the time and Also upgrade the packages inside the jails, and the same box in Create image. Only a global administrator changes it; everyone else sees it.


Every night at the chosen time (the host's time zone; 03:00 unless you choose another), a run does three things:
- It builds the image's next generation, with the patch updates of the release. When nothing changed, the run is recorded as unchanged.
- It moves the thin jails of the image to it, one at a time, exactly as
jailops image upgradedoes: snapshot, new root,/etcmerge, health check, and the automatic rollback of a jail whose check fails. It stops at the first jail that fails; the jails after it stay where they are until the next run. Jails that an earlier, stopped run left behind are moved too, even on a night when nothing new was built. - With packages on (the default), it upgrades the packages inside the running jails of the image. For a FreeBSD jail the host runs
pkg -ron the jail's root and names the jail's own packages, so a base system package never comes in this way: the base moves only with the generation.
It leaves alone:
- jails whose update strategy is manual or in place, thick jails, Linux jails (their root) and jails pinned to a generation such as
freebsd-15-1#g3(their root); - the packages of a stopped jail;
- the host. Upgrading the host is yours to do, and it comes first.
A host that was off at the chosen time runs the upgrade when it is back, if that is within four hours; later than that it waits for the next night. Every run is kept with the image: when it started, its result (ok, unchanged or failed, with what failed) and how many jails were moved, upgraded and failed. A failed run raises the event image-upgrade-failed and stays on the image's card as a notice until a later run succeeds.


Moving from your cron script: remove the entry and turn the nightly upgrade on for the image at the same hour. The daemon runs it itself, so it needs no token or client on the host; a host that was off catches up within four hours; the packages are upgraded in the same run; and each result is kept with the image instead of in a mail.
What a run prints
From a real run, and from the tests.
A run looks like this, on a host with the image freebsd-15-2. The jail up was on the first generation, one of its packages was outdated, and the nightly time was two minutes ahead, so the daemon's clock started the run:
$ jailops image show freebsd-15-2
Image freebsd-15-2
System: freebsd 15.2-PRERELEASE (amd64)
Source: pkgbase
Aliases: none
Keeps: every generation
Age: 1m
Nightly: off ('jailops image set freebsd-15-2 --auto-upgrade' turns it on)$ jailops image show freebsd-15-2 Image freebsd-15-2 System: freebsd 15.2-PRERELEASE (amd64) Source: pkgbase Aliases: none Keeps: every generation Age: 3m Nightly: every night at 14:49: generation and jails and their packages; next 2026-11-04 14:49 Automatic upgrades STARTED RESULT WHAT 2026-11-03 14:49 ok 2 moved, 1 packages upgraded Generations GEN PACKAGES AGE USED BY g1 47 3m demo/up,demo/web g2 47 2m demo/up,demo/web $ jailops jail list --project demo NAME STATE IMAGE GEN ADDRESSES AGE up running freebsd-15-2 freebsd-15-2#g2 10.77.0.3 2m web running freebsd-15-2 freebsd-15-2#g2 10.77.0.2 3m
The run built nothing new (the repository had nothing new for the image), moved the two jails that were behind to the newest generation, and upgraded the outdated package inside the one jail that had it. The test then checked that the package's version had changed and that the jail still ran.
A failed run looks like this when you run the same upgrade by hand. This output is from the command line's tests, with their fake server:
$ jailops image upgrade freebsd-15-1 generation/freebsd-15-1#g5 built from freebsd-15-1#g4 JAIL PROJECT STATUS FROM TO REASON pin main skipped freebsd-15-1#g1 - pinned to freebsd-15-1#g1 web main failed freebsd-15-1#g2 freebsd-15-1#g5 health check failed (the jail was swapped back to freebsd-15-1#g2; application data was not touched) api shop not_attempted freebsd-15-1#g3 - stopped after main/web failed ! error: jail web failed; the jails after it were not attempted ! hint: 'jailops update history web --project main' shows what happened; run the upgrade again once it is resolved $ jailops update history web ID JAIL KIND RESULT CHANGE SNAPSHOT AGE upd-<id> web packages ok 2 packages update-<id> 3h
The ids are placeholders of the tests. A jail's history lists every update with its result and the snapshot taken before it.
Alpine and Debian jails, and unattended-upgrades
apk yes, apt never.
- Alpine jails: their packages are checked and upgraded with
apk, run in the jail, byjailops update, the managed schedules and the nightly run. A Linux jail is always a full copy, so it never moves to a new generation. - Debian jails: JailOps never runs
aptin them, and no update of JailOps touches their packages. A Debian jail keeps its own packages up to date, for instance withunattended-upgradesinside the jail, as on any Debian system.
The reason is the same as for everything else here: an update that JailOps runs must be one it can check, roll back and record. For a Debian jail it does not do that yet, so it does not pretend to.
A new FreeBSD release: a new image
15.2, after the host.
When 15.2-RELEASE comes, nothing moves on its own. The order:
- Upgrade the host, then run
jailops doctor. A jail is never moved to a generation of a newer release than the host's kernel. - Create and build the image of the new release, and turn its nightly upgrade on if you want it: each release is its own image, with its own setting.
- Create new jails on it.
jailops app installtakes the image of the newest release the host can run when you name none.
$ jailops image create freebsd-15-2 --release 15.2-RELEASE $ jailops image build freebsd-15-2 $ jailops image set freebsd-15-2 --auto-upgrade --upgrade-at 03:00
The console points it out: when the host runs a newer release than its newest FreeBSD image, the Images page and the Overview say so and open Create image filled in for it.




Moving a jail's data to a jail of the new release is not automated. Create the new jail next to the old one, take a backup of the old one, copy or export the data with the application's own tools, check it, move the addresses or ports over, and delete the old jail when you no longer need it. The old image keeps getting its patch levels for as long as you keep it; delete it once no jail uses it.
Limits
So you can judge.
- The host is not upgraded. Upgrading the host's base system with boot environments is designed, not built.
- No live migration. A jail shares its host's kernel, so a move between releases or hosts means a new jail; moving a jail to another host is planned (the roadmap, a plan and not a promise).
- A failed package upgrade is not rolled back by itself. Packages live on the jail's datasets, so a root rollback does not undo them. The way back is
jailops jail rollback JAIL --all --snapshot SNAPSHOTwith the snapshot the update recorded, which discards what the jail wrote since. - No notification yet. A failed run is an event and a notice in the console; mail and webhook notifications are planned.
The details are in docs/upgrade.md.
More articles
Jail search and shell
Ctrl+K, a few letters, Shift+Enter: find a jail by name, label or app and open its shell. Labels that filter the jail list, bash in new jails, and the jailops command next to every step.
Read the article: Jail search and shellGetting started with the JailOps CLI
Root on the host, the command line and nothing else: install JailOps, build an image, create a network and a jail, reach it by name, snapshot it, open a port and install an app.
Read the article: Getting started with the JailOps CLIJailOps on a netcup server, with IPv6 that stays up
A /64, a router pair and a FreeBSD default that drops their probes. How every jail gets its own IPv6 address on netcup, and the one sysctl that ends the random unreachable alerts.
Read the article: JailOps on a netcup server, with IPv6 that stays upOne small cloud server, many services, solid IPv6
Run your database, web tier and workers on one low-cost server, each jail with its own IPv6 address, and fix the alerts a shared /64 causes with one sysctl.
Read the article: One small cloud server, many services, solid IPv6Write your own app: memcached, from package to catalog
Turn a small FreeBSD package into a JailOps app: the definition line by line, the offline check, a local install, the five traps, and the pull request that puts it in the catalog.
Read the article: Write your own app: memcached, from package to catalogFrom catalog to running service in one command
Install nginx from the app catalog with one command, see each of its steps, and find the data, the configuration, the logs and the snapshot afterwards.
Read the article: From catalog to running service in one commandA firewall you can read
Policies, address sets and jails by name (jail:web), each with a comment, so the firewall can be reviewed by someone who did not write it.
Read the article: A firewall you can readPostgreSQL and git, closed except for who needs them
Close a database and a git server, then let in exactly the web jail and the office, with a comment on every entry.
Read the article: PostgreSQL and git, closed except for who needs themProjects are boundaries
A project is a boundary. Another project is an external host, so only addresses cross it, written out on both sides. Why that is simpler to review, and what a project does not isolate.
Read the article: Projects are boundariesThe life of a jail
A jail starts at boot only when you declared it with --autostart. Why JailOps does it this way, how the order is decided, and how to see it with jailops boot.
Read the article: The life of a jailTab completion for jailops
Press Tab and get the names of your jails, networks and firewall policies, even on another host. How to install and turn on completion in bash, zsh and fish.
Read the article: Tab completion for jailopsTest the firewall before you trust it
Ask the firewall whether a connection would pass, and why, before you try it. Read the answer, put it in a script, and know what it cannot tell you.
Read the article: Test the firewall before you trust itSee a connection before it happens
Pick a From and a To, a protocol and a port, press Run, and see the connection flow through the firewall: what passes, what stops it, and which rule decides.
Read the article: See a connection before it happensLimit what a jail can use
Give a jail a ceiling for memory, processes, CPU, disk, firewall states and bandwidth, one command each, and know what happens when it reaches it.
Read the article: Limit what a jail can useStop every jail cleanly when the host shuts down
A host that reboots should stop its databases before it stops the disks. How JailOps stops the jails in order, and how to start them in order again.
Read the article: Stop every jail cleanly when the host shuts downOne line in pf.conf
The host's firewall stays yours. JailOps asks for one line, and everything for the jails lives below it.
Read the article: One line in pf.confWhat the host tells you by itself
A pool that reports an error, an uplink that goes down, a jail that reaches a limit: they show up in the event stream by themselves.
Read the article: What the host tells you by itselfNetworks the host controls
No bridge, no DHCP. The host hands out the addresses, gives each jail a link of its own and is the router, so jails cannot see or impersonate each other.
Read the article: Networks the host controlsVolumes: data that outlives a jail
Keep the data in a volume and the jail disposable. One volume can be attached to several jails, has its own snapshots and its own backup.
Read the article: Volumes: data that outlives a jailBack up volumes once
One copy of a volume, however many jails use it. Leave volumes out when you want to, bring them back with the jail.
Read the article: Back up volumes onceA private Docker registry
A registry of your own with users in a file: one jail, docker-registry and docker-auth, htpasswd for the passwords, the images on a volume.
Read the article: A private Docker registryNames for jails
A jail is reached by its name inside its project: db.shop.internal, or just db. Create a jail and its name is there; delete it and the name is gone.
Read the article: Names for jails
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.