Skip to content

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

idstringrequired
The VPS ID (vps_…).
posintegerrequired
Position of the rule, rules[].pos in the rule list. The first rule is 0. At least 0.

Body

typestringrequired
Always in. The API does not replace 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 and false off. Left out, it keeps its current state.
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

PUT /api/v2/vps/{id}/firewall/{pos}
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.

Response 200
{
"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 null
Position in the rule list. The first rule is 0.
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 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.
404vps_not_found: no VPS with this ID in your account. not_found: no rule at this position. Read the rule list again.
409upstream_failed: the VPS is still being set up. Nothing was changed. Try again when serviceStatus is active.
422invalid_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.
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. Read the rule list before you retry.
503upstream_failed: the current rules could not be read. Nothing was changed. Try again shortly.