A firewall is a reusable set of rules, inbound and outbound, that you attach to your machines. It is enforced by our network, before traffic reaches the system: nothing to install, it works the same on Linux, Windows and BSD, and a mistake inside the machine cannot switch it off.
How it filters
- A machine without a firewall accepts all inbound traffic, as before.
- As soon as a machine has at least one firewall, inbound traffic no rule allows is dropped. Rules are read in order, and the first one that matches wins.
- Replies to the machine's own connections always get through: updates, downloads and outgoing API calls need no rule.
- Its private networks stay open, unless one of its firewalls also filters the private network. The web console of the panel reaches the machine even if every rule is closed.
- Outbound traffic is free until one of the machine's firewalls has an outbound rule.
Create a firewall
A rule allows (or denies, see below) one protocol (tcp, udp, icmp for
ping in IPv4 and IPv6, or any), on ports ("22",
"80,443", a range "8000-8100"; omitted: all ports), from
sources (IPv4 and IPv6 addresses or ranges; omitted: anywhere).
curl -s -X POST https://api.ffxf.net/v1/firewalls \
-H "Authorization: Bearer $FFXF_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "web",
"rules": [
{"protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24", "2001:db8::/32"], "description": "SSH from the office"},
{"protocol": "tcp", "ports": "80,443", "description": "Web"},
{"protocol": "icmp", "description": "Ping"}
]
}'
{
"data": {
"id": 7,
"name": "web",
"rules": [
{ "direction": "in", "action": "allow", "enabled": true, "protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24", "2001:db8::/32"], "description": "SSH from the office" },
{ "direction": "in", "action": "allow", "enabled": true, "protocol": "tcp", "ports": "80,443", "sources": ["0.0.0.0/0", "::/0"], "description": "Web" },
{ "direction": "in", "action": "allow", "enabled": true, "protocol": "icmp", "ports": null, "sources": ["0.0.0.0/0", "::/0"], "description": "Ping" }
],
"private_network": false,
"members": []
}
}
Without rules, the firewall starts with SSH (TCP 22) and ping open from
anywhere; send "rules": [] for none. Addresses are brought back to their
network address (203.0.113.7/24 becomes 203.0.113.0/24).
Ten firewalls per account, fifty rules per firewall, twenty sources per rule.
Keep a way in. A firewall that does not open TCP 22 (or 3389 for Windows) cuts SSH (or remote desktop) to every machine it protects. The web console still works, but a script or an agent working over SSH loses its machine.
Protect a machine
curl -s -X POST https://api.ffxf.net/v1/firewalls/7/members \
-H "Authorization: Bearer $FFXF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"vm": 4821}'
{ "data": { "vm": 4821, "hostname": "web-1", "status": "applied" } }
The rules are written when the call returns, and enforced within about ten seconds. Attaching a firewall already attached
returns 200: a script can replay its configuration safely. Up to five
firewalls per machine. A machine without a public address cannot get one: it has
nothing to filter (409).
Change the rules
PUT /firewalls/{id} with rules replaces the whole
list: describe the state you want, the API applies it to every attached
machine before answering. Send every rule you keep, not only the new one.
curl -s -X PUT https://api.ffxf.net/v1/firewalls/7 \
-H "Authorization: Bearer $FFXF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"rules": [{"protocol": "tcp", "ports": "22"}, {"protocol": "tcp", "ports": "443"}]}'
pending_machines counts the machines the new rules could not be applied to
yet; they show "status": "error" in
members and are retried automatically within minutes.
Order, deny and disabled rules
Rules are read top to bottom, in list order. The first one that matches the
packet wins. A rule with "action": "deny" refuses it (dropped
without a reply). Put it above the allow it should override. Here, SSH is open to the
office only:
{
"rules": [
{"protocol": "tcp", "ports": "22", "sources": ["203.0.113.0/24"], "description": "SSH from the office"},
{"protocol": "tcp", "ports": "22", "action": "deny", "description": "SSH elsewhere"},
{"protocol": "tcp", "ports": "8080", "enabled": false, "description": "Test, off"}
]
}
A rule with "enabled": false stays in the list but is not applied: handy for
a temporary opening you switch back on without rewriting it. With several firewalls on a
machine, they are read one after the other, in creation order. In the console, each rule
has Edit, Enable or Disable buttons and arrows to move it. Through the API, send the
whole list with the change.
Private network and site-to-site VPN
By default a firewall only filters public access: whatever arrives through the
private network card gets in unfiltered, including
site-to-site VPN traffic, which uses that card. With
"private_network": true, the firewall's inbound rules also cover the private
network.
curl -s -X PUT https://api.ffxf.net/v1/firewalls/7 \
-H "Authorization: Bearer $FFXF_TOKEN" \
-H "Content-Type: application/json" \
-d '{"private_network": true}'
- Then open what the private network needs, for example RDP (TCP 3389) from your
office range (
192.168.77.0/24) or SSH from the VPC range. - Load balancers that target the machine stay allowed on their target port, with no rule to write.
- On a machine that also has firewalls without this box, their rules only cover public access.
- Outbound traffic to the private network is always open.
Detach, delete
| Action | Call | Good to know |
|---|---|---|
| Detach | DELETE /firewalls/{id}/members/{vm} | The firewall's rules leave the machine. With no other firewall, it accepts all inbound traffic again. |
| Rename | PUT /firewalls/{id} with name | Rules untouched when rules is omitted. |
| Delete | DELETE /firewalls/{id} | Refused (409) while it protects a machine: deleting it would open them all at once. |
Outbound rules
A rule with "direction": "out" covers outbound traffic, to
destinations instead of coming from sources. As long as none of
a machine's firewalls has an enabled outbound allow rule, everything may go out (outbound
deny rules alone only block what they match). As soon as one does,
only what outbound rules allow goes out, plus what is always allowed:
- DNS (port 53) to the resolvers FFxF configures on the machine;
- replies to inbound connections the firewall let in;
- the private network.
{
"rules": [
{"protocol": "tcp", "ports": "22"},
{"direction": "out", "protocol": "tcp", "ports": "80,443", "description": "Updates and HTTPS"},
{"direction": "out", "protocol": "tcp", "ports": "5432", "destinations": ["198.51.100.20"], "description": "External database"}
]
}
The first outbound rule closes everything else: without the 80,443 rule
above, package updates and downloads stop. Sending sources on an outbound
rule, or destinations on an inbound one, is refused
(validation_failed) rather than silently ignored. On a machine without IPv4,
an IPv4 destination also allows its NAT64 address (64:ff9b::/96), the way such
a machine reaches IPv4 hosts. Port 25 stays closed whatever the rules say.
Useful details
Read calls need the vms.read scope; creating, changing, attaching and
deleting need network.write. The MCP server exposes the same actions: see
MCP tools.