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 rules within those firewalls. Then you will need to call PUT /v2/instances/:id afterwards setting firewall_id to the ID of your firewall. If you set firewall_ID to default it will reset it back to the default 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 A unique name for this firewall within your account

Response

The response is a JSON object that confirms the details given, with a null for firewall rule_at (as it won't have been taken yet).

{
  "result": "success"
}

Example of creating a firewall

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls/instance-12345 \
  -d day=1&hour=6&repeat=true
var request = require('request');

request.post(
  'https://api.civo.com/v2/firewalls/instance-12345',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/firewalls/instance-12345', 'day=1&hour=6&repeat=true', 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 takes no parameters.

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).

[
  {
    "name": "instance-12345",
    "instance_count": 10,
    "rules_count": 3
  }
]

Example of listing firewalls

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls
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');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  '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 takes no parameters except the ID of the firewall to delete is in the URL. 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 202 Accepted.

{
  "result": "success"
}

Example of deleting a firewall

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/firewalls/12345
var request = require('request');

request.del(
  'https://api.civo.com/v2/firewalls/12345',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/firewalls/12345', 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/:name/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
protocol the protocol choice from tcp, udp or icmp (the default if unspecified is tcp)
start_port the start of the port range to configure for this rule (or the single port if required)
end_port the end of the port range (this is optional, by default it will only apply to the single port listed in start_port)
cidr the IP address of the other end (i.e. not your instance) to affect, or a valid network CIDR (defaults to being globally applied, i.e. 0.0.0.0/0)
direction will this rule affect inbound or outbound traffic (by default this is inbound)

Response

The response is a JSON object that confirms the details given, with a null for firewall rule_at (as it won't have been taken yet).

{
  "result": "success",
  "id": "12345678"
}

Example of creating a firewall rule

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls/instance-12345/rules \
  -d start_port=443
var request = require('request');

request.post(
  'https://api.civo.com/v2/firewalls/instance-12345/rules',
  {
    start_port: 443
  },
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.post('/v2/firewalls/instance-12345/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/:name/rules.

Request

This request takes no parameters.

Response

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

[
  {
    "id": "12345678-9012-3456-7890-123456789012",
    "protocol": "tcp",
    "start_port": "0",
    "end_port": "65535",
    "cidr": "0.0.0.0/0",
    "direction": "inbound",
    "restriction": "allow"
  }
]

Example of listing firewall rules

curl -H "Authorization: bearer 12345" https://api.civo.com/v2/firewalls/instance-12345/rules
var request = require('request');

request.get(
  'https://api.civo.com/v2/firewalls/instance-12345/rules',
  {},
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.get('/v2/firewalls/instance-12345/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/:name/rules/:id.

Request

This request takes no parameters, the ID of the firewall rule to delete and the name of the firewall are in the URL. No confirmation step is required, this step will remove the firewall 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"
}

Example of deleting a firewall rule

curl -H "Authorization: bearer 12345" \
  -X DELETE https://api.civo.com/v2/firewalls/instance-12345/rules/12345678-9012-3456-7890-123456789012
var request = require('request');

request.del(
  'https://api.civo.com/v2/firewalls/instance-12345/rules/12345678-9012-3456-7890-123456789012',
  function (error, response, body) {
    if (!error && response.statusCode == 200) {
      console.log(body)
    }
  }
).auth(null, null, true, '12345');
http = Net::HTTPS.new('api.civo.com', 443)
headers = {
  'Authorization' => 'bearer 123456',
  'Content-Type' => 'application/x-www-form-urlencoded'
}

resp, data = http.delete('/v2/firewalls/instance-12345/rules/12345678-9012-3456-7890-123456789012', headers)