Test the firewall before you trust it
jailops firewall test says whether a new connection between two jails, or from an address or the host, would pass the firewall, and which rule decides at each step. How to read it, how to use it in a script before a change, what it cannot know, and how to check the answer with a real connection.
Why ask first
A refused connection tells you nothing.
The usual test of a firewall rule is to try the connection and see. When it fails you know that something said no, not which rule, which policy or which of the two anchors a connection between two jails passes. Then you read the policies, the project's mandatory policy, the managed policy of an app and the defaults, and work it out.
jailops firewall test does that reading for you, on the rules JailOps would load, and prints the rule that decided. It changes nothing and sends no packet.
The console has the same test as a picture, with a form for the two ends: See a connection before it happens.
Asking
From, to, and a port.
The example: a project policy default (deny in, ping allowed) for every jail, and a policy postgres on the database jail that allows the address set postgresql-clients to port 5432. The set holds jail:web.
$ jailops firewall test --from jail:web --to jail:db --port 5432 $ jailops firewall test --from jail:web --to jail:db --port 5433 $ jailops firewall test --from jail:other --to jail:db --port 5432
An end is a jail of the project (jail:web), one address, or host. --proto is tcp by default; udp needs a port too, and icmp and icmp6 take --icmp-type (a ping, an echo request, when you leave it out).
Reading the answer
One line per anchor the connection meets.
The first question prints this:
tcp port 5432 10.20.0.11 -> 10.20.0.10 (inet): PASS web sends: allowed by the default of the anchor db takes: allowed by policy postgres rule 1 "who may reach PostgreSQL"
The first line is the verdict. Under it is one line for each end of the connection: what the source sends and what the destination takes, and the rule that decided. Here the web jail may send anything, so its own anchor allows it by its default, and the database anchor allows it because of rule 1 of policy postgres, with the comment you wrote for it. That comment is why a reviewer can read this without opening the policy.
Add -v when you want the detail: the pf line each answer was taken from, the rules that were skipped and what the test does not cover.
The second question, port 5433, ends in db takes: blocked by the default of the anchor: no rule allows it, so the default of the jail, deny in, decides. The third is blocked the same way, because jail:other is not in the set. The names that can decide are a policy and its rule number, a project policy, the managed policy of an app, the isolation between projects, and the default of the anchor.
The exit status is 0 for pass, 1 for block and 8 when the test cannot say. A usage error is 2.
The two ends
A connection between two jails has two hops.
What a jail sends is judged on its own port. What reaches the destination leaves the host on the gateway interface of its network. So a connection between two jails has to pass the source's anchor and the destination's, and the test shows both. From the host or from an address outside, only the destination side is evaluated.
- Another project is an external host: its jails are addresses here, and only the other end's anchor is evaluated. Write the address (
--from 10.30.0.5), as you do in the policy. - An address that belongs to a jail of the project is that jail.
- A set is not an end. Name a jail or an address and the set will show up as the rule that let it in.
- IPv4 and IPv6 are tested each on their own, for every family the two ends have in common (
--family 4or6to pick one).
In a script
Write down what must hold, and check it after a change.
The exit status makes it a check. Keep a short file of the connections that must pass and the ones that must not, and run it after every change of a policy or a set:
#!/bin/sh
# 0 = pass, 1 = block; anything else is an error or "cannot say" and fails the check
fail=0
expect() { # expect pass|block FROM TO PORT
want=$1; shift
jailops firewall test --from "$1" --to "$2" --port "$3" >/dev/null 2>&1; rc=$?
case "$want:$rc" in pass:0|block:1) ;; *) echo "FAIL: $want $1 -> $2:$3 (exit $rc)"; fail=1;; esac
}
expect pass jail:web jail:db 5432
expect block jail:web jail:db 5433
expect block jail:other jail:db 5432
exit $fail-o json prints the same answer for a program: the verdict, each case and hop with the policy, the rule number and its comment, and the caveats. A console that simulates a change can use the same answer later.
What it cannot know
It says so, and does not guess.
- A connection that is already open. pf keeps state, so the answer is for a new connection.
- A raw PF fragment in front of the decision. The answer is
unknown(exit status 8), naming the policy that has it. - The host's own
pf.confand NAT. The test evaluates the JailOps anchors; what the host's rules do before or after them is stated as not covered. - ICMP types. Without
--icmp-typethe test is an echo request, and the answer says so.
"Pass" therefore means "as far as these rules go", and -v lists under Not covered what that leaves out.
Checking with a real connection
The same question, asked to the network.
When it matters, ask the network too. From the host, with nc if the jail has it:
$ jailops exec web -- nc -z -w 2 10.20.0.10 5432; echo $?The answer should agree with the test. If the two ever disagree, the test is wrong, and that is a bug worth reporting.
The rules, sets and policies the test reads are explained in A firewall you can read, and why a project is a boundary in Projects are boundaries.
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 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 jailopsSee 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.