Firewall Policies

Allowed HTTP methods

Method Description
GET get / list object/s

Note

See RFC 2616#section-9 for more details on HTTP methods semantics

Listing

GET /fwpolicies/

Gets the list of firewall policies to which the authenticated user has access.

Parameters:
  • fields – A set of field names specifying the returned fields
Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Detailed listing

GET /fwpolicies/detail/

Gets a detailed list of firewall policies to which the authenticated user has access.

Status Codes:
  • 200 – no error

Example request:

GET /api/2.0/fwpolicies/detail/?limit=0 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {
        "limit": 0,
        "offset": 0,
        "total_count": 2
    },
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        },
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

Create

POST /fwpolicies/

Creates a firewall policy.

Status Codes:
  • 201 – no error

Example request - minimal:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {}
    ]
}

Example response - minimal:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": null,
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/1973b795-343c-421b-bd97-fa7471fc6491/",
            "rules": [],
            "servers": [],
            "tags": [],
            "uuid": "1973b795-343c-421b-bd97-fa7471fc6491"
        }
    ]
}

This is the minimal data required to create a policy. It is blank one ( does not contain any rules ), but you can use it to attach it to a couple of servers and edit it later to match your needs.

Example request - full:

POST /api/2.0/fwpolicies/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "objects": [
        {
            "name": "My awesome policy",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23"
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24"
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_port": "22",
                    "ip_proto": "tcp"
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55"
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp"
                }
            ]
        }
    ]
}

Example response - full:

HTTP/1.1 201 CREATED
Content-Type: application/json; charset=utf-8

{
    "objects": [
        {
            "meta": {},
            "name": "My awesome policy",
            "owner": {
                "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
                "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
            },
            "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
            "rules": [
                {
                    "action": "drop",
                    "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
                    "direction": "out",
                    "dst_ip": "23.0.0.0/32",
                    "dst_port": null,
                    "ip_proto": null,
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "accept",
                    "comment": "Allow SSH traffic to the VM from our office in Dubai",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": "172.66.32.0/24",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all other SSH traffic to the VM",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "22",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": null,
                    "ip_proto": "udp",
                    "src_ip": "!172.66.32.55/32",
                    "src_port": null
                },
                {
                    "action": "drop",
                    "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
                    "direction": "in",
                    "dst_ip": null,
                    "dst_port": "!1:1024",
                    "ip_proto": "tcp",
                    "src_ip": null,
                    "src_port": null
                }
            ],
            "servers": [],
            "tags": [],
            "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
        }
    ]
}

This is a more useful firewall policy. The rules are applied in the order they are stated.

Note

  • The IP and port fields support ”!” prefix, which specifies “NOT” ( ex. ”!192.168.1.1” ).
  • You can specify port ranges with ”:” ( ex. “1:1024” or ”!1:1024”)
  • The IP fields support subnet definition using the CIDR notation ( ex. “192.168.1.1/24” )

Editing

PUT /fwpolicies/{uuid}/

Update an existing firewall policy

Warning

Changes are applied every 30 seconds to all running servers with nics that have the policy attached.

Status Codes:
  • 200 – no error
Example policy:
{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "accept",
            "comment": "Allow SSH traffic to the VM from our office in Dubai",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": "172.66.32.0/24",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all other SSH traffic to the VM",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "22",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop all UDP traffic to the VM, not originating from 172.66.32.55",
            "direction": "in",
            "dst_ip": null,
            "dst_port": null,
            "ip_proto": "udp",
            "src_ip": "!172.66.32.55/32",
            "src_port": null
        },
        {
            "action": "drop",
            "comment": "Drop any traffic, to the VM with destination port not between 1-1024",
            "direction": "in",
            "dst_ip": null,
            "dst_port": "!1:1024",
            "ip_proto": "tcp",
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update request:
PUT /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}
Update response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "meta": {},
    "name": "My awesome policy",
    "owner": {
        "resource_uri": "/api/2.0/user/5b4a69a3-8e78-4c45-a8ba-8b13f0895e23/",
        "uuid": "5b4a69a3-8e78-4c45-a8ba-8b13f0895e23"
    },
    "resource_uri": "/api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/",
    "rules": [
        {
            "action": "drop",
            "comment": "Drop traffic from the VM to IP address 23.0.0.0/32",
            "direction": "out",
            "dst_ip": "23.0.0.0/32",
            "dst_port": null,
            "ip_proto": null,
            "src_ip": null,
            "src_port": null
        }
    ],
    "servers": [],
    "tags": [],
    "uuid": "ffc71b41-4ce8-4eda-98f8-24c1bd808928"
}

Delete

DELETE /fwpolicies/{uuid}/

Delete a firewall policy

Warning

Only policies attached to servers in status stopped can be deleted.

Status Codes:
  • 204 – no content, object is deleted

Example request:

DELETE /api/2.0/fwpolicies/ffc71b41-4ce8-4eda-98f8-24c1bd808928/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop

Example response:

HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8

Attach policy to a server

Attaching a policy is done by specifying the policy uuid in the field firewall_policy on the server’s NIC, using the create or edit server calls

{
    "cpu": 1000, 
    "mem": 536870912, 
    "name": "FirewalledServer", 
    "nics": [
        {
            "firewall_policy": "abb98bcb-2d3c-4758-b59c-3094b54b5c9e", 
            "ip_v4_conf": {
                "conf": "dhcp", 
                "ip": null
            }, 
            "model": "virtio"
        }
    ], 
    "vnc_password": "testserver"
}

Warning

Firewall policies are only applied when attached to your server’s public network interfaces.

Default network restrictions

Depending on your account’s current state, the following network restrictions are applied to the public interfaces of your running servers:

  • regular - for REGULAR users:
    Running servers have limits set on originating broadcast and multicast traffic:
    • broadcast - limited to 5 packets/second with burst of 100
    • multicast - limited to 10 packets/second with burst of 100
  • no_outgoing_email - for new REGULAR users:

    Same as regular, but users cannot send emails from running servers.

  • trial - for TRIAL users:

    Applies regular restrictions plus running servers cannot open communication channels to ports 22, 23, 25, 7777, 43594, 43595 and 25565

  • guest - for GUEST and NEW users:

    Applies regular restrictions plus running servers can only send ICMP requests, request a DHCP IP, query a DNS server and send requests to TCP port 80 and 443 ( usually HTTP and HTTPS )

Please contact support if any of these restrictions breaks your workflow. You can check your effective network restrictions via the network_restrictions field on the user profile

Note

When converting from one user type to another, restrictions are automatically adjusted - no need to powercycle your running servers.

Schema

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "allowed_detail_http_methods": [
        "get",
        "put",
        "delete"
    ],
    "allowed_list_http_methods": [
        "get",
        "put",
        "delete",
        "post"
    ],
    "default_format": "application/json",
    "default_limit": 20,
    "fields": {
        "meta": {
            "default": {},
            "help_text": "User assigned meta information for this policy",
            "readonly": false,
            "required": false,
            "type": "dict"
        },
        "name": {
            "default": null,
            "help_text": "Human readable name of the firewall policy",
            "readonly": false,
            "required": false,
            "type": "string"
        },
        "owner": {
            "default": null,
            "help_text": "Owner of the policy",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "resource_uri": {
            "default": "No default provided.",
            "help_text": "Unicode string data. Ex: \"Hello World\"",
            "readonly": true,
            "required": true,
            "type": "string"
        },
        "rules": {
            "default": [],
            "fields": {
                "action": {
                    "choices": [
                        "drop",
                        "accept"
                    ],
                    "default": null,
                    "help_text": "Action to be taken",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "comment": {
                    "default": null,
                    "help_text": "Optional rule comment",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "direction": {
                    "choices": [
                        "in",
                        "out",
                        "both"
                    ],
                    "default": null,
                    "help_text": "Packet direction",
                    "readonly": false,
                    "required": true,
                    "type": "string"
                },
                "dst_ip": {
                    "default": null,
                    "help_text": "Destination IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "dst_port": {
                    "default": null,
                    "help_text": "Destination port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "ip_proto": {
                    "choices": [
                        "tcp",
                        "udp"
                    ],
                    "default": null,
                    "help_text": "IP protocol",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_ip": {
                    "default": null,
                    "help_text": "Source IP address",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                },
                "src_port": {
                    "default": null,
                    "help_text": "Source port",
                    "readonly": false,
                    "required": false,
                    "type": "string"
                }
            },
            "help_text": "List of rules to be applied for this policy",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "servers": {
            "default": [],
            "help_text": "Servers which have nics with this policy applied",
            "readonly": true,
            "required": false,
            "type": "related"
        },
        "tags": {
            "default": "No default provided.",
            "help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
            "readonly": false,
            "required": false,
            "type": "related"
        },
        "uuid": {
            "default": null,
            "help_text": "UUID of the policy",
            "readonly": true,
            "required": true,
            "type": "string"
        }
    },
    "filtering": {
        "name": "exact",
        "name__contains": "exact",
        "tag": "exact",
        "uuid": "exact"
    }
}