Beginning to Work with the vShield Edge REST API

Welcome to the fourth installment in my vShield blog series,  featuring a hypothetical Network and Security System Administrator at  the company, “Example Systems.” In the first blog in this series,  I introduced the Example Systems company and described how it intended  to use the vShield REST API to rapidly provision security and to turn  its Tier-1 Applications into a business offering to multiple  organizations. In the second and third blogs in  this series, I discussed how the Network and Security System  Administrator utilized the Automation tools with vShield App for  scalability through the REST APIs.

In this installment, the Network and Security System Administrator is now ready to begin work with the vShield Edge REST API.

Before you can start to use the vShield Edge REST API you must:

1. Get and return the list of all vShield  Edge's installed with vShield Manager. This will provide you with the  following details on the vShield Edge device(s):

• PortGroup on which the vShield Edge device is installed
• Mode of installation
• vShield Edge version
• REST compatibility mode
• Features that are licensed

2. Provide the correct vShield Authorization.

• All vShield REST requests require authorization and which by default  (in the product documentation) use the following basic authorization:  Basic YWRtaW46ZGVmYXVsdA==

Where YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials which are admin:default.

Getting Started with the vShield Edge REST API Lab

In the following sections you will be running various commands, which  in turn will be executing the vShield REST APIs to fulfill your  requests. To get started please do the following:

1. Start a Command Prompt
2. Once the Command Prompt has started, cd to the directory where you have installed the scripts. As in the above example:

       Desktop\vShield-REST-API\Edge

Here you will find all the example commands that will be run in this section of the blog.

cURL Command Line

Using simple, proven tools such as cURL, we can consume the vShield  REST API. There is no need for fancy document descriptions, as we need  to only hit each URL with the appropriate method and data to cause an  immediate response.

What Is cURL? cURL, sometimes written as curl, is a set of C-based libraries in PHP that supports HTTP "GET".

The cURL command line can get a little messy. There are lots of  options available for controlling exactly how you want cURL to interface  with the remote server. For this particular blog we will be using the  following command line options.

- i (HTTP) Include the HTTP-header in the output. The HTTP-header  includes things like server-name, date of the document, HTTP-version and  more...
- k Allow connections to SSL sites without certificates.
- H Specify a custom HTTP header to pass to the server.
-  X Specifies a custom request method to use when communicating with the  HTTP server. The specified request will be used instead of the method  otherwise used (which defaults to GET). Read the HTTP 1.1 specification  for details and explanations. Common additional HTTP requests include  POST and DELETE.

Getting the vShield Edge Device Capability (Basic)

To get the vShield Edge Capability run the following command VSE-Capability.bat

Note:  The above command must be executed on one line, so if you are  experiencing any problems check for carriage returns and line breaks.

Getting the vShield Edge Device Capability (Advanced)

In the example, the Network and Security System Administrator has  provided the appropriate authorization and we see the correct HTTP  result code status (1). You can now  start to determine what information from the above output is required.  One of the key pieces of information required in order for the Network  and Security System Administrator to proceed, is to obtain the list of  all the edges installed on the vShield Manager and also the portGroup  information which can be identified in the field "networkId" for each  vShield Edge device as shown above (2).

Getting the vShield Edge Device Capability on a Specific Portgroup (Basic)

To get the specific vShield Edge Portgroup run the following command VSE-Capability-Portgroup.bat

Note:  The above command must be executed on one line, so if you are  experiencing any problems check for carriage returns and line breaks.

Getting the vShield Edge Device Capability on a Specific Portgroup (Advanced)

Now that you as the the Network and Security System Administrator  have the basic entry level information required, you can now start to  get the information and return the capabilities of the vShield Edge  device installed on a specific portgroup. In this particular case you  are going to use what is termed the "<vc-moref-id>" to return details of the:

• Portgroup on which the vShield Edge device is installed (1)
• vShield Edge version (2)
• REST compatibility mode (3)
• Features that are licensed (4) (For clarity only 'one' feature is shown as an example)
• Return HTTP result code status (5)

Checking the Status of the vShield Services (Load Balancer) (Basic)

http://blogs.vmware.com/.a/6a00d8341c328153ef0154373c8394970c-pi
To get the status of the vShield Edge Load Balancer run the following command VSE-LB-Status.bat

Checking the Status of the vShield Services (Load Balancer) (Advanced)

As the Network and Security System Administrator you are now at a  stage where you can start to interact with the vShield Edge Services.  The first task as the Network and Security System Administrator is to  check the status of the vShield Edge Services, such as the Load  Balancer, DHCP and IPsec (VPN) Services. This will provide you with the  status of whether the service is "up" or "down"  as per the service daemon running on the vShield Edge device. In this  example above the Network and Security System Administrator is checking  the status of the Load Balancer service.

• Load Balancer Service (1)
• Return HTTP result code status (2)
• Status of the Load Balancer Service (3)

Checking the Status of the vShield Services (DHCP) (Basic)

To get the status of the vShield Edge DHCP Server run the following command VSE-DHCP-Status.bat

http://dl.dropbox.com/u/37072735/VSE-DHCP-Status.bat

Note:  The above command must be executed on one line, so if you are  experiencing any problems check for carriage returns and line breaks.

Checking the Status of the vShield Services (DHCP) (Advanced)

In this instance above you can see that the DHCP service has not been  configured and thus the DHCP Service has not been started. In order to  start the DHCP Service a DHCP Pool must be created.

• DHCP Service (1)
• Return HTTP result code status (2)
• Status of the DHCP Service (3)

Checking the Status of the vShield Services (VPN) (Basic)

To get the status of the vShield Edge Site-to-Site IPsec VPN Server run the following command VSE-VPN-Status.bat

http://dl.dropbox.com/u/37072735/VSE-VPN-Status.bat

Note:  The above command must be executed on one line, so if you are  experiencing any problems check for carriage returns and line breaks.

Checking the Status of the vShield Services (VPN) (Advanced)

I

n this final instance above, the Network and Security System  Administrator can see that the VPN service has not been started and thus  the VPN Service is not available.

• VPN Service (1)
• Return HTTP result code status (2)
• Status of the VPN Service (3)

You have now observed the 'three' cases in which a vShield Service can be in. That is:

1. Up
2. Down
3. Not Configured

Special thanks to Kaushal Bansal, Sr MTS at VMware for all his help  and support. In my final installment of this series, you as the Network  and Security System Administrator will learn how to 'Stop' and 'Start'  the vShield Services using the vShield REST API. Be sure to follow @vCloud and @VMwareSP for future updates on this series.