VMware vShield 5.1 User guide

vShield API Programming Guide

vShield 5.1

vShield App 5.1

vShield Edge 5.1

vShield Endpoint 5.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-000869-02

VMware, Inc.

3401 Hillview Ave.

Palo Alto, CA 94304

www.vmware.com

2 VMware, 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:

docfeedback@vmware.com

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 11

1 OverviewofVMwarevShield 13

vShieldComponents 13

vShieldManager 13

vShieldApp 13

vShieldEdge 14

vShieldEndpoint 14

vShieldDataSecurity 14

CompatibilityBetweenDifferentRESTAPIVersions 14

RESTAPIVersion2.0invShield5.0 14

Multitenancy 15

AnIntroductiontoRESTAPIforvShieldUsers 15

HowRESTWorks 15

UsingthevShieldRESTAPI 16

PortsRequiredforvShieldRESTAPI 16

AbouttheRESTAPI 16

RESTfulWorkflowPatterns 17

ForMore

InformationAboutREST 17

2 vShieldManagerManagement 19

SynchronizingvShieldManagerwithvCenterServer,SSO,andDNS 19

QueryingvShieldManagerGlobalConfiguration 21

ResettingtheLocalAccountPassword 21

AddSecurityProfile 21

GetSecurityProfile 22

GetPasswordHintQuestions 22

ResetPassword 22

MonitoringvShieldManagerreachability 23

WorkingwithvShieldManagerSyslogServerConfiguration 23

ConfigurevShieldManagerSyslogServer 23

GetvShieldManagerSyslogServerConfiguration 23

DeletevShieldManager

SyslogServerConfiguration 23

QueryingvShieldManagerLogs 24

GetvShieldManagerSystemEvents 24

GetvShieldManagerAuditLogs 24

QueryingvShieldManagerTechSupportLog 24

UserManagement 24

GetInformationAboutaUser 25

CreateaLocalUseronvShieldManager 25

UpdateaLocalUserAccount 26

EnableorDisableaUserAccount 26

DeleteaUserAccount 26

RoleManagement 28

GetRolefor

aUser 28

GetRoleforavShieldManagerRoles 28

AddRoleandResourcesforaUser 29

ChangeUserRole 29

vShield API Programming Guide

4 VMware, Inc.

GetListofPossibleRoles 30

GetListofScopingObjects 30

DeleteUserRole 31

CreatingIPsetandMACsetContainers 31

ListIPsetsCreatedonaScope 31

CreateanIPsetonaScope 31

GetDetailsofanIPset 32

ModifyanExistingIPset 32

DeleteanIPset 32

ListMACsetsCreatedonaScope 33

CreateaMACsetonaScope 33

GetDetails

ofaMACset 33

ModifyanExistingMACset 34

DeleteaMACset 34

SecurityGroupScopeandMembers 34

ListSecurityGroupsCreatedonaScope 34

CreateSecurityGrouponaScope 35

GetMembersforaScope 35

GetSecurityGroupDetails 35

ModifyaSecurityGroup 36

DeleteaSecurityGroup 37

AddMembertoSecurityGroup 37

DeleteMemberfromSecurityGroup 37

TransportSet

forServices 37

WorkingwithServiceGroups 37

ListServiceGroupsonaScope 37

AddServiceGrouptoaScope 38

GetDetailsofaServiceGroup 40

ModifyServiceGroupDetails 40

DeleteServiceGroupfromScope 41

WorkingwithServices 41

ListServicesonaScope 41

AddServicetoaScope 41

GetDetailsofaService 43

ModifyServiceDetails 43

DeleteService

fromScope 44

WorkingwiththeMembersofaService 44

QueryServiceMembers 44

AddaMembertotheService 45

DeleteaMemberfromtheService 45

QueryingObjectIDs 45

QueryDatacenterMOID 45

QueryDatacenterID 45

QueryHostID 46

QueryPortgroupID 46

3 ESXHostPreparationforvShieldApp,vShieldEndpoint,andvShieldDataSecurity 47

InstallingLicensesforvShieldEdge,vShieldApp,andvShieldEndpoint 47

InstallingvShieldAppandvShieldEndpointServicesonanESXHost 47

InstallingvShieldDataSecurity 49

UpgradingvShieldDataSecurity 49

GettingtheInstallationStatusofvShieldServicesonanESXHost 50

UninstallingvShieldServicesfromanESXHost 50

UninstallingvShieldDataSecurity 50

VMware, Inc. 5

Contents

4 vShieldEdgeInstallationandUpgrade 51

InstallingavShieldEdge 51

RunningQueriesonallvShieldEdges 53

UpgradingvShieldEdge 55

DeletingavShieldEdge 55

5 vShieldEdgeManagement 57

RunningQueriesonaSpecificvShieldEdge 58

QueryvShieldEdgeDetails 58

QueryvShieldEdgeSummary 62

QueryingvShieldEdgeStatus 64

WorkingwithAppliances 66

QueryApplianceConfiguration 66

ModifyApplianceConfiguration 67

ChangeApplianceSize 67

ManageanAppliance 68

QueryAppliance 68

ModifyAppliance 68

DeleteAppliance 69

WorkingwithInterfaces 69

AddInterfaces 69

RetrieveInterfacesforavShieldEdge 70

DeleteInterfaces 71

ManageavShieldInterface 71

RetrieveInterface

withSpecificIndex 71

DeleteInterfaceConfiguration 71

ModifyanInterface 71

QueryInterfaceStatistics 72

QueryStatisticsforallInterfaces 72

QueryStatisticsforUplinkInterfaces 73

QueryStatisticsforInternalInterfaces 74

QueryDashboardStatistics 74

ConfiguringEdgeServices 75

ConfigureFirewall 75

AddFirewallConfiguration 75

QueryFirewallConfiguration 76

DeleteFirewallConfiguration 78

AppendFirewallRules 78

AddaFirewallRuleAboveaSpecificRule 79

QuerySpecific

Rule 80

ModifyFirewallRule 80

DeleteaFirewallRule 81

ManageDefaultFirewallPolicy 81

QueryFirewallStatistics 81

QueryFirewallStatisticsForaRule 82

ConfigureNAT 82

RetrieveNATRulesforavShieldEdge 83

DeleteallNATRules 84

AddaNATRuleaboveaSpecificRule 84

AppendNATRules 84

ChangeaNATRule 85

DeleteaRule 85

ConfigureRouting 85

vShield API Programming Guide

6 VMware, Inc.

ConfigureStaticandDefaultRoutes 85

QueryStaticandDefaultRoutes 86

DeleteStaticandDefaultRoutes 87

ChangeStaticRoutes 87

AppendStaticRoutes 87

DeleteStaticRoutes 88

ConfigureDefaultRoutesforvShieldEdge 88

DeleteDefaultRoutes 88

ConfigureDNSServers 88

ConfigureDNS 88

RetrieveDNSConfiguration 89

DeleteDNSConfiguration 89

RetrieveDNSStatistics 90

ConfigureDHCP 90

QueryDHCPConfiguration 92

DeleteDHCPConfiguration 93

RetrieveDHCPLeaseInformation 93

AppendIPPooltoDHCPConfiguration 93

AppendStaticBindingtoDHCPConfiguration 93

DeleteDHCPPool 94

DeleteDHCPStaticBinding 94

ConfigureCertificates 94

WorkingwithCertificates 94

WorkingwithCertificateSigningRequests(CSRs) 95

WorkingwithCertificateRevocationList(CRL) 96

ConfigureIPSECVPN 97

RetrieveIPSecConfiguration 98

RetrieveIPSecStatistics 99

QueryTunnelTrafficStatistics 100

DeleteIPSecConfiguration 101

ManagingSSLVPN 101

EnableorDisable

SSLVPN 101

QuerySSLVPNDetails 101

ManageServerSettings 102

ConfigurePrivateNetworks 102

ConfigureWebResource 105

ConfigureUsers 107

ConfigureIPPool 109

ConfigureNetworkExtensionClientParameters 111

ConfigureNetworkExtensionClientInstallationPackage 112

ConfigurePortalLayouts 116

ConfigureAuthenticationParameters 118

ConfigureSSLVPNAdvancedConfiguration 120

WorkingwithActiveClients 121

ManageLogonandLogoffscripts

 122

ReconfigureSSLVPN 124

QuerySSLVPNConfiguration 128

DeleteSSLVPNConfiguration 131

QuerySSLVPNStatistics 131

ConfigureLoadBalancer 132

QueryLoadBalancerConfiguration 134

QueryStatistics 135

DeleteLoadBalancerConfiguration 136

VMware, Inc. 7

Contents

ManageallBackendPools 136

ManageallVirtualServers 139

RetrieveLoadBalancerStatistics 142

EnableLayer‐4ModeforLoadBalancer 143

ConfigureHighAvailability(HA) 143

RetrieveHighAvailabilityConfiguration 144

DeleteHighAvailabilityConfiguration 144

ForceSyncingvShieldEdge 144

ConfiguringAdvancedOptionsforvShieldEdge 145

ChangeAESNISettingforavShieldEdge 145

ChangeFIPSSettingforavShieldEdge 145

Change

LoggingLevelforvShieldAppliance 145

ManageAutoConfigurationSettings 145

ModifyAutoConfigurationSettings 145

QueryAutoConfigurationSettings 146

ChangeTCPLooseSetting 146

ReplacingtheConfigurationofavShieldEdge 146

RedeployingvShieldEdgeAppliances 150

ManagingCLICredentialsandAccess 150

ChangeCLICredentials 150

ChangeCLIRemoteAccess 151

DebuggingandSupport 151

QueryTechnicalSupportLog 151

QueryvShieldEdgeServiceStatistics 151

6 WorkingwithVXLANVirtualWires 155

PreparingforVXLANVirtualWires 155

ConfiguringSwitches 156

PrepareSwitch 156

QueryConfiguredSwitches 156

QueryConfiguredSwitchesonDatacenter 157

QuerySpecificSwitch 157

DeleteSwitch 157

WorkingwithClusterSwitchMappings 158

MapaClustertoaSwitch 158

QueryallClusterMappings 158

QueryMappingsbySwitch 159

QuerySpecificCluster 159

WorkingwithEAMAgencies 160

InstallEAMAgency 160

SynchronizeAgencyState 160

ReplaceAgencyScope 160

QueryAgency

byCluster 161

QueryAgencyStatus 161

QueryAgencyIDforCluster 161

DeleteAgency 161

UninstallAgencyStatus 161

WorkingwithSegmentIDs 162

AddanewSegmentIDRange 162

QueryallSegmentIDRanges 162

QueryaSpecificSegmentIDRange 162

UpdateaSegmentIDRange 163

DeleteaSegmentIDRange 163

WorkingwithMulticastAddressRanges 163

AddanewMulticastAddress

Range 163

vShield API Programming Guide

8 VMware, Inc.

QueryallMulticastAddressRanges 164

GetaSpecificMulticastAddressRange 164

UpdateaMulticastAddressRange 164

DeleteaMulticastAddressRange 165

WorkingwithNetworkScopes 165

CreateaNetworkScope 165

EditaNetworkScope 165

UpdateAttributesonaNetworkScope 166

QueryexistingNetworkScopes 166

QueryaSpecificNetworkScope 166

DeleteaNetworkScope 167

WorkingwithVirtualizedNetworks 167

Create

aVXLANVirtualWire 167

QueryallVXLANVirtualWiresonaNetworkScope 168

QueryallVXLANVirtualWiresonallNetworkScopes 168

QueryaSpecificVXLANVirtualWire 169

DeleteaVXLANVirtualWire 169

ManagingtheVXLANVirtualWireUDPPort 169

GetUDPPort 170

UpdateUDPPort 170

QueryingAllocatedResources 170

TestingMulticastGroupConnectivity 170

Test

MulticastGroupConnectivityinaNetworkScope 170

TestMulticastGroupConnectivityinaVXLANVirtualWire 171

PerformingPingTest 171

7 vShieldAppManagement 173

ModifyingtheStateofaDatacenter 173

RetrieveDatacenterState 173

ModifyDatacenterState 174

ConfiguringFirewallRulesforvCenter 174

ConfiguringthevShieldAppFirewall 174

QueryFirewallConfiguration 174

AddaFirewallRule 180

ModifyaFirewallRule 182

DeleteaFirewallRule 184

ReverttoDefaultFirewallConfiguration 185

ConfiguringFail‐SafeModeforvShieldAppFirewall 185

ConfigureFail‐SafeModeforvShield

AppFirewall 185

QueryFail‐SafeModeConfigurationforvShieldAppFirewall 186

WorkingwithSpoofGuard 186

GetSpoofGuardSettingsatContextLevel 186

ReplaceSpoofGuardSettings 186

GetSpoofGuardIPSettings 187

ChangeSpoofGuardIPSettings 187

WorkingwithNamespaces 188

AddNamespaceinaDatacenter 188

GetNamespaceDetails 188

DeleteaNamespace 188

ShowNamespacesinaDatacenter 188

GettingFlowStatisticDetails 189

Get

FlowStatistics 189

GetFlowMeta‐Data 191

ExcludingVirtualMachinesfromvShieldAppProtection 192

AddaVirtualMachinetotheExclusionList 192

VMware, Inc. 9

Contents

GetVirtualMachineExclusionList 192

DeleteaVirtualMachinefromExclusionList 193

ConfiguringSyslogServiceforavShieldApp 193

SynchronizingvShieldApp 194

QueryingvShieldAppTechnicalSupportLog 194

QueryingvShieldAppStatus 194

UpgradingvShieldApp 195

8 vShieldEndpointManagement 197

OverviewofSolutionRegistration 197

RegisteringaSolutionwithvShieldEndpointService 197

RegisteraVendor 198

RegisteraSolution 198

AltitudeofaSolution 198

IPAddressandPortforaSolution 198

ActivateaSolution 199

QueryingRegistrationStatusofvShieldEndpoint 199

GetVendorRegistration 199

GetSolutionRegistration 199

GetIPAddressofaSolution 200

GetActivationStatusofaSolution 200

QueryingActivated

SecurityVirtualMachinesforaSolution 200

QueryActivatedSecurityVirtualMachines 200

QueryActivationInformation 201

UnregisteringaSolutionwithvShieldEndpoint 201

UnregisteraVendor 201

UnregisteraSolution 201

UnsetIPAddress 201

DeactivateaSolution 202

StatusCodesandErrorSchema 202

ReturnStatusCodes 202

ErrorSchema 202

9 vShieldDataSecurityConfiguration 205

vShieldDataSecurityUserRoles 205

DefiningaDataSecurityPolicy 206

QueryRegulations 206

EnableaRegulation 206

QueryClassificationValue 207

ConfigureaCustomizedRegexasaClassificationValue 207

ViewtheListofExcludableAreas 207

ExcludeAreasfromPolicyInspection 208

SpecifySecurityGroupstobeScanned 209

QuerySecurityGroupsBeingScanned 209

ConfigureFileFilters 210

SavingandPublishingPolicies 211

QuerySaved

Policy 211

QueryPublishedPolicy 212

PublishtheUpdatedPolicy 212

DataSecurityScanning 212

Start,Pause,Resume,orStopaScanOperation 213

QueryStatusforaScanOperation 213

QueryingScanResults 213

GetListofVirtualMachinesBeingScanned 214

GetNumberofVirtualMachinesBeingScanned 214

vShield API Programming Guide

10 VMware, Inc.

GetSummaryInformationabouttheLastFiveScans 215

GetInformationforVirtualMachinesScannedDuringPreviousScan 215

RetrieveInformationAboutPreviousScanResults 215

GetXMLRepresentationofPolicyUsedforPreviousScan 215

QueryingViolationDetails 217

GetListofViolationCounts 217

GetListofViolatingFiles 218

GetListofViolatingFilesinCSVFormat 219

GetViolations

inEntireInventory 220

220

Appendix 221

vShieldManagerGlobalConfigurationSchema 221

ESXHostPreparationandUninstallationSchema 226

vShieldAppSchemas 227

vShieldAppConfigurationSchema 227

vShieldAppFirewallSchema 227

vShieldAppSpoofGuardSchema 230

vShieldAppNamespaceSchema 232

ErrorMessageSchema 233

VMware, Inc. 11



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vSphere

environment.Theinformationinthismanualiswrittenforexperiencedsystemadministratorswhoare

familiarwithvirtualmachinetechnology,virtualizeddatacenteroperations,andRESTAPIs.Thismanualalso

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.

About This Book

vShield API Programming Guide

12 VMware, 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. 13

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communicationsto

providedetailedtrafficanalyticsandapplication‐awarefirewallprotection.Itisacriticalsecuritycomponent

toprotectvirtualizeddatacentersfromattacksand

misuse,andhelpsachievecompliance‐mandatedgoals.

Thischapterincludesthefollowingtopics:

 “vShieldComponents”onpage 13

 “CompatibilityBetweenDifferentRESTAPIVersions”onpage 14

 “PortsRequiredforvShieldRESTAPI”onpage 16

 “A n IntroductiontoRESTAPIforvShieldUsers”onpage 15

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.

vShield Components

vShieldincludescomponentsandservicesessentialforprotectingvirtualmachinesinavirtualizeddatacenter.

vShieldcanbeconfiguredwithaWeb‐baseduserinterface,acommandlineinterface(CLI),oraRESTAPI.

TorunvShield,youneedonevShieldManagervirtualapplianceandatleastonevShieldApporvShield

Edge

virtualappliance.ThevShieldManagervirtualappliancecanrunonadifferentESXhostthanthevShieldApp

andvShieldEdgevirtualappliances.

vShield Manager

vShieldManageristhecentralizedmanagementcomponentofvShield.Youinstallitasavirtualapplianceby

deployinganOVAfromthevSphereClient.UsingvShieldManager’suserinterfaceorvSphereClientplug‐in,

youcaninstall,configure,andmaintainvShieldappliances.ThevShieldManageruserinterfaceleveragesthe

vSphereWeb

ServicesSDKtodisplaytabswithinthevSphereClientinventorypanel.Fordetailsaboutthe

userinterface,seethevShieldAdministrationGuide.

vShield App

AvShieldAppvirtualappliance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,andit

regulatestrafficbasedonasetofrules,similartoanaccesscontrollist(ACL).

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for

networkcommunication.Basedonthisinformation,thevShieldAppallowsephemeralportusebypermitting

dynamicprotocols

suchasFTPorRPCtopassthrough,whilemaintaininglockdownonports1024andhigher.

YoucannotprotecttheESXServiceConsole,ESXidirectconsoleuserinterface(DCUI),ortheVMkernelwith

vShieldAppbecausethesecomponentsarenotvirtualmachines.

Overview of VMware vShield

1

vShield API Programming Guide

14 VMware, Inc.

vShield Edge

vShieldEdgeprovidesnetworkedgesecurityandgatewayservicestoisolateavirtualizednetwork,orvirtual

machinesinaportgroup,vDSportgroup,orCiscoNexus1000Vportgroup.YouinstallavShieldEdgeata

datacenterlevelandcanadduptoteninternaloruplinkinterfaces.ThevShield

Edgeconnectsisolated,stub

networkstoshared(uplink)networksbyprovidingcommongatewayservicessuchasDHCP,VPN,NAT,and

LoadBalancing.CommondeploymentsofvShieldEdgeincludeintheDMZ,VPNExtranets,andmulti‐tenant

CloudenvironmentswherethevShieldEdgeprovidesperimetersecurityforVirtualDatacenters(VDCs).

vShield Endpoint

vShieldEndpointoffloadsantivirusandanti‐malwareagentprocessingtoadedicatedsecurevirtual

appliancedeliveredbyVMwarepartners.Sincethesecurevirtualappliance(unlikeaguestvirtualmachine)

doesnʹtgooffline,itcancontinuouslyupdateantivirussignaturestherebygivinguninterruptedprotectionto

thevirtualmachinesonthehost.Also,

newvirtualmachines(orexistingvirtualmachinesthatwentoffline)

areimmediatelyprotectedwiththemostcurrentantivirussignatureswhentheycomeonline.

vShield Data Security

vShieldDataSecurityprovidesvisibilityintosensitivedatastoredwithinyourorganizationʹsvirtualizedand

cloudenvironments.BasedontheviolationsreportedbyvShieldDataSecurity,youcanensurethatsensitive

dataisadequatelyprotectedandassesscompliancewithregulationsaroundtheworld.

Compatibility Between Different REST API Versions

EachreleaseofthevShieldRESTAPIrepresentsanewversionoftheRESTAPIcodewithnewandchanged

features.IfyouarerunningapreviousversionofvShieldcomponentsoftware,youmightnotbeabletouse

allofthefeaturesofthelatestreleaseofthevShieldREST

API.

REST API Version 2.0 in vShield 5.0

Release5.0ofvShieldintroducesversion2.0oftheRESTAPI.ManyURLschangedfromversion1.0to2.0.

YoucandeterminetheAPIversionofavShieldcomponent(suchasEdgeorApp)withthefollowingexample

RESTcalls.IntheGETrequestsyntax,<vsm-ip>representstheIPaddressor

hostnameofvShieldManager.

Example 1-1. Determine the API version of the vShield Manager or vShield Endpoint

GET https://<vsm-ip>/api/versions

</version>

NOTEvShieldAppandvApparenotthesamething.AvAppisagroupingofvirtualmachinesinvSphere,

forexampleamanagementapplianceandadatabaseapplianceworkingtogether.

CAUTIONTheRESTAPIsdescribedinthisdocumentcanchangeovertime.Atthispoint,vShielddoesnot

guaranteeforwardcompatibility.

VMware, Inc. 15

Chapter 1 Overview of VMware vShield

</version>

</versions>

Example 1-2. Determine the API version of a vShield App

GET https://<vsm-ip>/api/versions/app/<datacenter-id>

</version>

</versions>

Example 1-3. Determine the API version of a vShield Edge

GET https://<vsm-ip>/api/versions/edge/dvportgroup-63

</version>

</versions>

TheAPIversionforvShieldAppisgovernedbythestateofthedatacenterinrelationtoavShieldcomponent.

IfthedatacenterstateisinbackwardCompatiblemode,thenitsupportsonlyversion1.0RESTcalls.Ifthe

datacenterstateisinregularmode,thenitsupportsonly2.0RESTcalls.

TheseAPIversionsaremutually

exclusive–onlyoneRESTAPIversionissupportedatatime.

Table 1‐1listscompatibilitybetweendifferentversionsoftheRESTAPI,vShieldManager,andthevShield

virtualappliances:vShieldApp,vShieldEndpoint,andvShieldEdge.

Multitenancy

InvShield5.0,thevShieldAppfirewallconfigurationsupportsmultitenancy.AsingleIPaddresscanshow

upinmultipleplacesinthenetwork(differentIPaddressnamespaces)associatedwithdifferentvirtual

machines.Only2.0RESTAPIssupportmultitenancy.Inbackwardcompatibilitymode,vShield5.0supports

theoldAPIsanddoesnot

enforceruleswithawarenessofmultitenancy.

Ifyouhavewrittenprogramsusing1.0RESTAPIs,youshouldreconsiderwhethertheirdesignworksas

intendedinthemultitenancyscenario.Ifnot,changeyourprogramstousetheAPI2.0calls.

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

Table 1-1. REST API Compatibility Matrix

REST API Version vShield Manager Version vShield Appliance Version Supported?

3.0 5.1 4.1 No

3.0 5.1 5.0 No

3.0 5.1 5.1 Yes

2.0 5.1 5.0 Yes

2.0 5.1 5.1 No

vShield API Programming Guide

16 VMware, Inc.

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.

Using the vShield REST API

YouhaveseveralchoicesforprogrammingthevShieldRESTAPI:usingFirefox,Chrome,orcurl.Tomake

XMLresponsesmorelegible,youcancopyandpastethemintoxmlcopyeditororpspad.

To use the REST API in Firefox

1 LocatetheRESTClientMozillaadd‐on,andaddittoFirefox.

2ClickTools>RESTClienttostartthe

add‐on.

3ClickLoginandenterthevShieldlogincredentials,whichthenappearencodedintheRequestHeader.

4 SelectamethodsuchasGET,POST,orPUT,andtypetheURLofaRESTAPI.Youmightbeaskedtoaccept

orignorethelackofSSLcertificate.ClickSend.

ResponseHeader,

ResponseBody,andRenderedHTMLappearinthebottomwindow.

To use the REST API in Chrome

1SearchtheWebtofindtheSimpleRESTClient,andaddittoChrome.

2Clickitsglobe‐likeicontostartitinatab.

3TheSimpleRESTClientprovidesnocertificate‐checkinginterface,souseanotherChrometabtoaccept



orignorethelackofSSLcertificate.

4TypetheURLofaRESTAPI,andselectamethodsuchasGET,POST,orPUT.

5IntheHeadersfield,typethebasicauthorizationline,asintheImportantnoteabove.ClickSend.

Status,Headers,andDataappearintheResponsewindow.

To use the REST API in curl

1Install

curlifnotalreadyinstalled.

2InfrontoftheRESTURL,the‐koptionavoidscertificatechecking,andthe‐uoptionspecifiescredentials.

curl -k -u admin:default https://<vsm-ip>/api/2.0/services/usermgmt/user/admin

Ports Required for vShield REST API

ThevShieldManagerrequiresport443/TCPforRESTAPIrequests.

About the REST API

RESTAPIsuseHTTPrequests(oftensentbyscriptorhigh‐levellanguage)asawayofmakingidempotent

remoteprocedurecallsthatcreate,modify,ordeleteobjectsdefinedbytheAPI.ARESTAPIisdefinedbya

collectionofXMLdocumentsthatrepresenttheobjectsonwhichtheAPI

operates.TheHTTPoperations

themselvesaregenerictoallHTTPclients.TowriteaRESTfulclient,youshouldunderstandHTTPprotocol

andthesemanticsofstandardHTMLmarkup.ForvShieldRESTAPI,youmustknowthreethings:

 ThesetofobjectsthattheAPIsupports,andwhattheyrepresent.Forexample,whatarevDCandOrg?

I

MPORTANTAllvShieldRESTrequestsrequireauthorization.ThedefaultvShieldManagerlogincredentials

areuseradminpassworddefault.Unlessyouchangedthese,youcanusethefollowingbasicauthorization,

whereYWRtaW46ZGVmYXVsdA==istheBase64encodingofthedefaultcredentialsadmin:default.

Authorization: Basic YWRtaW46ZGVmYXVsdA==

VMware, Inc. 17

Chapter 1 Overview of VMware vShield

 HowtheAPIrepresentstheseobjects.Forinstance,whatistheXMLschemaforthevShieldEdgefirewall

ruleset?Whatdotheindividualelementsandattributesrepresent?

 Howtheclientreferstoanobjectonwhichitwantstooperate.Forexample,whatisamanagedobjectID?

Toanswerthesequestions,youlookat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,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.UsuallyaclientcandeleteanobjectwithanHTTPDELETErequest.

Thisdocumentpresentsexamplerequestsandresponses,andprovides

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,whichyourepeatin

thisorderforaslongasnecessary.

 MakeanHTTPrequest(GET,PUT,POST,orDELETE).Thetargetofthisrequestiseitherawell‐known

URL(suchas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.

For More Information About REST

ForacomprehensivediscussionofRESTfrombothclientandserverperspectives,seeRESTfulWebServicesby

LeonardRichardsonandSamRuby,published2007byOʹReillyMedia.

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

vShield API Programming Guide

18 VMware, Inc.

VMware, Inc. 19

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:

 “SynchronizingvShieldManagerwithvCenterServer, SSO,andDNS”onpage 19

 “QueryingvShieldManagerGlobalConfiguration”onpage 21

 “ResettingtheLocalAccountPassword”onpage 21

 “MonitoringvShieldManagerreachability”onpage 23

 “WorkingwithvShieldManagerSyslogServerConfiguration”onpage 23

 “QueryingvShieldManagerLogs”onpage 24

 “QueryingvShieldManagerTechSupportLog”onpage 24

 “UserManagement”onpage 24

 “RoleManagement”onpage 28

 “CreatingIPsetandMACsetContainers”onpage 31

 “SecurityGroupScopeandMembers”onpage 34

 “TransportSetforServices”onpage 37

 “QueryingObjectIDs”onpage 45

Synchronizing vShield Manager with vCenter Server, SSO, and DNS

YoucansynchronizethevShieldManagerwiththevCenterServer,addDNSserverstothevShieldManager

forIPaddressandhostnameresolution,configuretime,andzoneandaddanNTPserver.Synchronizingwith

vCenterServerenablesthevShieldManageruserinterfacetodisplayyourVMwareInfrastructureinventory,

andrequiresits

IPaddress(orURL)andadministratorlogincredentials.ForthevcInfoschema,andthe

dnsInfoschema,see“vShieldManagerGlobalConfigurationSchema”onpage 221.

Example 2-1. Synchronize the vShield Manager with vCenter server and SSO and identify DNS services

Request:

POST https://<vsm-ip>/api/2.0/global/config

RequestBody:

vShield Manager Management

2

IMPORTANTAllvShieldRESTrequestsrequireauthorization.See“UsingthevShieldRESTAPI”onpage 16

fordetailsaboutbasicauthorization.

vShield API Programming Guide

20 VMware, Inc.

<lookupServiceUrl>https://<SSO IP or Host name>:7444/lookupservice/sdk</lookupServiceUrl>

<ssoAdminUserName>admin@System-Domain</ssoAdminUserName>

</ssoInfo>

<userName>admin</userName>

</vcInfo>

</dnsInfo>

</vsmGlobalConfig>

SpecifyingDNSinformationisoptional.YoucansynchronizevShieldManagerwithjustvCenterServer.

Example 2-2. Synchronize the vShield Manager with vCenter server and SSO

Request:

POST https://<vsm-ip>/api/2.0/global/config

RequestBody:

<lookupServiceUrl>https://<SSO IP or Host name>:7444/lookupservice/sdk</lookupServiceUrl>

<ssoAdminUserName>admin@System-Domain</ssoAdminUserName>

</ssoInfo>

<userName>admin</userName>

</vcInfo>

</vsmGlobalConfig>

Example 2-3. Synchronize the vShield Manager with vCenter Server

Request:

POST https://<vsm-ip>/api/2.0/global/config

RequestBody:

<userName>administrator</userName>

</vcInfo>

</vsmGlobalConfig>

Example 2-4. Configure NTP server

Request:

POST https://<vsm-ip>/api/2.0/global/config

RequestBody:

<

timeInfo>

Page is loading ...

VMware vShield 5.1 User guide

VMware vShield 5.1 User guide

Related papers

Other documents