VMware vShield 5.0 User guide

vShield API Programming Guide

vShield 5.0

vShield App 5.0

vShield Edge 5.0

vShield Endpoint 5.0

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

1 OverviewofVMwarevShield 9

vShieldComponents 9

vShieldManager 9

vShieldApp 9

vShieldEdge 10

vShieldEndpoint 10

vShieldDataSecurity 10

CompatibilityBetweenDifferentRESTAPIVersions 10

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

Multitenancy 11

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

HowRESTWorks 12

UsingthevShieldRESTAPI 12

PortsRequiredforvShieldRESTAPI 12

AbouttheRESTAPI 13

RESTfulWorkflowPatterns 13

ForMore

InformationAboutREST 13

2 vShieldManagerManagement 15

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

MonitoringvShieldManagerreachability 16

RetrievingTechSupportLogs 16

GetthevShieldManagerTechnicalSupportLogFilePath 16

GetthevShieldEdgeTechnicalSupportLogFilePath 16

UserManagement 17

GetaListofUsers 17

GetInformationAboutaUser 17

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

Updatea

LocalUserAccount 18

EnableorDisableaUserAccount 18

RemoveaUserAccount 18

RoleManagement 19

GetRoleforaUser 19

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

ChangeRoleforaUser 19

GetaListofPossibleRoles 20

GetaListofScopingObjects 20

CreatingIPsetandMACsetContainers 20

ListIPsetsCreatedonaScope 20

Create

anIPsetonaScope 20

GetDetailsofanIPset 21

ModifyanExistingIPset 21

DeleteanIPset 21

ListMACsetsCreatedonaScope 22

CreateaMACsetonaScope 22

GetDetailsofaMACset 22

vShield API Programming Guide

4 VMware, Inc.

ModifyanExistingMACset 22

DeleteaMACset 23

SecurityGroupScopeandMembers 23

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

CreateSecurityGrouponaScope 23

GetMembersforaScope 24

GetSecurityGroupDetails 24

ModifyaSecurityGroup 24

DeleteaSecurityGroup 25

AddMembertoSecurityGroup 25

DeleteMemberfromSecurityGroup 25

TransportSetforApplications 25

List

ApplicationsonaScope 25

AddApplicationtoaScope 26

GetDetailsofanApplication 26

ModifyApplicationDetails 27

DeleteApplicationfromScope 27

3 ESXHostPreparationforvShieldAppandvShieldEndpoint 29

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

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

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

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

4 vShieldEdgeInstallation 33

InstallingavShieldEdge 33

GettingtheCurrentConfigurationofavShieldEdge 34

UninstallingavShieldEdge 36

5 vShieldEdgeManagement 37

ConfiguringvShieldEdge 37

ListvShieldEdgeInstallations 37

DetermineAPIVersion 37

GetCapabilitiesofavShieldEdge 38

SwitchtoNewAPIVersion 38

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

ChangeConfigurationofavShieldEdge 38

InstallvShieldEdge 39

DeletevShieldEdge 39

ConfiguringEdgeServices 39

ConfigureDHCP 39

ManagetheDHCPService 40

DeleteDHCPConfiguration 40

ConfigureFirewall 40

ChangeFirewallRuleto

Allow 41

RevertFirewalltoDefault 42

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

DeleteFirewallConfiguration 43

ConfigureStaticRouting 43

DeletetheStaticRouting 43

ConfigureNAT 43

DeleteNATConfiguration 44

ConfigureLoadBalancer 45

ManageLoadBalancerService 45

VMware, Inc. 5

Contents

DeleteLoadBalancerConfiguration 46

Miscellaneous 46

ReconfigureEdgeInterfaces 46

SetvShieldEdgeCredentials 46

ConfigureRemoteLogging 46

ConfigureVPN 47

ManageVPNService 48

DeletetheVPNConfiguration 48

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

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

OperatingvShieldEdge 50

GetDetailsAboutEdge 50

RequestSyncorUpgrade 50

GetIPsecTunnelStatistics 50

GetDHCPStatistics 50

NetworkInterfaceStatistics 51

GetServiceStatus 51

DebuggingandSupport 51

RetrieveLogsforTechnicalSupport 51

GetServiceStatistics 52

6 vShieldAppManagement 53

ModifyingtheStateofaDatacenter 53

RetrieveDatacenterState 53

ModifyDatacenterState 54

ConfiguringFirewallRulesforvCenter 54

ConfiguringthevShieldAppFirewall 54

QuerytheFirewallConfiguration 54

ChangetheFirewallConfiguration 55

ReverttoDefaultFirewallConfiguration 56

WorkingwithSpoofGuard 56

RetrieveSpoofGuardGlobalSettings 56

EditSpoofGuardGlobalSettings 56

RetrieveSpoofGuardIPSettings 56

SaveSpoofGuardIPSettings 57

WorkingwithNamespaces 57

Add

NamespaceinaDatacenter 57

GetNamespaceDetails 58

DeleteaNamespace 58

ShowNamespacesinaDatacenter 58

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

ShowConfiguredNamespacesinDatacenter 58

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

UpgradingvShieldApp 59

7 vShieldEndpointManagement 61

OverviewofSolutionRegistration 61

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

RegisteraVendor 61

RegisteraSolution 62

AltitudeofaSolution 62

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

ActivateaSolution 63

QueryingRegistrationStatusofvShieldEndpoint 64

GetVendorRegistration 64

vShield API Programming Guide

6 VMware, Inc.

GetSolutionRegistration 64

GetIPAddressofaSolution 64

GetActivationStatusofaSolution 64

UnregisteringaSolutionwithvShieldEndpoint 64

UnregisteraVendor 64

UnregisteraSolution 65

UnsetIPAddress 65

DeactivateaSolution 65

StatusCodesandErrorSchema 65

ReturnStatusCodes 65

ErrorSchema 66

8 vShieldDataSecurityConfiguration 67

vShieldDataSecurityUserRoles 67

DefiningaDataSecurityPolicy 67

RetrieveAllRegulations 68

EnableaRegulation 68

RetrievetheClassificationValue 69

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

ViewtheListofExcludableAreas 69

ExcludeAreasfromPolicyInspection 70

ConfigureFileFilters 70

SavingandPublishingPolicies 71

RetrievetheSavedSDDPolicy 71

RetrievethePublishedSDDPolicy 73

Publish

theUpdatedPolicy 73

DataSecurityScanning 73

RetrievetheStatusforaScanOperation 73

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

AnalyzingResults 74

ViewtheListofViolationCounts 74

ViewtheListofViolatingFiles 74

ViewtheListofViolatingFilesinCSVFormat 75

ViewViolationsinEntireInventory 75

Appendix 77

vShieldManagerGlobalConfigurationSchema 77

ESXHostPreparationandUninstallationSchema 80

vShieldAppSchemas 81

vShieldAppConfigurationSchema 81

vShieldAppFirewallSchema 82

vShieldAppSpoofGuardSchema 85

vShieldAppNamespaceSchema 87

vShieldEdgeSchemas 88

ErrorMessageSchema 100

VMware, Inc. 7

Thismanual,thevShieldAPIProgrammingGuide,describeshowtoinstall,configure,monitor,andmaintainthe

VMware

®

vShield™systembyusingRESTAPIrequests.Theinformationincludesstep‐by‐stepconfiguration

instructionsandexamples.

Intended Audience

ThismanualisintendedforanyonewhowantstouseRESTAPItoinstallorusevShieldinaVMware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

8 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. 9

1

VMwarevShield™isasuiteofnetworkedgeandapplication‐awarefirewallsbuiltforVMwarevCenterServer

integration.vShieldinspectsclient‐servercommunicationsandinter‐virtual‐machine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 9

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

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

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

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

10 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

<module name="Dlp" baseUri="/api/2.0/dlp" version="2.0"/><module name="EndpointSolution"

baseUri="/api/2.0/endpointsecurity" version="2.0"/><module name="IPSet"

baseUri="/api/2.0/services/ipset" version="2.0"/><module name="UserMgmt"

baseUri="/api/2.0/services/usermgmt" version="2.0"/><module name="MACSet"

baseUri="/api/2.0/services/macset" version="2.0"/><module

name="SecurityGroup" baseUri="/api/2.0/services/securitygroup"

version="2.0"/><module name="Application"

baseUri="/api/2.0/services/application" version="2.0"/>

</version>

</versions>

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

Chapter 1 Overview of VMware vShield

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

vShield API Programming Guide

12 VMware, Inc.

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

VMware, Inc. 13

Chapter 1 Overview of VMware vShield

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

vShield API Programming Guide

14 VMware, Inc.

VMware, Inc. 15

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 15

 “RetrievingTechSupportLogs”onpage 16

 “UserManagement”onpage 17

 “RoleManagement”onpage 19

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

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

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

Synchronizing vShield Manager with vCenter Server and DNS

YoucanuseasinglerequesttosynchronizethevShieldManagerwiththevCenterServerandaddDNSservers

tothevShieldManagerforIPaddressandhostnameresolution.SynchronizingwithvCenterServerenables

thevShieldManageruserinterfacetodisplayyourVMwareInfrastructureinventory.ForthevcInfoschema,

andthe

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

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:

<userName>administrator</userName>

</vcInfo>

</dnsInfo>

</vsmGlobalConfig>

vShield Manager Management

2

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

fordetailsaboutbasicauthorization.

vShield API Programming Guide

16 VMware, Inc.

SynchronizationwithvCenterServerrequiresitsIPaddress(orURL)andadministratorlogincredentials.

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>

Monitoring vShield Manager reachability

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

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

Request:

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

Retrieving Tech Support Logs

YoucanretrieveTechnicalSupportlogsfromthevShieldManagerandvShieldEdge.

Get the vShield Manager Technical Support Log File Path

YoucangetthepathtothediagnosticlogfileforthevShieldManager.Youcanthensendthediagnosticlogto

technicalsupportforassistanceintroubleshootinganissue.

Example 2-4. Get the Tech Support Log File Path for a vShield Manager

Request:

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

Thetechnicalsupportlogisplacedinafileatthefollowingpath,howevertheRESTAPIhasnoprovisionfor

downloadingit,andwgetandcurldonothavepermissiontodownloadit,either.Youcanretrievethelog

withvShieldManagerbyclickingSettings&Reports>Configuration>

Support>[LogDownload]Initiate.

/tech_support_logs/vsm/vshield_mgr_support_<date_time>GMT.log.gz

Get the vShield Edge Technical Support Log File Path

YoucandownloadthediagnosticlogfromavShieldEdge.Youcanthensendthediagnosticlogtotechnical

supportforassistanceintroubleshootinganissue.

Example 2-5. Get the Tech Support Log File Path for a vShield Edge

Request:

VMware, Inc. 17

Chapter 2 vShield Manager Management

GET https://<vsm-ip>/api/2.0/networks/<internal-portgroup-vc-moref-id>/techSupportLogs

Thetechnicalsupportlogisplacedinafile,howevertheRESTAPIhasnoprovisionfordownloadingit,and

wgetandcurldonothavepermissiontodownloadit,either .YoucanretrievethelogwithvShieldManager

byclickingSettings&Reports>Configuration>Support>[LogDownload]

Initiate.

User Management

TheauthenticationandauthorizationAPIsincludemethodstomanageusersandroles.

Get a List of Users

YoucanretrievealistofvShieldManagerusers,bothlocalusersandvCenteruserswhoareassignedarole.

Example 2-6. Get a list of users

Request:

GET https://<vsm-ip>/api/2.0/services/usermgmt/users/vsm

BeforeyouadduserstovShieldManager,thepre‐existingdefaultsarelocaluseradminandthevCenteruser

administrator.

Get Information About a User

Youcanretrieveinformationaboutauser.

Example 2-7. Get information about a user

Request:

GET https://<vsm-ip>/api/2.0/services/usermgmt/user/<userId>

Userinformationincludesusername,fullname,emailaddress,whetherlocalornot,whetherenabled,

resourceobjects,roles,andscope.

Create a Local User on vShield Manager

YoucancreatealocalvShieldManageruser.

Example 2-8. Create a local user

RequestHeader:

POST https://<vsm-ip>/api/2.0/services/usermgmt/user/local

RequestBody:

<userId>somebody</userId>

<fullname>Person Somebody</fullname>

<email>[email protected]</email>

<role>security_admin</role>

</accessControlEntry>

</userInfo>

vShield API Programming Guide

18 VMware, Inc.

Update a Local User Account

Youcanupdatealocaluseraccountincludingpassword.Ifapasswordisnotprovided,theexistingpassword

isretained.The<userId>variableintherequestheadershouldbesameastheonespecifiedinXML.TheAPI

returnsupdatedinformationfortheuser.

Example 2-9. Update a local user account

RequestHeader:

PUT https://<vsm-ip>/api/2.0/services/usermgmt/user/local/<userId>

RequestBody:

<userId>somebody</userId>

<fullname>Person Somebody</fullname>

<email>[email protected]</email>

<role>security_admin</role>

<resource><resourceId>datacenter-312</resourceId></resource>

</accessControlEntry>

</userInfo>

Enable or Disable a User Account

Youcandisableorenableauseraccount,eitherlocaluserorvCenteruser.Whenauseraccountiscreated,the

accountisenabledbydefault.

Example 2-10. Enable or disable a user account

Request:

PUT https://<vsm-ip>/api/2.0/services/usermgmt/user/<userId>/enablestate/<value>

The<value>canbe0(zero)todisabletheaccount,or1(one)toenabletheaccount.

ThisAPIreturns“204NoContent”ifsuccessful.

Remove a User Account

ThefirstAPIremovesalocaluseraccount,orremovestheVSMroleassignmentforavCenteruser,without

affectingthevCenteraccount.ThesecondAPIremovesavCenteruser’srolesbutisnotallowedforlocalusers.

Example 2-11. Remove a user account

Request:

DELETE https://<vsm-ip>/api/2.0/services/usermgmt/user/<userId>

Example 2-12. Removing a user role

Request:

DELETE https://<vsm-ip>/api/2.0/services/usermgmt/role/<userId>

BothAPIsreturn“204NoContent”ifsuccessful.

VMware, Inc. 19

Chapter 2 vShield Manager Management

Role Management

Get Role for a User

Youcanretrieveinformationabouttheroleassignedtothisuser.

Example 2-13. Retrieve the role of a user

Request:

GET https://<vsm-ip>/api/2.0/services/usermgmt/role/<userId>

Possiblerolesaresuper_user,vshield_admin,enterprise_admin,security_admin,andauditor.

Add Role and Resources for a User

Youcanaddroleandaccessibleresourcesforthespecifieduser.ItaffectsonlyvCenterusers,notlocalusers.

ForlocalvShieldManagerusers,itthrowserror“400:Useralreadypresent.”

Example 2-14. Update the role of a user

RequestHeader:

POST https://<vsm-ip>/api/2.0/services/usermgmt/role/<userId>

RequestBody:

<resourceId>resource-num</resourceId>

...

</resource>

</accessControlEntry>

ThisAPIreturns“204NoContent”ifsuccessful.

Change Role for a User

Youcanupdatetheroleassignmentforagivenuser.TheAPIreturnsanoutputrepresentationspecifyinga

new<accessControlEntry>fortheuser.

Example 2-15. Change the role of a user

RequestHeader:

PUT https://<vsm-ip>/api/2.0/services/usermgmt/role/<userId>

RequestBody:

<resourceId>resource-num</resourceId>

...

</resource>

</accessControlEntry>

Possiblerolesaresuper_user,vshield_admin,enterprise_admin,security_admin,andauditor.

vShield API Programming Guide

20 VMware, Inc.

Get a List of Possible Roles

YoucanretrievethepossiblerolesinvShieldManager.

Example 2-16. Retrieve possible roles

Request:

GET https://<vsm-ip>/api/2.0/services/usermgmt/roles

Get a List of Scoping Objects

Youcanretrievealistofobjectsthatcanbeusedtodefineauser’saccessscope.

Example 2-17. Retrieve scoping objects

Request:

GET https://<vsm-ip>/api/2.0/services/usermgmt/scopingobjects

ThescopingobjectsareusuallymanagedobjectreferencesorvCenterServernamesofdatacentersandfolders.

Creating IPset and MACset Containers

YoucancreatevShieldcontainersbasedonIPaddressesandMACaddresses.TheseAPIscontroltwotypesof

resources:vShieldManagerscopeobject(adatacenterorportgroup)andtheIPsetorMACsetaddresses.

List IPsets Created on a Scope

YoucanretrievealltheIPsetsthatwerecreatedonthespecifiedscope.

Example 2-18. List IPsets on a scope

Request:

GET https://<vsm-ip>/api/2.0/services/ipset/scope/<scope-moref>

The<scope-moref>canbeadatacenterorportgroupofthevCentertowhichvShieldManagerisconnected.

Create an IPset on a Scope

YoucancreateanewIPsetonthespecifiedscope.

Example 2-19. Create IPset on a scope

Request:

POST https://<vsm-ip>/api/2.0/services/ipset/scope/<scope-moref>

RequestBodyExample:

<ipset>

<type>

</type>

New Description

</description>

<name>TestIPSet2</name>

Page is loading ...

VMware vShield 5.0, VSHIELD APP 1.0 - API User guide

Related papers

Other documents