VMware VSHIELD APP 1.0.0 UPDATE 1 - API Operating instructions

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

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, Inc.
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:
[e-mail]
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. 3
Contents
About This Book 7
1Overview 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
2vShield 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
3ESX 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
4vNetwork 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
5vShield 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

vShield API Programming Guide
4VMware, Inc.
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
6vShield 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

VMware, Inc. 5
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
7vShield 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. 6

VMware, Inc. 7
This manual, the vShield API Programming Guide, describes how to install, configure, monitor, and maintain the
VMware®vShield™ system by using REST API requests. The information includes step-by-step configuration
instructions and examples.
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 [e-mail].
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.
About This Book

vShield API Programming Guide
8VMware, Inc.
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.

VMware, Inc. 9
1
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.
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).
Overview of VMware vShield 1

vShield API Programming Guide
10 VMware, Inc.
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.

VMware, Inc. 11
Chapter 1 Overview of VMware vShield
Using the vShield REST API
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.
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).

vShield API Programming Guide
12 VMware, Inc.
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

VMware, Inc. 13
2
The vShield Manager requires communication with your vCenter Server and services such as DNS and NTP
to provide details on your VMware Infrastructure inventory.
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.
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
vShield Manager Management 2
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).

vShield API Programming Guide
14 VMware, Inc.
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

VMware, Inc. 15
3
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.
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
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.
6ClickOK.
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.
ESX Host Preparation for vShield
App, Endpoint, and Isolation 3
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).

vShield API Programming Guide
16 VMware, Inc.
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.
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.
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.

VMware, Inc. 17
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>

vShield API Programming Guide
18 VMware, Inc.
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.
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
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.

VMware, Inc. 19
4
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.
This chapter includes the following topics:
“Enabling Port Group Isolation” on page 19
“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
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.
vNetwork Preparation and vShield
Edge Installation 4
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.
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).
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.

vShield API Programming Guide
20 VMware, Inc.
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