Skip to main content

Firewalls

Edge firewalls run at the provider's network perimeter — before traffic ever reaches your VPS. They're separate from host-level firewalls (ufw, nftables) which run on the server itself. Use both: edge for broad ingress shaping, host for fine-grained policy.

Mental model​

firewall ─────► rule set
│
└── attached_server_ids[] ─► server, server, server, ...

A firewall is a named bundle of rules + a list of servers it's attached to. One firewall can protect many servers; one server can have at most one firewall attached.

Rule shape​

Rules are evaluated in order; first match wins; the implicit default is drop. Each rule:

{
"direction": "in", // "in" or "out"
"protocol": "tcp", // "tcp" | "udp" | "icmp"
"port": "22", // or "8000-9000"; ignored for icmp
"action": "accept", // "accept" or "drop"
"source_ips": ["0.0.0.0/0"],
"description": "SSH from anywhere"
}

For out rules, use destination_ips instead of source_ips. Both fields accept IPv4 and IPv6 CIDRs.

Create a firewall (web-tier example)​

cat > /tmp/web-tier.json <<'JSON'
[
{"direction":"in","protocol":"tcp","port":"22","action":"accept",
"source_ips":["203.0.113.0/24"],"description":"SSH from office"},
{"direction":"in","protocol":"tcp","port":"80","action":"accept",
"source_ips":["0.0.0.0/0","::/0"],"description":"HTTP"},
{"direction":"in","protocol":"tcp","port":"443","action":"accept",
"source_ips":["0.0.0.0/0","::/0"],"description":"HTTPS"},
{"direction":"out","protocol":"tcp","action":"accept",
"destination_ips":["0.0.0.0/0","::/0"],"description":"any egress"},
{"direction":"out","protocol":"udp","port":"53","action":"accept",
"destination_ips":["0.0.0.0/0","::/0"],"description":"DNS"}
]
JSON

vpsctl firewalls create --name web-tier --rules-file /tmp/web-tier.json
curl -X POST https://api.vps-server.host/v1/firewalls \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq -n --slurpfile rules /tmp/web-tier.json '{
name: "web-tier",
rules: $rules[0]
}')"

Note the returned id (looks like fwl_01HRZQ...).

Attach to a server​

vpsctl firewalls attach fwl_01HRZQ... srv_42

Attaching replaces any existing firewall on that server. Propagation takes about 30 seconds.

Filtering by labels​

Just like servers, firewalls accept a labels map:

curl -X POST https://api.vps-server.host/v1/firewalls \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-d '{
"name": "db-tier",
"labels": {"env": "prod", "tier": "db"},
"rules": [...]
}'

# Later, list only prod firewalls:
vpsctl firewalls list --label-selector env=prod

The same ?label_selector=env=prod,tier=db syntax works on listServers, listSnapshots, listDomains, and listServices.

Updating rules​

rules is a full replacement, not a patch. Read the current set, edit, write back:

vpsctl firewalls get fwl_01HRZQ... -o json > /tmp/fw.json
# edit /tmp/fw.json, then:
curl -X PATCH https://api.vps-server.host/v1/firewalls/fwl_01HRZQ... \
-H "Authorization: Bearer $VPSH_API_TOKEN" \
-H "Content-Type: application/json" \
-d "$(jq '{rules: .rules}' /tmp/fw.json)"

Detaching and deleting​

vpsctl firewalls detach fwl_01HRZQ... srv_42
vpsctl firewalls delete fwl_01HRZQ... # must be detached
vpsctl firewalls delete fwl_01HRZQ... --force # detach + delete

After detach, the server falls back to the provider's default policy (usually allow-all). Attach another firewall promptly or rely on host firewalls.

Plan support​

Edge-network firewalls are available on most VPS plans. Managed-database plans don't expose them — use the database's own auth + IP allow-list on those.

attach_firewall returns 409 backend_unsupported for plans without edge firewalls. Use a host firewall (ufw / nftables) on those servers.

MCP tools​

APIMCP tool
GET /firewallslist_firewalls
GET /firewalls/{id}get_firewall
POST /firewallscreate_firewall
PATCH /firewalls/{id}update_firewall (destructive — asks for confirmation)
POST /firewalls/{id}:attachattach_firewall (destructive)
POST /firewalls/{id}:detachdetach_firewall (destructive)
DELETE /firewalls/{id}delete_firewall (destructive)

What's next​