API

Firewalls

The simplest solution for most customers is to configure a firewall within their Instances using either iptables which is powerful or Uncomplicated Firewall/ufw which is much simpler but only works on Ubuntu.

As an another option, customers can configure custom firewall rules for their instances using the Firewall API which adjusts the security group for your network of instances. These are a freely configurable option, however customers should be careful to not lock out their access to the instances.

This API is effectively split in to two parts: 1) Managing firewalls themselves, and 2) Managing rules within those firewalls. Then you will need to call PUT /v2/instances/:id afterwards setting firewall_id to the ID of your firewall.

Create a new firewall

Any user can create firewalls for their network of instances, there is a quota'd limit to the number of firewalls that can be created, but generally this is much higher than most customers will require and it can be increased if required.

New firewalls are created by sending a POST request to https://api.civo.com/v2/firewalls.

Request

There are no URL parameters and only one POST parameter

Name Description
name (required) a unique name for this firewall within your account
network_id (required) network ID for the network in which you wish to create the firewall
region (required) the identifier for the region, from the current region list

Response

The response is a JSON object that confirms the details given.

{
    "result": "success",
    "name": "test",
    "id": "af5f3bae-38f7-496c-9561-283ae1349915"
}

Example of creating a firewall

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls \
  -d "name=test&network_id=5c16ab17-933a-46ed-96c6-8a093a0179e1&region=LON1"
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/firewalls',
  {
    form: {
      name: 'instance-123456'
    }
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/firewalls', 'name=instance-123456', headers)

List firewalls

A list of all firewalls within your account are available by sending a GET request to https://api.civo.com/v2/firewalls.

Request

This request accepts an optional region parameter (query string) containing the name of the region where the firewall is located. A random one will be picked by the system if not specified.

Response

The response is a JSON array of objects that describes summary details for each instance. It shows clearly how many rules it contains and how many instances are currently configured to be using it (you can share firewalls between multiple instances).

[
    {
        "id": "cde686be-6fbd-48e8-9777-83d805853235",
        "name": "Default (all open)",
        "account_id": "433e075e-37ac-4533-8b74-4a6d7337b394",
        "rules_count": 3,
        "instances_count": null,
        "default": "true",
        "label": null,
        "network_id": "5c16ab17-933a-46ed-96c6-8a093a0179e1"
    },
    {
        "id": "af5f3bae-38f7-496c-9561-283ae1349915",
        "name": "test",
        "account_id": "433e075e-37ac-4533-8b74-4a6d7337b394",
        "rules_count": 0,
        "instances_count": null,
        "default": "false",
        "label": null,
        "network_id": "5c16ab17-933a-46ed-96c6-8a093a0179e1"
    }
]

Example of listing firewalls

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/firewalls',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
     console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/firewalls', headers)

Deleting a firewall

An account holder can remove a firewall, freeing up the space used within their quota by sending a DELETE request to https://api.civo.com/v2/firewalls/:id. Note: Firewalls can exist even if the instances have all be removed, so if you are not setting up a firewall per instance, you should monitor the list of firewalls for any that has a zero instance_count and delete them, or their take up quota allocation.

Request

This request requires the ID parameter in the URL (query string) as well as a region parameter containing the name of the region where the firewall is located. No confirmation step is required; this step will remove the firewall immediately.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 200 OK.

{
  "result": "success"
}

Example of deleting a firewall

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a', headers)

Create a new firewall rule

An account holder can create firewall rules for a specific firewall, but there is a quota'd limit to the number of rules that can be created, but generally this is much higher than most customers will require and it can be increased if required.

New firewall rules are created by sending a POST request to https://api.civo.com/v2/firewalls/:firewall_id/rules.

Request

The following parameter are required for setting firewall rules (note: there's no allow/deny choice as the default for a new firewall is to deny everything, so you only need to open the ports/port ranges needed):

Name Description
region (required) the identifier for the region, from the current region list
protocol (required) the protocol choice from tcp, udp or icmp (default is tcp)
start_port (required) the start of the port range to configure for this rule (or the single port)
end_port (optional) the end of the port range
cidr (optional) the CIDR notation of the other end (i.e. not your instance) to affect (defaults to being globally applied, i.e. 0.0.0.0/0)
direction (optional) will this rule affect inbound or outbound traffic (default is ingress)
label (optional) a string that will be the displayed name/reference for this rule

Response

The response is a JSON object that confirms the details given.

{
    "id": "becc5419-510e-4385-9c69-d038622e4e08",
    "firewall_id": "663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7",
    "protocol": "tcp",
    "start_port": "443",
    "cidr": [
        "0.0.0.0/0"
    ],
    "direction": "ingress",
    "label": ""
}

Example of creating a firewall rule

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls/663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7/rules \
  -d "region=LON1&protocol=tcp&start_port=443"
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.post(
  'https://api.civo.com/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules',
  {
    start_port: 443
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules', 'start_port=443', headers)

List firewall rules

A list of all firewall rules in the specified firewall is available by sending a GET request to https://api.civo.com/v2/firewalls/:firewall_id/rules.

Request

This request require region parameter (query string) containing the name of the region where the rule is located.

Response

The response is a JSON array of objects that describes summary details for each instance.

[
    {
        "id": "becc5419-510e-4385-9c69-d038622e4e08",
        "firewall_id": "663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7",
        "protocol": "tcp",
        "start_port": "443",
        "cidr": [
            "0.0.0.0/0"
        ],
        "direction": "ingress",
        "label": ""
    }
]

Example of listing firewall rules

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls/663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7/rules?region=LON1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.get(
  'https://api.civo.com/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules', headers)

Deleting a firewall rule

An account holder can remove a firewall rule, freeing up the usage of their quota by sending a DELETE request to https://api.civo.com/v2/firewalls/:firewall_id/rules/:id.

Request

This request requires the firewall ID and rule ID parameters in the URL (query string) as well as a region parameter containing the name of the region where the rule is located. No confirmation step is required; this step will remove the rule immediately.

Response

The response from the server will be a JSON block. The response will include a result field and the HTTP status will be 202 Accepted.

{
    "result": "success",
    "id": "663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7",
    "name": "test"
}

Example of deleting a firewall rule

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/firewalls/663ee5a0-d3a6-4b5b-9a93-144fcd48d6a7/rules/becc5419-510e-4385-9c69-d038622e4e08?region=LON1
// At a shell prompt run:
// npm init -y
// npm i --save request

var request = require('request');

request.del(
  'https://api.civo.com/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules/1d0b4bec-2e94-44bd-9c08-8927aefa99cd',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
require 'net/http'

http = Net::HTTP.new('api.civo.com', 443)
http.use_ssl = true

headers = {
  'Authorization' => 'bearer 12345',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/firewalls/84c38c6b-e7ae-43c9-b8d2-7294cb811e1a/rules/1d0b4bec-2e94-44bd-9c08-8927aefa99cd', headers)