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.