VMware vShield VSHIELD APP 1.0

vShield API Programming Guide

vShield 5.0.1

vShield App 5.0.1

vShield Edge 5.0.1

vShield Endpoint 5.0.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-000840-00

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 9

1 OverviewofVMwarevShield 11

vShieldComponents 11

vShieldManager 11

vShieldApp 11

vShieldEdge 12

vShieldEndpoint 12

vShieldDataSecurity 12

CompatibilityBetweenDifferentRESTAPIVersions 12

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

Multitenancy 14

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

HowRESTWorks 15

UsingthevShieldRESTAPI 15

PortsRequiredforvShieldRESTAPI 15

AbouttheRESTAPI 16

RESTfulWorkflowPatterns 16

ForMore

InformationAboutREST 16

2 vShieldManagerManagement 17

SynchronizingvShieldManagerwithvCenterServerandDNS 17

QueryingvShieldManagerConfiguration 18

RegisteringvShieldManagerPlug‐InwithvSphereClient 19

UnregisteringvShieldManagerPlug‐InwithvSphereClient 19

QueryingRegistrationStatusofvShieldManagerPlug‐In 19

MonitoringvShieldManagerreachability 19

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

ConfigurevShieldManagerSyslogServer 20

GetvShieldManager

SyslogServerConfiguration 20

DeletevShieldManagerSyslogServerConfiguration 20

QueryingvShieldManagerLogs 20

GetvShieldManagerSystemEvents 20

GetvShieldManagerAuditLogs 21

QueryingvShieldManagerTechSupportLog 21

UserManagement 21

GetaListofUsers 21

GetInformationAboutaUser 21

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

UpdateaLocalUserAccount 22

EnableorDisable

aUserAccount 22

RemoveaUserAccount 23

RoleManagement 24

GetRoleforaUser 24

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

ChangeUserRole 24

GetListofPossibleRoles 25

GetListofScopingObjects 25

Title

4 VMware, Inc.

CreatingIPsetandMACsetContainers 25

ListIPsetsCreatedonaScope 25

CreateanIPsetonaScope 25

GetDetailsofanIPset 26

ModifyanExistingIPset 26

DeleteanIPset 26

ListMACsetsCreatedonaScope 27

CreateaMACsetonaScope 27

GetDetailsofaMACset 27

ModifyanExistingMACset 27

DeleteaMACset 28

SecurityGroupScope

andMembers 28

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

CreateSecurityGrouponaScope 28

GetMembersforaScope 29

GetSecurityGroupDetails 29

ModifyaSecurityGroup 30

DeleteaSecurityGroup 30

AddMembertoSecurityGroup 30

DeleteMemberfromSecurityGroup 30

TransportSetforApplications 31

ListApplicationsonaScope 31

AddApplicationtoaScope 31

Get

DetailsofanApplication 32

ModifyApplicationDetails 32

DeleteApplicationfromScope 32

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

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

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

InstallingvShieldDataSecurity 37

UpgradingvShieldDataSecurity 37

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

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

UninstallingvShieldDataSecurity 38

4 vShieldEdgeInstallation 39

InstallingavShieldEdge 39

QueryingvShieldEdgeConfiguration 40

UninstallingavShieldEdge 42

5 vShieldEdgeManagement 43

ConfiguringvShieldEdge 43

ListvShieldEdgeInstallations 43

DetermineAPIVersion 43

GetCapabilitiesofavShieldEdge 44

SwitchtoNewAPIVersion 44

GetFullConfigurationofavShieldEdge 44

ChangeConfigurationofavShieldEdge 44

InstallvShieldEdge 45

DeletevShieldEdge 45

ConfiguringEdgeServices 45

ConfigureDHCP 45

ManagetheDHCPService 46

VMware, Inc. 5

Contents

DeleteDHCPConfiguration 46

ConfigureFirewall 46

ChangeFirewallRuletoAllow 47

RevertFirewalltoDefault 48

CreateFirewallRulewithIPsetorapplicationSet 48

DeleteFirewallConfiguration 49

ConfigureStaticRouting 49

DeletetheStaticRouting 49

ConfigureNAT 49

DeleteNATConfiguration 50

ConfigureLoadBalancer 51

ManageLoadBalancerService 51

DeleteLoadBalancerConfiguration 52

Miscellaneous 52

ReconfigureEdgeInterfaces 52

SetvShieldEdgeCredentials 52

ConfigureRemoteLogging 52

Configure

VPN 53

ManageVPNService 54

DeletetheVPNConfiguration 54

GenerateCertificateSigningRequest(CSR) 54

AddX.509CertificateasVPNSite 55

OperatingvShieldEdge 56

GetDetailsAboutEdge 56

RequestSyncorUpgrade 56

GetIPsecTunnelStatistics 56

GetDHCPStatistics 56

NetworkInterfaceStatistics 57

GetServiceStatus 57

DebuggingandSupport 57

RetrieveTechnicalSupportLog 57

GetServiceStatistics 58

6 vShieldAppManagement 59

ModifyingtheStateofaDatacenter 59

RetrieveDatacenterState 59

ModifyDatacenterState 60

ConfiguringFirewallRulesforvCenter 60

ConfiguringthevShieldAppFirewall 60

QueryFirewallConfiguration 60

ChangeFirewallConfiguration 70

ReverttoDefaultFirewallConfiguration 70

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

ConfigureFail‐SafeModeforvShieldAppFirewall 70

GetFail‐SafeModeConfigurationforvShield

AppFirewall 71

WorkingwithSpoofGuard 71

GetSpoofGuardGlobalSettings 71

EditSpoofGuardGlobalSettings 71

GetSpoofGuardIPSettings 71

SaveSpoofGuardIPSettings 72

WorkingwithNamespaces 72

AddNamespaceinaDatacenter 72

GetNamespaceDetails 73

DeleteaNamespace 73

ShowNamespacesinaDatacenter 73

Title

6 VMware, Inc.

ShowPortGroupsthatcanbeMarkedasNamespace 73

ShowConfiguredNamespacesinDatacenter 73

GettingFlowStatisticDetails 73

GetFlowStatistics 74

GetFlowMeta‐Data 75

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

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

GetVirtualMachineExclusionList 77

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

ConfiguringSyslogService

foravShieldApp 78

SynchronizingvShieldApp 78

QueryingvShieldAppTechnicalSupportLog 79

UpgradingvShieldApp 79

7 vShieldEndpointManagement 81

OverviewofSolutionRegistration 81

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

RegisteraVendor 82

RegisteraSolution 82

AltitudeofaSolution 82

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

ActivateaSolution 83

QueryingRegistrationStatusofvShieldEndpoint 83

GetVendorRegistration 83

GetSolutionRegistration 83

GetIPAddressofaSolution 84

GetActivationStatusofaSolution 84

QueryingActivated

SecurityVirtualMachinesforaSolution 84

QueryActivatedSecurityVirtualMachines 84

QueryActivationInformation 85

UnregisteringaSolutionwithvShieldEndpoint 85

UnregisteraVendor 85

UnregisteraSolution 85

UnsetIPAddress 85

DeactivateaSolution 86

StatusCodesandErrorSchema 86

ReturnStatusCodes 86

ErrorSchema 86

8 vShieldDataSecurityConfiguration 89

vShieldDataSecurityUserRoles 89

DefiningaDataSecurityPolicy 90

QueryRegulations 90

EnableaRegulation 90

QueryClassificationValue 91

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

ViewtheListofExcludableAreas 91

ExcludeAreasfromPolicyInspection 92

SpecifySecurityGroupstobeScanned 93

QuerySecurityGroupsBeingScanned 93

ConfigureFileFilters 94

SavingandPublishingPolicies 95

QuerySaved

Policy 95

QueryPublishedPolicy 96

PublishtheUpdatedPolicy 96

VMware, Inc. 7

Contents

DataSecurityScanning 96

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

QueryStatusforaScanOperation 97

QueryingScanResults 97

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

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

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

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

RetrieveInformationAboutPrevious

ScanResults 99

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

QueryingViolationDetails 101

GetListofViolationCounts 101

GetListofViolatingFiles 102

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

GetViolationsinEntireInventory 104

104

Appendix 105

vShieldManagerGlobalConfigurationSchema 105

ESXHostPreparationandUninstallationSchema 108

vShieldAppSchemas 109

vShieldAppConfigurationSchema 110

vShieldAppFirewallSchema 110

vShieldAppSpoofGuardSchema 114

vShieldAppNamespaceSchema 115

vShieldEdgeSchemas 116

ErrorMessageSchema 128

Title

8 VMware, Inc.

VMware, Inc. 9



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

10 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. 11

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 11

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

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

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

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

12 VMware, Inc.

vShield Edge

AvShieldEdgevirtualappliance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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. 13

Chapter 1 Overview of VMware vShield

</version>

</versions>

CAUTIONIntheresponseofthisGETcall,themodulenameEndpointSolutionin5.0haschangedto

Endpointin5.0.1.

vShield API Programming Guide

14 VMware, Inc.

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.

Table 1-1. REST API Compatibility Matrix

REST API Version vShield Manager Version vShield Appliance Version Supported?

1.0 1.0 1.0 Yes

1.0 2.0 1.0 Yes,however,clientcannot

configureanynewfeaturesin

vShieldManager2.0

1.0 2.0 2.0BackwardMode

1

1. IfthevShieldEdgeisinBackwardMode,thevShieldManagerdoesnotacceptREST2.0callsforvShieldEdgeconfiguration.

YoumustswitchthevShieldEdgetoNormalMode.AfteravShieldEdgehasbeenswitchedtoNormalMode,youcannot

changetoBackwardMode.

Yes,however,clientcannot

configureanynewfeaturesin

vShieldManager2.0

2.0 2.0 1.0 No

2.0 2.0 2.0BackwardMode No

2.0 2.0 2.0 Yes

VMware, Inc. 15

Chapter 1 Overview of VMware vShield

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.

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.

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

vShield API Programming Guide

16 VMware, Inc.

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?

 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

VMware, Inc. 17

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andDNS”onpage 17

 “QueryingvShieldManagerConfiguration”onpage 18

 “RegisteringvShieldManagerPlug‐InwithvSphereClient”onpage 19

 “UnregisteringvShieldManagerPlug‐InwithvSphereClient”onpage 19

 “QueryingRegistrationStatusofvShieldManagerPlug‐In”onpage 19

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

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

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

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

 “UserManagement”onpage 21

 “RoleManagement”onpage 24

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

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

 “TransportSetforApplications”onpage 31

Synchronizing vShield Manager with vCenter Server 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 105.

Example 2-1. Synchronize the vShield Manager with vCenter server 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 15

fordetailsaboutbasicauthorization.

vShield API Programming Guide

18 VMware, Inc.

<userName>administrator</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

Request:

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

RequestBody:

<userName>administrator</userName>

</vcInfo>

</vsmGlobalConfig>

Example 2-3. Configure time and zone

Request:

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

RequestBody:

<

timeInfo>

<zone>Pacific</zone>

</timeInfo>

</vsmGlobalConfig>

Example 2-4. Configure NTP server

Request:

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

RequestBody:

<

timeInfo>

</timeInfo>

</vsmGlobalConfig>

Querying vShield Manager Configuration

YoucanquerythecurrentvCenter,DNS,andtime/zoneorNTPserverconfigurationforthevShieldManager .

VMware, Inc. 19

Chapter 2 vShield Manager Management

Example 2-5. Get vShield Manager configuration

Request:

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

Registering vShield Manager Plug-In with vSphere Client

YoucanregisterthevShieldManagerasavSphereClientplug‐in.

Example 2-6. Register vShield Manager plug-in with vSphere client

Request:

PUT https://<vsm-ip>/api/2.0/global/viplugin/register?natedIp=<ip>&natedPort=<port>

WhereipandportareoptionalparametersthatyoumaywanttospecifyinaNATenvironment.

Unregistering vShield Manager Plug-In with vSphere Client

YoucanunregisterthevShieldManagerasavSphereClientplug‐in.

Example 2-7. Unregister vShield Manager Plug-in with vSphere client

Request:

PUT https://<vsm-ip>/api/2.0/global/viplugin/unregister

Querying Registration Status of vShield Manager Plug-In

YoucangettheregistrationstatusofthevShieldManagerasavSphereClientplug‐in.

Example 2-8. Get registration status of vShield Manager Plug-in with vSphere client

Request:

GET https://<vsm-ip>/api/2.0/global/viplugin/status

Monitoring vShield Manager reachability

YoucanverifythatthevShieldManagerisreachable.

Example 2-9. Verify that the vShield Manager is reachable

Request:

GET https://<vsm-ip>/api/2.0/global/heartbeat

Working with vShield Manager Syslog Server Configuration

YoucanconfigurevShieldmanagertosendsystemeventsandauditlogstoasyslogserver,retrievecurrent

configuration,ordeletethecurrentconfiguration.

vShield API Programming Guide

20 VMware, Inc.

Configure vShield Manager Syslog Server

YoucanconfigurevShieldManagertosendlogstoasyslogserver.Ifasyslogserverconfigurationexists,this

callupdatestheconfiguration.

Example 2-10. Configure vShield Manager syslog server

Request:

PUT https://<vsm-ip>/api/2.0/services/syslog/config

Request Body:

<?xml version="1.0" encoding="UTF-8"?>

</syslogServerConfig>

Get vShield Manager Syslog Server Configuration

YoucangetthevShieldManagersyslogserverconfiguration.

Example 2-11. Get vShield Manager syslog server configuration

Request:

GET https://<vsm-ip>/api/2.0/services/syslog/config

Delete vShield Manager Syslog Server Configuration

YoucandeletethevShieldManagersyslogserverconfiguration.

Example 2-12. Delete vShield Manager syslog server configuration

Request:

DELETE https://<vsm-ip>/api/2.0/services/syslog/config

Querying vShield Manager Logs

YoucanretrievevShieldManagersystemeventandauditlogs.

Get vShield Manager System Events

YoucanretrievevShieldManagersystemevents.

Example 2-13. Get vShieldManagersystemevents

Request:

GET https://<vsm-ip>/api/2.0/systemevent?startIndex=0\&pageSize=10

Where

 start indexisanoptionalparameterwhichspecifiesthestartingpointforretrievingthelogs.Ifthis

parameterisnotspecified,logsareretrievedfromthebeginning.

 page sizeisanoptionalparameterthatlimitsthemaximumnumberofentriesreturnedbytheAPI.The

defaultvalueforthisparameteris256andthevalidrangeis1‐1024.

Page is loading ...

VMware vShield VSHIELD APP 1.0 - API, vShield 5.0.1 User guide

Related papers

Other documents