Firewall

UpCloud servers include a configurable software firewall that can be used to filter network traffic. The firewall operates at the network layer and can filter traffic based on IP addresses, ports, and protocols.

The firewall must be enabled on a per-server basis through the server configuration (firewall: "on"). Once enabled, firewall rules can be managed through these API endpoints.

Rules are processed in order by position, with the first matching rule being applied. The maximum number of firewall rules per server is 1000. Please allow 1-2 minutes for firewall changes to take effect.

GET/1.3/server/{uuid}/firewall_rule

List firewall rules

Returns a list of all firewall rules for a specific server.

Response fields

Name
action
Type
string
Description
Rule action: "accept" or "drop".
Name
direction
Type
string
Description
Traffic direction: "in" or "out".
Name
family
Type
string
Description
Address family: "IPv4" or "IPv6".
Name
protocol
Type
string
Description
Protocol: "tcp", "udp", or "icmp".
Name
position
Type
string
Description
Rule position in the firewall chain (1-1000).
Name
source_address_start
Type
string
Description
Start of source IP address range.
Name
source_address_end
Type
string
Description
End of source IP address range.
Name
destination_port_start
Type
string
Description
Start of destination port range.
Name
destination_port_end
Type
string
Description
End of destination port range.
Name
icmp_type
Type
string
Description
ICMP type (0-255) when protocol is ICMP.
Name
comment
Type
string
Description
Optional rule description.

Request

GET

/1.3/server/{uuid}/firewall_rule

curl -X GET https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule \
  -u your_username:your_password

GET/1.3/server/{uuid}/firewall_rule/{index}

Get firewall rule details

Returns details about a specific firewall rule by its position index.

Request

GET

/1.3/server/{uuid}/firewall_rule/{index}

curl -X GET https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule/1 \
  -u your_username:your_password

POST/1.3/server/{uuid}/firewall_rule

Create firewall rule

Creates a new firewall rule for a server.

If used, IP address and port ranges must have both start and end values specified (these can be the same for single values). Source and destination port numbers can only be set if the protocol is TCP or UDP. The ICMP type may only be set if the protocol is ICMP.

The last rule should be the default rule containing only direction and action attributes.

Required attributes

Name
direction
Type
string
Description
Traffic direction: "in" or "out". Required.
Name
action
Type
string
Description
Rule action: "accept" or "drop". Required.
Name
family
Type
string
Description
Address family: "IPv4" or "IPv6". Required if protocol is set.

Optional attributes

Name
position
Type
integer
Description
Position in the firewall chain (1-1000).
Name
protocol
Type
string
Description
Protocol: "tcp", "udp", or "icmp".
Name
source_address_start
Type
string
Description
Start of source IP address range.
Name
source_address_end
Type
string
Description
End of source IP address range.
Name
source_port_start
Type
string
Description
Start of source port range (TCP/UDP only).
Name
source_port_end
Type
string
Description
End of source port range (TCP/UDP only).
Name
destination_address_start
Type
string
Description
Start of destination IP address range.
Name
destination_address_end
Type
string
Description
End of destination IP address range.
Name
destination_port_start
Type
string
Description
Start of destination port range (TCP/UDP only).
Name
destination_port_end
Type
string
Description
End of destination port range (TCP/UDP only).
Name
icmp_type
Type
string
Description
ICMP type (0-255, ICMP protocol only).
Name
comment
Type
string
Description
Optional rule description.

Request

POST

/1.3/server/{uuid}/firewall_rule

curl -X POST https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "firewall_rule": {
      "position": "1",
      "direction": "in",
      "family": "IPv4",
      "protocol": "tcp",
      "source_address_start": "192.168.1.1",
      "source_address_end": "192.168.1.255",
      "destination_port_start": "22",
      "destination_port_end": "22",
      "action": "accept",
      "comment": "Allow SSH from this network"
    }
  }'

PUT/1.3/server/{uuid}/firewall_rule

Create multiple rules

Creates multiple firewall rules at once. This will overwrite any previous chain of rules.

The order of the firewall rules is defined by the index of the firewall_rule array. The last rule should be the default rule containing only direction and action attributes.

Request

PUT

/1.3/server/{uuid}/firewall_rule

curl -X PUT https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule \
  -u your_username:your_password \
  -H "Content-Type: application/json" \
  -d '{
    "firewall_rules": {
      "firewall_rule": [
        {
          "direction": "in",
          "family": "IPv4",
          "protocol": "tcp",
          "destination_port_start": "22",
          "destination_port_end": "22",
          "action": "accept",
          "comment": "Allow SSH"
        },
        {
          "direction": "in",
          "family": "IPv4",
          "protocol": "tcp",
          "destination_port_start": "80",
          "destination_port_end": "80",
          "action": "accept",
          "comment": "Allow HTTP"
        },
        {
          "direction": "in",
          "family": "IPv4",
          "protocol": "tcp",
          "destination_port_start": "443",
          "destination_port_end": "443",
          "action": "accept",
          "comment": "Allow HTTPS"
        },
        {
          "direction": "in",
          "action": "drop"
        }
      ]
    }
  }'

DELETE/1.3/server/{uuid}/firewall_rule/{index}

Remove firewall rule

Removes a firewall rule from a server by its position index. The positions of remaining firewall rules will be adjusted after a rule is removed.

The index of the first rule is 1.

Request

DELETE

/1.3/server/{uuid}/firewall_rule/{index}

curl -X DELETE https://api.upcloud.com/1.3/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule/2 \
  -u your_username:your_password