Contents

Overview

A security group defines a set of policies that can be applied to VM network interfaces. Security groups can be created in a bulk operation by providing all configuration in a single API call. They can also be created by individual specific API calls.


A policy defines a single policy for a security group. Policies have an idinfo, name, direction, protocol, portrange, icmptype, and address. The direction specifies whether this is for inbound, outbound, or any direction. The protocol specifies udp, tcp, or icmp. The portrange specifies which ports will be accepted (only valid for tcp or udp protocols). The icmptype specifies the icmp type (only valid for icmp protocol). The address can be a single IP address, subnet, all addresses, another security group, or self (this security group).


A connection is a way to connect a security group to a virtual machine interface. Once a security group is defined, a connection must be made to that security group through a seperate API call.

Security Groups

API calls to access and modify security groups.

Security Group URLs

  • /{customerid}/network/securitygroup
    • HTTP Method Support: GET
  • /{customerid}/network/securitygroup/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE


URI Parameter Type Description
customerid long The customer ID

Security Group Object Description


Name Required Type Version Constraints Description
idinfo yes string 2.0   The immutable identifier of the security group object. Max length size is 128 characters.
name yes string 2.0   The friendly name for this security group object. Max length size is 255 characters.
description   string 2.0   Description field for this security group object. Max length size is 1024 characters.
state yes string 2.0   The security group state which controls whether this group is enabled or disabled. The valid string values are:
  • enabled - This security group is enabled.
  • disabled - This security group is disabled.
policies   list 2.0   The security group policies which controls what policies the security group allows. Enter the parameters of the policies separated by a delimiter. See the policy object for the specific parameters.
self   string 2.0 read-only Relative URI identifying this object.
system   string 2.0 read-only Indicates whether the security group is a default system group. Default groups can not be edited. The possible string values are:
  • true - This security group is a default system group.
  • false - This security group is a user defined group.
version   string 2.0 read-only Identifies the version of this object.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created.
modifiedon   datetime 2.0 read-only Date time when this object was last modified.

Policies

API calls to access and modify policies of a security group.

Policy URLs

  • /{customerid}/network/securitygroup/{securitygroup}/policy
    • HTTP Method Support: GET
  • /{customerid}/network/securitygroup/{securitygroup}/policy/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE


URI Parameter Type Description
customerid long The customer ID
securitygroup string The immutable identifier of the security group this policy is attached to

Policy Object Description


Name Required Type Version Constraints Description
idinfo yes string 2.0   The immutable identifier of the policy object. Max length size is 128 characters.
name yes string 2.0   The friendly name for this policy object. Max length size is 255 characters.
description   string 2.0   Description field for this policy object. Max length size is 1024 characters.
portrange yes string 2.0   The port range of this policy. Valid for tcp and udp protocol only. The valid string values are:
  • any - All ports will be accepted.
  • * - All ports will be accepted.
  • port - The port to be accepted.
  • The range of ports to be accepted (i.e. 2000-3000)
  • The range of ports to be accepted (i.e. 2000:3000)
icmptype yes string 2.0   The icmp type of this policy. Valid for icmp protocol only. The valid string values are:
  • any - All ports will be accepted.
  • * - All ports will be accepted.
  • The number of the type to be accepted (i.e. 8)
protocol yes string 2.0   The protocol of this policy. The valid string values are:
  • tcp - The TCP protocol.
  • udp - The UDP protocol.
  • icmp - The ICMP protocol.
direction yes string 2.0   The direction of this policy. The valid string values are:
  • inbound - The policy applies to the inbound direction.
  • outbound - The policy applies to the outbound direction.
  • any - The policy applies to both the inbound and outbound directions.
address yes string 2.0   The address of this policy. The valid string values are:
  • 0.0.0.0/0 - Any address is accepted.
  • any - Any address is accepted.
  • * - Any address is accepted.
  • self - This security group.
  • The security group to be accepted (i.e. SecurityGroup2)
  • The IP address to be accepted (i.e. 192.168.100.25)
  • The IP address and subnet to be accepted (i.e. 192.168.100.1/28)
self   string 2.0 read-only Relative URI identifying this object.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created.
modifiedon   datetime 2.0 read-only Date time when this object was last modified.

Connections

API calls to access and modify connections to security groups.

Connection URLs

  • /{customerid}/network/connection
    • HTTP Method Support: GET
  • /{customerid}/network/connection/{idinfo}
    • HTTP Method Support: GET, POST, PUT, DELETE


URI Parameter Type Description
customerid long The customer ID

Connection Object Description


Name Required Type Version Constraints Description
idinfo yes string 2.0   The immutable identifier of the connection object. Max length size is 128 characters.
name yes string 2.0   The friendly name for this policy object. Max length size is 255 characters.
description   string 2.0   Description field for this connection object. Max length size is 1024 characters.
securitygroup yes string 2.0   The security group to create a connection to.
serveraddress yes list 2.0   The server IP address to create a connection to
datacenter   string 2.0 read-only The data center this connection is used in.
self   string 2.0 read-only Relative URI identifying this object.
createdby   string 2.0 read-only User identity who created this object.
modifiedby   string 2.0 read-only User identity who modified this object.
deletedby   string 2.0 read-only User identity who deleted this object.
createdon   datetime 2.0 read-only Date time when this object was created.
modifiedon   datetime 2.0 read-only Date time when this object was last modified.

Examples

Add a Security Group

POST /12345/network/securitygroup/group1

JSON Content:
{
    "name": "mygroupname",
    "state": "enabled",
    "description": "this is a sample security group post",
    "policies": [{"idinfo": "policy1", "name": "policy1", "direction": "inbound", "protocol": "udp", "portrange": "100", "address": "1.2.3.4"},
                 {"idinfo": "policy2", "name": "policyName2", "direction": "inbound", "protocol": "tcp", "portrange": "any", "address": "*"},
                 {"idinfo": "policy3", "name": "policy3", "direction": "outbound", "protocol": "tcp", "portrange": "any", "address": "*"},
                 {"idinfo": "policy4", "name": "policyName4", "direction": "any", "protocol": "icmp", "icmptype": "0", "address": "10.10.10.1/24"},
                 {"idinfo": "policy5", "name": "policy5", "direction": "any", "protocol": "icmp", "icmptype": "8", "address": "10.10.10.1/24"}]
}

Retrieve a security group

GET /12345/network/securitygroup/group1

Response:
{
    "idinfo": "group1",
    "name": "mygroupname",
    "state": "enabled",
    "description": "this is a sample security group post",
    "system": "false",
    "modifiedon": "2013-02-26T18:14:29.868",
    "modifiedby": "testuser@gogrid.com",
    "createdon": "2013-02-21T20:26:10.210",
    "createdby": "testuser@gogrid.com",
    "deletedon": null,
    "deletedby": null,
    "version": "0 US-West-1",
    "self": "/12345/network/securitygroup/group1",
    "policies": [{"idinfo": "policy1", "name": "policy1", "direction": "inbound", "protocol": "udp", "portrange": "100", "description": "", 
                  "address": "1.2.3.4", "self": "/12345/network/securitygroup/group1/policy/policy1", "modifiedon": "2013-02-26T18:14:29.868",
                  "modifiedby": "testuser@gogrid.com", "createdon": "2013-02-21T20:26:10.210", "createdby": "testuser@gogrid.com",
                  "deletedon": null, "deletedby": null},
                 {"idinfo": "policy2", "name": "policyName2", "direction": "inbound", "protocol": "tcp", "portrange": "any", "description": "", 
                  "address": "*", "self": "/12345/network/securitygroup/group1/policy/policy2", "modifiedon": "2013-02-26T18:14:29.868", 
                  "modifiedby": "testuser@gogrid.com", "createdon": "2013-02-21T20:26:10.210", "createdby": "testuser@gogrid.com",
                  "deletedon": null, "deletedby": null},
                 {"idinfo": "policy3", "name": "policy3", "direction": "outbound", "protocol": "tcp", "portrange": "any", "description": "",
                  "address": "*", "self": "/12345/network/securitygroup/group1/policy/policy3", "modifiedon": "2013-02-26T18:14:29.868",
                  "modifiedby": "testuser@gogrid.com", "createdon": "2013-02-21T20:26:10.210", "createdby": "testuser@gogrid.com",
                  "deletedon": null, "deletedby": null},
                 {"idinfo": "policy4", "name": "policyName4", "direction": "any", "protocol": "icmp", "icmptype": "0", "description": "",
                  "address": "10.10.10.1/24", "self": "/12345/network/securitygroup/group1/policy/policy4", "modifiedon": "2013-02-26T18:14:29.868", 
                  "modifiedby": "testuser@gogrid.com", "createdon": "2013-02-21T20:26:10.210", "createdby": "testuser@gogrid.com",
                  "deletedon": null, "deletedby": null},
                 {"idinfo": "policy5", "name": "policy5", "direction": "any", "protocol": "icmp", "icmptype": "8", "description": "",
                  "address": "10.10.10.1/24", "self": "/12345/network/securitygroup/group1/policy/policy5", "modifiedon": "2013-02-26T18:14:29.868",
                  "modifiedby": "testuser@gogrid.com", "createdon": "2013-02-21T20:26:10.210", "createdby": "testuser@gogrid.com",
                  "deletedon": null, "deletedby": null}]
}

Edit a security group

PUT /12345/network/securitygroup/group1

Content:
{
    "name": "mygroupnameput",
    "state": "disabled",
    "description": "this is a sample security group put",
    "policies": [{"idinfo": "policy2", "name": "policyName2", "port_range": "any", "direction": "inbound", "protocol": "tcp", "address": "*"},
                 {"idinfo": "policy3", "name": "policy3", "port_range": "any", "direction": "outbound", "protocol": "tcp", "address": "*"}]
}

Delete a security group

DELETE /12345/network/securitygroup/group1

Add a policy to a security group

POST /12345/network/securitygroup/group1/policy/policy-add-idinfo

Content:
{
    "direction": "outbound",
    "protocol": "tcp",
    "description": "",
    "portrange": "8080",
    "address": "0.0.0.0/0",
    "name": "policy-add-name"
}

Retrieve a policy from a security group

GET /12345/network/securitygroup/group1/policy/policy-add-idinfo

Content:
{
    "idinfo": "policy-add-idinfo", 
    "direction": "outbound", 
    "protocol": "tcp", 
    "description": "", 
    "portrange": "8080", 
    "createdon": "2013-02-26T18:31:54.220", 
    "modifiedby": "testuser@gogrid.com", 
    "createdby": "testuser@gogrid.com", 
    "address": "0.0.0.0/0", 
    "modifiedon": "2013-02-26T18:31:54.220", 
    "deletedon": null,
    "deletedby": null,
    "self": "/12345/network/securitygroup/group1/policy/policy-add-idinfo", 
    "name": "policy-add-name"
}

Edit a policy in a security group

PUT /12345/network/securitygroup/group1/policy/policy-add-idinfo

Content:
{
    "direction": "inbound",
    "protocol": "udp",
    "description": "",
    "portrange": "100",
    "address": "0.0.0.0/0",
    "name": "policy-add-name"
}

Deleting a policy from a security group

DELETE /12345/network/securitygroup/group1/policy/policy-add-idinfo

Add a connection

POST /12345/network/connection/connection-1

Content:
{
    "serveraddress": "192.168.100.200",
    "securitygroup": "group1",
    "name": "conn-to-group1"
}

Retrieve a connection

GET /12345/network/connection/connection-1

Content:
{
    "datacenter": "EU-West-1", 
    "modifiedon": "2013-02-26T23:52:21.471", 
    "description": "", 
    "createdon": "2013-02-26T23:09:25.630", 
    "securitygroup": "group1", 
    "modifiedby": "testuser@gogrid.com", 
    "createdby": "testuser@gogrid.com", 
    "deletedon": null,
    "deletedby": null,
    "idinfo": "connection-1", 
    "self": "/12345/network/connection/connection-1", 
    "serveraddress": "192.168.100.200", 
    "name": "conn-to-group1"
}

Edit a connection

PUT /12345/network/connection/connection-1

Content:
{
    "serveraddress": "192.168.100.300",
    "securitygroup": "group1",
    "name": "conn-to-group1"
}

Deleting a connection

DELETE /12345/network/connection/connection-1
Personal tools