Skip to content

Add a VPS firewall rule

POST /api/v2/vps/{id}/firewall

Add an inbound rule to the VPS firewall. Check actions.canAddRule on GET /api/v2/vps/{id}/firewall first. It is false while the firewall cannot be read, while a stored rule waits for repair by support and when the VPS has 100 rules. Its reason says which. type is always in. Outbound rules and group references are read-only through the API. action is ACCEPT or DROP. When you set dport or sport, proto must be tcp or udp. Leave out source to match any IPv4 and IPv6 sender. Send enabled: true to switch the rule on at once. The new rule goes first in the list (position 0) and the other rules move down one. The response has pos: null. Read the rule list again for the positions. Rules only filter while the firewall is on (PUT /api/v2/vps/{id}/firewall/options).

Authentication: An API key with the scope write:vm. About keys and scopes

Request

Path parameters

idstringrequired
The VPS ID (vps_…).

Body

typestringrequired
Always in. The API does not create outbound rules or group references. One of in.
actionstringrequired
ACCEPT lets matching traffic in. DROP discards it. REJECT is refused for inbound rules (inbound_reject_forbidden). One of ACCEPT, DROP.
enabledboolean
true switches the rule on at once. Left out, the rule is added switched off.
protostring or null
Protocol: tcp, udp or icmp. Leave it out for all protocols. icmp allows ping over IPv4 and IPv6. With a source or dest, only over that address’s IP version. Must be tcp or udp when dport or sport is set.
dportstring or null
Port on the VPS: a port, a range such as 8000:8100 or a comma-separated list. Needs proto tcp or udp.
sportstring or null
Port on the sender’s side. Leave it out for almost every rule. It does not open a port on the VPS (that is dport). Clients connect from random ports. A rule with sport therefore matches almost nothing. Needs proto tcp or udp.
sourcestring or null
Sender address or CIDR, IPv4 or IPv6. Leave it out or send null to match any sender. 0.0.0.0/0 and ::/0 also mean any sender, over IPv4 and IPv6 alike. They are stored as no address and the response shows source: null. An IPv4 CIDR is stored as its network address (198.51.100.42/24 becomes 198.51.100.0/24).
deststring or null
Destination address or CIDR. Leave it out to match any. 0.0.0.0/0 and ::/0 also mean any, over IPv4 and IPv6 alike. Must use the same IP version as source.
descriptionstring or null
Single-line label for the rule, up to 128 characters.

Example

POST /api/v2/vps/{id}/firewall
curl -X POST "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/firewall" \
-H "Authorization: Bearer $HOSTUP_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "in",
"action": "ACCEPT",
"enabled": true,
"proto": "tcp",
"dport": "22",
"source": "198.51.100.10",
"description": "Allow SSH from office"
}'

Responses

201 Rule added.

Response 201
{
"pos": null,
"type": "in",
"action": "ACCEPT",
"enabled": true,
"proto": "tcp",
"dport": "22",
"sport": null,
"source": "198.51.100.10",
"dest": null,
"description": "Allow SSH from office",
"isSystem": false,
"editable": true
}
Response fields
posinteger or null
Null in this response. Read the rule list for positions.
typestring or null
Always in. One of in.
actionstring or null
ACCEPT lets matching traffic through. DROP discards it. REJECT refuses it. One of ACCEPT, DROP, REJECT.
enabledboolean
Whether the rule is switched on.
protostring or null
Protocol, for example tcp, udp or icmp. Null for all protocols.
dportstring or null
Port on the VPS: a port, a range such as 8000:8100 or a comma-separated list. Null for all ports.
sportstring or null
Port on the sender’s side. Null for any. It does not open a port on the VPS.
sourcestring or null
Sender address or CIDR. Null for any sender.
deststring or null
Destination address or CIDR. Null for any.
descriptionstring or null
Your label for the rule.
isSystemboolean
True for a group reference.
editableboolean
Whether you can change or delete the rule through the API.

Errors

Errors are Problem Details with a stable code. Branch on the code, not on the text.

400invalid_request. errors[] names each field. errors[].code is inbound_reject_forbidden for action: REJECT and missing_required for a port without proto.
401Unauthorized. Authentication is required.
403Forbidden. The caller lacks a required scope or does not own the resource.
404Not found. The resource does not exist or is not owned by the caller; code is vps_not_found.
409upstream_failed: the VPS is still being set up. No rule was added. Wait until serviceStatus is active on GET /api/v2/vps/{id} and try again.
422invalid_request: dport is not a port from 1 to 65535, a range such as 8000:8100 or a comma-separated list of them. Or description is longer than 128 characters. The body has no errors array.
429Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers.
500internal_error. A proto the firewall does not know also answers 500. So does a sport that is not a port, a range or a comma-separated list. Check both fields before you retry.