cohesive networks support docs: vns3 version 3.5+ api guide

© 2016

VNS3 3.5+ API InstructionsVNS3:vpn VNS3:net and VNS3:turret 2016

© 2016

Table of Contents

2

Introduction 3

Getting Started with the VNS3 API 9

List of Commands by Function 13

Licensing 15

Runtime 24

Overlay: Clientpacks 39

Overlay: Peering 60

Connections: IPsec 71Connections: Firewall 98Connections: Routes 105Containers 112Maintenance: Snapshots 141Maintenance: Remote Support 152Admin 157

© 2016

Introductions

3

© 2016

VNS3 Products

4

Management System

Free, self-service cloud connectivityvpn

Security and connectivity networkingnet

scalable VPN

end-to-end encryption

multi-cloud, multi-region

monitor & manage

automatic failover

secure app isolation

High Availability

Application Security Controllerturret

ADD-ONs ms ha

© 2016

Getting Help with VNS3

5

This document assumes you have a VNS3 Controller instance launched and running in a security group, network or similar that has the appropriate access rules included for normal VNS3 operations.

See the specific instructions for your cloud setup and instance launch on our Product Resources page.

Please review the VNS3 Support Plans and Contacts before sending support inquiries. If you need specific help with project planning, POCs, or audits, contact our professional services team via [email protected] for details.

http://www.cohesive.net/support/product-resources/

http://www.cohesive.net/support/support-plans/

http://www.cohesive.net/support/support-contacts/

© 2016

Requirements

6

•You have a cloud account that Cohesive can use for enabling your access to the VNS3 Controller images.

•Ability to configure a client (whether desktop based or cloud based) to use OpenVPN client software.

•You have agreed to the VNS3 Terms and Conditions.

•You have a compliant IPsec firewall/router networking device:

Preferred Most models from Cisco Systems*, Juniper, Watchguard, Dell SONICWALL, Netgear, Fortinet, Barracuda Networks, Check Point*, Zyxel USA, McAfee Retail, Citrix Systems, Hewlett Packard, D-Link, WatchGuard, Palo Alto Networks, OpenSwan, pfSense, and Vyatta. Best Effort Any IPsec device that supports: IKE1 or IKE2, AES256 or AES128 or 3DES, SHA1 or MD5. *Known Exclusions Checkpoint R65+ requires native IPSec connections as Checkpoint does not conform to NAT-Traversal Standards and Cisco ASA 8.4(2)-8.4(4) bugs prevent a stable connection from being maintained.

http://cohesive.net/termslegal/terms-of-service/

© 2016

Firewall Considerations

7

VNS3 Controller instances use the following TCP and UDP ports.

• UDP port 1194 For client VPN connections; must be accessible from all servers that will join VNS3 topology as clients.

• UDP 1195-1203*For tunnels between Controller peers; must be accessible from all peers in a given topology.

• TCP port 8000 HTTPS admin interface; must be accessible from hosts where you will want to obtain runtime status or configure peering, also needs to be open to and from the Controllers at least for the peering process, and needs to be accessible when downloading credentials for installation on overlay network clients.

• UDP port 500UDP port 500 is used the phase 1 or IKE (Internet Key Exchange) component of an IPsec VPN connection.

• UDP port 4500 or Protocol 50 (ESP)Protocol 50 is used for phase 2 or ESP (Encapsulated Security Payload) component of an IPsec VPN connection only when negotiating with native IPsec. UDP port 4500 is used for the phase 2 or ESP (Encapsulated Security Payload) component of an IPsec VPN connection when using NAT-Traversal Encapsulation.

*VNS3:vpn and VNS3:net Lite Edition will not require UDP ports 1195-1197 access as it is not licensed for Controller Peering. ** Some public cloud providers require IPsec connections to use NAT-Traversal encapsulation on UDP port 4500

© 2016

Remote Support

8

Note that TCP 22 (ssh) is not required for normal operations.

Each VNS3 Controller is running a restricted SSH daemon, with access limited only to Cohesive for debugging purposes controlled by the user via the Remote Support toggle and key exchange generation.

In the event Cohesive needs to observe runtime state of a VNS3 Controller in response to a tech support request, we will ask you to open Security Group access to SSH from our support IP range and Enable Remote Support via the Web UI.

Cohesive will send you an encrypted passphrase to generate a private key used by Cohesive Support staff to access your Controller. Access to the restricted SSH daemon is completely controlled by the user. Once the support ticket has been closed you can disable remote support access and invalidate the access key.

© 2016

Getting Started with the VNS3 API

9

© 2016

Getting Started with the VNS3 API

10

All operations performed on a VNS3 Manager via the UI are available via the RESTful API.

This document will show how to access the API using both our VNS3 API Tool (ruby-based) as well as the generic API URIs with curl command examples.

Basic Workflow Choices:

A. Use the web UI to "design" one or more networks. Take snapshots of the managers and start API testing from launching managers and calling "import_snapshot"

B. Start with launching managers and use "upload_license" to begin designing your network interactively with the API.

Notes: There are no specific errata for VNS3 API at this time.

© 2016

VNS3 API Tool: Calling Structure and Arguments

11

VNS3 API calls take several arguments in common across all calls: "-K" for access key, "-S" for access secret, "-H" for the ip address of the manager you are connecting to.

Some of the calls can only be made after a manager is licensed or configured. This will be noted in the documentation for the API call.

In this document ruby API calls have a list of arguments in the form of:"Argument Switch: --enabled (boolean)"

The example above shows an allowed argument switch of "--enabled" that can have a value of true or false.

Here are common argument types and their meanings:

• CIDR - a string in subnet format with a subnet mask specified in the form of "172.10.20.0/24" where the /24 is the subnet mask.

• boolean - has a value of true or false • integer - a whole number greater than or equal to zero • positive_or_negative_integer - a whole number which can have a negative sign in front, or be zero or greater than zero • address-string - an IP address without a subnet mask "172.10.20.10" for example • string - just plain text, for example "this is my random crypto string" • pathname - a file system path and file name used as an input file or output file

© 2016

VNS3 API (URI): Calling Structure and Arguments

For each of the commands in the provided ruby API script "vnscubed.rb", there is an example of the same functionality utilizing "curl". For example:

curl -k -X PUT -u api:vnscubed -d '{"enabled":true, "username":"vnscubed", "password":"apidemopassword"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/admin_ui

The actual output is in "json" format without line breaks which looks something like the following: {"response":{"peered":true,"id":1,"managers":{"2":{"not_set":true,"id":2},"1":{"id":1,"self":true}}}}

In this document, the output examples have been run through a json formatter that adds line breaks and indentation so that the structure can be be more easily seen. Note that in some examples, multiple attributes are on a single line so the complete output from a command can fit on a single page.

It is assumed that curl is already understood by those choosing to use it for accessing the VNS3

The "curl" information does not attempt to explain the command or its data. For this information you will still need to reference the documentation for the ruby scripts equivalent command.

12

© 2016

List of Commands By Function

13

© 2016

List of Commands by Function

14

Licensing upload_license* set_license_parameters desc_license upgrade_license

Runtime desc_config* desc_status desc_client_status desc_system_status desc_link_history desc_connected_subnets

Overlay: Clientpacks desc_keyset setup_keyset desc_clientpacks fetch_clientpacks get_next_available_clientpack edit_clientpack reset_client reset_all_clients set_clientpack_tag delete_clientpack_tag

Overlay: Peering desc_peering set_manager_id add_peer edit_peer delete_peer

Connections: IPsec desc_ipsec_status setup_ipsec edit_ipsec_config create_ipsec_endpoint edit_ipsec_endpoint delete_ipsec_endpoint desc_ipsec_endpoint create_ipsec_tunnel edit_ipsec_tunnel delete_ipsec_tunnel create_ebgp_peer delete_ebgp_peer

Connections: Firewall desc_firewall add_firewall_rule delete_firewall_rule

Connections: Routes desc_routes add_route delete_route

Containers desc_container_system setup_container_systen start_container_system stop_container_system create_image desc_images edit_image delete_image start_container stop_container delete_container commit_container get_container_log

Maintenance: Snapshots desc_snapshot create_snapshot delete_snapshot import_snapshot* fetch_snapshot

Maintenance: Remote Support setup_remote_support* generate_remote_support_keypair*

Admin reset_password* setup_admin_ui server_action edit_config

* Available Pre-license upload | New Command or additional options available

© 2016

Licensing

15

© 2016 16

Resource PUT license

Argument Switch :licenseArgument Valid path to a file containing the

encrypted license

Pre-License YesDetail License a VNS3 Manager to be a part of a

specific topology.

It is important to note that the response is not "finalized" meaning you will see default addressing that satisfies the criteria of the license. You can change the subnet, manager addresses, client pack addresses , etc. subsequently with the set_license_parameters call.

Generic Command

curl -k -X PUT -u api:myapisecret --data-binary @licensefile.encmap -H 'Content-Type: text/plain' https://manager-ip-address:8000/api/license

Example Request

$ curl -v -k -X PUT -u api:apidemopassword --data-binary @vns3-lic.encmap -H 'Content-Type: text/plain' https://192.168.30.247:8000/api/license

{"response": {

"capabilities": [ "IPsec", "eBGP", "LinearAddressing", "LinearAddressingConfigurable", "CloudWAN" ],

"finalized": false, "license": "accepted","default_topology": {

"clients": [ "172.31.0.33", "172.31.0.37",

. . . other clients removed from display for readability ..."172.31.2.117"

], "ipsec_max_endpoints": 12,

"total_clients": 150, "ipsec_max_subnets": 48, "overlay_subnet": "172.31.0.0/22", "managers": [

{ "asn": 65001, "manager_id": 1, "overlay_ipaddress": "172.31.0.1" }, { "asn": 65002, "manager_id": 2, "overlay_ipaddress": "172.31.0.5" },

] }

"license_present": true } }

API URI LicensingUpload License

© 2016 17

Resource upload_license

Argument Switch --license (input path to license file)Argument Valid path to a file containing the

encrypted license

Pre-License YesDetail License a VNS3 Controller to be a part of

a specific topology.


Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address upload_license --license /pathtolicensefile/license.txt

Example Request

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 upload_license --license apidemo_ipsectrial_license.txt

--- capabilities: - IPsec- eBGP- LinearAddressing- LinearAddressingConfigurable- CloudWANdefault_topology: ipsec_max_endpoints: 50 overlay_subnet: 172.31.1.0/24 total_clients: 50 managers: - manager_id: 1 asn: 65001 overlay_ipaddress: 172.31.1.1 - manager_id: 2 asn: 65002 overlay_ipaddress: 172.31.1.5ipsec_max_subnets: 100 clients: - 172.31.1.17 - 172.31.1.21 - 172.31.1.25 - 172.31.1.29(some clientpacks removed for display purposes)license: acceptedfinalized: falselicense_present: true

API Tool LicensingUpload License

© 2016 18

Resource GET license

Argument Switch NoneArgument NonePre-License NoDetail Provides information about the Manager's

License.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/license

Example Request

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/license{ "response": { "capabilities": [ "IPsec", "eBGP" "LinearAddressing" "LinearAddressingConfigurable", "CloudWAN" ], "finalized": true, "sha1_checksum": "c82b205e47c6b0927b2e58f586e9e05a6cff5224", "uploaded_at": "Fri Jan 10 11:18:14 -0600 2014", "custom_addressing": true, "uploaded_at_i": 1389374294, "topology": { "clients": [ "172.31.0.1", "172.31.0.2" ], "ipsec_max_endpoints": 2, "total_clients": 8, "ipsec_max_subnets": 4, "license_upgrades": ["None"], "overlay_subnet": "172.31.0.0/24", "managers": [ { "asn": 65001, "manager_id": 1 "overlay_ipaddress": "172.31.0.100" }, ] }, "license_present": true } }

API URI LicensingDescribe License

© 2016 19

Resource desc_license

Argument Switch NoneArgument NonePre-License NoDetail Provides information about the Manager's

license.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_license

Example Request

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_licensecapabilities: - IPsec - eBGP - LinearAddressing - LinearAddressingConfigurable - CloudWAN topology: ipsec_max_endpoints: 50 overlay_subnet: 172.31.3.0/24total_clients: 47 managers: - manager_id: 1 asn: 65001 overlay_ipaddress: 172.31.3.1 - manager_id: 2 asn: 65002ipsec_max_subnets: 100 clients: - 172.31.3.10 - 172.31.3.11(some clientpacks removed for display purposes)uploaded_at: Fri May 25 19:34:25 +0000 2012sha1_checksum: 9ab6482da85c1f2d5660f5a9e9948dff6835c64dfinalized: trueuploaded_at_i: 1337974465license_present: truecustom_addressing: true

API Tool LicensingDescribe License

© 2016 20

Example Request

$ curl -k -X PUT -u api:apidemopassword -d '{"subnet":"172.31.1.0/24", "managers":"172.31.1.253 172.31.1.252 172.31.1.251 172.31.1.250", "clients":"172.31.1.1-172.31.1.10", "my_manager_vip":"172.31.1.254", "default":"false"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/license/parameters

{ "response":{ "license":"accepted", "finalized":true, "parameters":{ "subnet":"172.31.1.0/24", "managers"[ "172.31.1.253", "172.31.1.252", "172.31.1.251", "172.31.1.250" ], "clients":[ "172.31.1.1", "172.31.1.2", "172.31.1.3", "172.31.1.4", "172.31.1.5", "172.31.1.6", "172.31.1.7", "172.31.1.8", "172.31.1.9", "172.31.1.10" ], "my_manager_vip":"172.31.1.254" } }}

Resource PUT /license/parameters

Argument Switch :subnet [CIDR]:managers [multiple address string]:clients [multiple address string]:my_manager_vip [address string]:default [boolean]

Argument The "subnet" arg specifies the CIDR of the virtual network created for use with the VNS3 Manager.

The "managers" arg specifies a whitespace delimited address string in the subnet to use for the VNS3 Managers' virtual interfaces.

The "clients" arg specifies a comma delimited, or hyphenated sequence of addresses for use as client addresses in the virtual network.

The "my-manager-vip" address must be allocated from the subnet, and must be the same for all managers (it is used in the internal implementation of VNS3).

The "default" arg specifies whether to use default Pre-License No

Detail Allows customization of the overlay network elements. It also "finalizes" the license, once these settings are made they cannot be changed. To change requires launching a new manager and configuring with different parameters.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"subnet":"OverlaySubnet", "managers":"M1-IP", "clients":"IP-range", "my_manager_vip":"VIP", "default":"false"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/license/parameters

API URI LicensingSet License Parameters

© 2016 21

Example RequestResource set_license_parameters

Argument Switch --subnet (CIDR)--managers (multiple address string)--clients (multiple address string)--my-manager-vip (address string)--default (boolean)

Argument The "--subnet" arg specifies the CIDR of the virtual network created for use with the VNS3 Manager.

The "--managers" arg specifies a whitespace delimited address string in the subnet to use for the VNS3 Managers' virtual interfaces.

The "--clients" arg specifies a comma delimited, or hyphenated sequence of addresses for use as client addresses in the virtual network.

The "--my-manager-vip" address must be allocated from the subnet, and must be the same for all managers (it is used in the internal implementation of VNS3).

The "--default" arg should be called with "true" to accept default addressing.

Pre-License No

Detail Allows customization of the overlay network elements. It also "finalizes" the license, once these settings are made they cannot be changed. To change requires launching a new manager and configuring with different parameters.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address set_license_parameters --subnet "cidr" --managers "manager1address,manager2address" --clients "address1,address2,address3" --my-manager-vip "vipaddress"

$ ./vnscubed.rb -K api -S apidemopassword -H 54.68.150.11 set_license_parameters --subnet 172.31.1.0/24 --managers 172.31.1.253,172.31.1.252,172.31.1.251,172.31.1.250 --my-manager-vip 172.31.1.254 --clients 172.31.1.1,172.31.1.2,172.31.1.3,172.31.1.4,172.31.1.5,172.31.1.6,172.31.1.7,172.31.1.8,172.31.1.9,172.31.1.10 --default false

--- license: acceptedfinalized: trueparameters: subnet: 172.31.1.0/24 managers: - 172.31.1.253 - 172.31.1.252 - 172.31.1.251 - 172.31.1.250 clients: - 172.31.1.1 - 172.31.1.2 - 172.31.1.3 - 172.31.1.4 - 172.31.1.5 - 172.31.1.6 - 172.31.1.7 - 172.31.1.8 - 172.31.1.9 - 172.31.1.10 my_manager_vip: 172.31.1.254

API Tool LicensingSet License Parameters

© 2016 22

Example RequestResource PUT license/upgrade

Argument Switch :license (blob)Argument Valid path to a file containing the

encrypted license

Pre-License NoDetail Upgrades parts of a VNS3 Manager

topology parameters (additional client packs, more tunnels, more endpoints, etc..).

Generic Command

curl -k -X PUT -u api:myapisecret --data-binary @licensefile.encmap -H 'Content-Type: text/plain' https://manager-ip-address:8000/api/license/upgrade

$ curl -k -X PUT -u api:apidemopassword --data-binary @lic-upgrade.snap -H 'Content-Type: text/plain' https://192.168.30.247:8000/api/license/upgrade { "response": { "finalized": false, "uniq": "c6b99c0ee432fa2ebec6a311619402c844888301be75c3530204d7180e5414a0", "license": "accepted", "new_clientpacks": 0, "new_managers": 1 } }

API URI LicensingUpgrade License

© 2016 23

Example RequestResource upgrade_license


encrypted license

Pre-License NoDetail Upgrades parts of a VNS3 Manager

topology parameters (additional client packs, more tunnels, more endpoints, etc..).

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address upgrade_license --license /pathtolicensefile/license.txt

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 upgrade_license --license apidemo_ipsectrial_license.txt license: accepted

API Tool LicensingUpgrade License

© 2016

Runtime

24

© 2016 25

Example Request

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/config { "response": { "asn": 65001, "topology_name": "cft", "topology_checksum": "a04a92073a4f6f32a2abce45439a2d8c016334dc", "manager_id": 1 "vns3_version": "3.04.00-20131120171529", "licensed": true, "overlay_ipaddress": "172.31.0.100" "peered": true, "public_ipaddress": "50.240.142.209" "private_ipaddress": "192.168.30.247" } }

Resource GET config

Argument Switch NoneArgument NonePre-License YesDetail Provides general information about the

manager's topology, license state and checksums.

Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/config

API URI RuntimeDescribe Configuration

© 2016 26

Example RequestResource desc_config

Argument Switch NoneArgument NonePre-License YesDetail Provides general information about the

manager's topology, license state and checksums.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_config

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_ipsec_statuspublic_ipaddress: 174.129.238.73 peered: false licensed: true vns3_version: 2.9999.14-20120523200216 private_ipaddress: 10.4.117.122 topology_name: Your Excellent Topology topology_checksum: e5bfef539780d269c3f692132a2df8c51e7557d7

API Tool RuntimeDescribe Configuration

© 2016 27

Example Request

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/status

{"response":{

"connected_clients":{"172.31.1.1":{

"overlay_ipaddress":"172.31.1.1", "managerid":1,"ipaddress":"10.17.134.242"

}}"connected_subnets":[

["192.168.1.1","255.255.255.255"]["192.168.1.2","255.255.255.255"]]"ipsec":{

"1"{"local_subnet":"172.31.1.1/32""remote_subnet":"192.168.1.1/32""endpointid":1"endpoint_name":"M2""active":true"description":"test""connected":true"tunnel_params":{

"phase2":"up","outbound_spi":"656c43fc","inbound_spi":"47dee573","esp_time_remaining":"6936s","esp_port":"4500","phase2_algo":"AES 128","phase2_hash":"SHA1","nat_t":"on","dpd":"off","phase1":"up","isakmp_port":"4500","isakmp_time_remaining":"1236s","last_dpd":"None","phase1_cipher":"AES 128","phase1_prf":"SHA1","phase1_dh_group":14}

}}

}}

}

Resource GET status

Argument Switch NoneArgument NonePre-License No, also requires Peering operations to be

completed.Detail Provides general information on all

defined IPsec and client overlay connections.

Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/status

API URI RuntimeDescribe Status

© 2016 28

Example RequestResource desc_status

Argument Switch NoneArgument NonePre-License No, also requires Peering operations to be

completed.Detail Provides general information on all

defined IPsec and client overlay connections.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_status

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_status

connected_clients: 172.31.3.10: ipaddress: 63.250.226.147 managerid: 1 overlay_ipaddress: 172.31.3.10ipsec: "6": tunnel_params: phase1_cipher: aes_256 phase1: up nat_t: "on" phase2: up phase1_dh_group: 2 dpd: "on" phase2_algo: AES_256-HMAC_SHA1 phase1_prf: sha remote_subnet: 192.168.4.0/24 connected: true endpointid: 5 local_subnet: 172.31.3.0/24 active: true connected_subnets: - - 192.168.4.0 - 255.255.255.0

API Tool RuntimeDescribe Status

© 2016 29

Example Request

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/status/ipsec { "response": { "2": { "active": true, "description": "tunnel-3-1", "endpointid": 3, "remote_subnet": "192.168.9.0/24", "connected": false, "local_subnet": "172.31.0.0/24", "endpoint_name": "ep 1", "tunnel_params": { } } }

Resource GET status/ipsec

Argument Switch NoneArgument NonePre-License NoDetail Provides information on all defined IPsec

connectionsGeneric Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/status/ipsec

API URI RuntimeDescribe IPsec Status

© 2016 30

Example RequestResource desc_ipsec_status



vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_ipsec_status

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_ipsec_status

"6": tunnel_params: phase1_cipher: aes_256 phase1: up nat_t: "on" phase2: up phase1_dh_group: 2 dpd: "on" phase2_algo: AES_256-HMAC_SHA1 phase1_prf: sha remote_subnet: 192.168.4.0/24 connected: true endpointid: 5 local_subnet: 172.31.3.0/24 active: true

API Tool RuntimeDescribe IPsec Status

© 2016 31

Example Request

$ curl -k -X GET -u api:test https://54.185.32.202:8000/api/status/clients

{"response":{

"172.31.1.1":{"overlay_ipaddress":"172.31.1.1""managerid":1"ipaddress":"10.17.134.242"

},"172.31.1.2":{

"overlay_ipaddress":"172.31.1.2""managerid":1"ipaddress":"10.17.134.242"

}}

}

Resource GET status/clients



curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/status/clients

API URI RuntimeDescribe Client Status

© 2016 32

Example RequestResource desc_clients_status

Argument Switch NoneArgument NonePre-License NoDetail Provides information on connected

Overlay Network client devices.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_clients_status

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_client_status172.31.3.10: ipaddress: 63.250.226.147 managerid: 1 overlay_ipaddress: 172.31.3.10

API Tool RuntimeDescribe Client Status

© 2016 33

Example Request

$ curl -k -X GET -u api:test https://54.185.32.202:8000/api/status/system

{"response":{

"data":{"2014-06-26":{}"2014-06-27":{}}"timestamp":"2014-06-27 18:12:23 +0100""timestamp_i":1403889143"uptime":78325"loadavg":["0.30","0.27","0.25","1/179","27020"]"diskinfo":[["/dev/xvda1","11G","3.2G","6.9G","32%","/"]]"meminfo":

["3931365376","1807974400","2123390976","0","206532608","1285763072"]"swapinfo":["1073737728","0","1073737728"]

}}

Resource GET status/system

Argument Switch NoneArgument NonePre-License NoDetail Provides information about the underlying

appliance; memory, cpu, disk space, etc.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/status/system

API URI RuntimeDescribe System Status

© 2016 34

Example RequestResource desc_system_status

Argument Switch NoneArgument NonePre-License NoDetail Provides information about the underlying

appliance; memory, cpu, disk space, etc.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_system_status

$ vnscubed.rb -K api -S test -H 54.185.32.202 desc_system_status---data: "2014-06-27": {}

"2014-06-26": {}

meminfo:- "3931365376"- "1810505728"- "2120859648"- "0"- "206671872"- "1285783552"swapinfo:- "1073737728"- "0"- "1073737728"timestamp: 2014-06-27 18:18:15 +0100loadavg:- "0.59"- "0.34"- "0.27"- 1/179- "31609"uptime: 78676diskinfo:- - /dev/xvda1 - 11G - 3.2G - 6.9G - 32% - /timestamp_i: 1403889495

API Tool RuntimeDescribe System Status

© 2016 35

Example RequestResource GET status/link_history

Argument Switch :remote [CIDR]:local [CIDR]:tunnelid [integer]

Argument The "--remote" arg is an address string in CIDR format to display link history to a remote endpoint.

The "--local" arg is an address string in CIDR format which will display status of the local route.

The "--tunnel-id" arg will display link history of just the tunnel specified, which may be only one tunnel to a remote endpoint.

Pre-License NoDetail Provides information about the

connection history of the subnet or tunnelGeneric Command

curl -k -X GET -u api:myapisecret --d '{"remote":"remote CIDR", "local":"local CIDR", "tunnelid":integer}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/status/link_history

$ curl -k -X GET -u api:test -d '{"remote":"192.168.1/32", "local":"172.31.1.1/32", "tunnelid":3}' -H 'Content-Type: application/json' https://54.185.32.202:8000/api/status/link_history

{"response":{

"remote":"192.168.1.1/32""history":[{"event":"up","timestamp_i":1403811498,"timestamp":"2014-06-26 20:38:18 +0100"},{"event":"down","timestamp_i":1403811501,"timestamp":"2014-06-26 20:38:21 +0100"},{"event":"up","timestamp_i":1403811506,"timestamp":"2014-06-26 20:38:26 +0100"},{"event":"down","timestamp_i":1403889752,"timestamp":"2014-06-27 18:22:32 +0100"},{"event":"up","timestamp_i":1403889757,"timestamp":"2014-06-27 18:22:37 +0100"},{"event":"down","timestamp_i":1403890073,"timestamp":"2014-06-27 18:27:53 +0100"},{"event":"up","timestamp_i":1403890106,"timestamp":"2014-06-27 18:28:26 +0100"},{"event":"down","timestamp_i":1403890667,"timestamp":"2014-06-27 18:37:47 +0100"},]"local":"172.31.1.1/32""tunnelid":3

}}

API URI RuntimeDescribe Link History

© 2016 36

Example RequestResource desc_link_history

Argument Switch --remote (CIDR)--local (CIDR)--tunnelid (iteger)

Argument The "--remote" arg is an address string in CIDR format to display link history to a remote endpoint.

The "--local" arg is an address string in CIDR format which will display status of the local route.

The "--tunnel-id" arg will display link history of just the tunnel specified, which may be only one tunnel to a remote endpoint.

Pre-License NoDetail Provides information about the

connection history of the subnet or tunnel

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_link_history --remote cidr_as_string --local cidr_as_string --tunnel-id tunnelnumber

$ vnscubed.rb -K api -S test -H 54.185.32.202 desc_link_history --tunnelid 3

---tunnelid: 3remote: 192.168.1.1/32local: 172.31.1.1/32history:- timestamp_i: 1403811498 timestamp: 2014-06-26 20:38:18 +0100 event: up- timestamp_i: 1403811501 timestamp: 2014-06-26 20:38:21 +0100 event: down- timestamp_i: 1403811506 timestamp: 2014-06-26 20:38:26 +0100 event: up- timestamp_i: 1403889752 timestamp: 2014-06-27 18:22:32 +0100 event: down- timestamp_i: 1403889757 timestamp: 2014-06-27 18:22:37 +0100 event: up- timestamp_i: 1403890073 timestamp: 2014-06-27 18:27:53 +0100 event: down- timestamp_i: 1403890106 timestamp: 2014-06-27 18:28:26 +0100 event: up- timestamp_i: 1403890667 timestamp: 2014-06-27 18:37:47 +0100 event: down- timestamp_i: 1403890669 timestamp: 2014-06-27 18:37:49 +0100 event: up

API Tool RuntimeDescribe Link History

© 2016 37

Example RequestResource GET status/connected_subnets

Argument Switch :extended_output (boolean)Argument The "extended_output" arg is true to

receive verbose information about the connected subnets.

Pre-License NoDetail Provides information about any connected

subnets.Generic Command

curl -k -X GET -u api:myapisecret --d '{"extended-output":"true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/status/connected_subnets

$ curl -k -X GET -u api:test -d '{"extended_output":"true"}' -H 'Content-Type: application/json' https://54.185.32.202:8000/api/status/connected_subnets

{"response":[

["192.168.1.1","255.255.255.255"]["192.168.1.2","255.255.255.255"]

]}

API URI RuntimeDescribe Connected Subnets

© 2016 38

Example RequestResource desc_connected_subnets

Argument Switch --extended-output (boolean)Argument The "--extended-output" arg is true to

receive verbose information about the connected subnets.

Pre-License NoDetail Provides information about any connected

subnets.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_connected_subnets --extended-output true

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_connected_subnets --extended-output true

- netmask: 255.255.255.0 cidr_mask: "24" network: 192.168.4.0 origin: ipsec subnet: 192.168.4.0/24 managerid: 1

API Tool RuntimeDescribe Connected Subnets

© 2016

Overlay: Clientpacks

39

© 2016 40

Example RequestResource GET keyset

Argument Switch NoneArgument NonePre-License NoDetail Returns status of whether cryptographic

credentials, which are used to provide overlay devices access to the topology, have been generated.

Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/keyset

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/keyset

{ "response": { "keyset_present": true, "checksum": "553fbfa37752fb4652387cc25dd2d5e1633445a2", "created_at": "2014/01/15 12:16:36 -0600", "created_at_i": 1389809796, "uuid": "2b8928e0-7e11-11e3-9f3c-005056003374" } }

API URI OverlayDescribe Keyset

© 2016 41

Example RequestResource desc_keyset

Argument Switch NoneArgument NonePre-License NoDetail Returns status of whether cryptographic

credentials, which are used to provide overlay devices access to the topology, have been generated.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_keyset

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_keyset Response: (One of three states; there are no keys, they are being generated, they have been generated.)

No Keys: keyset_present: false in_progress: false

Keys are being generated: keyset_present: false running: 0 in_progress: true

Keys Generated: keyset_present: true created_at: 2010/08/28 19:25:57 +0000 created_at_i: 1283023557 checksum: 0d61536900908f1b985eae65aa9473a2f312c94c

API Tool OverlayDescribe Keyset

© 2016 42

Example RequestResource PUT keyset

Argument Switch :source (address-string):token (string):topology_name (string)

Argument The optional "source" arg is the Source Manager's hostname/address.

The "token" arg is any arbitrary key used to help randomize the checksum, it must be identical for each manager in a topology.

The "topology_name" arg specifies a name for the topology

Pre-License NoDetail Generates cryptographic credentials

which are used to provide overlay devices access to the topology.

The "--source" arg is not required for the first invocation on a manager in the topology, without --source the keys are generated, with source the keys are pulled from one manager to another.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"token":"keysettoken", "topology_name":"toponame"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/keyset

$ curl -k -X PUT -u api:test -d '{"token":"test", "topology_name":"Manager1"}' -H 'Content-Type: application/json' https://54.202.22.3:8000/api/keyset

{"response":{

"keyset_present":false"in_progress":true"started_at":"2014-06-27T20:02:51+01:00""started_at_i":1403895771"running":0

}}

API URI OverlaySet Up Clientpack

© 2016 43

Example RequestResource setup_keyset

Argument Switch --source (address-string)--token (string)--topology_name (string)

Argument The optional "source" arg is the Source Manager's hostname/address.

The "token" arg is any arbitrary key used to help randomize the checksum, it must be identical for each manager in a topology.

The "topology_name" arg specifies a name for the topology

Pre-License NoDetail Generates cryptographic credentials

which are used to provide overlay devices access to the topology.

The "--source" arg is not required for the first invocation on a manager in the topology, without --source the keys are generated, with source the keys are pulled from one manager to another.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H another-manager-ip-address setup_keyset --source manager-ip-address --token "arandomstring"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 setup_keyset --token "arandomstring"keyset_present: false running: 0 in_progress: true started_at_i: 1337976741 started_at: 2012/05/25 20:12:21 +000 After Several Minutes; query again, and the key set has been generated. $vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 desc_keysetkeyset_present: true created_at: 2012/05/25 20:12:43 +0000 created_at_i: 1337976763 uuid: fc8433e4-a6a5-11e1-9d32-123139268763 checksum: 79ac7639cb044978b2bfef38231fa365d10861ee

Example Request - Fetch Keys

API Tool OverlaySet Up Clientpack

© 2016 44

Example RequestResource GET clientpacks

Argument Switch :sorted [boolean]Argument The "sorted" arg allows you to specify a

true to get the clientpack info back in medically sorted order.

Pre-License NoDetail Returns detailed information about all of

the clientpacks in the topology. If manager's are properly peered, this information can come from any of the managers.

Generic Command

curl -k -X GET -u api:myapisecret -d '{"sorted":"true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpacks

$ curl -v -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/clientpacks Response: { "response": { "172.31.0.8": { "linux_onefile": "172_31_0_8.conf", "enabled": true, "conf_sha1": "d6ec458b6791829532b8382fd29bf01599df3ad8", "windows_onefile": "172_31_0_8.ovpn", "tarball_file": "172_31_0_8.tar.gz", "tarball_sha1": "298bf924339e3d26fb035e805c71a33bddcc6991", "overlay_ipaddress": "172.31.0.8", "sequential_id": 8, "checked_out": false, "zip_sha1": "39034e298fbb748232614d1a58b108ca03d85549", "name": "172_31_0_8", "zip_file": "172_31_0_8.zip", "ovpn_sha1": "d6ec458b6791829532b8382fd29bf01599df3ad8" }, < other client packs here but not shown in this document > } }

API URI OverlayDescribe Clientpack

© 2016 45

Example RequestResource desc_clientpacks

Argument Switch --sorted (boolean)Argument The "sorted" arg allows you to specify a

true to get the clientpack info back in medically sorted order.

Pre-License NoDetail Returns detailed information about all of

the clientpacks in the topology. If manager's are properly peered, this information can come from any of the managers.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address desc_clientpacks

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 desc_clientpacks

name: 172_31_3_56 tarball_file: 172_31_3_56.tar.gz checked_out: false tarball_sha1: 23e14ce164a57cf865c488302233043bb7212396 zip_file: 172_31_3_56.zip zip_sha1: 828fa1390e111282fb574086c534bd25851d2faf enabled: true sequential_id: 47 overlay_ipaddress: 172.31.3.56

API Tool OverlayDescribe Clientpack

© 2016 46

Example Request

$ curl -k -X GET -H 'Content-Type: application/json' -d '{"name":"172_31_0_5", "format":"tarball"}' https://api:[email protected]:8000/api/clientpack -o myclientpack.tgz

$ curl -k -X GET -H 'Content-Type: application/json' -d '{"name":"172_31_0_5", "format":"zip"}' https://api:[email protected]:8000/api/clientpack -o myclientpack.zip

$ curl -k -X GET -H 'Content-Type: application/json' -d '{"name":"172_31_0_5", "format":"conf"}' https://api:[email protected]:8000/api/clientpack -o myclientpack.conf

$ curl -k -X GET -H 'Content-Type: application/json' -d '{"name":"172_31_0_5", "format":"ovpn"}' https://api:[email protected]:8000/api/clientpack -o myclientpack.ovpn

No success code is printed. Clientpack is output to the requested file name.

Resource GET clientpack

Argument Switch :name [string]:format [Zip, tarball, conf, or ovpn]-o (output pathname)

Argument The "name" is the name of the clientpack as returned by the "desc_clientpacks" call.

The " format" has four possible values "tarball" (default), "zip", "conf", or "ovpn" which as stated, returns the clientpack in that compression/file format.

The "-o" is an output file name for the clientpack.

Pre-License NoDetail Clientpacks are files with the necessary

information and credentials for an overlay client to be connected to the VNS3 topology.

Generic Command

curl -k -X GET -u api:myapisecret -d '{"name":"clientpackname", "format":"fileformat"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpack -o pathtofle

API URI OverlayFetch Clientpack

© 2016 47

Example RequestResource fetch_clientpack

Argument Switch --name (string)--format (Zip, tarball, conf, or ovpn)-o (output pathname)

Argument The "--name" is the name of the clientpack as returned by the "desc_clientpacks" call.

The " --format" has four possible values "tarball" (default), "zip", "conf", or "ovpn" which as stated, returns the clientpack in that compression/file format.

The "-o" is an output file name for the clientpack.

Pre-License NoDetail Clientpacks are files with the necessary

information and credentials for an overlay client to be connected to the VNS3 topology.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address fetch_clientpack --name 172_31_1_17 --format "zip" -o "mycredentials.zip"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 fetch_clientpack --name "172_31_1_17" --format "zip" -o "mycredentials.zip"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 fetch_clientpack --name "172_31_1_17" --format "tarball" -o "mycredentials.tar"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 fetch_clientpack --name "172_31_1_17" --format "conf" -o "mycredentials.conf"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 fetch_clientpack --name "172_31_1_17" --format "ovpn" -o "mycredentials.ovpn"

No success code is printed. Clientpack is output to the requested file name.

API Tool OverlayFetch Clientpack

© 2016 48

Example Request$ curl -k -X POST -u api:apidemopassword -d '{"low_ip":"172.31.0.1", "high_ip":"172.31.0.5"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/clientpacks/next_available

{ "response": { "name": "172_31_0_2", "overlay_ipaddress": "172.31.0.2", "enabled": true, "checked_out": true, "sequential_id": 2, "linux_onefile": "172_31_0_2.conf", "conf_sha1": "e31cc4db37ce2b082d0b08dc73b6af27ac0ff9ae", "windows_onefile": "172_31_0_2.ovpn", "ovpn_sha1": "e31cc4db37ce2b082d0b08dc73b6af27ac0ff9ae"

"tarball_file": "172_31_0_2.tar.gz", "tarball_sha1": "b9a2e4961d2519154af488ea5572fe083e624ea7",

"zip_file": "172_31_0_2.zip", "zip_sha1": "21340d31bf939da497f042a5eaecb6a9d7dbd947" } }

Resource POST clientpacks/next_available

Argument Switch :low_ip (string):high_ip(string)

Argument The optional "low_ip" arg set the lower bound for the resulting IP.

The optional "high_ip" arg set the upper bound for the resulting IP.

Pre-License NoDetail Using this resource against multiple

managers in the same topology could cause distribution of the same clientpack to multiple overlay devices which is not allowed. Note: The "get_next_available_clientpack" call does not actually fetch the credentials. It provides sufficient information for you to the call "fetch_clientpack".

Using the resource without either argument will return the lowest next available clientpack.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"low_ip":"lowIP", "high_ip":"highIP"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpack/next_available

API URI OverlayGet Next Available CP

© 2016 49

Example RequestResource get_next_available_clientpack

Argument Switch --low_ip (string)--high_ip(string)

Argument The optional "low_ip" arg set the lower bound for a resulting IP.

The optional "high_ip" arg set the upper bound for a resulting IP.

Pre-License NoDetail Using this resource against multiple

managers in the same topology could cause distribution of the same clientpack to multiple overlay devices which is not allowed. Note: The "get_next_available_clientpack" call does not actually fetch the credentials. It provides sufficient information for you to the call "fetch_clientpack".

Using the resource without either argument will return the lowest next available clientpack.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address get_next_available_clientpack

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 get_next_available_clientpack name: 172_31_3_10 tarball_file: 172_31_3_10.tar.gz checked_out: true tarball_sha1: 5e2597372e5c96ac07f5a5471f05f5d1a663e53f zip_file: 172_31_3_10.zip zip_sha1: 8e14120ed58e3bf5c05d6755eed954adc3f13146 enabled: true sequential_id: 1 overlay_ipaddress: 172.31.3.10

API Tool OverlayGet Next Available CP

© 2016 50

Example Request

$ curl -k -X PUT -u api:apidemopassword -d '{"name":"172_31_0_1", "enabled":"true", "checked_out":"false"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/clientpack { "response": { "linux_onefile": "172_31_0_1.conf", "enabled": true, "conf_sha1": "3bb9d60710d2340d91ed2a442a2a59e4469132f3", "windows_onefile": "172_31_0_1.ovpn", "tarball_file": "172_31_0_1.tar.gz", "tarball_sha1": "4eaab2f4ac254923b029e250cbc3f31e31b87d5b", "overlay_ipaddress": "172.31.0.1", "sequential_id": 1, "checked_out": true, "zip_sha1": "c641a080fcde5cc5848845d7fa2e9e172ab9111f", "name": "172_31_0_1", "zip_file": "172_31_0_1.zip", "ovpn_sha1": "3bb9d60710d2340d91ed2a442a2a59e4469132f3" }}

Resource PUT clientpack

Argument Switch :name (string):enabled (string):checked_out (string):regenerate (string)

Argument The "name" arg is the name of the clientpack.

The "enabled" arg is set to true or false. A false setting means the clientpack is disabled.

The "checked_out" arg is set to true or false. A checked-out clientpack is unavailable via get_next_available_clientpack.

The "regenerate" arg when set to true will regenerate the clientpack.

Pre-License NoDetail For changing properties of cleintpacks;

enabling or disabling, checking in or out, or regenerating.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"name":"cp-name", "enabled":"true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpack

API URI OverlayEdit Clientpack

© 2016 51

Example RequestResource edit_clientpack

Argument Switch --name (string)--enabled (string)--checked-out (string)--regenerate (string)


The "enabled" arg is set to true or false. A false setting means the clientpack is disabled.

The "checked-out" arg is set to true or false. A checked-out clientpack is unavailable via get_next_available_clientpack.

The "regenerate" arg when set to true will regenerate the clientpack.

Pre-License NoDetail For changing properties of cleintpacks;

enabling or disabling, checking in or out, or regenerating.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address edit_clientpack --name clientpackname --enabled "true" --checked_out "false"

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 edit_clientpack --name "172_31_3_10" --enabled "true" --checked_out "false"name: 172_31_3_10 tarball_file: 172_31_3_10.tar.gz checked_out: false tarball_sha1: 5e2597372e5c96ac07f5a5471f05f5d1a663e53f zip_file: 172_31_3_10.zip zip_sha1: 8e14120ed58e3bf5c05d6755eed954adc3f13146 enabled: true sequential_id: 1 overlay_ipaddress: 172.31.3.10

API Tool OverlayEdit Clientpack

© 2016 52

Example RequestResource POST client/reset

Argument Switch :name (string)


Pre-License NoDetail For resetting the connection of a client to

a VNS3 Manager. Generic Command

curl -k -X POST -u api:myapisecret -d '{"name":"cp-name"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/client/reset

$ curl -k -X POST -u api:test -d '{"name":"172_31_1_2"}' -H 'Content-Type: application/json' https://54.185.32.202:8000/api/client/reset

{"response":{

"disconnecting":"172_31_1_2""overlay_ipaddress":"172.31.1.2"

}}

API URI OverlayReset Client

© 2016 53

Example RequestResource reset_client

Argument Switch --name (string)


Pre-License NoDetail For resetting the connection of a client to

a VNS3 Manager. Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address reset_client --name clientpack-name

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 reset_client --name "172_31_0_10" overlay_ipaddress: 172.31.3.10 disconnecting: 172_31_3_10

API Tool OverlayReset Client

© 2016 54

Example RequestResource reset_all_client

Argument Switch None

Argument None

Pre-License NoDetail For resetting all of the connections of

clients connected to the VNS3 Manager.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address reset_all_clients

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 reset_all_clients resetting: [ ]

API URI OverlayReset All Clients

© 2016 55

Example RequestResource reset_all_client


Argument None

Pre-License NoDetail For resetting all of the connections of

clients connected to the VNS3 Manager.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address reset_all_clients

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 reset_all_clients resetting: [ ]

API Tool OverlayReset All Clients

© 2016 56

Example RequestResource POST clientpack/:name

Argument Switch :name (string):key (string):value (string)

Argument The "name" arg is the name of the clientpack to be tagged.

The "key" arg is the tag key.

The "value" arg is the tag value.Pre-License NoDetail For tagging individual clientpacks.Generic Command

curl -k -X POST -u api:myapisecret -d '{"key":"name", "value":"clientpack-name"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpack/name

$ curl -k -X POST -u api:test -d '{"key":"name", "value":"test"}' -H 'Content-Type: application/json' https://54.185.32.202:8000/api/clientpack/172_31_1_1

{ "response":{ "name":"172_31_1_1", "tags":{ "name":"test" } }}

API URI OverlaySet Clientpack Tag

https://54.185.32.202:8000/api/clientpack/172_31_1_1

© 2016 57

Example RequestResource set_clientpack_tag

Argument Switch --name (string)--key (string)--value (string)

Argument The "name" arg is the name of the clientpack to be tagged.


The "value" arg is the tag value.Pre-License NoDetail For tagging individual clientpacks.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address set_clientpack_tag --name clientpack-name --key tag-key --value tag-value

$ vnscubed.rb -K api -S test -H 54.185.32.202 set_clientpack_tag --name 172_31_1_2 --key name --value test---tags: name: testname: 172_31_1_2

API Tool OverlaySet Clientpack Tag

© 2016 58

Example RequestResource DELETE clientpack/:name

Argument Switch :name (string):key (string):value (string)

Argument The "name" arg is the name of the clientpack where the tag will be deleted


The "value" arg is the tag value.Pre-License NoDetail For deleting clientpack tags.Generic Command

curl -k -X DELETE -u api:myapisecret -d '{"key":"name", "value":"clientpack-name"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/clientpack/name

$ curl -k -X DELETE -u api:test -d '{"key":"name", "value":"test"}' -H 'Content-Type: application/json' https://54.185.32.202:8000/api/clientpack/172_31_1_1

{ "response":{ "name":"172_31_1_1", "tags":{} }}

API URI OverlayDelete Clientpack Tag

https://54.185.32.202:8000/api/clientpack/172_31_1_1

© 2016 59

Example RequestResource delete_clientpack_tag

Argument Switch --name (string)--key (string)

Argument The "name" arg is the name of the clientpack where the tag will be deleted

The "key" arg is the tag key.Pre-License NoDetail For deleting clientpack tags.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address delete_clientpack_tag --name clientpack-name --key tag-key

$ vnscubed.rb -K api -S test -H 54.185.32.202 delete_clientpack_tag --name 172_31_1_2 --key name---tags: {}

name: 172_31_1_2

API Tool OverlayDelete Clientpack Tag

© 2016

Overlay: Peering

60

© 2016 61

Example RequestResource GET peering


Argument None

Pre-License NoDetail Provides the status of whether a Manager

is peered to other Managers.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/peering

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/peering

{ "response": { "peered": true, "id": 1, "managers": { "2": { "not_set": true, "id": 2 }, "1": { "id": 1, "self": true } } }}

API URI OverlayDescribe Peering

© 2016 62

Example RequestResource desc_peering


Argument None

Pre-License NoDetail Provides the status of whether a Manager

is peered to other Managers.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_peering

$ vnscubed.rb -K api -S test -H 54.202.22.3 desc_peering---peered: trueid: 1managers: "4": id: 4 not_set: true "3": id: 3 not_set: true "2": id: 2 not_set: true "1": id: 1 self: true

API Tool OverlayDescribe Peering

© 2016 63

Example RequestResource PUT peering/self

Argument Switch :id (integer)

Argument The manager ID as an integer, cannot be the same as the id of another manager in the topology, and cannot be greater than the number of managers in the topology.

Pre-License NoDetail Sets the Manager ID of a manager so that

it can be peered within a topology.Generic Command

curl -k -X PUT -u api:myapisecret -d '{"id":"ManagerID"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/peering/self

$ curl -k -X PUT -u api:test -d '{"id":"1"}' -H 'Content-Type: application/json' https://54.202.22.3:8000/api/peering/self

{"response":{

"peered":true"managers":{

"1":{"self":true,"id":1}"2":{"not_set":true,"id":2}"3":{"not_set":true,"id":3}"4":{"not_set":true,"id":4}

}"id":1

}}

API URI OverlaySet Manager ID

© 2016 64

Example RequestResource set_manager_id

Argument Switch --id (integer)

Argument The manager ID as an integer, cannot be the same as the id of another manager in the topology, and cannot be greater than the number of managers in the topology.

Pre-License NoDetail Sets the Manager ID of a manager so that

it can be peered within a topology.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address set_manager_id --id 1

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 set_manager_id --id 1Response: id: 1 managers: "1": self: true id: 1

API Tool OverlaySet Manager ID

© 2016 65

Example RequestResource POST peering/peers

Argument Switch :id (integer):name (string)

Argument The "id" is the manager ID as an integer of the the manager you are peering with, NOT the id of the manager you are calling "add_peer" on.

The "name" is the IP address or host name of the manager you are peering with.

Pre-License NoDetail Creates a peering relationship from a

manager to another manager. The peering call is unidirectional. Reciprocal calls must be made to peer two managers together.

Note in order to complete the peering process the reciprocal manager peering call needs to be run on the Manager ID 2.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"id":2, "name":"Manager2IP"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/peering/peers

$ curl -k -X POST -u api:apidemopassword -H 'Content-Type: application/json' -d '{"id":2, "name":"172.31.2.0"}' https://192.168.30.247:8000/api/peering/peers { "response": { "peered": true, "id": 1, "managers": { "2": { "address": "172.31.2.0", "id": 2, "reachable": false }, "1": { "id": 1, "self": true } } } }

API URI OverlayAdd Peer

© 2016 66

Example RequestResource add_peer

Argument Switch --id (integer)--name (string)






Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address add_peer --id 2 --name manager2-ip-address

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 add_peer --id 2 --name 174.129.238.73

peered: true id: 1 managers: "1": self: true id: 1 "2": address: xxx.xxx.xxx.xxx.compute-1.amazonaws.com reachable: false id: 2

API Tool OverlayAdd Peer

© 2016 67

Example RequestResource POST peering/peers

Argument Switch :id (integer):name (string)






Generic Command

curl -k -X POST -u api:myapisecret -d '{"id":2, "name":"Manager2IP"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/peering/peers

$ curl -k -X POST -u api:test -d '{"id":"2", "name":"54.245.46.154"}' -H 'Content-Type: application/json' https://54.202.22.3:8000/api/peering/peers

{"response":{

"peered":true"managers":{

"1":{"self":true,"id":1}"2":{"address":"54.245.46.154","reachable":false,"id":2}"3":{"not_set":true,"id":3}"4":{"not_set":true,"id":4}

}"id":1

}}

API URI OverlayEdit Peer

© 2016 68

Example RequestResource add_peer

Argument Switch --id (integer)--name (string)






Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address add_peer --id 2 --name manager2-ip-address

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 add_peer --id 2 --name 174.129.238.73

peered: true id: 1 managers: "1": self: true id: 1 "2": address: xxx.xxx.xxx.xxx.compute-1.amazonaws.com reachable: false id: 2

API Tool OverlayEdit Peer

© 2016 69

Example RequestResource DELETE peering/peers/:id

Argument Switch NoneArgument The "id" is the manager ID as an integer of

the the manager you want to break your peering relationship with.

Pre-License NoDetail Breaks a peering relationship from a

manager to another manager. The peering call is unidirectional. Reciprocal calls must be made to fully break the peer relationship.

Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/peering/peers/id

$ curl -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/peering/peers/2 { "response": { "peered": true, "id": 1, "managers": { "2": { "not_set": true, "id": 2 }, "1": { "id": 1, "self": true } } } }

API URI OverlayDelete Peer

© 2016 70

Example RequestResource delete_peer

Argument Switch --id (integer)Argument The "id" is the manager ID as an integer of

the the manager you want to break your peering relationship with.

Pre-License NoDetail Breaks a peering relationship from a

manager to another manager. The peering call is unidirectional. Reciprocal calls must be made to fully break the peer relationship.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager1-ip-address delete_peer --id 2

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 delete_peer --id 2

peered: true id: 1 managers: "1": self: true id: 1 "2": not_set: true id: 2....

API Tool OverlayDelete Peer

© 2016

Connections: IPsec

71

© 2016 72

Example Request

$ curl -k -X GET -u api:test https://54.202.22.3:8000/api/ipsec

{"response":{

"remote_endpoints":{"1":{

"name":"M2""ipaddress":"54.189.243.82""pfs":true"id":1"private_ipaddress":"192.0.2.253""extra_config":[]"tunnels":{

"1":{"id":1"local_subnet":"172.31.1.1/32""remote_subnet":"192.168.1.1/32""description":"test"

}},"bgp_peers":{}"type":"ipsec"

}}"this_endpoint":{

"nat_traversal":true"ipaddress":"54.202.22.3""overlay_subnet":"172.31.1.0/24""private_ipaddress":"192.0.2.254""ipsec_local_ipaddress":"192.0.2.254""asn":65001

}}

}

Resource GET ipsec

Argument Switch NoneArgument NonePre-License NoDetail Returns information about all IPsec

endpoints and subnets defined.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/ipsec

API URI ConnectionsDescribe IPsec

© 2016 73

Example RequestResource describe_ipsec

Argument Switch NoneArgument NonePre-License NoDetail Returns information about all IPsec

endpoints and subnets defined.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_ipsec

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 desc_ipsec this_endpoint: overlay_subnet: 172.31.3.0/24 ipaddress: 50.17.119.158 nat_traversal: true asn: 65001 private_ipaddress: 50.17.119.158 ipsec_local_ipaddress: 50.17.119.158 remote_endpoints: "4": name: API_Created_Endpoint ipaddress: 63.250.226.147 tunnels: {} id: 4 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 pfs: true bgp_peers: {}

API Tool ConnectionsDescribe IPsec

© 2016 74

Example RequestResource get_ipsec_local_ipaddress

Argument Switch NoneArgument None

Pre-License NoDetail Because VNS3 managers run as virtual

instances in virtual infrastructure - there is a possibility that an instance will be re-launched, ending up with a different internal NAT address than it originally had, which would require all connected devices to change their information. As a result VNS3 has a "fake" NAT which is used so that it can remain constant across launches, meaning no reconfiguration by peer gateways.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address get_ipsec_local_ipaddress

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 get_ipsec_local_address ipsec_local_ipaddress: 192.0.2.254

DEPRECATED, please use desc_ipsec

API Tool ConnectionsGet IPsec Local IP Address

© 2016 75

Example RequestResource POST ipsec

Argument Switch :restart (boolean)Argument The "restart" arg restarts the Manager's

IPsec subsystem when the value is true.Pre-License NoDetail Does a complete restart of the IPsec

subsystem, resetting all IPsec tunnels.Generic Command

curl -k -X POST -u api:myapisecret -d '{"restart":"true"}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec

$ curl -k -X POST -u api:apidemopassword https://192.168.30.247:8000/api/ipsec -H 'Content-Type: application/json' -d '{"restart":"true"}' { "response": { "restart": true }

API URI ConnectionsRestart IPsec Subsystem

© 2016 76

Example RequestResource setup_ipsec

Argument Switch --restart (boolean)Argument The "restart" arg restarts the Manager's

IPsec subsystem when the value is true.Pre-License NoDetail Does a complete restart of the IPsec

subsystem, resetting all IPsec tunnels.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address setup_ipsec --restart true

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 setup_ipsec --restart true restart: true

API Tool ConnectionsRestart IPsec Subsystem

© 2016 77

Example RequestResource PUT ipsec

Argument Switch :nat_traversal (boolean):ipsec_local_ipaddress (address-string)

Argument The "nat-traversal" switch is true to enable nat-traversal and false to disable. This is a device wide setting.

The "ipsec_local_ipaddress" arg is effectively a "cloud NAT" address, since you don't know what your LAN address will be between invocations in a cloud, this address can be used by remote endpoints as your "behind a NAT" address, sometimes referred to Peer or IKE ID, if needed (e.g. Watchguard or Juniper).

Pre-License NoDetail Allows the setting of 2 parameters; NAT

Traversal and local LAN address. NOTE: These are device wide and must be set before any remote endpoint definitions are created. If they need to be changed, all remote endpoint information and tunnel information must be deleted.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"nat_traversal":"true", "ipsec_local_ipaddress":"ipaddress"}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec

$ curl -k -X PUT -u api:apidemopassword https://192.168.30.247:8000/api/ipsec -H 'Content-Type: application/json' -d '{"nat_traversal":"true", "ipsec_local_ipaddress":"192.168.5.6"}' Response: { "response": { "this_endpoint": { "asn": 65001, "nat_traversal": true, "ipsec_local_ipaddress": "192.168.5.6", "overlay_subnet": "172.31.0.0/22", "ipaddress": "99.8.10.90", "private_ipaddress": "192.168.5.6" }, "remote_endpoints": { } } }

API URI ConnectionsEdit IPsec Configuration

© 2016 78

Example RequestResource edit_ipsec_config

Argument Switch --nat_traversal (boolean)--ipsec_local_ipaddress (address-string)

Argument The "nat-traversal" switch is true to enable nat-traversal and false to disable. This is a device wide setting.

The "ipsec_local_ipaddress" arg is effectively a "cloud NAT" address, since you don't know what your LAN address will be between invocations in a cloud, this address can be used by remote endpoints as your "behind a NAT" address, sometimes referred to Peer or IKE ID, if needed (e.g. Watchguard or Juniper).

Pre-License NoDetail Allows the setting of 2 parameters; NAT

Traversal and local LAN address. NOTE: These are device wide and must be set before any remote endpoint definitions are created. If they need to be changed, all remote endpoint information and tunnel information must be deleted.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address edit_ipsec_config --nat_traversal true --ipsec_local_ipaddress vpn3-manager-local-address

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 edit_ipsec_config --nat_traversal true --ipsec_local_ipaddress 50.17.119.158

--- this_endpoint: overlay_subnet: 172.31.3.0/24 ipaddress: 50.17.119.158 nat_traversal: true asn: 65001 private_ipaddress: 50.17.119.158 ipsec_local_ipaddress: 50.17.119.158 remote_endpoints: {}

Note: This call can only be done before there are any remote endpoint defined. It is device wide across all endpoints.

API Tool ConnectionsEdit IPsec Configuration

© 2016 79

Example RequestResource set_ipsec_local_ipaddress

Argument Switch NoneArgument NonePre-License NoDetail Because VNS3 managers run as virtual

instances in virtual infrastructure - there is a possibility that an instance will be re-launched, ending up with a different internal NAT address than it originally had, which would require all connected devices to change their information. As a result VNS3 has a "fake" NAT which is used so that it can remain constant across launches, meaning no reconfiguration by peer gateways.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address set_ipsec_local_ipaddress --ipaddress my_new_persistent_NAT_address

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 set_ipsec_local_address --ipaddress 192.0.8.200

DEPRECATED, please use edit_ipsec_conf

API URI ConnectionsSet IPsec Local IP Address

© 2016 80

Example RequestResource POST ipsec/endpoints

Argument Switch :name (string):ipaddress (address-string):secret (string):pfs (boolean):extra_config (string):private_ipaddress (address-string):gre (boolean)

Argument The "name" arg is the name for the connection.

The "ipaddress" arg is the IP of the remote gw.

The "secret" arg is the pre-shared key.

The "pfs" enables Perfect Forward Secrecy if true, disables if false.

The "extra_config" arg is a string with additional options for the connection.

The "private_ipaddress" arg is the internal NAT address of the remote gateway.

The "gre" arg specifies if GRE is being used for the specific endpoint.

Pre-License No

Detail Create IPsec connection to the defined remote gateway.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"name":name, "ipaddress":"ipaddress", "secret":"psk}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec/endpoints

$ curl -k -X POST -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints -H 'Content-Type: application/json' -d '{"name":"ep_1", "ipaddress":"192.168.2.3", "secret":"ipsec_key"} Response: { "response": { "pfs": true, "tunnels": { }, "extra_config": [ ], "bgp_peers": { }, "name": "ep_1", "id": 1, "ipaddress": "192.168.2.3" } }

API URI ConnectionsCreate IPsec Endpoint

© 2016 81

Example RequestResource create_ipsec_endpoint

Argument Switch --name (string)--ipaddress (address-string)--secret (string)--pfs (boolean)--extra_config (string)--private_ipaddress (address-string)--gre (boolean)

Argument The "name" arg is the name for the connection.



The "pfs" enables Perfect Forward Secrecy if true, disables if false.

The "extra_config" arg is a string with additional options for the connection.

The "private_ipaddress" arg is the internal NAT address of the remote gateway.

The "gre" arg specifies if GRE is being used for the specific endpoint.

Pre-License No

Detail Create IPsec connection to the defined remote gateway.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address create_ipsec_endpoint --name "IPsec Connection" --ipaddress remote-gateway-address --secret preshared-key --pfs true --extra_config config-string

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 create_ipsec_endpoint --name "API_Created_Endpoint" --ipaddress 63.250.226.147 --secret "testing" --pfs true --extra-config "phase1=aes256-sha1-dh5 phase2=aes256-sha1"

name: API_Created_Endpoint ipaddress: 63.250.226.147 tunnels: {}id: 4 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 pfs: true bgp_peers: {}

API Tool ConnectionsCreate IPsec Endpoint

© 2016 82

Example RequestResource PUT ipsec/endpoints/:endpoint

Argument Switch :endpoint (integer):name (string):ipaddress (address-string):secret (string):pfs (boolean):extra_config (string):private_ipaddress (address-string):gre (boolean

Argument The "endpoint" arg is the id number of the specific endpoint which is being edited.

The "name" arg is the name for the connection.



The "--pfs" arg enables/disables PFS.

The "--extra_config" arg is a string with additional options for the connection.

The "--private_ipaddress" arg is the internal NAT address of the remote gateway.

The "gre" arg enables/disables GRE.

Pre-License No

Detail Edit an existing IPsec Endpoint definition.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"name":name,}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec/endpoints./1

$ curl -k -X PUT -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1 -H 'Content-Type: application/json' -d '{"pfs":"true"}' Response:{ "response": { "pfs": true, "tunnels": { }, "extra_config": [ ], "bgp_peers": { }, "name": "ep_1", "id": 1, "ipaddress": "192.168.2.3 } }

API URI ConnectionsEdit IPsec Endpoint

© 2016 83

Example RequestResource edit_ipsec_endpoint

Argument Switch --endpoint (integer)--name (string)--ipaddress (address-string)--secret (string)--pfs (boolean)--extra_config (string)--private_ipaddress (address-string)--gre (boolean

Argument The "endpoint" arg is the id number of the specific endpoint which is being edited.

The "name" arg is the name for the connection.



The "--pfs" arg enables/disables PFS.

The "--extra_config" arg is a string with additional options for the connection.

The "--private_ipaddress" arg is the internal NAT address of the remote gateway.

The "gre" arg enables/disables GRE.

Pre-License No

Detail Edit an existing IPsec Endpoint definition.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address edit_ipsec_endpoint --endpointid 1 --private-ipaddress gateway_nat_address

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 edit_ipsec_endpoint --endpoint 4 --ipaddress 63.250.226.147 --secret "testing" --pfs true --extra-config "phase1=aes256-sha1-dh5 phase2=aes256-sha1 dpdaction=restart dpdtimeout=90s dpddelay=30s" --private-ipddress 192.168.1.30

name: API_Created_Endpoint ipaddress: 63.250.226.147 tunnels: {} id: 4 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 - dpdaction=restart - dpdtimeout=90s - dpddelay=30s pfs: true private_ipaddress: 192.168.1.30 bgp_peers: {}

API Tool ConnectionsEdit IPsec Endpoint

© 2016 84

Example Request

$ curl -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1 Response: { "response": { "this_endpoint": { "asn": 65001, "nat_traversal": true, "ipsec_local_ipaddress": "192.168.5.6", "overlay_subnet": "172.31.0.0/22", "ipaddress": "99.8.10.90", "private_ipaddress": "192.168.5.6" }, "remote_endpoints": { } } }

Resource DELETE ipsec/endpoints/:endpoint

Argument Switch :endpoint (integer)Argument The "endpoint" arg specifies which of the

defined remote endpoints is to be deleted.

Pre-License NoDetail Deletes the IPsec endpoint specified.Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/ipsec/1

API URI ConnectionsDelete IPsec Endpoint

© 2016 85

Example RequestResource delete_ipsec_endpoint

Argument Switch --endpoint (integer)Argument The "endpoint" arg specifies which of the


Pre-License NoDetail Deletes the IPsec endpoint specified.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_ipsec_endpoint --endpointid integer_of_one_of_the_endpoints

$ ./vnscubed.rb -K api -S test -H 54.202.22.3 delete_ipsec_endpoint --endpoint 2

---remote_endpoints: "1": extra_config: [] bgp_peers: {} type: ipsec name: M2 private_ipaddress: 192.0.2.253 ipaddress: 54.189.243.82 id: 1 tunnels: "2": ping_interval: remote_subnet: 192.168.1.2/32 ping_ipaddress: "" description: test2 local_subnet: 172.31.1.2/32 id: 2 "1": ping_interval: remote_subnet: 192.168.1.1/32 ping_ipaddress: "" description: test local_subnet: 172.31.1.1/32 id: 1 pfs: truethis_endpoint: ipsec_local_ipaddress: 192.0.2.254 overlay_subnet: 172.31.1.0/24 nat_traversal: true private_ipaddress: 192.0.2.254 ipaddress: 54.202.22.3 asn: 65001

API Tool ConnectionsDelete IPsec Endpoint

© 2016 86

Example RequestResource GET ipsec/endpoints/:endpoint

Argument Switch :endpoint (integer)Argument The "endpoint" arg specifies which of the


Pre-License NoDetail Returns detailed information about the

IPsec endpoint specified.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/ipsec/1

$ curl -k -X GET -u api:test https://54.185.32.202:8000/api/ipsec/endpoints/1

{"response":{

"name":"M2""ipaddress":"54.189.243.82""pfs":true"id":1"private_ipaddress":"192.0.2.253""extra_config":[]"tunnels":{

"2":{"id":2"local_subnet":"172.31.1.2/32""remote_subnet":"192.168.1.2/32""description":"test2""ping_ipaddress":"""ping_interval":null

}"3":{

"id":3"local_subnet":"172.31.1.1/32""remote_subnet":"192.168.1.1/32""description":"test""ping_ipaddress":"""ping_interval":null

}}"bgp_peers":{}"type":"ipsec"

}}

API URI ConnectionsDescribe IPsec Endpoint

© 2016 87

Example RequestResource desc_ipsec_endpoint

Argument Switch --endpoint (integer)Argument The "endpoint" arg specifies which of the


Pre-License NoDetail Returns detailed information about the

IPsec endpoint specified.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_ipsec_endpoint --endpointid integer_of_one_of_the_endpoints

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 desc_ipsec_endpoint --endpointid 1

this_endpoint: overlay_subnet: 172.31.3.0/24 ipaddress: 50.17.119.158 nat_traversal: true asn: 65001 private_ipaddress: 50.17.119.158 ipsec_local_ipaddress: 50.17.119.158 remote_endpoints: "1": name: API_Created_Endpoint ipaddress: 63.250.226.147 tunnels: {} id: 1 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 pfs: true bgp_peers: {}

API Tool ConnectionsDescribe IPsec Endpoint

© 2016 88

Example RequestResource POST ipsec/endpoints/:endpoint/tunnels

Argument Switch :endpoint (integer):remote_subnet (CIDR):local_subnet (CIDR):ping_ipaddress (address-string):ping_interval (integer):description (string)

Argument The "endpoint" arg specifies which of the defined remote endpoints the tunnel is to be created for.

The "remote-subnet" arg is the subnet desired from the remote endpoint.

The "local-subnet" arg specifies the subnet available behind the Manager.

The "ping-ipaddress" arg is the IP address of a host in the "--remote-subnet" address space that will have a ping sent to it every "--ping-interval". (Note: This ping goes through the tunnel))

The "description" arg is a description of the tunnel.

Pre-License No

Detail Creates an ipsec tunnel description offering up a local subnet specification for talking to a remote subnet on the other side of a remote endpoint/gateway.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"remote_subnet":"subnet", "local_subnet":"subnet"}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec/endpoints/1/tunnels

$ curl -k -X POST -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1/tunnels -H 'Content-Type: application/json' -d '{"remote_subnet":"192.168.9.0/24", "description":"tunnel-1-1"}' Response: { "response": { "pfs": true, "tunnels": { "1": { "description": "tunnel-1-1", "remote_subnet": "192.168.9.0/24", "local_subnet": "172.31.0.0/22", "id": 1 } }, "extra_config": [ ], "bgp_peers": { }, "name": "ep_1", "id": 1, "ipaddress": "192.168.2.3" } }

API URI ConnectionsCreate IPsec Tunnel

© 2016 89

Example RequestResource create_ipsec_tunnel

Argument Switch --endpoint (integer)--remote_subnet (CIDR)--local_subnet (CIDR)--ping_ipaddress (address-string)--ping_interval (integer)--description (string)


The "remote-subnet" arg is the subnet desired from the remote endpoint.

The "local-subnet" arg specifies the subnet available behind the Manager.

The "ping-ipaddress" arg is the IP address of a host in the "--remote-subnet" address space that will have a ping sent to it every "--ping-interval". (Note: This ping goes through the tunnel))


Pre-License No

Detail Creates an ipsec tunnel description offering up a local subnet specification for talking to a remote subnet on the other side of a remote endpoint/gateway.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address create_ipsec_tunnel --endpoint endpoint-id --remote_cubnet cidr_string --local_subnet cidr_string --ping_ipaddress address_on_remote_subnet --ping_interval seconds_as_integer

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 create_ipsec_tunnel --endpoint 5 --remote_subnet "192.168.4.0/24" --local_subnet "172.31.3.0/24" --ping-ipaddress 192.168.4.1 --ping_interval 60

name: API_Created_Endpoint ipaddress: 63.250.226.147 tunnels: "5": remote_subnet: 192.168.4.0/24 ping_ipaddress: 192.168.4.1 id: 5 description: ping_interval: 60 local_subnet: 172.31.3.0/24 id: 5 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 - dpdaction=restart - dpdtimeout=90s - dpddelay=30spfs: true private_ipaddress: 192.168.1.30 bgp_peers: {}

API Tool ConnectionsCreate IPsec Tunnel

© 2016 90

Example RequestResource PUT ipsec/endpoints/:endpoint/tunnels/:tunnelid

Argument Switch :endpoint (integer):tunnelid (integer):bounce (boolean):description (string):ping_address (address-string):ping_interval (integer)


The "tunnelid" arg is id of the tunnel to be edited.

The "bounce" arg, when "true" resets the IPsec connection for this specific tunnel.


The "ping-ipaddress" arg is the IP address of a host in the "--remote-subnet" address space that will have a ping sent to it every "--ping-interval". (Note: This ping goes through the tunnel)

Pre-License No

Detail Edits the IPsec tunnel specified.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"bounce":"true", "description":"newtext"}' -H Content-Type: application/json'' https://manager-ip-address:8000/api/ipsec/endpoints/1/tunnels/1

$ curl -k -X PUT -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1/tunnels/1 -H 'Content-Type: application/json' -d '{"bounce":false}'Response: { "response": { "description": "tunnel-1-1", "remote_subnet": "192.168.9.0/24", "local_subnet": "172.31.0.0/22", "id": 1 } }

API URI ConnectionsEdit IPsec Tunnel

© 2016 91

Example RequestResource edit_ipsec_tunnel

Argument Switch --endpoint (integer)--tunnelid (integer)--bounce (boolean)--description (string)--ping_address (address-string)--ping_interval (integer)


The "tunnelid" arg is id of the tunnel to be edited.

The "bounce" arg, when "true" resets the IPsec connection for this specific tunnel.


The "ping-ipaddress" arg is the IP address of a host in the "--remote-subnet" address space that will have a ping sent to it every "--ping-interval". (Note: This ping goes through the tunnel)

Pre-License No

Detail Edits the IPsec tunnel specified.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address edit_ipsec_tunnel --endpoint integer_of_one_of_the_endpoints --ping-address address_on_remote_subnet --ping-interval seconds_as_integer --bounce true

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 edit_ipsec_tunnel --endpoint 5 --tunnelid 5 --ping-ipaddress 192.168.4.1 --ping-interval 60 --bounce true

remote_subnet: 192.168.4.0/24 ping_ipaddress: 192.168.4.1 id: 5 description: ping_interval: 60 bounce: true local_subnet: 172.31.3.0/24

API Tool ConnectionsEdit IPsec Tunnel

© 2016 92

Example RequestResource DELETE ipsec/endpoints/:endpoint/subnets/:tunnelid

Argument Switch :endpoint (integer):tunnelid (integer)

Argument The "endpointid" arg specifies which of the defined remote endpoints is to be deleted.

The "tunnelid" arg is the tunnel id of the specific tunnel for the specified endpoint to be deleted.

Pre-License NoDetail Delete an IPsec tunnel from a specified

endpoint. Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/ipsec/1/subnets/:tunnelid

$ curl -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1/subnets/1 Response: { "response": { "pfs": true, "tunnels": { }, "extra_config": [ ], "bgp_peers": { "1": { "asn": 65123, "ipaddress": "192.168.10.0", "id": 1 } }, "name": "ep_1", "id": 1, "ipaddress": "192.168.2.3" } }

API URI ConnectionsDelete IPsec Tunnel

© 2016 93

Example RequestResource delete_ipsec_tunnel

Argument Switch --endpoint (integer)--tunnelid (integer)

Argument The "endpointid" arg specifies which of the defined remote endpoints is to be deleted.

The "tunnelid" arg is the tunnel id of the specific tunnel for the specified endpoint to be deleted.

Pre-License NoDetail Delete an IPsec tunnel from a specified

endpoint. Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_ipsec_tunnel --endpoint integer_of_one_of_the_endpoints --tunnelid integer_of_one_of_the_tunnels

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 delete_ipsec_tunnel --endpoint 5 --tunnelid 5

name: API_Created_Endpoint ipaddress: 50.17.119.158 tunnels: {} id: 5 extra_config: - phase1=aes256-sha1-dh5 - phase2=aes256-sha1 - dpdaction=restart - dpdtimeout=90s - dpddelay=30s pfs: true private_ipaddress: 192.168.1.30 bgp_peers: {}

API Tool ConnectionsDelete IPsec Tunnel

© 2016 94

Example RequestResource POST ipsec/endpoints/:endpoint/ebgp_peers

Argument Switch :endpoint (integer):ipaddress (integer):asn (integer)

Argument The "endpoint" arg specifies which of the defined remote endpoints the eBGP peer is to be created for.

The "ipaddress" arg is the IP address of the desired BGP peer.

The "asn" argument is the "autonomous system number" assigned to the device at "ipaddress".

Pre-License NoDetail Create a BGP peer connection.Generic Command

curl -k -X POST -u api:myapisecret -d '{"ipaddress":"ip", "asn":"number"}' https://manager-ip-address:8000/api/ipsec/endpoints/1/ebgp_peers

$ curl -k -X POST -u api:apidemopassword https://192.168.30.247:8000/api/ipsec/endpoints/1/ebgp_peers -H 'Content-Type: application/json' -d '{"ipaddress":"192.168.10.0", "asn":65123}' Response: { "response": { "pfs": true, "tunnels": { "1": { "description": "tunnel-1-1", "remote_subnet": "192.168.9.0/24", "local_subnet": "172.31.0.0/22", "id": 1 } }, "extra_config": [ ], "bgp_peers": { "1": { "asn": 65123, "ipaddress": "192.168.10.0", "id": 1, } }, "name": "ep_1", "id": 1, "ipaddress": "192.168.2.3" } }

API URI ConnectionsCreate eBGP Peer

© 2016 95

Example RequestResource create_ebgp_peer

Argument Switch --endpoint (integer)--ipaddress (integer)--asn (integer)

Argument The "endpoint" arg specifies which of the defined remote endpoints the eBGP peer is to be created for.

The "ipaddress" arg is the IP address of the desired BGP peer.

The "asn" argument is the "autonomous system number" assigned to the device at "ipaddress".

Pre-License NoDetail Create a BGP peer connection.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address create_ebgp_peer --endpoint integer_of_one_of_the_endpoints --ipaddress ipaddress_of_bgppeer --asn asn_number

$ ./vnscubed.rb -K api -S test -H 54.202.22.3 create_ebgp_peer --endpoint 3 --ipaddress 10.54.10.203 --asn 65101

---extra_config: []

bgp_peers: "1": asn: 65101 id: 1 ipaddress: 10.54.10.203pfs: trueid: 3name: AWS_VPC_VPGipaddress: 54.221.34.10type: ipsectunnels: {}

API Tool ConnectionsCreate eBGP Peer

© 2016 96

Example RequestResource DELETE ipsec/endpoints/:endpoint/ebgp_peers/:ebgppeerid

Argument Switch :endpoint (integer):ebgpeerid (integer)

Argument The "endpoint" arg specifies which of the defined remote endpoints the eBGP peer is to be deleted from.

The "ebgppeerid" arg is the id of the BGP Peer gotten from the create command or via a desc_ipsec command.

Pre-License NoDetail Deletes a BGP peer connection.Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/ipsec/1/ebgp_peers/1

$ curl -k -X DELETE -u api:test https://54.202.22.3:8000/api/ipsec/endpoints/3/ebgp_peers/2

{"response":{

"name":"AWS_VPC_VPG""ipaddress":"54.221.34.10""pfs":true"id":3"extra_config":[]"tunnels":{}"bgp_peers":{}"type":"ipsec"

}}

API URI ConnectionsDelete eBGP Peer

© 2016 97

Example RequestResource delete_ebgp_peer

Argument Switch --endpoint (integer)--ebgpeerid (integer)

Argument The "endpoint" arg specifies which of the defined remote endpoints the eBGP peer is to be deleted from.

The "ebgppeerid" arg is the id of the BGP Peer gotten from the create command or via a desc_ipsec command.

Pre-License NoDetail Deletes a BGP peer connection.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_ebgp_peer --endpoint integer_of_one_of_the_endpoints --ebgppeerid integer_of_one_of_peers

$ ./vnscubed.rb -K api -S test -H 54.202.22.3 delete_ebgp_peer --endpoint 3 --ebgppeerid 1

---type: ipsecextra_config: []

tunnels: {}

ipaddress: 54.221.34.10id: 3name: AWS_VPC_VPGbgp_peers: {}

pfs: true

API Tool ConnectionsDelete eBGP Peer

© 2016

Connections: Firewall

98

© 2016 99

Example Request

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/firewall/rules

{ "response": [ [ "-o eth0 -s 10.199.1.0/24 -j MASQUERADE\n", 0 ], [ "-o eth0 -s 10.199.2.0/24 -j MASQUERADE", 1 ] ] }

Resource GET firewall/rules

Argument Switch NoneArgument NonePre-License NoDetail Describes any firewall setting on the VNS3

Manager.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/firewall/rules

API URI ConnectionsDescribe Firewall

© 2016 100

Example RequestResource desc_firewall

Argument Switch NoneArgument NonePre-License NoDetail Describes any firewall setting on the VNS3


vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_firewall

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 desc_firewall

--- - - -s 192.168.11.5/32 -j ACCEPT - 0

The response means "this rules is at position 0" in the rule table.

API Tool ConnectionsDescribe Firewall

© 2016 101

Example RequestResource POST firewall/rules

Argument Switch :rule (string):position (positive or negative integer)

Argument The "rule" arg is a string to add to the firewall at position --position in the list of rules. It is a string that needs to be compatible with a Linux "iptables" statement. See the VNS3 Administration Guide for rule syntax.

The "position" arg is the position which the rule will be inserted in the list of Firewall rules. The default is "-1", meaning at the top of the rule set.

Pre-License NoDetail Adds a firewall rule to the VNS3

Manager's firewall. Generic Command

curl -k -X POST -u api:myapisecret -d '{"rule":"MACRO_CUST -o eth0 -s 10.199.2.0./24 -j MASQUERADE"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/firewall/rules

$ curl -k -X POST -u api:apidemopassword -d '{"rule":"-o eth0 -s 10.199.2.0/24 -j MASQUERADE"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/firewall/rules Response: { "response": [ [ "-o eth0 -s 10.199.1.0/24 -j MASQUERADE\n", 0 ], [ "-o eth0 -s 10.199.2.0/24 -j MASQUERADE", 1 ] ] }

API URI ConnectionsAdd Firewall Rule

© 2016 102

Example RequestResource add_firewall_rule

Argument Switch --rule (string)--position (positive or negative integer)

Argument The "rule" arg is a string to add to the firewall at position --position in the list of rules. It is a string that needs to be compatible with a Linux "iptables" statement. See the VNS3 Administration Guide for rule syntax.

The "position" arg is the position which the rule will be inserted in the list of Firewall rules. The default is "-1", meaning at the top of the rule set.

Pre-License NoDetail Adds a firewall rule to the VNS3


vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address add_firewall-rule --position -1 --rule iptables_string

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 add_firewall_rule --position -1 "-s 192.168.11.5/32" -j ACCEPT"--- - - -s 192.168.11.5/32 -j ACCEPT - 0

Note: This rule may not be relevant to the rest of the topology parameters and is just for example purposes. The response means "this rule at position 0" in the rule table.

API Tool ConnectionsAdd Firewall Rule

© 2016 103

Example Request

$ curl -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/firewall/rules/1

{ "response": { "rules": [ [ "-o eth0 -s 10.199.1.0/24 -j MASQUERADE\n", 0 ] ], "deleted": "-o eth0 -s 10.199.2.0/24 -j MASQUERADE } }

Resource DELETE firewall/rules/:position

Argument Switch :position (positive or negative integer)Argument The "position" arg is the position which

the rule will be deleted in the list of Firewall rules.

Pre-License NoDetail Removes a firewall rule from the VNS3


curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/firewall/rules/1

API URI ConnectionsDelete Firewall Rule

© 2016 104

Example RequestResource delete_firewall_rule

Argument Switch --position (positive or negative integer)Argument The "position" arg is the position which

the rule will be deleted in the list of Firewall rules.

Pre-License NoDetail Removes a firewall rule from the VNS3


vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_firewall-rule --position position_in_rule_list

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 delete_firewall_rule --position 0--- rules: [ ] deleted: -s 192.168.11.5/32 -j ACCEPT

API Tool ConnectionsDelete Firewall Rule

© 2016

Connections: Routes

105

© 2016 106

Example RequestResource GET routes

Argument Switch NoneArgument NonePre-License NoDetail Describes routes that this manager has

access to via its network interfaces (virtual or otherwise) that it wants to publish to overlay network devices. Other VPN3 Managers will receive the route essentially instantly. Network clients will receive it when they get their next route push, which is normally on a re-connect or in neartime if they use the VNS3 routing agent on their cloud servers. Remote endpoints (other data centers) would not receive the route unless specified as part of their IPsec configuration AND the configuration of such a tunnel on the VNS3 manager.

Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/routes

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/routes{ "response": { "172.31.4.0/24": { "netmask": "255.255.255.0", "id": "2887713792-24", "cidr": "172.31.4.0/24" }, "172.31.3.0/24": { "netmask": "255.255.255.0", "id": "2887713536-24", "cidr": "172.31.3.0/24" } } }

API URI ConnectionsDescribe Route

© 2016 107

Example RequestResource desc_routes

Argument Switch NoneArgument NonePre-License NoDetail Describes routes that this manager has

access to via its network interfaces (virtual or otherwise) that it wants to publish to overlay network devices. Other VPN3 Managers will receive the route essentially instantly. Network clients will receive it when they get their next route push, which is normally on a re-connect or in neartime if they use the VNS3 routing agent on their cloud servers. Remote endpoints (other data centers) would not receive the route unless specified as part of their IPsec configuration AND the configuration of such a tunnel on the VNS3 manager.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_routes

$ ./vnscubed.rb -K api -S test -H 54.185.32.202 desc_routes

---224.0.0.0/4: netmask: 240.0.0.0 interface: tun0 cidr: 224.0.0.0/4 description: Multicast (auto-added) id: 1

API Tool ConnectionsDescribe Route

© 2016 108

API URILicensingUpload License

Example RequestResource POST routes

Argument Switch :cidr (CIDR):description (string):interface (string):tunnel (integer)

Argument The "cidr" argument is the CIDR of a route that the VNS3 Manager has access to that it wants to publish throughout the routing tables of the overlay network.

The "description" argument is the description added to the route.

The "interface" argument sets the interface for advertisement.

The "tunnel" argument set the numerical reference for the route.

Pre-License NoDetail Pushes routes that this manager has

access to via its network interfaces (virtual or otherwise) that it wants to publish to overlay network devices.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"cidr":"172.31.100.0/24", "interface":"eth0", "tunnel";2}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/routes

$ curl -k -X POST -u api:apidemopassword -d '{"cidr":"172.31.3.0/24"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/routesResponse: { "response": { "172.31.3.0/24": { "netmask": "255.255.255.0", "id": "2887713536-24", "cidr": "172.31.3.0/24 } }}

© 2016 109

Example RequestResource add_route

Argument Switch --cidr (CIDR)--description (string)--interface (string)--tunnel (integer)

Argument The "cidr" argument is the CIDR of a route that the VNS3 Manager has access to that it wants to publish throughout the routing tables of the overlay network.

The "description" argument is the description added to the route.

The "interface" argument sets the interface where this route will be advertised.

The "tunnel" argument set the numerical reference for the route.

Pre-License NoDetail Pushes routes that this manager has

access to via its network interfaces (virtual or otherwise) that it wants to publish to overlay network devices.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address add_route --cidr cidr-string-of-interface-i-am-connected-to

$ ./vnscubed.rb -K api -S test -H 54.185.32.202 add_route --cidr 172.31.3.0/24 --description VLAN --interface eth0

---224.0.0.0/4: id: 1 cidr: 224.0.0.0/4 netmask: 240.0.0.0 description: Multicast (auto-added) interface: tun0172.31.3.0/24: id: 2 cidr: 172.31.3.0/24 netmask: 255.255.255.0 description: VLAN interface: eth0

API Tool ConnectionsAdd Route

© 2016 110

Example Request

$ curl -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/routes/2{ "response": { "192.168.1.0/24": { "netmask": "255.255.255.0", "id": "3232235776-24", "cidr": "192.168.1.0/24" } } }

Resource DELETE routes/:id

Argument Switch :id (integer)Argument The "id" is the id number of the route as

returned in the add_route response, or from the desc_routes response.

Pre-License NoDetail Deletes routes that this manager has

access to via its network interfaces (virtual or otherwise) but that it wants to "un-publish" to overlay network devices.

Response is the list of remaining routes.Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/routes/id

API URI ConnectionsDelete Route

© 2016 111

Example RequestResource delete_route

Argument Switch --id (integer)Argument The "id" argument is the id number of the

route as returned in the add_route response, or from the desc_routes response.

Pre-License NoDetail Deletes routes that this manager has

access to via its network interfaces (virtual or otherwise) but that it wants to "un-publish" to overlay network devices.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_route --id route-id

$ vpn3api/vpncubed.rb -K $common_api_key -S $common_api_secret -H $manager1 delete_route --id 167840266-32 --- {}

API Tool ConnectionsDelete Route

© 2016

Containers

112

© 2016 113

Example Request

$ curl -k -X GET -u api:apipassword https://192.168.30.123:8000/api/container_system{ "response": { "running":true", "network":"172.0.20.0/28" } }

Resource GET container_system

Argument Switch NoneArgument NonePre-License NoDetail Provides status and network information

for the Manager's container system.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/container_system

API URI ContainersDescribe Container System

© 2016 114

Example RequestResource desc_container_system

Argument Switch NoneArgument NonePre-License NoDetail Provides status and network information

for the Manager's container system.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address desc_container_system

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 desc_container_system

network: 172.0.10.0/28 running: true

API Tool ContainersDescribe Container System

© 2016 115

Example RequestResource PUT container_system

Argument Switch :network (CIDR)Argument The "network" arg is the subnet CIDR that

will be used for the container network.

Pre-License NoDetail Configures the container systems

network.Generic Command

curl -k -X PUT -u api:myapisecret -d '{"network":"cidr"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system

$ curl -k -X PUT -u api:apipassword -H 'Content-Type: application/json' -d '{"network":"172.0.10.0/28"}' https://192.168.30.123:8000/api/container_system{ "response":{ "running":true, "network":"172.0.10.0/28" } }

API URI ContainersSet up Container System

© 2016 116

Example RequestResource setup_container_system

Argument Switch --network (CIDR)Argument The "network" arg is the subnet CIDR that

will be used for the container network.

Pre-License NoDetail Configures the container systems

network.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address setup_container_system --network network-subnet

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 setup_container_system --network 172.0.20.0/28

network: 172.0.20.0/28 running: true

API Tool ContainersSet up Container System

© 2016 117

Example RequestResource POST container_system

Argument Switch :action (string)Argument The "action" arg is used to pass the "start"

command.Pre-License NoDetail Starts the Manager's container system.Generic Command

curl -k -X POST -u api:myapisecret -d '{"action":"start"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system

$ curl -k -X POST -u api:apipassword -H 'Content-Type:application/json' -d '{"action":"start"}' https://192.168.30.123:8000/api/container_system{ "response":{ "running":true, "network":"172.0.10.0/28" } }

API URI ContainersStart Container System

© 2016 118

Example RequestResource start_container_system

Argument Switch NoneArgument NonePre-License NoDetail Starts the Manager's container system.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address start_container_system

$ ./vnscubed.rb -K api -S test -H 54.202.22.3 start_container_system

---running: truenetwork: 198.51.100.0/28

API Tool ContainersStart Container System

© 2016 119

Example RequestResource POST container_system

Argument Switch :action (string)Argument The "action" arg is used to pass the "stop"

command.Pre-License NoDetail Starts the Manager's container system.Generic Command

curl -k -X POST -u api:myapisecret -d '{"action":"stop"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system

$ curl -k -X POST -u api:apipassword -H 'Content-Type:application/json' -d '{"action":"stop"}' https://192.168.30.123:8000/api/container_system{ "response":{ "running":false, "network":"172.0.10.0/28" } }

API URI ContainersStop Container System

© 2016 120

Example RequestResource stop_container_system

Argument Switch NoneArgument NonePre-License NoDetail Stops the Manager's container system.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address stop_container_system

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 50.17.119.158 stop_container_system

network: 172.0.20.0/28 running: false

API Tool ContainersStop Container System

© 2016 121

Example RequestResource GET container_system/images

Argument Switch :uuid (string)Argument The "uuid" arg specifies a container image.

If not specified all container images are displayed.

Pre-License NoDetail Provides description information for one

or all container images on a specific Manager.

Generic Command

curl -k -X GET -u api:myapisecret -d '{"uuid":"uuid-of-container-image"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system/images

$ curl -k -X GET -u api:apipassword -H 'Content-Type:application/json' -d '{"uuid":"8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12"}' https://192.168.30.123:8000/api/container_system/images{ "response": { "images": [ { "created": "2014-06-04T14:07:54.381920459Z", "comment": "Imported from https://s3.amazonaws.com/cftdocker/sshd_nginx.tar.gz", "container_config": { "Entrypoint": null, "Dns": null, "OpenStdin": false, "AttachStdout": false, "AttachStdin": false, "Env": null,"User": "", "Tty": false, "ExposedPorts": null, "MemorySwap": 0, "VolumesFrom": "", "Volumes": null, "Cmd": null, "PortSpecs": null, "Image": "", "WorkingDir": "", "CpuShares": 0, "NetworkDisabled": false, "StdinOnce": false, "AttachStderr": false, "Memory": 0, "Domainname": "", "OnBuild": null, "Hostname": "" }, "docker_version": "0.9.1", "Size": 254732355, "os": "linux", "id": "eed15f7f3292cf8852774dad3811a43ba9f8d3af8497a26182cb4b4febe2e347", "architecture": "amd64" } ] } }

API URI ContainersDescribe Container Image

© 2016 122

Example RequestResource desc_images

Argument Switch --uuid (string)Argument The "uuid" arg specifies a container image.

If not specified all container images are displayed.


or all container images on a specific Manager.

Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address desc_images -uuid uuid-of-a-container

$ vnscubed.rb -K api -S apipassword -H 182.168.30.123 desc_images --uuid 8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12

images: - os: linux architecture: amd64 container_config: WorkingDir: "" Entrypoint: Cmd: Tty: false ExposedPorts: AttachStdin: false User: "" Volumes: OpenStdin: false MemorySwap: 0 StdinOnce: false Hostname: "" PortSpecs: Domainname: "" NetworkDisabled: false VolumesFrom: "" Image: "" AttachStderr: false CpuShares: 0 OnBuild: Dns: Env: AttachStdout: false Memory: 0 created: "2014-06-03T14:20:29.11989495Z" docker_version: 0.9.1 id: 8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12 comment: Imported from https://s3.amazonaws.com/cftdocker/sshd_nginx.tar.gz Size: 254732355

API Tool ContainersDescribe Container Image

© 2016 123

Example RequestResource POST container_system/images

Argument Switch :name (string):url (string):buildurl (string):description (string)

Argument The "name" arg is the name of the image.

The "url" arg is the URL of the LXC or Libcontainer image file to be imported.

The "buildurl" arg is the URL of a docker file that will be used to build the image.

The "description" arg is a text description of the image.

Note: either "--url" or "--buildurl" must be specified

Pre-License NoDetail Creates a Container Image.Generic Command

curl -k -X POST -u api:myapisecret -d '{"name":"container-name", "url":"container-url"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system/images

$ curl -k -X POST -u api:test -d '{"name":"TCP Tools", "url":"https://s3.amazonaws.com/cft.customer.downloads/lxc-images/CohesiveFT_Demo_TCP_Tools.export.tar.gz", "description":"CohesiveFT TCP Tools Image"}' -H 'Content-Type: application/json' https://54.224.182.199:8000/api/container_system/images

{ "response": { "status":"Image being uploaded" } }

API URI ContainersCreate a Container Image

© 2016 124

Example RequestResource create_image

Argument Switch --name (string)--url (string)--buildurl (string)--description (string)

Argument The "name" arg is the name of the image.

The "url" arg is the URL of the LXC or Libcontainer image file to be imported.

The "buildurl" arg is the URL of a docker file that will be used to build the image.


Note: either "--url" or "--buildurl" must be specified

Pre-License NoDetail Creates a Container Image.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address create_image --name image-name --url container-url

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 create image --url https://s3.amazonaws.com/mybucket/sshd_nginx.tar.gz --name "myImageName" --description "my image"

status: Image being uploaded

API Tool ContainersCreate a Container Image

© 2016 125

Example RequestResource PUT container_system/images/:uuid

Argument Switch :uuid (string):name (string):description (string)

Argument The "uuid" arg specifies a container image to edit.

The "name" arg is the name of the image.


Pre-License NoDetail Edits a Container Image.Generic Command

curl -k -X PUT -u api:myapisecret -d '{"name":"new-name"}' -H 'Content-Type: applicaiton/json https://manager-ip-address:8000/api/container_system/images/uuid

$ curl -k -X PUT -u api:apipassword -H 'Content-Type:application/json' -d '{"name":"new image name","description":"new image description"}' https://192.168.30.123:8000/api/container_system/images/8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12

{ "response"{ "uuid":"8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12", "status":"Image updated" } }

API URI ContainersEdit a Container Image

© 2016 126

Example RequestResource edit_image

Argument Switch --uuid (string)--name (string)--description (string)

Argument The "uuid" arg specifies a container image to edit.

The "name" arg is the name of the image.


Pre-License NoDetail Edits a Container Image.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address edit_image --uuid uuid-of-a-container --name new-image-name --description new-description

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 edit_image --uuid 4c7fa47be1f0301731469bedaccc2e57ace98634b3c0320387e213ef3b45bfc1 --name "imageName" --description "new image description"status: Image updated uuid: 4c7fa47be1f0301731469bedaccc2e57ace98634b3c0320387e213ef3b45bfc1

API Tool ContainersEdit a Container Image

© 2016 127

Example RequestResource DELETE container_system/images/:uuid

Argument Switch :uuid (string)Argument The "uuid" arg specifies a container image

to delete.Pre-License NoDetail Deletes a Container Image.Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/container_system/images/uuid

$ curl -k -X DELETE -u api:apipassword https://192.168.30.123:8000/api/container_system/images/f9b44f60969c77bf7c3baaf6f54ec4382e59e89510356b2e21263d574ab9221d

{ "response":{ "uuid":"f9b44f60969c77bf7c3baaf6f54ec4382e59e89510356b2e21263d574ab9221d", "image_deleted":true } }

API URI ContainersDelete a Container Image

© 2016 128

Example RequestResource delete_image

Argument Switch --uuid (string)Argument The "uuid" arg specifies a container image

to delete.Pre-License NoDetail Deletes a Container Image.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address delete_image --uuid uuid-of-a-container

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 delete_image --uuid 8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12uuid: 8a11af14365a57d050c06821f4caa00865461334ca2598ca38d4b4bda9ce3b12 image_deleted: true

API Tool ContainersDelete a Container Image

© 2016 129

Example RequestResource GET container_system/containers

Argument Switch :uuid (string):show_all (boolean)

Argument The "uuid" arg specifies a container image to delete.

The "show_all" switch displays all allocated containers when true.


or all allocated containers.Generic Command

curl -k -X GET -u api:myapisecret -d '{"uuid":"container-uuid", "show_all":"true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/container_system/containers

$ curl -k -X GET -u api:test -d '{"show_all":"true"}' -H 'Content-Type: application/json' https://54.202.22.3:8000/api/container_system/containers

{"response":{"containers":[{"ID":"703b2942c083e03bd13cb7a11daceae9ea670098ebf1d27d8cbe87120aca8d92","Created":"2014-06-27T19:35:15.564002419Z","Path":"/usr/sbin/sshd","Args":["-D"],"Config":{"Hostname":"703b2942c083","Domainname":"","User":"","Memory":0,"MemorySwap":0,"CpuShares":0,"AttachStdin":false,"AttachStdout":false,"AttachStderr":false,"PortSpecs":null,"ExposedPorts":{},"Tty":true,"OpenStdin":false,"StdinOnce":false,"Env":null,"Cmd":["/usr/sbin/sshd","-D"],"Dns":null,"Image":"18eee59152d30ec65c5de594afe524f3d86f68c3be0957c77205afdbbbe5af99","Volumes":{},"VolumesFrom":"","WorkingDir":"","Entrypoint":null,"NetworkDisabled":false,"OnBuild":null},"State":{"Running":true,"Pid":5992,"ExitCode":0,"StartedAt":"2014-06-27T19:35:15.673268835Z","FinishedAt":"0001-01-01T00:00:00Z","Ghost":false},"Image":"18eee59152d30ec65c5de594afe524f3d86f68c3be0957c77205afdbbbe5af99","NetworkSettings":{"IPAddress":"198.51.100.2","IPPrefixLen":28,"Gateway":"198.51.100.1","Bridge":"docker0","PortMapping":null,"Ports":{}},"ResolvConfPath":"/etc/resolv.conf","HostnamePath":"/var/lib/docker/containers/703b2942c083e03bd13cb7a11daceae9ea670098ebf1d27d8cbe87120aca8d92/hostname","HostsPath":"/var/lib/docker/containers/703b2942c083e03bd13cb7a11daceae9ea670098ebf1d27d8cbe87120aca8d92/hosts","Name":"/furious_ptolemy","Driver":"devicemapper","ExecDriver":"native-0.1","Volumes":{},"VolumesRW":{},"HostConfig":{"Binds":null,"ContainerIDFile":"","LxcConf":[],"Privileged":false,"PortBindings":{},"Links":null,"PublishAllPorts":false}}]}}

API URI ContainersDescribe Allocated Containers

© 2016 130

Example RequestResource desc_containers

Argument Switch --uuid (string)--show_all (boolean)

Argument The "uuid" arg specifies a container image to delete.

The "show_all" switch displays all allocated containers when true.


or all allocated containers.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address desc_containers --uuid uuid-of-a-container

$./vnscubed.rb -K api -S test -H 54.202.22.3 desc_containers

---containers:- VolumesRW: {}

Some information has been removed for display purposes.

ID: 703b2942c083e03bd13cb7a11daceae9ea670098ebf1d27d8cbe87120aca8d92 Image: 18eee59152d30ec65c5de594afe524f3d86f68c3be0957c77205afdbbbe5af99 Name: /furious_ptolemy ResolvConfPath: /etc/resolv.conf State: Ghost: false FinishedAt: "0001-01-01T00:00:00Z" Pid: 5992 StartedAt: "2014-06-27T19:35:15.673268835Z" ExitCode: 0 Running: true Path: /usr/sbin/sshd Driver: devicemapper NetworkSettings: Gateway: 198.51.100.1 PortMapping: IPAddress: 198.51.100.2 Bridge: docker0 IPPrefixLen: 28 Ports: {}

Created: "2014-06-27T19:35:15.564002419Z" HostnamePath: /var/lib/docker/containers/703b2942c083e03bd13cb7a11daceae9ea670098ebf1d27d8cbe87120aca8d92/hostname

API Tool ContainersDescribe Allocated Containers

© 2016 131

Example RequestResource POST container_system/containers

Argument Switch :uuid (string):image_uuid (string):name (string):description (string):command (string)

Argument The "uuid" arg is the container ID if one is present.

The "image-uuid" arg specifies a container image source to use to allocate the container.

The "name" arg specifies the name for the allocated container.

The "description" arg specifies a description for the allocated container.

The "command" arg specifies the command used to run the allocated container.

Pre-License No

Detail Creates a new allocated container using the specified container image.

Generic Command

curl -k -X POST -u api:myapisecret -d '{"image_uuid":"image-uuid", "name":"name", "command":"cmd"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/container_system/containers

$ curl -k -X POST -u api:apipassword -H 'Content-Type:application/json' -d '{"image_uuid":"a21b42ef986fa2c74ad3dc2b316f5844ef4fc7b5a18ca4e3477ab8ff00110ba1","name":"app1","description":"application 1","command":"/usr/sbin/sshd -D"}' https://192.168.30.123:8000/api/container_system/containers

{ "response":{ "uuid":"a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139", "container_started":true,"ip_addr":"172.0.10.4","status":"Running" } }

API URI ContainersStart/Allocate a Container

© 2016 132

Example RequestResource start_container

Argument Switch --uuid (string)--image-uuid (string)--name (string)--description (string)--command (string)

Argument The "uuid" arg is the container ID if one is present.

The "image-uuid" arg specifies a container image source to use to allocate the container.

The "name" arg specifies the name for the allocated container.

The "description" arg specifies a description for the allocated container.

The "command" arg specifies the command used to run the allocated container.

Pre-License No

Detail Creates a new allocated container using the specified container image.

Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address start_container --image-uuid uuid-of-an-image --name container-name --description container-description --command container-command

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 --image_uuid a21b42ef986fa2c74ad3dc2b316f5844ef4fc7b5a18ca4e3477ab8ff00110ba1 --name "app2" --description "app2 test" --command "/usr/sbin/sshd -D"status: Running ip_addr: 172.0.10.3 uuid: b6fb326e1c4a03a388f538b5b4db308ab6ac1eae5ea11070b44a58a66cbc5a82 container_started: true

API Tool ContainersStart/Allocate a Container

© 2016 133

Example RequestResource PUT container_system/containers/:uuid

Argument Switch :uuid (string)Argument The "uuid" arg specifies a container to

stop.Pre-License NoDetail Stop a running container.Generic Command

curl -k -X PUT -u api:myapisecret https://manager-ip-address:8000/api/container_system/containers/uuid

$ curl -k -X PUT -u api:apipassword https://192.168.30.247:8000/api/container_system/containers/ a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139{ "response":{ "uuid":"a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139", "status":"Stopped" } }

API URI ContainersStop a Container

© 2016 134

Example RequestResource stop_container

Argument Switch --uuid (string)Argument The "uuid" arg specifies a container to

stop.Pre-License NoDetail Stop a running container.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address stop_container --uuid uuid-of-a-container

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 stop_container --uuid b6fb326e1c4a03a388f538b5b4db308ab6ac1eae5ea11070b44a58a66cbc5a82 uuid: b6fb326e1c4a03a388f538b5b4db308ab6ac1eae5ea11070b44a58a66cbc5a82 status: Stopped

API Tool ContainersStop a Container

© 2016 135

Example RequestResource DELETE container_system/containers/:uuid

Argument Switch :uuid (string)Argument The "uuid" arg specifies a container to

stop.

Pre-License NoDetail Stop a running container.Generic Command

curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/container_system/containers/uuid

$ curl -k -X DELETE -u api:apipassword https://192.168.30.123:8000/api/container_system/containers/afee0b2ce700770581b5f1a80beb01f2a33e35b8f62c43738203a275c70a40f0 { "response":{ "uuid":"afee0b2ce700770581b5f1a80beb01f2a33e35b8f62c43738203a275c70a40f0", "container_deleted":true } }

API URI ContainersDelete a Container

© 2016 136

Example RequestResource delete_container

Argument Switch --uuid (string)Argument The "uuid" arg specifies a container to be

deleted.Pre-License NoDetail Delete a container.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address delete_container --uuid uuid-of-a-container

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 delete_container --uuid a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139 uuid: 4a6fac15222b49b55513d80e1970da8bd2e20536bacc35cf2a9814b5150f2a6a container_deleted: true

API Tool ContainersDelete a Container

© 2016 137

Example RequestResource POST container_system/containers/:uuid/commit

Argument Switch :uuid (string):name (string):description (string)

Argument The "uuid" arg specifies a container to be deleted.

The "name' arg specifies a name for the resulting container image.

The "description' arg specifies a description for the resulting container image.

Pre-License NoDetail Creates a new container image from a

running container.Generic Command

curl -k -X POST -u api:myapisecret -d '{"name":"image-name", "description":"image-description"}' -H 'Content-Type: application/json" https://manager-ip-address:8000/api/container_system/containers/uuid/commit

$ curl -k -X POST -u api:apipassword -H 'Content-Type:application/json' -d '{"name":"app2_version_1.2.3", "description":"app2 version 1.2.3"}' https://192.168.30.123:8000/api/container_system/containers/e65dfe85fed9826a0649e241aa7c57f09b0bcb9eef638fec3a7d75cfa368e1b7/commit{ "response":{ "uuid":"e65dfe85fed9826a0649e241aa7c57f09b0bcb9eef638fec3a7d75cfa368e1b7", "name":"app2_version_1.2.3" } }

API URI ContainersCommit a Container

© 2016 138

Example RequestResource commit_container

Argument Switch --uuid (string)--name (string)--description (string)


The "name' arg specifies a name for the resulting container image.

The "description' arg specifies a description for the resulting container image.

Pre-License NoDetail Creates a new container image from a

running container.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address commit_container --uuid uuid-of-a-container --name new-image-name --description new-image-description

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 commit_container --name newImage --uuid a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139 --description "app2 rev 8.1.2" uuid: 4339cee4a215f3a7adad750c3c5bc2b348d5555ff0f1fded3cc1281b08a88cb2 name: newImage

API Tool ContainersCommit a Container

© 2016 139

Example RequestResource GET container_system/containers/:uuid/logs

Argument Switch :uuid (string):lines (integer)


The "lines" arg specifies the log lines returned. Default is 25.

Pre-License NoDetail Fetch a specific container's log messages.Generic Command

curl -k -X GET -u api:myapisecret -d '{"lines":"log-length"}' -H 'Content-Type: application/json" https://manager-ip-address:8000/api/container_system/containers/uuid/logs

$ curl -k -X GET -u api:apipassword -H 'Content-Type:application/json' -d '{"lines":"10"}' https://192.168.30.247:8000/api/container_system/containers/a0df70a7ae3f52cdf33d8ee1003b7c2c982f9cba018caf29f6be043741044139/logs

{ "response":{ "uuid":"b6fb326e1c4a03a388f538b5b4db308ab6ac1eae5ea11070b44a58a66cbc5a82", "logs":[ ] } }

API URI ContainersGet Container Logs

© 2016 140

Example RequestResource get_conatiner_logs

Argument Switch --uuid (string)--lines (integer)


The "lines" arg specifies the log lines returned. Default is 25.

Pre-License NoDetail Fetch a specific container's log messages.Generic Command

vnscubed.rb -K api -S apipassword -H manager-ip-address get_container_logs --uuid uuid-of-a-container --lines log-length

$ vnscubed.rb -K api -S apipassword -H 192.168.30.123 get_container_log --lines 20 logs: [ ]uuid: e4d0f3b18457dbebde4f0f1f90af4e9b8ed929649a0d4b2646b557054fd1d713

API Tool ContainersGet Container Logs

© 2016 142

Example Request

$ curl -v -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/snapshots Response: { "response": { "snapshots": { "snapshot_20140117_1389943258_50.240.142.209": { "sha1_checksum": "0ea0e930b96a6276b8dcb23d39378128784da557", "created_at": "2014/01/17 01:20:58 -0600", "size": 334120, "created_at_i": 1389943258 } }, "latest_snapshot": "snapshot_20140117_1389943293_50.240.142.209" } }

Resource GET snapshots

Argument Switch NoneArgument NonePre-License NoDetail Shows snapshots that have been taken on

that manager being queried.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/snapshots

API URI MaintenanceDescribe Snapshot

© 2016 143

Resource upload_license


encrypted license

Pre-License YesDetail License a VNS3 Controller to be a part of

a specific topology.


Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address upload_license --license /pathtolicensefile/license.txt

Example Request

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 upload_license --license apidemo_ipsectrial_license.txt

--- capabilities: - IPsec- eBGP- LinearAddressing- LinearAddressingConfigurable- CloudWANdefault_topology: ipsec_max_endpoints: 50 overlay_subnet: 172.31.1.0/24 total_clients: 50 managers: - manager_id: 1 asn: 65001 overlay_ipaddress: 172.31.1.1 - manager_id: 2 asn: 65002 overlay_ipaddress: 172.31.1.5ipsec_max_subnets: 100 clients: - 172.31.1.17 - 172.31.1.21 - 172.31.1.25 - 172.31.1.29(some clientpacks removed for display purposes)license: acceptedfinalized: falselicense_present: true

API Tool MaintenanceDescribe Snapshot

© 2016 144

Example RequestResource desc_snapshots

Argument Switch NoneArgument NonePre-License NoDetail Shows snapshots that have been taken on

that manager being queried.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address desc_snapshots

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 desc_snapshots snapshots: snapshot_20100830_1283176087_174.129.238.68: size: 912974 created_at: 2010/08/30 13:48:08 +0000 created_at_i: 1283176088 sha1_checksum: 6b1ddca58d454022ca804c31fc016447613df218 latest_snapshot: snapshot_20100830_1283176087_174.129.238.68

Note: This response shows either an empty list token "{ }" or returns a list of snapshots with the token "latest_snapshot" indicating the most recent snapshot created.

API Tool MaintenanceCreate Snapshot

© 2016 145

Example RequestResource create_snapshot

Argument Switch NoneArgument NonePre-License NoDetail Create a snapshot file on that manager

being queried. The snapshot is named based on date, time and IP address of the manager.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address create_snapshot

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 create_snapshot --- snapshot_20120525_1337978471_50.17.119.158: size: 840098 created_at: 2012/05/25 20:41:12 +0000 created_at_i: 1337978472 sha1_checksum: b4fc625d068c2936ef4f480c0bc09e0594f6660f

Note: Snapshots have a 1-to-1 relationship with managers in a topology. To recover an "N" manager topology from snapshots requires "N" distinct snapshot files.

API Tool MaintenanceCreate Snapshot

© 2016 146

Example RequestResource GET snapshots/:name

Argument Switch :name (string)-o (output pathname)

Argument The "name" switch is the name of the snapshot desired.

"The "-o" switch is for the name of the output file you want for the snapshot.

Pre-License NoDetail Download a snapshot file for later use.Generic Command

curl -k -X GET -u api:myapisecret https://manager-ip-address:8000/api/snapshots/:name -o mysnapshotfile

$ curl -k -X GET -u api:apidemopassword https://192.168.30.247:8000/api/snapshots/snapshot_20140117_1389943258_50.240.142.209 -o MyManager.snap

Response: The requested snapshot file is downloaded to the file specified by the "-o" switch.

API URI MaintenanceFetch/Dowload Snapshot

© 2016 147

Example RequestResource fetch_snapshot

Argument Switch --name (string)-o (output pathname)

Argument The "name" switch is the name of the snapshot desired.

"The "-o" switch is for the name of the output file you want for the snapshot.

Pre-License NoDetail Download a snapshot file for later use.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address fetch_snapshot --name snapshot_as_string -o mysnapshotfile

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 fetch_snapshot --name snapshot_20100830_1283176087_174.129.238.68 -o m1_snapshot -o MyManager.snap Response: The requested snapshot file is downloaded to the file specified by the "-o" switch.

API Tool MaintenanceFetch/Dowload Snapshot

© 2016 148

Example Request

$ curl -v -k -X DELETE -u api:apidemopassword https://192.168.30.247:8000/api/snapshots/snapshot_20140117_1389943293_50.240.142.209 { "response": { "snapshots": { "snapshot_20140117_1389943258_50.240.142.209": { "sha1_checksum": "0ea0e930b96a6276b8dcb23d39378128784da557", "created_at": "2014/01/17 01:20:58 -0600", "size": 334120, "created_at_i": 1389943258 } }, "latest_snapshot": "snapshot_20140117_1389943258_50.240.142.209" } }

Resource DELETE snapshots/:name

Argument Switch :name (string)Argument The "name" switch is the name of the

snapshot desired. Pre-License NoDetail Delete the named snapshot from the


curl -k -X DELETE -u api:myapisecret https://manager-ip-address:8000/api/snapshots/:name

API URI MaintenanceDelete Snapshot

© 2016 149

Example RequestResource delete_snapshot

Argument Switch --name (string)Argument The "name" switch is the name of the

snapshot desired. Pre-License NoDetail Delete the named snapshot from the


vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address delete_snapshot --name snapshot_as_string

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 delete_snapshot --name snapshot_20100830_1283176087_174.129.238.68 Response: (the call returns the list of remaining snapshots, in this case an empty list) {}

API Tool MaintenanceDelete Snapshot

© 2016 150

Example RequestResource PUT snapshots/running_config

Argument Switch :snapshot (string pathname)Argument The "snapshot" switch is the file containing

the snapshot you wish to import.Pre-License NoDetail Imports the snapshot into the manager

and triggers a reboot for the configuration to take effect.

Generic Command

curl -k -X PUT -u api:myapisecret --data-binary @/path/to/snapshot -H "Content-Type: application/octet/stream' https://manager-ip-address:8000/api/snapshots/running_config

$ curl -k -X PUT -u api:apidemopassword --data-binary @/home/me/MyManager.snap -H 'Content-Type:application/octet-stream' https://192.168.30.247:8000/api/snapshots/running_config

{ "response": { "snapshot": "accepted" } }

API URI MaintenanceImport Snapshot

© 2016 151

Example RequestResource import_snapshot

Argument Switch --snapshot (string pathname)Argument The "snapshot" switch is the file containing

the snapshot you wish to import.

Pre-License NoDetail Imports the snapshot into the manager

and triggers a reboot for the configuration to take effect.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address import_snapshot --snapshot filename_of_snapshot

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.68 import_snapshot --snapshot m1_snapshot snapshot: accepted

Import Snapshot API Tool Maintenance

© 2016 153

Example RequestResource PUT remote_support

Argument Switch :enabled [boolean]:revoke_credential [boolean]

Argument The "enabled" arg specifies whether remote support is enabled.

The "revoke_credential" argument specifies whether to destroy a currently active remote support credential.

Pre-License YesDetail Enables and disables remote support.

Revokes the validity of a remote support keypair generated with generate_remote_support_keypair

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"enabled": "true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/remote_support

$ curl -k -X PUT -u api:apidemopassword -d '{"enabled":"true"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/remote_support

{ "response": { "enabled": true } }

API URI MaintenanceSetup Remote Support

© 2016 154

Example RequestResource reset_password

Argument Switch --enabled (boolean)--revoke-credential (boolean)

Argument The "enabled" arg specifies whether remote support is enabled.

The "revoke-credential" argument specifies whether to destroy a currently active remote support credential.

Pre-License YesDetail Enables and disables remote support.

Revokes the validity of a remote support keypair generated with generate_remote_support_keypair

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address setup_remote_support --enabled true

$ vns3api/vnscubed.rb -K api -S i-6b344d01 -H 174.129.238.73 reset_password --password "apidemopassword"

password_reset: ok

API Tool MaintenanceSetup Remote Support

© 2016 155

Example RequestResource POST remote_support/keypair

Argument Switch :encrypted_passphrase (input pathname)-o (output pathname)

Argument The "encrypted_passphrase" arg specifies an encrypted passphrase file which will be used to generate an X509 key for accessing the VNS3 Manager in support mode.

The "-o" argument lets you put in a local path and output file name for the remote access key which can be used to access the internals of the VNS3 manager.

Pre-License YesDetail Generating a remote support key which

can be shared with CohesiveFT to provide access to the internal of the VNS3 Manager remotely as a "one time key". Once CFT has used the key it can be revoked and access terminated.

Generic Command

curl -k -X POST -u api:myapisecret --data-binary @PathToPassPhrase -H 'Content-Type: text/plain' https://manager-ip-address:8000/api/remote_support/keypair -o sshkeyfilename

$ curl -k -X POST -u api:test --data-binary @Remote-Support-Passphrase.txt -H 'Content-Type: text/plain' https://54.185.32.202:8000/api/remote_support/keypair -o sshkey.pem

% Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed100 1452 100 138 100 1314 191 1821 --:--:-- --:--:-- --:--:-- 1819

API URI MaintenanceGenerate Remote Support Keypair

© 2016 156

Generate Remote Support KeypairExample RequestResource generate_remote_support_keypair

Argument Switch :encrypted-passphrase (blob)-o (output pathname)

Argument The "encrypted-passphrase" arg specifies an encrypted passphrase file which will be used to generate an X509 key for accessing the VNS3 Manager in support mode.

The "-o" argument lets you put in a local path and output file name for the remote access key which can be used to access the internals of the VNS3 manager.

Pre-License YesDetail Generating a remote support key which

can be shared with CohesiveFT to provide access to the internal of the VNS3 Manager remotely as a "one time key". Once CFT has used the key it can be revoked and access terminated.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address generate_remote_support_keypair --encrypted-passphrase /home/myhome/mypassphrase-file -o /home/myhome/remote-cred-for-cft

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 generate_remote_support_keypair --encrypted-passphrase /home/myhome/mypassphrase-file -o /home/myhome/remotecred-for-cft

There is no printed response to the command line call. An ssh key file is generated with the name and location specified with the "-o" argument.

API Tool Maintenance

© 2016 158

Example Request

$ curl -k -X PUT -u api:apidemopassword -d '{"topology_name":"cft"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/config { "response": { "asn": 65001, "topology_name": "cft", "topology_checksum": "a04a92073a4f6f32a2abce45439a2d8c016334dc", "manager_id": 1, "vns3_version": "3.04.00-20131120171529" "licensed": true "overlay_ipaddress": "172.31.0.100", "peered": true, "public_ipaddress": "50.240.142.209", "private_ipaddress": "192.168.30.247" } }

Resource PUT config

Argument Switch :topology_name [string]Argument The "topology_name" arg specifies a text

name to display at the top of the web ui and in the desc_config API response.

Pre-License NoDetail Provides general information about the

manager's topology, license state and checksums and allows you to set the topology name.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"topology_name":"topologyname"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/config

API URI AdminEdit Configuration

© 2016 159

Resource edit_config

Argument Switch --topology-name (string)Argument The "topology-name" arg specifies a text

name to display at the top of the web ui and in the desc_config API response.

Pre-License NoDetail Provides general information about the

manager's topology, license state and checksums and allows you to set the topology name.

Generic Command

vnscubed.rb -K api -S "myapisecret" -H manager-ip-address edit_config --topology-name "topologyname"

Example Request

$ vns3api/vnscubed.rb -K api -S apidemopassword -H 174.129.238.73 edit_config --topology-name "Your Excellent Topology"

public_ipaddress: 174.129.238.73 peered: false licensed: true vns3_version: 2.9999.14-20120523200216 private_ipaddress: 10.4.117.122 topology_name: Your Excellent Topology topology_checksum: e5bfef539780d269c3f692132a2df8c51e7557d7

API Tool AdminEdit Configuration

© 2016 160

Example RequestResource PUT api_password

Argument Switch :password [string]Argument Password you want to use for the API

interaction.

Pre-License YesDetail Allows you to change the API password/

secret key.

To change the Web UI password (or username) use setup_admin_ui.

Note: Once you have changed the password, use your new password for the "-S" argument.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"password": "myapisecret"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/api_password

$ curl -k -X PUT -u api:i-6b344d01 -d '{"password":"apidemopassword"}' -H 'Content-Type: application/json' https://192.160.30.247:8000/api/api_password

{ "response":{ "password_reset":"ok" } }

API URI AdminReset Password

© 2016 161

Example RequestResource reset_password

Argument Switch --password (string)Argument Password you want to use for the API

interaction.

Pre-License YesDetail Allows you to change the API password/

secret key.

To change the Web UI password (or username) use setup_admin_ui.

Note: Once you have changed the password, use your new password for the "-S" argument.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address reset_password --password "mysuperpassword"

$ vns3api/vnscubed.rb -K api -S i-6b344d01 -H 174.129.238.73 reset_password --password "apidemopassword"

password_reset: ok

API Tool AdminReset Password

© 2016 162

Example RequestResource PUT admin_ui

Argument Switch :enabled [boolean]:admin_username [string]:admin_password [string]

Argument The "enabled" arg specifies whether the web UI is enabled.

The "username" arg specifies the username for the web UI.

The "password" arg specifies the password for the web UI.

Pre-License NoDetail Enables and disables the web UI. Allows

the username and password for the web UI to be set.

Generic Command

curl -k -X PUT -u api:myapisecret -d '{"enabled": "true", "admin_username":"vnscubed", "admin_password":"password"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/admin_ui

$ curl -k -X PUT -u api:apidemopassword -d '{"enabled":"true", "admin_username":"vnscubed", "admin_password":"uipassword"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/admin_ui

{ "response": { "enabled": true "username":"vnscubed" } }

API URI AdminSetup Admin UI

© 2016 163

Example RequestResource setup_admin_ui

Argument Switch --enabled (boolean)--admin-username (string)--admin-password (string)

Argument The "enabled" arg specifies whether the web UI is enabled.

The "username" arg specifies the username for the web UI.

The "password" arg specifies the password for the web UI.

Pre-License NoDetail Enables and disables the web UI. Allows

the username and password for the web UI to be set.

Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address setup_admin_ui --enabled true --username newusername --password newpassword

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 setup_admin_ui --enabled true --admin-username vnscubed --admin-password vnscubed

username: vnscubed enabled: true

API Tool AdminSetup Admin UI

© 2016 164

Example Request

$ curl -k -X PUT -u api:apidemopassword -d '{"enabled":"true", "username":"vnscubed", "password":"apidemopassword"}' -H 'Content-Type: application/json' https://192.168.30.247:8000/api/admin_ui

{ "response": { "enabled": true "username":"vnscubed" } }

Resource PUT server

Argument Switch :reboot [boolean]Argument The "reboot" arg specifies whether to

reboot the VNS3 manager.

Pre-License NoDetail Reboots the Manager.Generic Command

curl -k -X PUT -u api:myapisecret -d '{"reboot":"true"}' -H 'Content-Type: application/json' https://manager-ip-address:8000/api/server

API URI AdminServer Action - Reboot

© 2016 165

API Tool AdminServer Action - Reboot

Example RequestResource server_action

Argument Switch --reboot (boolean)Argument The "reboot" arg specifies whether to

reboot the VNS3 manager.

Pre-License NoDetail Reboots the Manager.Generic Command

vnscubed.rb -K "api" -S "myapisecret" -H manager-ip-address server_action --reboot true

$ vns3api/vnscubed.rb -K api -S "apidemopassword" -H 174.129.238.73 server_action --reboot true status: rebooting

© 2016

VNS3 Document Links

166

VNS3 Product Resources - Documentation | Add-ons

VNS3 Configuration Document Instructions and screenshots for configuring a VNS3 Controller in a single or multiple Controller topology. Specific steps include, initializing a new Controller, generating clientpack keys, setting up peering, building IPsec tunnels, and connecting client servers to the Overlay Network.

VNS3 Docker InstructionsExplains the value of the VNS3 3.5 Docker integration and covers uploading, allocating and exporting application containers.

VNS3 Troubleshooting Troubleshooting document that provides explanation issues that are more commonly experienced with VNS3.

http://www.cohesive.net/support/product-resources/

http://www.cohesive.net/support/add-ons/

https://cohesive.net/dnld/Cohesive-Networks_VNS3-3.5-Configuration.pdf

http://www.cohesive.net/dnld/Cohesive-Networks_VNS3-3.5-Docker.pdf

https://cohesive.net/dnld/Cohesive-Networks_VNS3-Troubleshooting.pdf

cohesive networks support docs: vns3 version 3.5+ api guide

Technology