View
19
Download
0
Category
Preview:
Citation preview
© 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 sales@cohesive.net for details.
© 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.
© 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.
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
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
Argument Switch --license (input path to license file)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
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
Argument Switch NoneArgument NonePre-License NoDetail Provides information on all defined IPsec
connectionsGeneric Command
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
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/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:apidemopassword@192.168.30.247: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:apidemopassword@192.168.30.247: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:apidemopassword@192.168.30.247: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:apidemopassword@192.168.30.247: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)
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
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)
Argument The "name" arg is the name of the clientpack.
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)
Argument The "name" arg is the name of the clientpack.
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 POST clients/reset_all
Argument Switch None
Argument None
Pre-License NoDetail For resetting all of the connections of
clients connected to the 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/clients/reset_all
API URI OverlayReset All Clients
$ curl -k -X POST -u api:test -H 'Content-Type: application/json' https://52.200.220.131:8000/api/clients/reset_all
{"response":{
"resetting":["172.16.1.1"]}
}
© 2016 55
Example RequestResource reset_all_clients
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 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
© 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 "key" arg is the tag key.
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 "key" arg is the tag key.
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
© 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 Switch None
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 Switch None
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)
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
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)
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: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)
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
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 "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
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 "ipaddress" arg is the IP of the remote gw.
The "secret" arg is the pre-shared key.
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 "ipaddress" arg is the IP of the remote gw.
The "secret" arg is the pre-shared key.
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
defined remote endpoints is to be deleted.
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
defined remote endpoints is to be deleted.
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
defined remote endpoints is to be deleted.
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)
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
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)
Argument The "endpoint" arg specifies which of the defined remote endpoints the tunnel is to be created for.
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 "description" arg is a description of the 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)
Argument The "endpoint" arg specifies which of the defined remote endpoints the tunnel is to be created for.
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 "description" arg is a description of the 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
Manager.Generic Command
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
Manager's firewall. Generic Command
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
Manager's firewall. Generic Command
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
Manager's firewall. Generic Command
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.
Pre-License NoDetail Provides description information for one
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.
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
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.
The "description" arg is a text description 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.
The "description" arg is a text description 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.
Pre-License NoDetail Provides description information for one
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.
Pre-License NoDetail Provides description information for one
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)
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
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)
Argument The "uuid" arg specifies a container to be deleted.
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)
Argument The "uuid" arg specifies a container to be deleted.
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
Maintenance: Snapshots
141
© 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
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.
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
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 Request
$ curl-k -H 'Content-Type: application/json' -X POST -u api:apidemopassword -d '{"name":"snapshot_name"}' https://192.168.30.247:8000/api/snapshots Response:{
"response":{"snapshot_name":{
"sha1_checksum":"adc8052f3c0f618b9b1f9564aaa76bf8ce0bd381","created_at":"2016-11-22T16:23:11+00:00","created_at_i":1479831791,"size":957078
}}
}
Resource POST snapshots
Argument Switch :name (string)Argument The "name' arg specifies a name for the
resulting VNS3 snapshot file.
Pre-License No
Detail Creates a new snapshot using the name argument
Generic Command
curl -k -H 'Content-Type: application/json' -X POST -u api:myapisecret -d '{"name":"snapshot_name"}' https://manager-ip-address:8000/api/snapshots
API URI 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
Manager.Generic Command
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
Manager.Generic Command
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
Maintenance: Remote Support
152
© 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
Admin
157
© 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.
Recommended