Replace a VPS firewall rule
PUT /api/v2/vps/{id}/firewall/{pos}
Replace the inbound firewall rule at position pos with the rule in the body. The body is the whole rule, not a patch. proto, dport, sport, source, dest and description that you leave out or send as null are cleared. enabled left out keeps its current value. Read GET /api/v2/vps/{id}/firewall right before and take pos from the rule you mean. Rules have no ID and the call does not check for changes. If another client changed the list in between, it replaces whatever rule is at pos now. type is always in. Replace only rules with editable: true. Outbound rules and group references are read-only and answer 403. A key that also holds write:network and write:services skips that check. It overwrites any rule at pos. An empty pos then answers 500. 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. The response is the rule as stored after the change. A rule sent with proto: "icmp" comes back with proto: null in this response. GET /api/v2/vps/{id}/firewall shows it as icmp.
Authentication: An API key with the scope write:vm. About keys and scopes
Request
Path parameters
idstringrequiredvps_…).posintegerrequiredrules[].pos in the rule list. The first rule is 0. At least 0.Body
typestringrequiredin. The API does not replace 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 and false off. Left out, it keeps its current state.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 PUT "https://cloud.hostup.se/api/v2/vps/vps_01hxa3b4c5d6e7f8g9h0j1k2m3/firewall/0" \ -H "Authorization: Bearer $HOSTUP_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "type": "in", "action": "ACCEPT", "enabled": true, "proto": "tcp", "dport": "443", "source": null, "description": "Allow HTTPS" }'Responses
200 The rule as stored after the change.
{ "pos": 0, "type": "in", "action": "ACCEPT", "enabled": true, "proto": "tcp", "dport": "443", "sport": null, "source": null, "dest": null, "description": "Allow HTTPS", "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 key lacks the scope, or the rule at pos is an outbound rule or a group reference. A missing scope is named in detail and requiredScopes. An outbound rule or a group reference gets a general detail and no requiredScopes. Check editable in the rule list. |
| 404 | vps_not_found: no VPS with this ID in your account. not_found: no rule at this position. Read the rule list again. |
| 409 | upstream_failed: the VPS is still being set up. Nothing was changed. Try again when serviceStatus is active. |
| 422 | invalid_request: dport or sport is not a port from 1 to 65535, a range or a comma-separated list. 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. Read the rule list before you retry. |
| 503 | upstream_failed: the current rules could not be read. Nothing was changed. Try again shortly. |