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.