Guides

Configuring firewalls

Create a firewall group, add allow and block rules in one request, apply the group to an address, and change rules afterwards.

A firewall group holds rules and applies them to every address it is assigned to. The example group suits a web server that also answers DNS: HTTP and HTTPS from anywhere, SSH from one office network and from nowhere else, DNS queries capped at a packet rate, and ping allowed. Groups can be managed in the cloud console at https://cloud.serverside.com as well as through the API, and both edit the same groups.

Create the group

Create firewall group takes a name:

curl --request POST \
  --url https://api.serverside.com/v1/networking/firewall/groups \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "web-servers"
}
'

The name takes up to 50 characters. The response's data.id is the group's id, which the rule, assignment and update requests take as {groupId}.

Add rules

Create firewall rules takes an array, so one request can carry the whole rule set:

curl --request POST \
  --url https://api.serverside.com/v1/networking/firewall/groups/{groupId}/rules \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "type": "ALLOW",
    "direction": "INBOUND",
    "protocol": "TCP",
    "destPortStart": 80,
    "description": "HTTP"
  },
  {
    "type": "ALLOW",
    "direction": "INBOUND",
    "protocol": "TCP",
    "destPortStart": 443,
    "description": "HTTPS"
  },
  {
    "type": "ALLOW",
    "direction": "INBOUND",
    "protocol": "TCP",
    "destPortStart": 22,
    "sourceAddress": "203.0.113.0/24",
    "description": "SSH from the office"
  },
  {
    "type": "BLOCK",
    "direction": "INBOUND",
    "protocol": "TCP",
    "destPortStart": 22,
    "description": "SSH from anywhere else"
  },
  {
    "type": "RATE_LIMIT",
    "direction": "INBOUND",
    "protocol": "UDP",
    "destPortStart": 53,
    "rateLimitPps": 5000,
    "description": "DNS rate limit"
  },
  {
    "type": "ALLOW",
    "direction": "INBOUND",
    "protocol": "ICMP",
    "description": "Ping"
  }
]
'

The response lists the rules as stored, each with its id and priority, and List firewall rules returns them again later. Priority follows the order of the array, so the office ALLOW on port 22 gets a lower number than the BLOCK after it.

A RATE_LIMIT rule caps matching traffic at rateLimitPps packets per second. The 5000 here shows the shape of the rule and is not a recommended value: measure the query rate your DNS server sees at its busiest and set the limit above it.

What the API checks

The API checks every rule in the request and answers VALIDATION_FAILED, naming the broken rule in message, when one breaks these rules:

Ports belong to TCP, UDP and ANY rules only. On ANY, ports match TCP and UDP traffic on those ports. An ICMP, ICMP_V6 or GRE rule with a port is refused.
Port ranges: a start alone matches one port, a start and an end match the range, and leaving both out matches every port. An end without a start is refused, as is a start above its end. Ports run from 1 to 65535.
Rate limits: a RATE_LIMIT rule needs rateLimitPps above zero, and any other type must leave it out.
Packet length: packetCriteria.minPacketLength and maxPacketLength take values from 64 to 9000 bytes.
Descriptions take up to 100 characters.

sourceAddress is a network in CIDR form. A rule without one applies to every source.

How rules are applied

Rules run on the access switch your server connects to, so a packet a rule blocks is dropped before it reaches the server. They filter traffic from other Serverside public addresses as well as from the internet. A packet is checked against the rules in priority order, lowest number first. Traffic that no rule matches is allowed. Restricting a port therefore takes two rules: an ALLOW for the sources you permit, followed by a BLOCK for the rest. In the example, SSH from 203.0.113.0/24 matches the ALLOW and SSH from any other source reaches the BLOCK.

Only INBOUND rules are enforced today. The API accepts and stores OUTBOUND rules, and the switches do not apply them. A group applies to public addresses only, so traffic on a private network is never filtered by it.

Find the address to protect

Assignments point at an address entity, not at the address itself. The entity ids are listed with the prefix that holds the address: take the public network and the prefix from Get virtual network, then Get IPv4 prefix:

curl --request GET \
  --url https://api.serverside.com/v1/networking/spn/{spnId}/prefixes/v4/{prefixId} \
  --header 'X-API-KEY: <api-key>'

In data.addresses, the entry whose address is the one to protect (198.51.100.25 in this example) carries the entity id as its id.

Assigning an address to a server also returns its id, as ipAddressEntityId; see Managing IP addresses.

Apply the group

Assign firewall group to IP with the entity id:

curl --request POST \
  --url https://api.serverside.com/v1/networking/firewall/groups/{groupId}/assignments \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ipAddressEntityId": "<address-entity-id>"
}
'

The call answers 204. Get firewall group returns the group's rules and its assignedIpAddressIds; Remove firewall group from IP takes the same entity id in the path to undo an assignment.

One address can carry more than one group. Their rules are then matched as one list: the lowest priority number wins across every group on the address, so an ALLOW at priority 2 in one group is matched before a BLOCK at priority 5 in another.

Change rules later

Update firewall rule is a PATCH, but it replaces every field of the rule, so send the whole rule with the one value changed. A rule change takes effect immediately. isEnabled: false switches a rule off without deleting it, which is the quick way to test whether a rule is what blocks some traffic. This request switches off the SSH BLOCK from the example:

curl --request PATCH \
  --url https://api.serverside.com/v1/networking/firewall/groups/{groupId}/rules/{ruleId} \
  --header 'X-API-KEY: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "BLOCK",
  "direction": "INBOUND",
  "protocol": "TCP",
  "destPortStart": 22,
  "description": "SSH from anywhere else",
  "isEnabled": false
}
'

To reorder rules, send the rule ids in their new order as ruleOrder to Update firewall group. Delete firewall rule and Delete firewall group remove them for good.