JailOps
Get started

Get started

Build it, try it, read it

There is no tagged release yet. Until the first one, JailOps is built from source or from packages you build yourself.

Pre-release. JailOps is under active development, has not reached a stable release and has not been security audited. Do not point it at a pool that holds data you cannot lose. The documentation lives in the source repository at github.com/jailops/jailops, which may not be public yet when you read this.

What you need

  • A FreeBSD 15 host with ZFS. The reference test host runs FreeBSD 15.1. JailOps manages jails with jail(8), ZFS, PF and if_bridge, so it needs a real FreeBSD kernel to do anything beyond the fakes.
  • A scratch ZFS pool for prototypes and integration tests. The FreeBSD integration tests take the pool from JAILOPS_TEST_POOL and fail, never skip, when a prerequisite is missing.
  • Go 1.27 or newer and just to build. Binaries are pure Go with CGO_ENABLED=0. You can build on Linux and cross-build for FreeBSD.
  • Node 22 or newer only if you build the web consoles.
  • PostgreSQL for a backup node, which uses it as its only control-plane store. The per-host daemon uses SQLite and needs nothing extra.

Build from source

These recipes come from the repository's Justfile. The repository URL is the planned public location.

  1. Get the source

    $ git clone https://github.com/jailops/jailops.git
$ cd jailops

  2. Build the web consoles (optional)

    The consoles are embedded in jailopsd and jailops-backupd, so build them first if you want them in the binaries.

    $ just web-all

  3. Build the binaries

    This builds jailops, jailopsd, jailops-priv, jailops-sync and jailops-backupd, version-stamped from version.txt, into bin/.

    $ just build              # native binaries in bin/
$ just build-freebsd      # cross-build for FreeBSD amd64
$ just build-freebsd arm64

  4. Run the tests

    Unit tests run anywhere, against fakes. The integration tests need a FreeBSD host with a scratch pool.

    $ just test                   # anywhere, with fakes
$ JAILOPS_TEST_POOL=scratch just test-freebsd   # on a FreeBSD host

  5. Look around

    Every command has built-in help, and every error code is explained.

    $ bin/jailops --help
$ bin/jailops explain
$ bin/jailops-sync --help
$ bin/jailopsd version

Install on a FreeBSD host

This is the flow the project's own end-to-end test runs on a clean FreeBSD machine, from the packages to a restored backup.

  1. Install the packages

    The release workflow builds three FreeBSD packages: jailops-client (the command line and the fleet tool), jailops (the daemon and its privileged helper) and jailops-backupd (the backup node). The signed repository at pkg.jailops.net goes live with the first tagged release. Until then, build the packages yourself with just build-freebsd and scripts/pkg-build.sh, or install the binaries from just build.

    $ pkg install jailops

  2. Set the host up

    jailops-priv init creates the unprivileged user and groups, the storage dataset and its state dataset, and writes the two configuration files. It never overwrites a file, and it can be run again.

    $ jailops-priv init -pool tank

  3. Start the services

    The helper runs as root and does the few things that need it; the daemon runs as the user jailops. PF needs the line anchor "jailops/*" once (and the matching nat-anchor and rdr-anchor); jailops doctor says if it is missing.

    $ sysrc jailops_priv_enable=YES jailopsd_enable=YES
$ service jailops_priv start
$ service jailopsd start
$ jailops doctor

  4. Your first jail

    $ jailops image create freebsd --release 15.0-RELEASE --alias stable
$ jailops image build freebsd
$ jailops network create lan --ipv4 10.50.0.1/24 --uplink em0 --nat
$ jailops project create web
$ jailops project set web --network lan --storage default
$ jailops create nginx --project web --image freebsd@stable --network lan
$ jailops start nginx --project web
$ jailops exec --project web nginx -- uname -a

Backups need a backup node, which uses PostgreSQL. The repository's scripts/ci-freebsd-e2e.sh sets one up from scratch, enrols the host, backs a jail up, verifies the backup and restores it as a new jail.

Documentation

These pages are in the source repository, on the main branch.

  • Design document

    The contract: principles, ZFS layout, thin jails and generations, networking, trust, backup, hub, cluster, fleet sync, and the list of what is still unverified on FreeBSD.

  • README

    What JailOps is, in one page, and the build commands.

  • Wire protocol

    The REST contract the SDK, the fake server and the daemon implement: envelope, conventions, routes.

  • Web consoles

    How the host and backup consoles are organised, built and tested, and how to run them in demo mode.

  • Example fleet repository

    A small jailops-sync repository: hosts, groups, a jail template, a rollout and an age-encrypted secret.

  • Sample daemon configuration

    Every key of jailopsd.yaml with its default and a comment.

  • Justfile

    Every build, test, web and release recipe.

  • Changelog

    What changed, release by release.

Looking for the status of a feature rather than how to use it? See the status and roadmap page, or the feature overview.

Questions, bugs and contributions

Open an issue in the issue tracker. JailOps is released under the BSD 2-Clause license.