Firewall Policies¶
Allowed HTTP methods¶
Method | Description |
---|---|
GET | get / list object/s |
Note
See RFC 2616 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" } }