Articles

Getting started with the JailOps CLI

From a fresh FreeBSD host to a running jail with the command line alone: install, set the host up, build an image, make a network, create a jail, give it a name, a snapshot and a firewall rule. No browser, no user, no token.

Install

One package, signed.

You need a FreeBSD 15.1 host with ZFS and root. Everything here is typed as root on that host; the CLI talks to the daemon over its local socket, so there is no user to create and no token to copy.

Trust the package repository once: fetch its public key, then name the repository. The key's fingerprint is in the README of jailops-packages; compare it before you go on.

As root on the host
# mkdir -p /usr/local/etc/pkg/keys /usr/local/etc/pkg/repos
# fetch -o /usr/local/etc/pkg/keys/jailops.pub https://pkg.jailops.net/jailops.pub
# cat > /usr/local/etc/pkg/repos/jailops.conf <<'EOF'
jailops: {
  url: "https://pkg.jailops.net/${ABI}/latest",
  signature_type: "pubkey",
  pubkey: "/usr/local/etc/pkg/keys/jailops.pub",
  enabled: yes
}
EOF
# pkg update
# pkg install jailops

The package brings the daemon, the privileged helper, the rc scripts, the jailops command with its shell completion and man pages, and the app catalog.

Set the host up

One command, and it shows its work.

jailops-setup does what a jail host needs once: the kernel modules, the datasets on your ZFS pool, IP forwarding, a resolver that gives the jails names, one anchor line in pf.conf, and the service. It prints every action on one line before it runs, and it leaves what is done already as it is. Look first, then run it:

As root on the host
# jailops-setup -n
# jailops-setup

With more than one pool, name the one for JailOps: jailops-setup -pool tank. It never changes a line of your pf.conf: it adds what is missing, keeps a copy of the old file and checks the new text before it loads it. The web console stays off. --web turns it on if you want it; nothing in this page needs it.

Check the result:

As root on the host
# jailops doctor
# jailops server info

doctor prints PASS, WARN or FAIL for each check and a hint for each one that is not a pass. A fresh host should show no FAIL.

An image

One release, one name.

Jails start from an image. An image is one FreeBSD release, named after it: freebsd-15-1 is 15.1-RELEASE, and its generations are the patch levels of that release. Use the release your host runs (freebsd-version -k tells you). The build downloads the base system and takes a few minutes.

As root on the host
# jailops image create freebsd-15-1 --release 15.1-RELEASE
# jailops image build freebsd-15-1

To keep the image and its jails on the newest patch level, turn on the nightly upgrade. It is off until you do:

As root on the host
# jailops image set freebsd-15-1 --auto-upgrade --upgrade-at 03:00

What it does and leaves alone is in Jail updates without cron.

Projects and grants

The host owns it; a project is given it.

Networks and storages belong to the host. A project may use only what is granted to it, and a network belongs to one project at a time. That is the whole model: you make a project, then grant it a network and a storage. The storage default exists from the first start of the daemon, on the datasets jailops-setup made.

Make the network first (next section), then the project and its grants. jailops project create shop --new-network is the short way when you want a dedicated network from the server's pool instead of one you describe yourself.

A network

An address range and a way out.

A network is an address range with the host as its gateway and an uplink to the outside. --nat lets the jails reach the internet through the host's address. vtnet0 is the host's interface on most virtual machines; ifconfig -l lists yours. The private range must not overlap anything the host already has.

As root on the host
# jailops network create lan --ipv4 10.77.0.1/24 --uplink vtnet0 --nat
# jailops project create shop
# jailops network grant lan --project shop
# jailops storage grant default --project shop
# jailops project switch shop

project switch makes shop the project of every command that follows, so you do not repeat --project. The command jailops project list shows the projects.

IPv6 is the same command with --ipv6 and a mode: routed when your provider routes a prefix to the host, proxy when the prefix sits on a shared segment and the host answers neighbor discovery for each jail. IPv6 for jails explains both.

A jail

One command, then look inside.

The project shop has exactly one network and one storage, so the jail takes them by itself and says so. --start starts it now. --autostart starts it every time the host boots: a jail without it stays stopped after a reboot.

As root on the host
# jailops create web --image freebsd-15-1 --start --autostart
# jailops list
# jailops info web

Open a shell in it, run one command, read a log:

As root on the host
# jailops shell web
# jailops exec web -- uname -a
# jailops jail logs web messages --tail 20

No SSH server runs in the jail: shell and exec go through the daemon. jailops stop web and jailops start web do what they say. Limits such as --memory 2G and --disk 20G go on create, or on jailops jail set web later.

Names

Jails find each other by name.

The jail web in the project shop is web.shop.internal, and any jail of the project can say just web. The host's resolver answers, and the names follow what runs: create a jail and its name is there, delete it and the name is gone.

As root on the host
# jailops jail info web

The report has a DNS block: the nameserver, the search domain and the names the jail answers to. Names for jails has the rest.

Snapshots

Before you change something.

A snapshot is a consistent ZFS snapshot of every dataset of the jail. It costs almost nothing until the data changes.

As root on the host
# jailops jail snapshot create web before-change -m "before I edit the site"
# jailops jail snapshot list web
# jailops jail rollback web --data --snapshot before-change

The rollback shows how much was written since the snapshot, which is what it would discard for good, and asks you to type the jail's name. Without --data the rollback only returns the root of the jail to the previous image generation and leaves your data alone. Backups keep copies of jails and volumes off the host; jailops backup --help lists the commands.

A firewall rule

Two commands, then ask pf.

A firewall policy denies inbound traffic and allows outbound traffic unless you say otherwise. Make a policy, add a rule that lets your office network reach port 80, and attach the policy to the jail. --comment says why the rule is there: it shows in the policy and in the rendered anchor.

As root on the host
# jailops firewall policy create web-in
# jailops firewall rule add web-in in --proto tcp --port 80 --from 192.0.2.0/24 --comment "the office reaches the web server"
# jailops jail set web --firewall-policy web-in

Then ask the firewall what it would do. firewall test names the rule that decides, and its exit status says whether the connection would pass (0) or be blocked (1):

As root on the host
# jailops firewall test --from 192.0.2.10 --to jail:web --port 80
# jailops firewall test --from 198.51.100.7 --to jail:web --port 80

JailOps never owns your pf.conf. The rules live in an anchor per jail. Firewall for jails goes further.

An app

A catalog entry instead of a recipe.

The catalog holds ready definitions of services. Look at what an installation does, then install it. The new jail is closed: nothing reaches it until you allow a source.

As root on the host
# jailops app list
# jailops app install nginx --dry-run
# jailops app install nginx
# jailops app allow nginx --from host

The installation takes a snapshot named app-installed, so you can go back to the fresh state. From catalog to running service follows each step.

When something is off

Three commands.

  • jailops doctor checks the host and the server, and says what to do about each warning.
  • jailops op list lists the operations; jailops op show ID shows the steps of one, with the time each took and where it stopped.
  • jailops explain CODE explains an error code. Every error prints as code: message with a hint on the next line, for example jailops explain already_exists.

Tab completes commands, flags and the names of your jails, networks, images and projects: Shell completion.

Next

Where to go from here.

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.