VMware VSHIELD APP 1.0.0 UPDATE 1 - API, vShield Edge 1.0.0 Update 1, vShield Manager 4.1.0 Update 1, vShield Endpoint 1.0.0 Update 1, vShield Zones 4.1.0 Update 1 Programming Manual
...
vShield API Programming Guide
vShield Manager 4.1.0 Update 1
vShield Zones 4.1.0 Update 1
vShield App 1.0.0 Update 1
vShield Edge 1.0.0 Update 1
vShield Endpoint 1.0.0 Update 1
This document supports the version of each product listed and
supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.
EN-000434-01
vShield API Programming Guide
You can find the most up-to-date technical documentation on the VMware Web site at:
http://www.vmware.com/support/
The VMware Web site also provides the latest product updates.
If you have comments about this documentation, submit your feedback to:
docfeedback@vmware.com
Copyright © 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
intellectual property laws. VMware products are covered by one or more patents listed at
http://www.vmware.com/go/patents.
VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks
and names mentioned herein may be trademarks of their respective companies.
VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2 VMware, Inc.
Contents
About This Book 7
1 Overview of VMware vShield 9
vShield Components 9
vShield Manager 9
vShield App 9
vShield Edge 10
vShield Endpoint 10
Ports Required for vShield 10
An Introduction to REST API for vShield Users 10
How REST Works 10
Using the vShield REST API 11
RESTful Workflow Patterns 11
For More Information About REST 12
2 vShield Manager Management 13
Synchronize the vShield Manager with vCenter Server and DNS 13
Retrieving Tech Support Logs 14
Get the vShield Manager Technical Support Log File Path 14
Get the vShield Edge Technical Support Log File Path 14
3 ESX Host Preparation for vShield App, Endpoint, and Isolation 15
Install the Licenses for vShield Edge, vShield App, and vShield Endpoint 15
Install vShield App, vShield Endpoint, and Port Group Isolation Services on an ESX Host 15
Get the Installation Status of vShield Services on an ESX Host 17
Uninstalling vShield Services from an ESX Host 18
4 vNetwork Preparation and vShield Edge Installation 19
Enabling Port Group Isolation 19
Enable Port Group Isolation on a vDS 20
Get the Port Group Isolation Debug Statistics from an ESX Host 20
Disable Port Group Isolation on a vDS 20
Installing a vShield Edge 21
Get the Install Parameters of a vShield Edge 22
Uninstall a vShield Edge 22
5 vShield Edge Management 23
Upgrading a vShield Edge 24
Force a vShield Edge to Synchronize with the vShield Manager 24
Manage CLI Credentials on a vShield Edge 25
Managing DHCP 25
Get the DHCP Server Status 25
Start, Stop, or Restart the DHCP Service 25
Post a DHCP Configuration 26
Get the Configuration for All DHCP Hosts and Pools 26
Get Timestamps of Last 10 DHCP Configurations 27
Get a DHCP Configuration by Timestamp 27
VMware, Inc. 3
vShield API Programming Guide
Revert to a DHCP Configuration by Timestamp 27
Delete the DHCP Configuration on a vShield Edge 27
Managing NAT 28
Managing SNAT Rules 28
Managing DNAT Rules 30
Configuring the vShield Edge Firewall 33
Get the Firewall Rule Set for a vShield Edge 33
Post a Firewall Rule Set 34
Get the Status of the Default Policy for a vShield Edge 35
Change the Default Firewall Policy Action 35
Get Details of a Specific Firewall Rule 36
Get Timestamps of Last 10 Firewall Rule Sets for a vShield Edge 36
Get Firewall Rule Set by Timestamp 36
Revert to a Firewall Rule Set by Timestamp 36
Delete All Firewall Rules on a vShield Edge 36
Configuring VPNs 37
Get the Status of VPN Service 38
Start or Stop the VPN Service on a vShield Edge 38
Configure VPN Parameters on a vShield Edge 38
Add a Remote Site 39
Add Tunnels for a VPN Site 40
Get the Detailed IPSec Configurations for a Network 40
Get the Detailed Configuration for a VPN Site 41
Get the Detailed Tunnel Configuration 41
Delete a Tunnel for a VPN Site 41
Delete a Remote Site 41
Get the Current VPN Configuration on a vShield Edge 41
Get Timestamps of Last 10 VPN Configurations 42
Get a VPN Configuration by Timestamp 42
Revert to a VPN Configuration by Timestamp 42
Delete the VPN Configuration on a vShield Edge 42
Load Balancer 43
Get the Status of Load Balancer Service on a vShield Edge 43
Start or Stop the Load Balancer Service on a vShield Edge 44
Add a Listener for Load Balancing Service 44
Get the Current Load Balancer Configuration on a vShield Edge 45
Get the Configuration of a Specific Load Balancing Server 45
Get Timestamps of Last 10 Load Balancer Configurations 45
Get a Load Balancer Configuration by Timestamp 46
Revert to a Load Balancer Configuration by Timestamp 46
Delete the Load Balancer Configuration on a vShield Edge 46
Managing the MTU Threshold for a vShield Edge 46
View Traffic Statistics 47
Debug vShield Edge Services Using Service Statistics 47
Managing the Connection to a Syslog Server 47
Post a Syslog Server Configuration 47
Get the Current Syslog Server Configuration 48
Get Timestamps of Last 10 Syslog Server Configurations 48
Get a Syslog Server Configuration by Timestamp 48
Revert to a Syslog Server Configuration by Timestamp 48
Delete the Current Syslog Server Configuration 49
6 vShield App Management 51
Configuring Firewall Rules for a vCenter Container 51
View All Firewall Rules for a Container 51
Post an App Firewall Rule Set for a Container 52
4 VMware, Inc.
View a List of Timestamps Identifying App Firewall Rule Set Changes 55
View a Previous Firewall Rule Set by Timestamp 55
Revert to a Previous Firewall Rule Set 55
Delete All Firewall Rules under a Container 55
Managing Security Groups 56
Add a Security Group 56
Add a Virtual Machine to a Security Group 57
Get the List of All Security Groups under a Base Node 57
Get the Details for a Single Security Group under a Base Node 58
Get IP Addresses for the Virtual Machines in a Security Group 58
Get the Properties from a Virtual Machine 58
Delete a Virtual Machine from a Security Group 58
Delete a Single Security Group 59
Delete All Security Groups under a Base Node 59
Configuring Syslog Service for a vShield App 59
7 vShield Endpoint Management 61
Register an SVM with the vShield Endpoint Service on an ESX Host 61
Retrieve SVM-Specific Network Information 62
Retrieve vShield Endpoint Service Status on an ESX Host 63
Uninstalling the vShield Endpoint Service from an ESX Host 63
Unregister an SVM from vShield Endpoint 63
Uninstall vShield Endpoint from the vShield Manager 64
Error Schema 64
Appendix 65
vShield Manager Schemas 65
vShield Manager to vCenter Server Synchronization Schema 65
DNS Service Schema 66
Virtual Machine Information Schema 66
Security Groups Schema 67
ESX Host Preparation and Uninstallation Schema 68
vShield App Schemas 69
vShield App Configuration Schema 69
vShield App Firewall Schema 70
Port Group Isolation Management Schema 71
Port Group Isolation Statistics Schema 71
vShield Edge Schemas 72
Base vShield Edge Configuration Schema 72
vShield Edge Installation and Upgrade Schema 72
vShield Edge Global Configuration Schema 73
vShield Edge CLI Login Credentials Schema 74
vShield Edge Firewall Schema 74
NAT Schema 77
DHCP Schema 79
VPN Schema 80
Load Balancer Schema 83
MTU Threshold Schema 84
Traffic Stats Schema 85
Syslog Schema 85
Error Message Schema 86
Index 87
VMware, Inc. 5
VMware, Inc. 6
About This Book
This manual, the vShield API Programming Guide, describes how to install, configure, monitor, and maintain the
VMware
instructions and examples.
®
vShield™ system by using REST API requests. The information includes step-by-step configuration
Intended Audience
This manual is intended for anyone who wants to use REST API to install or use vShield in a VMware
vCenter™ environment. The information in this manual is written for experienced system administrators who
are familiar with virtual machine technology and virtual datacenter operations. This manual assumes
familiarity with vShield.
VMware Technical Publications Glossary
VMware Technical Publications provides a glossary of terms that might be unfamiliar to you. For definitions
of terms as they are used in VMware technical documentation go to http://www.vmware.com/support/pubs.
Document Feedback
VMware welcomes your suggestions for improving our documentation. If you have comments, send your
feedback to docfeedback@vmware.com.
vShield Documentation
The following documents comprise the vShield documentation set:
vShield Administration Guide
vShield Quick Start Guide
vShield API Programming Guide, this guide
Technical Support and Education Resources
The following sections describe the technical support resources available to you. To access the current version
of this book and other books, go to http://www.vmware.com/support/pubs.
Online and Telephone Support
To use online support to submit technical support requests, view your product and contract information, and
register your products, go to http://www.vmware.com/support.
Customers with appropriate support contracts should use telephone support for the fastest response on
priority 1 issues. Go to http://www.vmware.com/support/phone_support.
VMware, Inc. 7
vShield API Programming Guide
Support Offerings
To find out how VMware support offerings can help meet your business needs, go to
http://www.vmware.com/support/services.
VMware Professional Services
VMware Education Services courses offer extensive hands-on labs, case study examples, and course materials
designed to be used as on-the-job reference tools. Courses are available onsite, in the classroom, and live
online. For onsite pilot programs and implementation best practices, VMware Consulting Services provides
offerings to help you assess, plan, build, and manage your virtual environment. To access information about
education classes, certification programs, and consulting services, go to http://www.vmware.com/services.
8 VMware, Inc.
1
Overview of VMware vShield
VMware® vShield™ is a suite of network edge and application-aware firewalls built for VMware vCenter™
Server integration. vShield inspects client-server communications and inter-virtual-machine communication
to provide detailed traffic analytics and application-aware firewall protection. vShield is a critical security
component for protecting virtualized datacenters from attacks and misuse helping you achieve your
compliance-mandated goals.
This guide assumes you have administrator access to the entire vShield system. If you are unable to access a
screen or perform a particular task, consult your vShield administrator.
This chapter includes the following topics:
“vShield Components” on page 9
“Ports Required for vShield” on page 10
“An Introduction to REST API for vShield Users” on page 10
vShield Components
vShield includes components and services essential for protecting virtual machines. vShield can be configured
through a web-based user interface, a command line interface (CLI), and REST API.
1
To run vShield, you need one vShield Manager virtual machine and at least one vShield Zones, vShield App,
or vShield Edge virtual machine.
vShield Manager
The vShield Manager is the centralized management component of vShield and is installed from OVA as a
virtual machine by using the vSphere Client. Using the vShield Manager user interface or vSphere Client
plug-in, administrators can install, configure, and maintain vShield components.
The vShield Manager virtual machine can run on a different ESX host from your vShield App and vShield
Edge virtual machines.
The vShield Manager user interface leverages the VMware Infrastructure SDK to display a copy of the vSphere
Client inventory panel.
For more on the using the vShield Manager user interface, see the vShield Administration Guide.
vShield App
A vShield App monitors all traffic into and out of an ESX host, and between virtual machines on the host.
vShield App provides application-aware traffic analysis and stateful firewall protection. vShield App
regulates traffic based on a set of rules, similar to an access control list (ACL).
VMware, Inc. 9
vShield API Programming Guide
As traffic passes through a vShield App, each session header is inspected to catalog the data. The vShield App
creates a profile for each virtual machine detailing the operating system, applications, and ports used in
network communication. Based on this information, the vShield App allows ephemeral port usage by
permitting dynamic protocols such as FTP and RPC to pass through, while maintaining lockdown on ports
1024 and higher.
You cannot protect the Service Console or VMkernel with a vShield App because these components are not
virtual machines.
vShield Edge
A vShield Edge provides network edge security to protect the virtual machines in a vCloud tenant’s network
from attacks originating from the public network. The vShield Edge connects the isolated, private networks of
cloud tenants to the public side of the service provider network through common edge services such as DHCP,
VPN, NAT, and load balancing.
You install a vShield Edge from the vShield Manager. You can install one vShield Edge instance per tenant port
group on a vNetwork Distributed Switch (vDS).
You configure a vShield Edge by using REST API.
vShield Endpoint
vShield Endpoint delivers an introspection-based antivirus solution. vShield Endpoint uses the hypervisor to
scan guest virtual machines from the outside without a bulky agent. vShield Endpoint is efficient in avoiding
resource bottlenecks while optimizing memory use.
Ports Required for vShield
The vShield Manager requires ports 80/TCP and 443/TCP for REST API requests.
An Introduction to REST API for vShield Users
REST, an acronym for Representational State Transfer, is a term that has been widely employed to describe an
architectural style characteristic of programs that rely on the inherent properties of hypermedia to create and
modify the state of an object that is accessible at a URL.
How REST Works
Once a URL of such an object is known to a client, the client can use an HTTP GET request to discover the
properties of the object. These properties are typically communicated in a structured document with an HTTP
Content-Type of XML or JSON, that provides a representation of the state of the object. In a RESTful workflow,
documents (representations of object state) are passed back and forth (transferred) between a client and a
service with the explicit assumption that neither party need know anything about an entity other than what is
presented in a single request or response. The URLs at which these documents are available are often “sticky,”
in that they persist beyond the lifetime of the request or response that includes them. The other content of the
documents is nominally valid until the expiration date noted in the HTTP Expires header.
10 VMware, Inc.
Chapter 1 Overview of VMware vShield
Using the vShield REST API
I
MPORTANT All vShield REST requests require authorization. You can use the following basic authorization:
Authorization: Basic YWRtaW46ZGVmYXVsdA==
YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials
(admin:default).
REST API uses HTTP requests (which are often executed by a script or other higher-level language) as a way
of making what are essentially idempotent remote procedure calls that create, modify, or delete the objects
defined by the API. This REST API (and others) is defined by a collection of XML documents that represent
the objects on which the API operates. The operations themselves (HTTP requests) are generic to all HTTP
clients.
To write a RESTful client, you need to understand only the HTTP protocol and the semantics of standard
HTML markup. To use the vShield API effectively in such a client, you need to know three things:
the set of objects that the API supports, and what they represent (What is a vDC? How does it relate to an
Org?)
how the API represents these objects (What does the XML schema for the vShield Edge firewall rule set
look like? What do the individual elements and attributes represent?)
how the client refers to an object on which it wants to operate
To answer these questions, you need to understand the vShield API resource schemas. These schemas define
a number of XML types, many of which are extended by other types. The XML elements defined in these
schemas, along with their attributes and composition rules (minimum and maximum number of elements or
attributes, for example, or the prescribed hierarchy with which elements can be nested) represent the data
structures of vShield objects. A client can “read” an object by making an HTTP GET request to the object’s
resource URL. A client can “write” (create or modify) an object with an HTTP PUT or POST request that
includes a new or changed XML body document for the object. And a client can usually delete an object with
an HTTP DELETE request.
In this document, we present example requests and responses, and also provide reference information on the
XML schemas that define the request and response bodies.
RESTful Workflow Patterns
All RESTful workflows fall into a pattern that includes only two fundamental operations:
Make an HTTP request (typically GET, PUT, POST, or DELETE). The target of this request is either a
well-known URL (such as the vShield Manager) or a link obtained from the response to a previous
request. (For example, a GET request to an Org URL returns links to vDC objects contained by the Org.)
Examine the response, which can be an XML document or an HTTP response code. If the response is an
XML document, it may contain links or other information about the state of an object. If the response is
an HTTP response code, it indicates whether the request succeeded or failed, and may be accompanied
by a URL that points to a location from which additional information can be retrieved.
These two operations can repeat, in this order, for as long as necessary.
VMware, Inc. 11
vShield API Programming Guide
For More Information About REST
For a comprehensive discussion of REST from both the client and server perspectives, see:
Richardson, Leonard, and Sam Ruby. RESTful Web Services. North Mankato: O'Reilly Media, Inc., 2007.
There are also many sources of information about REST on the Web, including:
http://www.infoq.com/articles/rest-introduction
http://www.infoq.com/articles/subbu-allamaraju-rest
http://www.stucharlton.com/blog/archives/000141.html
12 VMware, Inc.
2
vShield Manager Management
The vShield Manager requires communication with your vCenter Server and services such as DNS and NTP
to provide details on your VMware Infrastructure inventory.
IMPORTANT All vShield REST requests require authorization. You can use the following basic authorization:
Authorization: Basic YWRtaW46ZGVmYXVsdA==
YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials
(admin:default).
The chapter includes the following topics:
“Synchronize the vShield Manager with vCenter Server and DNS” on page 13
“Retrieving Tech Support Logs” on page 14
Synchronize the vShield Manager with vCenter Server and DNS
You can use a single request to synchronize the vShield Manager with the vCenter Server and add DNS servers
to the vShield Manager for IP address and hostname resolution. Synchronizing with vCenter Server enables
the vShield Manager user interface to display your VMware Infrastructure inventory.
2
Synchronization with vCenter requires the vCenter URL and login credentials.
For the schema, see “vShield Manager to vCenter Server Synchronization Schema” on page 65.
For the DNS schema, see “DNS Service Schema” on page 66.
Example 2-1. Synchronizing the vShield Manager with vCenter Server and Identify DNS Services
Request:
POST <vshield_manager-uri>/api/1.0/global/config
You can also synchronize the vShield Manager with the vCenter Server without specifying DNS.
Example 2-2. Synchronizing the vShield Manager with vCenter Server without DNS
Request:
POST <vshield_manager-uri>/api/1.0/global/vcInfo
VMware, Inc. 13
vShield API Programming Guide
Retrieving Tech Support Logs
You can retrieve Technical Support logs from the vShield Manager and vShield Edge.
Get the vShield Manager Technical Support Log File Path
You can get the path to the diagnostic log file for the vShield Manager. You can then send the diagnostic log to
technical support for assistance in troubleshooting an issue.
Example 2-3. Getting the Tech Support Log File Path for a vShield Manager
Request:
GET <vshield_manager-uri>/api/1.0/global/techSupportLogs
Get the vShield Edge Technical Support Log File Path
You can download the diagnostic log from a vShield Edge. You can then send the diagnostic log to technical
support for assistance in troubleshooting an issue.
Example 2-4. Getting the Tech Support Log File Path for a vShield Edge
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/techSupportLogs
14 VMware, Inc.
3
ESX Host Preparation for vShield
App, Endpoint, and Isolation
You can extend the capabilities of vShield by adding the following services: vShield App, vShield Endpoint,
and vShield Edge. You must prepare each ESX host in your environment for these services. The vShield
Manager OVA file contains the drivers and files necessary to install all additional services.
IMPORTANT All vShield REST requests require authorization. You can use the following basic authorization:
Authorization: Basic YWRtaW46ZGVmYXVsdA==
YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials
(admin:default).
This chapter includes the following topics:
“Install vShield App, vShield Endpoint, and Port Group Isolation Services on an ESX Host” on page 15
“Get the Installation Status of vShield Services on an ESX Host” on page 17
“Uninstalling vShield Services from an ESX Host” on page 18
Install the Licenses for vShield Edge, vShield App, and vShield
Endpoint
3
You must install licenses for vShield Edge, vShield App, and vShield Endpoint before installing these
components. You can install these licenses by using the vSphere Client.
1 From a vSphere Client host that is connected to a vCenter Server system, select Home > Licensing.
2 For the report view, select Asset.
3 Right-click a vShield asset and select Change license key.
4 Select Assign a new license key and click Enter Key.
5 Enter the license key, enter an optional label for the key, and click OK.
6Click OK.
7 Repeat these steps for each vShield component for which you have a license.
Install vShield App, vShield Endpoint, and Port Group Isolation
Services on an ESX Host
To shorten the time to deployment, you can install vShield App, vShield Endpoint, and Port Group Isolation
services on an ESX host by using a single REST call. You can do this by including VszInstallParams,
PortgroupIsolationInstallParams, and EpsecInstallParams in the POST body.
VMware, Inc. 15
vShield API Programming Guide
Port Group Isolation is a service used by a vShield Edge to isolate the virtual machines in a vDS port group
from the external network. When Port Group Isolation is enabled, traffic is not allowed access to the virtual
machines in the protected port group unless NAT rules or VLAN tags are configured.
NOTE Port Group Isolation is an optional feature that is not required for vShield Edge operation. Port Group
Isolation is available for vDS-based vShield Edge installations only.
You must specify the host ID of the target ESX host to install all services.
See “ESX Host Preparation and Uninstallation Schema” on page 68.
Example 3-1. Installing a vShield App, vShield Endpoint, and Port Group Isolation on an ESX Host
Request:
POST <vshield_manager-uri>/api/1.0/vshield/<host-id>
Example:
POST /api/1.0/vshield/host-5450 HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: 10.112.196.244
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 489
<VshieldConfiguration><VszInstallParams><DatastoreId>datastore-5035</DatastoreId>
<ManagementPortSwitchId>network-4485</ManagementPortSwitchId><MgmtInterface>
<IpAddress>10.112.196.245</IpAddress><NetworkMask>255.255.252.0</NetworkMask>
<DefaultGw>10.112.199.253</DefaultGw></MgmtInterface></VszInstallParams>
<PortgroupIsolationInstallParams><DatastoreId>datastore-5035</DatastoreId>
</PortgroupIsolationInstallParams><EpsecInstallParams>true</EpsecInstallParams>
<InstallAction>install</InstallAction></VshieldConfiguration>
ESX host preparation requires the following elements:
DatastoreId: VC MOID of the datastore on which the vShield App and Port Group Isolation service
virtual machine files will be stored.
ManagementPortSwitchId: VC MOID of the port group that will host the management port of the
vShield App.
MgmtInterface
IpAddress: IP address to be assigned to the management port of the vShield App. This IP address
must be able to communicate with the vShield Manager.
NetworkMask: Subnet mask associated with the IP address assigned to the management interface of
the vShield App.
DefaultGw: IP address of the default gateway.
16 VMware, Inc.
Chapter 3 ESX Host Preparation for vShield App, Endpoint, and Isolation
After installation of all components is complete, do the following:
vShield App: At this point, vShield App installation is complete. Each vShield App inherits global
firewall rules set in the vShield Manager. The default firewall rule set allows all traffic to pass. You must
configure blocking rules to explicitly block traffic. To configure App Firewall rules, see “Configuring
Firewall Rules for a vCenter Container” on page 51.
Port Group Isolation: You must enable the Port Group Isolation feature on each vDS. After enablement
is complete, install a vShield Edge on each port group. See “vNetwork Preparation and vShield Edge
Installation” on page 19.
vShield Endpoint: To complete installation, see “vShield Endpoint Management” on page 61.
You can install a single service by identifying only that service in the POST body. In Example 3-2, only vShield
App is installed, as identified by inclusion of the VszInstallParams element only.
Example 3-2. Installing a vShield App Only
Request:
POST <vshield_manager-uri>/api/1.0/vshield/<host-id>/vsz
Example:
POST /api/1.0/vshield/host-5126 HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: 10.112.196.244
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 368
<VshieldConfiguration><VszInstallParams><DatastoreId>datastore-5131</DatastoreId>
<ManagementPortSwitchId>network-5134</ManagementPortSwitchId><MgmtInterface>
<IpAddress>10.112.196.245</IpAddress><NetworkMask>255.255.252.0</NetworkMask>
<DefaultGw>10.112.199.253</DefaultGw></MgmtInterface></VszInstallParams>
<InstallAction>install</InstallAction></VshieldConfiguration>
Get the Installation Status of vShield Services on an ESX Host
You can retrieve the installation or uninstallation status of vShield services on an ESX host to track progress as
complete or not initiated. If neither of these operations is in progress, the response includes the list of installed
services on the ESX host.
Example 3-3. Getting vShield Service Installation Status on an ESX Host
Request:
GET <vshield_manager-uri>/api/1.0/vshield/<host-id>
VMware, Inc. 17
vShield API Programming Guide
Uninstalling vShield Services from an ESX Host
You can uninstall vShield App, vShield Endpoint, and Port Group Isolation from an ESX host by using a single
request.
Before uninstalling these services, complete the following tasks:
vShield Endpoint: You must unregister SVMs before uninstalling vShield Endpoint from the ESX host. See
“Unregister an SVM from vShield Endpoint” on page 63.
Port Group Isolation: You must disable Port Group Isolation before uninstalling the service. See “Disable
Port Group Isolation on a vDS” on page 20.
CAUTION Uninstalling any of these vShield services places the ESX host in maintenance mode. After
uninstallation is complete, the ESX host reboots. If any of the virtual machines that are running on the target
ESX host cannot be migrated to another ESX host, these virtual machines must be powered off or migrated
manually before the uninstallation can continue. If the vShield Manager is on the same ESX host, the vShield
Manager must be migrated prior to uninstalling the vShield App.
Before uninstalling Port Group Isolation, disable the service on the host vDS. See “Disable Port Group Isolation
on a vDS” on page 20.
Example 3-4. Uninstalling All Three vShield Services from an ESX Host
Request:
DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>
To uninstall two services at the same time, separate the services to be uninstalled with hyphens.
Example 3-5. Uninstalling More than One Service
Request:
DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>/<hyphen-separated-service-names>
Example:
This request uninstalls a vShield App (zones) and Port Group Isolation (pgi). The vShield Endpoint service
is shortened to epsec.
DELETE /api/1.0/zones/vshield/<host-id>/vsz-pgi
You can uninstall a single service by specifying the service name.
Example 3-6. Uninstall a vShield App Only
Request:
DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>/vsz
18 VMware, Inc.
4
vNetwork Preparation and vShield
Edge Installation
After ESX host preparation is complete, you can secure internal networks by installing a vShield Edge. If you
are installing vShield Edge instances on vDS port groups, you can isolate those port groups by enabling Port
Group Isolation on each vDS.
IMPORTANT If you intend to use the Port Group Isolation feature, you should install Port Group Isolation on
all ESX hosts in your vCenter environment before you install any vShield Edge virtual machines. If you do not
install Port Group Isolation and attempt to enable the feature during vShield Edge installation, Port Group
Isolation does not work. See “Install vShield App, vShield Endpoint, and Port Group Isolation Services on an
ESX Host” on page 15.
I
MPORTANT All vShield REST requests require authorization. You can use the following basic authorization:
Authorization: Basic YWRtaW46ZGVmYXVsdA==
YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials
(admin:default).
This chapter includes the following topics:
“Enabling Port Group Isolation” on page 19
4
“Installing a vShield Edge” on page 21
Enabling Port Group Isolation
Port Group Isolation creates a barrier between the virtual machines protected by a vShield Edge and the
external network. When you enable Port Group Isolation and install a vShield Edge on a vDS port group, you
isolate each secured vDS port group from the external network. When Port Group Isolation is enabled, traffic
is not allowed access to the virtual machines in the secured port group unless NAT rules or VLAN tags are
configured
NOTE Port Group Isolation is an optional feature that is not required for vShield Edge operation. Port Group
Isolation is available for vDS-based vShield Edge installations only.
To enable Port Group Isolation on a vDS
1 Enable Port Group Isolation on each vDS.
2 Install a vShield Edge on each vDS port group you plan to secure.
3 Move the virtual machines to secured vDS port groups.
VMware, Inc. 19
vShield API Programming Guide
Enable Port Group Isolation on a vDS
After Port Group Isolation is installed on each ESX host, you must enable Port Group Isolation on each vDS
where you will install a vShield Edge.
Example 4-1. Enabling Port Group Isolation on a vDS
Request:
PUT <vshield_manager-uri>/api/1.0/network/portgroupIsolation/dvs/<dvs-Moid>
Example:
PUT /api/1.0/portgroupIsolation/dvs/dvs-1069 HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: 10.112.196.244
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Get the Port Group Isolation Debug Statistics from an ESX Host
You can retrieve the statistics on Port Group Isolation activity from an ESX host for debug purposes.
The query returns XML with the path of the location of the statistics file on the vShield Manager. This path can
be used to download the file over HTTP.
See “Port Group Isolation Statistics Schema” on page 71.
Example 4-2. Getting the Port Group Isolation Debug Statistics from an ESX Host
Request:
GET <vshield_manager-uri>/api/1.0/network/portgroupIsolation/<host-Id>/statsLocation
Disable Port Group Isolation on a vDS
Before uninstalling Port Group Isolation, disable the service on the host vDS.
Example 4-3. Disabling Port Group Isolation on a vDS
Request:
DELETE <vshield_manager-uri>/api/1.0/network/portgroupIsolation/dvs/<dvs-Moid>
Example:
DELETE /api/1.0/portgroupIsolation/dvs/dvs-1069 HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: 10.112.196.244
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
20 VMware, Inc.
Installing a vShield Edge
You can install one vShield Edge per port group, vDS port group, or Cisco® Nexus 1000V. A vShield Edge
requires an external port group with a physical NIC and an internal port group that contains the virtual
machines to be secured. The vShield Edge sits inline between these port groups. If an internal port group does
not exist, you must create this port group before installing a vShield Edge.
The vShield Edge installation API copies the vShield Edge OVF from the vShield Manager to the specified
datastore and deploys a vShield Edge on the given port group. After the vShield Edge is installed, the virtual
machine powers on and initializes according to the given network configuration.
Installing a vShield Edge instance adds a virtual machine to the vCenter Server inventory, which is mirrored
in the vShield Manager user interface. You must name the vShield Edge instance and specify an IP address for
the management interface.
For the schema, see “vShield Edge Installation and Upgrade Schema” on page 72.
Example 4-4. Installing a vShield Edge
Request:
POST <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/vshieldedge
<VShieldEdgeConfig>
<InstallParams>
<operationMode>routing</operationMode>
<resourcePoolId>resource_pool_id_from_MOB</resourcePoolId>
<hostId>host_id_from_MOB</hostId>
<dataStoreId>datastore_id_from_MOB</dataStoreId>
<InternalInterface>
<networkId>interface_id_of_internal_interface_from_MOB</networkId>
<networkAddress>ip_address_of_internal_interface</networkAddress>
<subnetMask>subnetmask_for_internal_interface</subnetMask>
</InternalInterface>
<ExternalInterface>
<networkId>interface_id_of_external_interface_from_MOB</networkId>
<networkAddress>ip_address_of_external_interface</networkAddress>
<subnetMask>subnetmask_for_external_interface</subnetMask>
<defaultGw>default_gateway_for_external_interface</defaultGw>
</ExternalInterface>
</InstallParams>
</VShieldEdgeConfig>
Rules:
Chapter 4 vNetwork Preparation and vShield Edge Installation
The installation schema requires the following values:
operationMode: Enter routing as the value.
resourcePoolId: Enter the VC MOID of the resource pool.
hostId: Enter the VC MOID of the ESX Host to which the vShield Edge is to be cloned.
dataStoreId: Enter the VC MOID of the Datastore to which the vShield Edge is to be cloned.
InternalInterface: Enter the VC MOID for the internal port group.
ExternalInterface: Enter the VC MOID for the external port group.
Example:
POST /api/1.0/network/network-244/vshieldedge HTTP/1.1
Content-Type: application/xml
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: localhost:9998
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Content-Length: 620
VMware, Inc. 21
vShield API Programming Guide
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><VShieldEdgeConfig><InstallParams><operationMode>routing
</operationMode><resourcePoolId>network-244</resourcePoolId><hostId>host-28
</hostId><dataStoreId>datastore-29</dataStoreId><InternalInterface><networkId>
network-43</networkId><networkAddress>172.16.1.8</networkAddress><subnetMask>
255.255.255.0</subnetMask></InternalInterface><ExternalInterface><networkId>
network-39</networkId><networkAddress>10.112.196.218</networkAddress><subnetMask>
255.255.252.0</subnetMask><defaultGw>10.112.199.253</defaultGw>
</ExternalInterface></InstallParams></VShieldEdgeConfig>
Get the Install Parameters of a vShield Edge
Example 4-5. Getting the Install Parameters of a vShield Edge
Request:
GET <vshield_manager-uri>/network/<internal-portgroup-vc-moref-id>/vshieldedge
Example:
GET /api/1.0/network/network-244/vshieldedge HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.169:9998
Uninstall a vShield Edge
CAUTION If you have enabled Port Group Isolation, you must migrate or power off the virtual machines on
the ESX host from which you want to uninstall a vShield Edge. Uninstalling Port Group Isolation places the
ESX host in maintenance mode. After uninstallation is complete, the ESX host reboots. If any of the virtual
machines that are running on the target ESX host cannot be migrated to another ESX host, these virtual
machines must be powered off or migrated manually before the uninstallation can continue. If the vShield
Manager is on the same ESX host, the vShield Manager must be migrated prior to uninstalling Port Group
Isolation.
If you did not install and enable Port Group Isolation on an ESX host, you do not have to migrate virtual
machines to uninstall a vShield Edge.
Example 4-6. Uninstalling a vShield Edge
Request:
DELETE <vshield_manager-uri>/network/<internal-portgroup-vc-moref-id>/vshieldedge
Example:
DELETE /api/1.0/network/network-244/vshieldedge HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: localhost:9998
22 VMware, Inc.
5
vShield Edge Management
You can manage vShield Edge services and firewall policies by using REST API. By using REST call, you can
start or stop services, post and delete configurations, and get service status.
For each service, you can enable logging to view debug and audit messages. You must identify a syslog server
to receive the logs.
IMPORTANT All vShield REST requests require authorization. You can use the following basic authorization:
Authorization: Basic YWRtaW46ZGVmYXVsdA==
YWRtaW46ZGVmYXVsdA== represents the Base 64 encoding of the vShield Manager default login credentials
(admin:default).
This chapter includes the following topics:
“Upgrading a vShield Edge” on page 24
“Force a vShield Edge to Synchronize with the vShield Manager” on page 24
“Manage CLI Credentials on a vShield Edge” on page 25
“Managing DHCP” on page 25
5
“Managing NAT” on page 28
“Configuring the vShield Edge Firewall” on page 33
“Configuring VPNs” on page 37
“Load Balancer” on page 43
“Managing the MTU Threshold for a vShield Edge” on page 46
“View Traffic Statistics” on page 47
“Debug vShield Edge Services Using Service Statistics” on page 47
“Managing the Connection to a Syslog Server” on page 47
VMware, Inc. 23
vShield API Programming Guide
Upgrading a vShield Edge
You can upgrade a vShield Edge via REST API when a new software version is available.
For the schema, see “vShield Edge Installation and Upgrade Schema” on page 72.
Example 5-1. Upgrading vShield Edge Software
Request:
PUT <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/vshieldedge/update
Example:
PUT /api/1.0/network/network-598/vshieldedge/update HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: localhost
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
You can get the status of a vShield Edge upgrade by checking the status of a vShield Edge.
Example 5-2. Getting the Status of a vShield Edge Upgrade
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/vshieldedge
Example:
GET /api/1.0/network/network-600/vshieldedge HTTP/1.1
Content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Cache-Control: no-cache
Pragma: no-cache
Host: localhost
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Force a vShield Edge to Synchronize with the vShield Manager
If the configuration of a vShield Edge is out of sync with what shows in the vShield Manager user interface,
you can force the vShield Manager to push the latest configuration to a vShield Edge.
Example 5-3. Forcing a vShield Edge to Sync with the vShield Manager
Request:
PUT <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/action/forcesync
Example:
PUT /api/1.0/network/network-244/action/forcesync HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: localhost
24 VMware, Inc.
Manage CLI Credentials on a vShield Edge
You can set and change login credentials for the CLI on a vShield Edge virtual appliance via REST.
You can change the default CLI login credentials (username admin and password default) on a vShield Edge
via REST.
You can use lower-case letters, numbers, and underscores in the CLI username. The username must start with
a letter and be between 1 and 33 characters in length. The password cannot have spaces and must be at least 1
character in length.
For the schema, see “vShield Edge CLI Login Credentials Schema” on page 74.
Example 5-4. Managing CLI Credentials on a vShield Edge
Request:
PUT <vshield_manager-uri>/api/1.0/network/<vdc-moref-id>/cli/credentials
Managing DHCP
vShield Edge provides DHCP service to bind assigned IP addresses to MAC addresses, preventing MAC
spoofing attacks. All virtual machines protected by a vShield Edge can obtain IP addresses dynamically from
the vShield Edge DHCP service.
Chapter 5 vShield Edge Management
vShield Edge supports IP address pooling and one-to-one static IP address allocation based on the vCenter
managed object ID (vmid) and interface ID (interfaceId) of the requesting client.
vShield Edge DHCP service adheres to the following rules:
Listens on the vShield Edge internal interface (InternalInterface) for DHCP discovery.
Uses the IP address of the internal interface on the vShield Edge as the default gateway address for all
clients, and the broadcast and subnetMask values of the internal interface for the container network.
All DHCP settings configured by using REST requests appear under the vShield Edge > DHCP tab for the
appropriate vShield Edge in the vShield Manager user interface and vSphere Client plug-in.
For the DHCP schema, see “DHCP Schema” on page 79.
Get the DHCP Server Status
Example 5-5. Getting the Status of the DHCP Service on a vShield Edge
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/service
Example:
GET /api/1.0/network/network-244/dhcp/service HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.213
Start, Stop, or Restart the DHCP Service
Example 5-6. Starting or Stopping the DHCP Service on a vShield Edge
Request:
PUT <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/action/
{start | stop | restart}
VMware, Inc. 25
vShield API Programming Guide
Example:
PUT /api/1.0/network/network-244/dhcp/action/start HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.213
Post a DHCP Configuration
You can add hosts and IP pools for DHCP service on a vShield Edge, The vShield Edge can allocate IP
addresses to protected virtual machines from configured IP pools.
The vShield Manager processes the posted XML file as a complete configuration for the specific vShield Edge.
The current configuration is replaced with this new configuration.
If you do not specify a value for the <leaseTime/> parameter, the default value of one day is used. A value of
infinite is supported.
Example 5-7. Adding IP Pool Ranges to a vShield Edge
Request:
POST <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/config
Rules:
DHCPConfigParams and its elements are optional
leaseTime can be infinite or number of seconds. If not specified, the default lease time is 1 day.
Logging is disabled by default. To enable logging, add a <log /> element within <DHCPConfig />.
Example:
POST /api/1.0/network/network-244/dhcp/config HTTP/1.1
content-type: application/xml; charset=UTF-8
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.213
accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
content-length: 655
<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><VShieldEdgeConfig><DHCPConfig><DHCPBinding><vmId>vm-70</vmId><interfaceId>1
</interfaceId><hostName>vmware</hostName><internalIPAddress>172.16.1.54
</internalIPAddress><DHCPConfigParams><domainName>vmware.com</domainName>
<primaryNameServer>10.112.192.1</primaryNameServer><secondaryNameServer>
10.112.192.2</secondaryNameServer><leaseTime>3000</leaseTime></DHCPConfigParams>
</DHCPBinding><DHCPPool><PoolRange><rangeStart>172.16.1.50</rangeStart>
<rangeEnd>172.16.1.53</rangeEnd></PoolRange><DHCPConfigParams><leaseTime>infinite
</leaseTime></DHCPConfigParams></DHCPPool></DHCPConfig></VShieldEdgeConfig>
Get the Configuration for All DHCP Hosts and Pools
You can retrieve the current DHCP configuration for a vShield Edge, including all configured hosts and IP
pools.
Example 5-8. Getting the Configuration of All DHCP Hosts and Pools
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/config
26 VMware, Inc.
Chapter 5 vShield Edge Management
Example:
GET /api/1.0/network/network-244/dhcp/config HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.213
Get Timestamps of Last 10 DHCP Configurations
You can get a list of the last 10 DHCP configurations by timestamp.
Example 5-9. Getting Last 10 DHCP Configurations
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/snapshots
Get a DHCP Configuration by Timestamp
You can view the details of a past DHCP configuration by specifying the timestamp of the snapshot.
Example 5-10. Getting a DHCP Configuration by Snapshot Timestamp
Request:
GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/
dhcp/snapshot/<snapshot-timestamp>
Revert to a DHCP Configuration by Timestamp
You can revert to a previous DHCP configuration by specifying the timestamp of the snapshot. The current
configuration is saved for future reference.
Example 5-11. Revert to an DHCP Configuration by Timestamp
Request:
PUT <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/
dhcp/snapshot/<snapshot-timestamp>
Delete the DHCP Configuration on a vShield Edge
You can delete the current DHCP configuration a vShield Edge.
Example 5-12. Delete the DHCP Configuration on a vShield Edge
Request:
DELETE <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/dhcp/config
Example:
DELETE /api/1.0/network/network-244/dhcp/config HTTP/1.1
Authorization: Basic YWRtaW46ZGVmYXVsdA==
Host: 10.112.196.213
VMware, Inc. 27
Loading...