VMware vShield vShield 5.5 User guide

vShield API Programming

Guide

vShield 5.5

vShield App 5.5

vShield Edge 5.5

vShield Endpoint 5.5

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-03

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 43

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 67

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 73

QueryDashboardStatistics 74

ConfiguringEdgeServices 74

ConfigureFirewall 75

AddFirewallConfiguration 75

QueryFirewallConfiguration 76

DeleteFirewallConfiguration 77

AppendFirewallRules 78

AddaFirewallRuleAboveaSpecificRule 78

QuerySpecific

Rule 79

ModifyFirewallRule 79

DeleteaFirewallRule 80

ManageDefaultFirewallPolicy 80

QueryFirewallStatistics 81

QueryFirewallStatisticsForaRule 81

ConfigureNAT 81

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

DeleteallNATRules 83

AddaNATRuleaboveaSpecificRule 83

AppendNATRules 84

ChangeaNATRule 84

DeleteaRule 84

ConfigureRouting 85

vShield API Programming Guide

6 VMware, Inc.

ConfigureStaticandDefaultRoutes 85

QueryStaticandDefaultRoutes 85

DeleteStaticandDefaultRoutes 86

ChangeStaticRoutes 86

AppendStaticRoutes 86

DeleteStaticRoutes 87

ConfigureDefaultRoutesforvShieldEdge 87

DeleteDefaultRoutes 87

ConfigureDNSServers 87

ConfigureDNS 87

RetrieveDNSConfiguration 88

DeleteDNSConfiguration 88

RetrieveDNSStatistics 89

ConfigureDHCP 89

QueryDHCPConfiguration 91

DeleteDHCPConfiguration 91

RetrieveDHCPLeaseInformation 92

AppendIPPooltoDHCPConfiguration 92

AppendStaticBindingtoDHCPConfiguration 92

DeleteDHCPPool 93

DeleteDHCPStaticBinding 93

ConfigureCertificates 93

WorkingwithCertificates 93

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

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

ConfigureIPSECVPN 96

RetrieveIPSecConfiguration 97

RetrieveIPSecStatistics 98

QueryTunnelTrafficStatistics 99

DeleteIPSecConfiguration 100

ManagingSSLVPN 100

EnableorDisable

SSLVPN 100

QuerySSLVPNDetails 100

ManageServerSettings 100

ConfigurePrivateNetworks 101

ConfigureWebResource 103

ConfigureUsers 105

ConfigureIPPool 107

ConfigureNetworkExtensionClientParameters 110

ConfigureNetworkExtensionClientInstallationPackage 110

ConfigurePortalLayouts 114

ConfigureAuthenticationParameters 116

ConfigureSSLVPNAdvancedConfiguration 118

WorkingwithActiveClients 119

ManageLogonandLogoffscripts

 120

ReconfigureSSLVPN 122

QuerySSLVPNConfiguration 125

DeleteSSLVPNConfiguration 128

QuerySSLVPNStatistics 128

ConfigureLoadBalancer 129

QueryLoadBalancerConfiguration 131

QueryStatistics 132

DeleteLoadBalancerConfiguration 133

VMware, Inc. 7

Contents

ManageallBackendPools 133

ManageallVirtualServers 136

RetrieveLoadBalancerStatistics 138

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

ConfigureHighAvailability(HA) 140

RetrieveHighAvailabilityConfiguration 141

DeleteHighAvailabilityConfiguration 141

ForceSyncingvShieldEdge 141

ConfiguringAdvancedOptionsforvShieldEdge 141

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

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

Change

LoggingLevelforvShieldAppliance 142

ManageAutoConfigurationSettings 142

ModifyAutoConfigurationSettings 142

QueryAutoConfigurationSettings 142

ChangeTCPLooseSetting 143

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

RedeployingvShieldEdgeAppliances 147

ManagingCLICredentialsandAccess 147

ChangeCLICredentials 147

ChangeCLIRemoteAccess 147

DebuggingandSupport 148

QueryTechnicalSupportLog 148

QueryvShieldEdgeServiceStatistics 148

6 WorkingwithVXLANVirtualWires 153

PreparingforVXLANVirtualWires 153

ConfiguringSwitches 154

PrepareSwitch 154

EditTeamingPolicy 154

QueryConfiguredSwitches 154

QueryConfiguredSwitchesonDatacenter 155

QuerySpecificSwitch 155

DeleteSwitch 156

WorkingwithClusterSwitchMappings 156

MapaClustertoaSwitch 156

QueryallClusterMappings 156

QueryMappingsbySwitch 157

QuerySpecificCluster 157

DeleteClusterSwtichMapping 158

WorkingwithEAMAgencies 158

InstallEAMAgency 158

Synchronize

AgencyState 159

ReplaceAgencyScope 159

QueryAgencybyCluster 159

QueryAgencyStatus 159

QueryAgencyIDforCluster 159

DeleteAgency 160

UninstallAgencyStatus 160

WorkingwithSegmentIDs 160

AddanewSegmentIDRange 160

QueryallSegmentIDRanges 161

QueryaSpecificSegmentIDRange 161

UpdateaSegmentIDRange 161

DeleteaSegmentIDRange 162

vShield API Programming Guide

8 VMware, Inc.

WorkingwithMulticastAddressRanges 162

AddanewMulticastAddressRange 162

QueryallMulticastAddressRanges 162

GetaSpecificMulticastAddressRange 163

UpdateaMulticastAddressRange 163

DeleteaMulticastAddressRange 163

WorkingwithNetworkScopes 163

CreateaNetworkScope 163

EditaNetworkScope 164

UpdateAttributesonaNetworkScope 164

QueryexistingNetworkScopes 164

Querya

SpecificNetworkScope 165

DeleteaNetworkScope 166

WorkingwithVirtualizedNetworks 166

CreateaVXLANVirtualWire 166

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

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

QueryaSpecificVXLANVirtualWire 167

DeleteaVXLANVirtualWire 168

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

GetUDPPort 168

Update

UDPPort 168

QueryingAllocatedResources 168

TestingMulticastGroupConnectivity 169

TestMulticastGroupConnectivityinaNetworkScope 169

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

PerformingPingTest 170

7 vShieldAppManagement 171

ModifyingtheStateofaDatacenter 171

RetrieveDatacenterState 171

ModifyDatacenterState 172

ConfiguringFirewallRulesforvCenter 172

ConfiguringthevShieldAppFirewall 172

QueryFirewallConfiguration 172

AddaFirewallRule 178

ModifyaFirewallRule 180

DeleteaFirewallRule 182

ReverttoDefaultFirewallConfiguration 183

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

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

AppFirewall 183

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

WorkingwithSpoofGuard 184

GetSpoofGuardSettingsatContextLevel 184

ReplaceSpoofGuardSettings 184

GetSpoofGuardIPSettings 185

ChangeSpoofGuardIPSettings 185

WorkingwithNamespaces 186

AddNamespaceinaDatacenter 186

GetNamespaceDetails 186

DeleteaNamespace 186

ShowNamespacesinaDatacenter 186

GettingFlowStatisticDetails 187

Get

FlowStatistics 187

GetFlowMeta‐Data 189

VMware, Inc. 9

Contents

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

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

GetVirtualMachineExclusionList 190

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

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

SynchronizingvShieldApp 192

QueryingvShieldAppTechnicalSupportLog 192

QueryingvShieldAppStatus 192

UpgradingvShieldApp 193

8 vShieldEndpointManagement 195

OverviewofSolutionRegistration 195

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

RegisteraVendor 196

RegisteraSolution 196

AltitudeofaSolution 196

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

ActivateaSolution 197

QueryingRegistrationStatusofvShieldEndpoint 197

GetVendorRegistration 197

GetSolutionRegistration 197

GetIPAddressofaSolution 198

GetActivationStatusofaSolution 198

QueryingActivated

SecurityVirtualMachinesforaSolution 198

QueryActivatedSecurityVirtualMachines 198

QueryActivationInformation 199

UnregisteringaSolutionwithvShieldEndpoint 199

UnregisteraVendor 199

UnregisteraSolution 199

UnsetIPAddress 199

DeactivateaSolution 200

StatusCodesandErrorSchema 200

ReturnStatusCodes 200

ErrorSchema 200

9 vShieldDataSecurityConfiguration 203

vShieldDataSecurityUserRoles 203

DefiningaDataSecurityPolicy 204

QueryRegulations 204

EnableaRegulation 204

QueryClassificationValue 205

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

ViewtheListofExcludableAreas 205

ExcludeAreasfromPolicyInspection 206

SpecifySecurityGroupstobeScanned 207

QuerySecurityGroupsBeingScanned 207

ConfigureFileFilters 208

SavingandPublishingPolicies 209

QuerySaved

Policy 209

QueryPublishedPolicy 210

PublishtheUpdatedPolicy 210

DataSecurityScanning 210

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

QueryStatusforaScanOperation 211

QueryingScanResults 211

vShield API Programming Guide

10 VMware, Inc.

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

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

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

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

RetrieveInformationAboutPreviousScanResults 213

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

QueryingViolationDetails 215

GetListofViolationCounts 215

Get

ListofViolatingFiles 216

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

GetViolationsinEntireInventory 217

218

Appendix 219

vShieldManagerGlobalConfigurationSchema 219

ESXHostPreparationandUninstallationSchema 224

vShieldAppSchemas 225

vShieldAppConfigurationSchema 225

vShieldAppFirewallSchema 225

vShieldAppSpoofGuardSchema 228

vShieldAppNamespaceSchema 230

ErrorMessageSchema 231

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

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 vShield 5.5 User guide

Related papers

Other documents