FIREWALL
Each server has its own firewall rules. The firewall is enabled on all network interfaces.
The firewall filters packets by:
- Traffic direction (in, out)
- IP family (IPv4, IPv6)
- Network protocol (TCP, UDP, ICMP)
- Source and/or destination IP addresses
- For TCP and UDP protocols, the source and/or destination ports
- For the ICMP protocol, the packet type
Network traffic is checked against the firewall rules in numerical order starting from the first rule. It is important to add the firewall rules in the correct order to make sure the firewall functions properly. Place the most specific rules first and the more generic rules later.
The firewall takes two different actions based on the applied rules.
Accept lets the packet pass the firewall and Drop blocks the traffic.
List firewall rules
Returns a list of firewall rules for a specific server.
Request
GET /1.2/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule
Normal response
HTTP/1.0 200 OK
{
"firewall_rules": {
"firewall_rule": [
{
"action": "accept",
"comment": "Allow HTTP from anywhere",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "80",
"destination_port_start": "80",
"direction": "in",
"family": "IPv4",
"icmp_type": "",
"position": "1",
"protocol": "",
"source_address_end": "",
"source_address_start": "",
"source_port_end": "",
"source_port_start": ""
},
{
"action": "accept",
"comment": "Allow SSH from a specific network only",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "22",
"destination_port_start": "22",
"direction": "in",
"family": "IPv4",
"icmp_type": "",
"position": "2",
"protocol": "tcp",
"source_address_end": "192.168.1.255",
"source_address_start": "192.168.1.1",
"source_port_end": "",
"source_port_start": ""
},
{
"action": "accept",
"comment": "Allow SSH over IPv6 from this range",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "22",
"destination_port_start": "22",
"direction": "in",
"family": "IPv6",
"icmp_type": "",
"position": "3",
"protocol": "tcp",
"source_address_end": "2a04:3540:1000:aaaa:bbbb:cccc:d001",
"source_address_start": "2a04:3540:1000:aaaa:bbbb:cccc:d001",
"source_port_end": "",
"source_port_start": ""
},
{
"action": "accept",
"comment": "Allow ICMP echo request (ping)",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "",
"destination_port_start": "",
"direction": "in",
"family": "IPv4",
"icmp_type": "8",
"position": "4",
"protocol": "icmp",
"source_address_end": "",
"source_address_start": "",
"source_port_end": "",
"source_port_start": ""
},
{
"action": "drop",
"comment": "",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "",
"destination_port_start": "",
"direction": "in",
"family": "",
"icmp_type": "",
"position": "5",
"protocol": "",
"source_address_end": "",
"source_address_start": "",
"source_port_end": "",
"source_port_start": ""
}
]
}
}
Get firewall rule details
Returns detailed information about a specific firewall rule.
Request
GET /1.2/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule/1
The last number denotes the index of the firewall rule in the server's firewall rule list. The index of the first rule is 1.
Normal response
HTTP/1.0 200 OK
{
"firewall_rule": {
"action": "accept",
"comment": "Allow HTTP from anywhere",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "80",
"destination_port_start": "80",
"direction": "in",
"family": "IPv4",
"icmp_type": "",
"position": "1",
"protocol": "",
"source_address_end": "",
"source_address_start": "",
"source_port_end": "",
"source_port_start": ""
}
}
Create firewall rule
Creates a new firewall rule.
If used, IP address and port ranges must have both start and end values specified. These can be the same value if only one IP address or port number is specified. 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 maximum number of firewall rules per server is 1000.
The order of the firewall rules is set with a the position attribute.
The position of the first rule is always 1. Firewall rule positions are always
successive numbers. The rule positions will be adjusted accordingly when rules
are added or deleted. The last rule is a special case and corresponds to
Default Rule set through Control Panel. It should contain only direction and
action attributes in addition to position.
Request
POST /1.2/server/00798b85-efdc-41ca-8021-f6ef457b8531/firewall_rule
{
"firewall_rule": {
"position": "1",
"direction": "in",
"family": "IPv4",
"protocol": "tcp",
"source_address_start": "192.168.1.1",
"source_address_end": "192.168.1.255",
"source_port_end": "",
"source_port_start": "",
"destination_address_start": "",
"destination_address_end": "",
"destination_port_start": "22",
"destination_port_end": "22",
"icmp_type": "",
"action": "accept",
"comment": "Allow SSH from this network"
}
}
Attributes
| Attribute | Accepted values | Required | Description |
|---|---|---|---|
| direction | in / out | yes | The direction of network traffic this rule will be applied to. |
| action | accept / drop | yes | Action to take if the rule conditions are met. |
| position | 1-1000 | no | Add the firewall rule to this position in the server's firewall list. |
| family | IPv4 / IPv6 | yes | if protocol is set The address family of new firewall rule |
| protocol | tcp / udp / icmp | no | The protocol this rule will be applied to. |
| icmp_type | 0-255 | no | The ICMP type. |
| destination_address_start | Valid IP address | yes if destination_address_end is set | The destination address range starts from this address. |
| destination_address_end | Valid IP address | yes if destination_address_start is set | The destination address range ends to this address. |
| destination_port_start | 1-65535 | yes if destination_port_end is set | The destination port range starts from this port number. |
| destination_port_end | 1-65535 | yes if destination_port_start is set | The destination port range ends to this port number. |
| source_address_start | Valid IP address | yes if source_address_end is set | The source address range starts from this address. |
| source_address_end | Valid IP address | yes if source_address_start is set | The source address range ends to this address. |
| source_port_start | 1-65535 | yes if source_port_end is set | The source port range starts from this port number. |
| source_port_end | 1-65535 | yes if source_port_start is set | The source port range ends to this port number. |
| comment | 0-250 characters | no | Freeform comment string for the rule. |
Note: No default value is set to attributes.
Normal response
HTTP/1.0 201 Created
{
"firewall_rule": {
"action": "accept",
"comment": "Allow SSH from this network",
"destination_address_end": "",
"destination_address_start": "",
"destination_port_end": "80",
"destination_port_start": "80",
"direction": "in",
"family": "IPv4",
"icmp_type": "",
"position": "1",
"protocol": "",
"source_address_end": "",
"source_address_start": "",
"source_port_end": "",
"source_port_start": ""
}
}
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | DIRECTION_INVALID | The attribute direction has an invalid value. |
| 400 Bad Request | DIRECTION_MISSING | The required attribute direction is missing from the request. |
| 400 Bad Request | ACTION_INVALID | The attribute action has an invalid value. |
| 400 Bad Request | ACTION_MISSING | The required attribute action is missing from the request. |
| 400 Bad Request | ICMP_TYPE_INVALID | The attribute icmp_type has an invalid value. |
| 400 Bad Request | DESTINATION_ADDRESS_ORDER_ILLEGAL | The destination end address is smaller than the destination start address. |
| 400 Bad Request | DESTINATION_ADDRESS_START_INVALID | The attribute destination_address_start has an invalid value. |
| 400 Bad Request | DESTINATION_ADDRESS_END_INVALID | The attribute destination_address_end has an invalid value. |
| 400 Bad Request | DESTINATION_PORT_ORDER_ILLEGAL | The destination end port is smaller than the destination start port. |
| 400 Bad Request | DESTINATION_PORT_START_INVALID | The attribute destination_port_start has an invalid value. |
| 400 Bad Request | DESTINATION_PORT_END_INVALID | The attribute destination_port_end has an invalid value. |
| 400 Bad Request | ICMP_TYPE_PROTOCOL_MISMATCH | The icmp_type attribute was specified, but protocol was not icmp. |
| 400 Bad Request | PORT_PROTOCOL_MISMATCH | Port numbers were specified but protocol was not tcp or udp. |
| 400 Bad Request | POSITION_INVALID | The attribute position has an invalid value. |
| 400 Bad Request | PROTOCOL_INVALID | The attribute protocol has an invalid value. |
| 400 Bad Request | SERVER_INVALID | The server UUID was invalid. |
| 400 Bad Request | SOURCE_ADDRESS_ORDER_ILLEGAL | The source end address is smaller than the source start address. |
| 400 Bad Request | SOURCE_ADDRESS_START_INVALID | The attribute source_address_start has an invalid value. |
| 400 Bad Request | SOURCE_ADDRESS_END_INVALID | The attribute source_address_end has an invalid value. |
| 400 Bad Request | SOURCE_PORT_ORDER_ILLEGAL | The source end port is smaller than the source start port. |
| 400 Bad Request | SOURCE_PORT_START_INVALID | The attribute source_port_start has an invalid value. |
| 400 Bad Request | SOURCE_PORT_END_INVALID | The attribute source_port_end has an invalid value. |
| 400 Bad Request | COMMENT_INVALID | The attribute comment has an invald value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 409 Conflict | FIREWALL_RULE_EXISTS | An identical rule already exist for this server. |
| 409 Conflict | FIREWALL_RULE_LIMIT_REACHED | The limit of the number of firewall rules for this server has been reached. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |
Remove firewall rule
Removes a firewall rule from a server. Firewall rules must be removed individually. The positions of remaining firewall rules will be adjusted after a rule is removed.
Request
DELETE /1.2/server/UUID/firewall_rule/position
Attributes
| Attribute | Possible values | Default value | Required | Description |
|---|---|---|---|---|
| position | 1-1000 | yes | Position of the firewall rule to remove. |
Normal response
HTTP/1.0 204 No Content
Error responses
| HTTP status | Error code | Description |
|---|---|---|
| 400 Bad Request | POSITION_INVALID | The attribute position has an invalid value. |
| 400 Bad Request | SERVER_INVALID | The server UUID has an invalid value. |
| 403 Forbidden | SERVER_FORBIDDEN | The server exists, but is owned by another account. |
| 404 Not Found | SERVER_NOT_FOUND | The server does not exist. |
| 404 Not Found | FIREWALL_RULE_NOT_FOUND | The firewall rule does not exist. |
| 409 Conflict | SERVER_STATE_ILLEGAL | The server is in a state in which it cannot be used. See Server states. |