Articles

See a connection before it happens

The firewall simulator in the JailOps console: choose where a connection starts, where it goes, a protocol and a port, and see how it flows through the firewall, which rule lets it through or stops it, and where to change that. The same question on the command line, and what it cannot know.

What it is for

Ask the firewall instead of trying.

Why can the web jail not reach the database? Does the new rule open what you meant it to, and nothing else? Would a connection from the office reach the git server? The usual way to find out is to try, and a refused connection does not say which policy, which rule or which side said no.

The simulator answers before you try. It follows the same rules JailOps loads into pf, step by step, and shows which one decides. Nothing is sent and nothing changes, so it is as safe on a host in production as on a test machine.

Asking

From, To, protocol, port.

Open Firewall in the console and choose the Test tab, next to Policies and Address sets. You need the operator role in the project.

  • From is where the connection starts and To is where it goes. Type a jail (jail:web; the project's jails are offered as you type), one address, or host. The arrow button swaps them.
  • Protocol is tcp, udp, icmp or icmp6. tcp and udp need a port. For a ping, leave the ICMP type empty and the test asks as an echo request.
  • When both ends have an IPv4 and an IPv6 address, you can limit the test to one of them. Otherwise each family is tested on its own and shown as its own card.

Press Run the test, or Enter in any field. Nothing runs while you type.

The Test tab of the Firewall page of the JailOps host console in dark theme: From jail:web, To jail:db, Protocol tcp, Port 5432, a Run the test button, and under them the same question as a jailops firewall test command with a Copy button. Demo data.The Test tab of the Firewall page of the JailOps host console in light theme: From jail:web, To jail:db, Protocol tcp, Port 5432, a Run the test button, and under them the same question as a jailops firewall test command with a Copy button. Demo data.
The form: where from, where to, a protocol and a port, and the same question as a command. Demo data.

Reading the flow

Every step says pass or block, and why.

The answer is a flow from left to right: where the connection starts, what the source jail sends, what reaches the destination jail, where it goes. A connection between two jails has to pass the source's firewall and the destination's, so you see both.

  • Each step shows PASS, BLOCK or CANNOT SAY with an icon and the word, never by colour alone.
  • Under it is the anchor of the jail and what decided, in words: policy postgres, rule 1: who may reach PostgreSQL, a project policy, the managed policy of an app, the isolation between projects, or the default of the anchor when no rule matched. The comment you wrote for a rule is the explanation.
  • Details opens the rule as it is loaded in pf, and the rules the test passed over: a disabled rule the connection would have met, or the allow rules that a deny rule won over.
  • The big verdict above the flow is PASS only if every step passes. When a step blocks, the destination is shown as not reached.
The result in the Test tab in dark theme: a green PASS banner, The result in the Test tab in light theme: a green PASS banner,
A connection that passes: the web jail may send, and one rule of the database jail lets it in. Demo data.

When it blocks

See which rule, then change it.

A blocked connection shows the step that stopped it, and the rest of the path as not reached. If the rule is a policy rule, its number and comment tell you where to go: open the policy on the Policies tab and change that rule. If the default of the anchor decided, nothing allowed the connection: add an allow rule, or put the source in an address set the policy names.

  • A deny rule wins over every allow rule, whatever the order of the policies. The details list the allow rules it won over.
  • A rule that is switched off lets nothing through. The details name it, so you can see that it would have matched.
  • Another project is an external host: type the address of its jail, as you write it in the policy.
A blocked result in dark theme: a red BLOCK banner, A blocked result in light theme: a red BLOCK banner,
A blocked connection: rule 4 of the policy decides, the details show the pf rule and the allow rule it won over. Demo data.

Sharing a question

The address holds it.

The question is in the address of the page: the jails or addresses, the protocol and the port. Send the link to a colleague and the page asks the same question when it opens; reload it after changing a policy and you see the new answer.

The same question as a command is under the form, with a Copy button, for a script or a review:

the same question
$ jailops firewall test --from jail:web --to jail:db --port 5432

The command has the same answer and its exit status says it: 0 pass, 1 block, 8 when it cannot say. Test the firewall before you trust it shows it in a script.

What it does not cover

It says so, and does not guess.

  • New connections. pf keeps the state of a connection that is already open, so the answer is for a new one.
  • Raw PF fragments. A policy that carries one can decide before the test can see it. The answer is cannot say, with the policy named.
  • The host's own pf.conf and NAT. The simulator evaluates the JailOps anchors; the box Not covered under the result says what that leaves out for this question.

Policies, address sets and how a project keeps its firewall apart are in A firewall you can read and Projects are boundaries.

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.