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
idstringrequiredvps_…).Body
typestringrequiredin. The API does not create outbound rules or group references. One of in.actionstringrequiredACCEPT lets matching traffic in. DROP discards it. REJECT is refused for inbound rules (inbound_reject_forbidden). One of ACCEPT, DROP.enabledbooleantrue switches the rule on at once. Left out, the rule is added switched off.protostring or nulltcp, 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 null8000:8100 or a comma-separated list. Needs proto tcp or udp.sportstring or nulldport). Clients connect from random ports. A rule with sport therefore matches almost nothing. Needs proto tcp or udp.sourcestring or null0.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 null0.0.0.0/0 and ::/0 also mean any, over IPv4 and IPv6 alike. Must use the same IP version as source.descriptionstring or nullExample
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.
{ "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 nulltypestring or nullin. One of in.actionstring or nullACCEPT lets matching traffic through. DROP discards it. REJECT refuses it. One of ACCEPT, DROP, REJECT.enabledbooleanprotostring or nulltcp, udp or icmp. Null for all protocols.dportstring or null8000:8100 or a comma-separated list. Null for all ports.sportstring or nullsourcestring or nulldeststring or nulldescriptionstring or nullisSystembooleaneditablebooleanErrors
Errors are Problem Details with a stable code. Branch on the code, not on the text.
| 400 | invalid_request. errors[] names each field. errors[].code is inbound_reject_forbidden for action: REJECT and missing_required for a port without proto. |
| 401 | Unauthorized. Authentication is required. |
| 403 | Forbidden. The caller lacks a required scope or does not own the resource. |
| 404 | Not found. The resource does not exist or is not owned by the caller; code is vps_not_found. |
| 409 | upstream_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. |
| 422 | invalid_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. |
| 429 | Rate limited. Retry after the limit resets. 429 responses include Retry-After seconds plus X-RateLimit-* headers. |
| 500 | internal_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. |