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.
# 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:
# 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:
# 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.
# 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:
# jailops image set freebsd-15-1 --auto-upgrade --upgrade-at 03:00What 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.
# 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.
# 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:
# 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.
# jailops jail info webThe 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.
# 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.
# 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):
# 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.
# 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 doctorchecks the host and the server, and says what to do about each warning.jailops op listlists the operations;jailops op show IDshows the steps of one, with the time each took and where it stopped.jailops explain CODEexplains an error code. Every error prints ascode: messagewith a hint on the next line, for examplejailops 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.
- Projects are boundaries: what a project owns and what it may use.
- Volumes for jails: data that outlives the jail.
- Jail lifecycle: start, stop and boot order.
- Networks the host controls: what a network gives a jail.
- Documentation: every command and setting.
More articles
Jail updates without cron
Replace the nightly script that upgrades every jail: automatic jail upgrades per image, with a health check, a rollback and a record of every run, what they leave alone, and how a new FreeBSD release comes in.
Read the article: Jail updates without cronJail 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 shellJailOps 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.