2015/07/20 - Apache Deltacloud has been retired.

For more information, please explore the Attic.

Deltacloud API


Firewalls

Firewalls represent sets of rules that govern the accessibility of a running instance over the public Internet. At present, only Amazon EC2 cloud (Amazon EC2 'Security Groups') and Fujitsu GCP support this collection. A firewall has these attributes:

  • a name
  • a description
  • an owner_id
  • set of rules

For Amazon EC2, an instance is launched into a firewall by specifying the firewalls1 ... firewallsN parameters in the POST /api/instances operation (see the Create an instance section).

Each firewall rule has a number of attributes describing the access granted to clients that want to communicate with the instance over the Internet. Each rule consists of

  • an allow_protocol (tcp, udp or icmp);
  • a port_from and a port_to that delimit the port range for access; and
  • a sources list, which can contain firewalls (i.e. allow instances in another firewall to communicate with instances in the firewall in which this rule exists), or a number of IP addresses in CIDR format, or a mix of both.

Each rule also specifies a direction, indicating whether it applies to ingress or egress traffic. A rule can also specify a rule_action (accept, deny), to indicate whether the firewall should accept or deny access for this traffic, and log_rule (true, false), to indicate whether an entry should be added to the log.

As Amazon EC2 has no notion of a firewall rule ID, the Deltacloud server constructs one ID for each rule as the concatenation of its attributes. The format used is: owner_id~protocol~from_port~to_port~@sources.

As explained above a source can be the address type in which case it defines an IP type (ipv4/ipv6), an IP address and routing prefix (CIDR netmask). Sources of type group have an owner_id and a name. The owner_id is the identifier of the account that created the specified firewall. The name defines the firewall to which the access is being granted.

An example of a rule id is: 

393485797142~tcp~22~22~@group,393485797142,default,@address,ipv4,10.1.2.3,24
          {owner_id~protocol~from_port~to_port~@sources}

By creating the rule identifier abstraction, the Deltacloud API supports deletion of an entire firewall rule as one operation.


Get a list of all firewalls

To retrieve a list of all firewalls use call GET /api/firewalls.

Example request:

GET /api/firewalls?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Server response:

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Tue, 26 Jul 2011 15:56:04 GMT
Content-Length: 1640

<?xml version='1.0' encoding='utf-8' ?>
<firewalls>
  <firewall href='http://localhost:3001/api/firewalls/default' id='default'>
    <name><![CDATA[default]]></name>
    <description><![CDATA[default group]]></description>
    <owner_id>393485797142</owner_id>
    <rules>
      <rule id='393485797142~tcp~22~22~@address,ipv4,87.228.192.251,32'>
        <allow_protocol>tcp</allow_protocol>
        <port_from>22</port_from>
        <port_to>22</port_to>
        <direction>ingress</direction>
        <sources>
          <source address='87.228.192.251' family='ipv4' prefix='32' type='address'></source>
        </sources>
      </rule>
    </rules>
  </firewall>
  <firewall href='http://localhost:3001/api/firewalls/test' id='test'>
    <name><![CDATA[test]]></name>
    <description><![CDATA[this is just a test]]></description>
    <owner_id>393485797142</owner_id>
    <rules>
      <rule id='393485797142~tcp~22~22~@group,393485797142,default,@address,ipv4,10.1.2.3,24'>
        <allow_protocol>tcp</allow_protocol>
        <port_from>22</port_from>
        <port_to>22</port_to>
        <direction>ingress</direction>
        <sources>
          <source name='default' owner='393485797142' type='group'></source>
          <source address='10.1.2.3' family='ipv4' prefix='24' type='address'></source>
        </sources>
      </rule>
    </rules>
  </firewall>
  <firewall href='http://localhost:3001/api/firewalls/new_firewall' id='new_firewall'>
    <name><![CDATA[new_firewall]]></name>
    <description><![CDATA[new_one]]></description>
    <owner_id>393485797142</owner_id>
    <rules>
    </rules>
  </firewall>
</firewalls>

Get the details of a specified firewall

To retrieve details of a single specified firewall use call GET /api/firewalls/:id.

Example request:

GET /api/firewalls/test?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Server reponse:

HTTP/1.1 200 OK
Content-Type: application/xml
Date: Wed, 27 Jul 2011 08:20:29 GMT
Content-Length: 835

<?xml version='1.0' encoding='utf-8' ?>
<firewall href='http://localhost:3001/api/firewalls/test' id='test'>
  <name><![CDATA[test]]></name>
  <description><![CDATA[this is just a test]]></description>
  <owner_id>393485797142</owner_id>
  <rules>
    <rule href='http://localhost:3001/api/firewalls/test/393485797142~tcp~22~22~@group,393485797142,default,@address,ipv4,10.1.2.3,24' id='393485797142~tcp~22~22~@group,393485797142,default,@address,ipv4,10.1.2.3,24'>
      <allow_protocol>tcp</allow_protocol>
      <port_from>22</port_from>
      <port_to>22</port_to>
      <direction>ingress</direction>
      <sources>
        <source name='default' owner='393485797142' type='group'></source>
        <source address='10.1.2.3' family='ipv4' prefix='24' type='address'></source>
      </sources>
    </rule>
  </rules>
</firewall>

Create a new firewall

To create a new firewall use call GET /api/firewalls/:id. Clients must specify the firewall name and description as parameters to the request. The Deltacloud server will respond with HTTP 201 Created to a succesful completion and return details of the newly created firewall. As with other POST operations in the Deltacloud API, a client may specify parameters as multipart/form-data or using the application/x-www-form-urlencoded content-type.

Example request:

POST /api/firewalls?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
Content-Length: 64
Content-Type: application/x-www-form-urlencoded

name=Devel_Group&description=Access%20for%20all%20development%20machines

Server response:

HTTP/1.1 201 Created
Content-Type: application/xml
Date: Wed, 27 Jul 2011 08:35:43 GMT
Content-Length: 296

<?xml version='1.0' encoding='utf-8' ?>
<firewall href='http://localhost:3001/api/firewalls/Devel_Group' id='Devel_Group'>
  <name><![CDATA[Devel_Group]]></name>
  <description><![CDATA[Access for all development machines]]></description>
  <owner_id></owner_id>
  <rules>
  </rules>
</firewall>

Delete a firewall

To delete the specified firewall from the back-end cloud provider use call DELETE /api/firewalls/:id. The Deltacloud server will respond with HTTP 204 No Content after a successful deletion:

Example request:

DELETE /api/firewalls/test?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Client response:

HTTP/1.1 204 No Content
Date: Wed, 27 Jul 2011 09:47:43 GMT

The rules governing the deletion of a firewall are back-end cloud specific.

For Fujitsu GCP, as this operation destroys the virtual system with it, all instances in the system, including the firewall need to be in the STOPPED state.

For Amazon EC2, it is permitted to delete a firewall that has rules defined within it, with two exceptions. You cannot delete a firewall if it is referenced by another firewall; for instance firewall_1 has a rule giving access to firewall_2. An attempt to delete firewall_2 will result in the error InvalidGroup.InUse, as you can see in the example below. The second exception is that you cannot delete a firewall if there are currently any running instances within that firewall (i.e. instances that specified the given firewall when they were launched). The error message in that case would be InvalidGroup.InUse: There are active instances using security group. In both cases the error messages are propagated from the back-end cloud provider to the requesting client.

Example request (error deleting a firewall referenced by another firewall): 

DELETE /api/firewalls/firewall_2?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Server response:

HTTP/1.1 502 Bad Gateway
Content-Type: application/xml
Content-Length: 626

<error status='502' url='/api/firewalls/firewall_2?format=xml'>
  <kind>backend_error</kind>
  <backend driver='ec2'>
    <code>502</code>
  </backend>
  <message><![CDATA[InvalidGroup.InUse: Group 393485797142:firewall_2 is used by groups: 393485797142:firewall_1
  REQUEST=ec2.us-east-1.amazonaws.com:443/?AWSAccessKeyId=AGG332FWWR5A11F327Q&Action=DeleteSecurityGroup&GroupName=firewall_2&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2011-07-27T08%3A50%3A50.000Z&Version=2010-08-31&Signature=g613223efwv5WAVhAosmPcrsfHqApAuw\nnwfYnZp0k3U%3D
  REQUEST ID=8591fa20-a6ee-4db7-b30f-3022ecc9a9f5]]></message>
</error>

Create a firewall rule

To create a new firewall rule within a specified firewall use call POST /api/firewalls/:id/rules. This operation of the firewalls collection is not supported by Fujitsu GCP. A client must supply the protocol (one of udp, tcp or icmp), port_from and port_to as parameters. Of course the client must also specify the sources to which the given rule is applied. IP addresses are specified in CIDR format sequentially: ip_address1=192.168.10.10/24, ip_address2=10.1.1.1/16 ... ip_addressN=.... The IP address '0.0.0.0/0' acts as a wildcard to specify any IP address. Source firewalls are also specified sequentially, but the owner_id of the firewall prepared for authorization must also be supplied (this is an Amazon EC2 requirement): group1=name1, group1owner=1234567890, group2=name2, group2owner=0987654321, ... groupN=nameN, groupNowner=...

The Deltacloud server responds with a HTTP 201 Created after a successful operation and adds the details of the given firewall. The example client request below specifies the required parameters as multipart/form-data. However clients may also legitimately use the application/x-www-form-urlencoded to provide firewall rule parameters.

Example request:

POST /api/firewalls/default/rules?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*
Content-Length: 1005
Expect: 100-continue
Content-Type: multipart/form-data; boundary=----------------------------4c9e7fa0a35e

------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="protocol"

tcp
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="port_from"

22
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="port_to"

22
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="group1"

devel_group
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="group1owner"

393485797142
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="group2"

outside
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="group2owner"

393485797142
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="ip_address1"

192.168.1.1/24
------------------------------4c9e7fa0a35e
Content-Disposition: form-data; name="ip_address2"

65.128.31.27/32
------------------------------4c9e7fa0a35e--

Server response:

HTTP/1.1 201 Created
Content-Type: application/xml
Date: Wed, 27 Jul 2011 10:18:51 GMT
Content-Length: 1143

<firewall href='http://localhost:3001/api/firewalls/default' id='default'>
  <name><![CDATA[default]]></name>
  <description><![CDATA[default group]]></description>
  <owner_id>393485797142</owner_id>
  <rules>
    <rule href='http://localhost:3001/api/firewalls/default/393485797142~tcp~22~22~@group,393485797142,devel_group,@group,393485797142,outside,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32' id='393485797142~tcp~22~22~@group,393485797142,devel_group,@group,393485797142,outside,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32'>
      <allow_protocol>tcp</allow_protocol>
      <port_from>22</port_from>
      <port_to>22</port_to>
      <direction>ingress</direction>
      <sources>
        <source name='devel_group' owner='393485797142' type='group'></source>
        <source name='outside' owner='393485797142' type='group'></source>
        <source address='192.168.1.1' family='ipv4' prefix='24' type='address'></source>
        <source address='65.128.31.27' family='ipv4' prefix='32' type='address'></source>
      </sources>
    </rule>
  </rules>
</firewall>

Delete a firewall rule

To delete the specified firewall rule use call DELETE /api/firewalls/:id/:rule_id. The Deltacloud server will respond with HTTP 204 No Content on completion of a successful delete operation:

Example request:

DELETE /api/firewalls/default/393485797142~tcp~0~0~@group,393485797142,devel_group,@group,393485797142,outside,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32?format=xml HTTP/1.1
Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa==
User-Agent: curl/7.20.1 (i386-redhat-linux-gnu)
Host: localhost:3001
Accept: */*

Server response:

HTTP/1.1 204 No Content
Date: Wed, 27 Jul 2011 10:39:52 GMT

Addresses