VMware VSHIELD MANAGER 4.1.0 UPDATE 1

vShield API Programming Guide

vShield Manager 4.1.0 Update 1

vShield Zones 4.1.0 Update 1

vShield App 1.0.0 Update 1

vShield Edge 1.0.0 Update 1

vShield Endpoint 1.0.0 Update 1

This document supports the version of each product listed and

supports all subsequent versions until the document is replaced

by a new edition. To check for more recent editions of this

document, see http://www.vmware.com/support/pubs.

EN-000434-02

VMware, Inc.

3401 Hillview Ave.

Palo Alto, CA 94304

www.vmware.com

2 VMware, Inc.

vShield API Programming Guide

You can find the most up-to-date technical documentation on the VMware Web site at:

http://www.vmware.com/support/

The VMware Web site also provides the latest product updates.

If you have comments about this documentation, submit your feedback to:

docfeedback@vmware.com

intellectual property laws. VMware products are covered by one or more patents listed at

http://www.vmware.com/go/patents.

VMware is a registered trademark or trademark of VMware, Inc. in the United States and/or other jurisdictions. All other marks

and names mentioned herein may be trademarks of their respective companies.

VMware, Inc. 3

Contents

AboutThisBook 7

1 OverviewofVMwarevShield 9

vShieldComponents 9

vShieldManager 9

vShieldApp 9

vShieldEdge 10

vShieldEndpoint 10

PortsRequiredforvShield 10

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

HowRESTWorks 10

UsingthevShieldRESTAPI 11

RESTfulWorkflowPatterns 11

ForMoreInformationAboutREST 12

2 vShieldManagerManagement 13

SynchronizethevShieldManagerwithvCenterServerandDNS 13

RetrievingTechSupportLogs 14

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

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

3 ESXHostPreparationforvShieldApp,Endpoint,andIsolation 15

InstalltheLicensesforvShieldEdge,vShieldApp,andvShieldEndpoint 15

InstallvShieldApp,vShieldEndpoint,andPortGroupIsolationServicesonanESXHost 15

GettheInstallationStatusofvShieldServicesonanESXHost 17

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

4 vNetworkPreparationandvShieldEdgeInstallation 19

EnablingPortGroupIsolation 19

EnablePortGroupIsolationonavDS 20

GetthePortGroupIsolationDebugStatisticsfromanESXHost 20

DisablePortGroupIsolationonavDS 20

InstallingavShieldEdge 21

GettheInstallParametersofavShieldEdge 22

UninstallavShieldEdge 22

5 vShieldEdgeManagement 23

UpgradingavShieldEdge 24

ForceavShieldEdgetoSynchronizewiththevShieldManager 24

ManageCLICredentialsonavShieldEdge 25

ManagingDHCP 25

GettheDHCPServerStatus 25

Start,Stop,orRestarttheDHCPService 25

PostaDHCPConfiguration 26

GettheConfigurationforAllDHCPHostsandPools 26

GetTimestampsofLast10DHCPConfigurations 27

GetaDHCPConfigurationbyTimestamp 27

vShield API Programming Guide

4 VMware, Inc.

ReverttoaDHCPConfigurationbyTimestamp 27

DeletetheDHCPConfigurationonavShieldEdge 27

ManagingNAT 28

ManagingSNATRules 28

ManagingDNATRules 30

ConfiguringthevShieldEdgeFirewall 33

GettheFirewallRuleSetforavShieldEdge 33

PostaFirewallRuleSet 34

GettheStatusoftheDefaultPolicyforavShieldEdge 35

Changethe

DefaultFirewallPolicyAction 35

GetDetailsofaSpecificFirewallRule 36

GetTimestampsofLast10FirewallRuleSetsforavShieldEdge 36

GetFirewallRuleSetbyTimestamp 36

ReverttoaFirewallRuleSetbyTimestamp 36

DeleteAllFirewallRulesonavShieldEdge 36

ConfiguringVPNs 37

GettheStatusofVPNService 38

Startor

StoptheVPNServiceonavShieldEdge 38

ConfigureVPNParametersonavShieldEdge 38

AddaRemoteSite 39

AddTunnelsforaVPNSite 40

GettheDetailedIPSecConfigurationsforaNetwork 40

GettheDetailedConfigurationforaVPNSite 41

GettheDetailedTunnelConfiguration 41

DeleteaTunnelforaVPNSite 41

Delete

aRemoteSite 41

GettheCurrentVPNConfigurationonavShieldEdge 41

GetTimestampsofLast10VPNConfigurations 42

GetaVPNConfigurationbyTimestamp 42

ReverttoaVPNConfigurationbyTimestamp 42

DeletetheVPNConfigurationonavShieldEdge 42

LoadBalancer 43

GettheStatusofLoadBalancerServiceonavShieldEdge 43

Startor

StoptheLoadBalancerServiceonavShieldEdge 44

AddaListenerforLoadBalancingService 44

GettheCurrentLoadBalancerConfigurationonavShieldEdge 45

GettheConfigurationofaSpecificLoadBalancingServer 45

GetTimestampsofLast10LoadBalancerConfigurations 45

GetaLoadBalancerConfigurationbyTimestamp 46

Reverttoa

LoadBalancerConfigurationbyTimestamp 46

DeletetheLoadBalancerConfigurationonavShieldEdge 46

ManagingtheMTUThresholdforavShieldEdge 46

ViewTrafficStatistics 47

DebugvShieldEdgeServicesUsingServiceStatistics 47

ManagingtheConnectiontoaSyslogServer 48

PostaSyslogServerConfiguration 48

GettheCurrentSyslogServerConfiguration 48

GetTimestampsofLast10

SyslogServerConfigurations 48

GetaSyslogServerConfigurationbyTimestamp 49

ReverttoaSyslogServerConfigurationbyTimestamp 49

DeletetheCurrentSyslogServerConfiguration 49

6 vShieldAppManagement 51

ConfiguringFirewallRulesforavCenterContainer 51

ViewAllFirewallRulesforaContainer 51

PostanAppFirewallRuleSetforaContainer 52

VMware, Inc. 5

ViewaListofTimestampsIdentifyingAppFirewallRuleSetChanges 55

ViewaPreviousFirewallRuleSetbyTimestamp 55

ReverttoaPreviousFirewallRuleSet 55

DeleteAllFirewallRulesunderaContainer 55

ManagingSecurityGroups 56

AddaSecurityGroup 56

AddaVirtualMachinetoaSecurityGroup 57

GettheListofAllSecurity

GroupsunderaBaseNode 57

GettheDetailsforaSingleSecurityGroupunderaBaseNode 58

GetIPAddressesfortheVirtualMachinesinaSecurityGroup 58

GetthePropertiesfromaVirtualMachine 58

DeleteaVirtualMachinefromaSecurityGroup 58

DeleteaSingleSecurityGroup 59

DeleteAllSecurityGroupsundera

BaseNode 59

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

7 vShieldEndpointManagement 61

RegisteranSVMwiththevShieldEndpointServiceonanESXHost 61

RetrieveSVM‐SpecificNetworkInformation 62

RetrievevShieldEndpointServiceStatusonanESXHost 63

UninstallingthevShieldEndpointServicefromanESXHost 63

UnregisteranSVMfromvShieldEndpoint 63

UninstallvShieldEndpointfromthevShieldManager 64

ErrorSchema 64

Appendix 65

vShieldManagerSchemas 65

vShieldManagertovCenterServerSynchronizationSchema 65

DNSServiceSchema 66

VirtualMachineInformationSchema 66

SecurityGroupsSchema 67

ESXHostPreparationandUninstallationSchema 68

vShieldAppSchemas 69

vShieldAppConfigurationSchema 69

vShieldAppFirewallSchema 69

PortGroupIsolationManagementSchema 71

PortGroupIsolationStatisticsSchema 71

vShieldEdgeSchemas 71

BasevShieldEdgeConfigurationSchema 72

vShieldEdge

InstallationandUpgradeSchema 72

vShieldEdgeGlobalConfigurationSchema 73

vShieldEdgeCLILoginCredentialsSchema 74

vShieldEdgeFirewallSchema 74

NATSchema 77

DHCPSchema 79

VPNSchema 80

LoadBalancerSchema 83

MTUThresholdSchema 84

TrafficStatsSchema 85

SyslogSchema 85

ErrorMessageSchema 86

Index 87

VMware, Inc. 6

VMware, Inc. 7

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

VMware

®

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

instructionsandexamples.

Intended Audience

ThismanualisintendedforanyonewhowantstouseRESTAPItoinstallorusevShieldinaVMware

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

arefamiliarwithvirtualmachinetechnologyandvirtualdatacenteroperations.Thismanualassumes

familiaritywithvShield.

VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions

oftermsastheyareusedinVMwaretechnicaldocumentationgotohttp://www.vmware.com/support/pubs.

Document Feedback

VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Ifyouhavecomments,sendyour

feedbackto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communication

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

componentforprotectingvirtualizeddatacentersfromattacksand

misusehelpingyouachieveyour

compliance‐mandatedgoals.

ThisguideassumesyouhaveadministratoraccesstotheentirevShieldsystem.Ifyouareunabletoaccessa

screenorperformaparticulartask,consultyourvShieldadministrator.

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

 “vShieldComponents”onpage 9

 “PortsRequiredforvShield”onpage 10

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

vShield Components

vShieldincludescomponentsandservicesessentialforprotectingvirtualmachines.vShieldcanbeconfigured

throughaweb‐baseduserinterface,acommandlineinterface(CLI),andRESTAPI.

TorunvShield,youneedonevShieldManagervirtualmachineandatleastonevShieldZones,vShieldApp,

orvShieldEdgevirtualmachine.

vShield Manager

ThevShieldManageristhecentralizedmanagementcomponentofvShieldandisinstalledfromOVAasa

virtualmachinebyusingthevSphereClient.UsingthevShieldManageruserinterfaceorvSphereClient

plug‐in,administratorscaninstall,configure,andmaintainvShieldcomponents.

ThevShieldManagervirtualmachinecanrunon

adifferentESXhostfromyourvShieldAppandvShield

Edgevirtualmachines.

ThevShieldManageruserinterfaceleveragestheVMwareInfrastructureSDKtodisplayacopyofthevSphere

Clientinventorypanel.

FormoreontheusingthevShieldManageruserinterface,seethevShieldAdministrationGuide.

vShield App

AvShieldAppmonitorsalltrafficintoandoutofanESXhost,andbetweenvirtualmachinesonthehost.

vShieldAppprovidesapplication‐awaretrafficanalysisandstatefulfirewallprotection.vShieldApp

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

Overview of VMware vShield

1

vShield API Programming Guide

10 VMware, Inc.

AstrafficpassesthroughavShieldApp,eachsessionheaderisinspectedtocatalogthedata.ThevShieldApp

createsaprofileforeachvirtualmachinedetailingtheoperatingsystem,applications,andportsusedin

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

permittingdynamic

protocolssuchasFTPandRPCtopassthrough,whilemaintaininglockdownonports

1024andhigher.

YoucannotprotecttheServiceConsoleorVMkernelwithavShieldAppbecausethesecomponentsarenot

virtualmachines.

vShield Edge

AvShieldEdgeprovidesnetworkedgesecuritytoprotectthevirtualmachinesinavCloudtenant’snetwork

fromattacksoriginatingfromthepublicnetwork.ThevShieldEdgeconnectstheisolated,privatenetworksof

cloudtenantstothepublicsideoftheserviceprovidernetworkthroughcommonedgeservicessuchasDHCP,



VPN,NAT,andloadbalancing.

YouinstallavShieldEdgefromthevShieldManager.YoucaninstallonevShieldEdgeinstancepertenantport

grouponavNetworkDistributedSwitch(vDS).

YouconfigureavShieldEdgebyusingRESTAPI.

vShield Endpoint

vShieldEndpointdeliversanintrospection‐basedantivirussolution.vShieldEndpointusesthehypervisorto

scanguestvirtualmachinesfromtheoutsidewithoutabulkyagent.vShieldEndpointisefficientinavoiding

resourcebottleneckswhileoptimizingmemoryuse.

Ports Required for vShield

ThevShieldManagerrequiresports80/TCPand443/TCPforRESTAPIrequests.

An Introduction to REST API for vShield Users

REST,anacronymforRepresentationalStateTransfer,isatermthathasbeenwidelyemployedtodescribean

architecturalstylecharacteristicofprogramsthatrelyontheinherentpropertiesofhypermediatocreateand

modifythestateofanobjectthatisaccessibleataURL.

How REST Works

OnceaURLofsuchanobjectisknowntoaclient,theclientcanuseanHTTPGETrequesttodiscoverthe

propertiesoftheobject.ThesepropertiesaretypicallycommunicatedinastructureddocumentwithanHTTP

Content‐TypeofXMLorJSON,thatprovidesarepresentationofthe

stateoftheobject.InaRESTfulworkflow,

documents(representationsofobjectstate)arepassedbackandforth(transferred)betweenaclientanda

servicewiththeexplicitassumptionthatneitherpartyneedknowanythingaboutanentityotherthanwhatis

presentedinasinglerequestorresponse.The

URLsatwhichthesedocumentsareavailableareoften“sticky,”

inthattheypersistbeyondthelifetimeoftherequestorresponsethatincludesthem.Theothercontentofthe

documentsisnominallyvaliduntiltheexpirationdatenotedintheHTTPExpiresheader.

VMware, Inc. 11

Chapter 1 Overview of VMware vShield

Using the vShield REST API

RESTAPIusesHTTPrequests(whichareoftenexecutedbyascriptorotherhigher‐levellanguage)asaway

ofmakingwhatareessentiallyidempotentremoteprocedurecallsthatcreate,modify,ordeletetheobjects

definedbytheAPI.ThisRESTAPI(andothers)isdefinedbyacollectionof

XMLdocumentsthatrepresent

theobjectsonwhichtheAPIoperates.Theoperationsthemselves(HTTPrequests)aregenerictoallHTTP

clients.

TowriteaRESTfulclient,youneedtounderstandonlytheHTTPprotocolandthesemanticsofstandard

HTMLmarkup.TousethevShieldAPIeffectivelyinsucha

client,youneedtoknowthreethings:

 thesetofobjectsthattheAPIsupports,andwhattheyrepresent(WhatisavDC?Howdoesitrelatetoan

Org?)

 howtheAPIrepresentstheseobjects(WhatdoestheXMLschemaforthevShieldEdgefirewallruleset

looklike?Whatdotheindividualelementsandattributesrepresent?)

 howtheclientreferstoanobjectonwhichitwantstooperate

Toanswerthesequestions,youneedtounderstandthe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,forexample,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.Andaclientcanusuallydeleteanobjectwith

anHTTPDELETErequest.

Inthisdocument,wepresentexamplerequestsandresponses,andalsoprovide

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

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

well‐knownURL(suchasthe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.

Thesetwooperationscanrepeat,inthisorder,foraslongasnecessary.

I

MPORTANTAllvShieldRESTrequestsrequireauthorization.Youcanusethefollowingbasicauthorization:

Authorization: Basic YWRtaW46ZGVmYXVsdA==

YWRtaW46ZGVmYXVsdA==representstheBase64encodingofthevShieldManagerdefaultlogincredentials

(admin:default).

vShield API Programming Guide

12 VMware, Inc.

For More Information About REST

ForacomprehensivediscussionofRESTfromboththeclientandserverperspectives,see:

Richardson,Leonard,andSamRuby.RESTfulWebServices.NorthMankato:OʹReillyMedia,Inc.,2007.

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

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:

 “SynchronizethevShieldManagerwithvCenterServerandDNS”onpage 13

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

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

SynchronizationwithvCenterrequiresthevCenter

URLandlogincredentials.

Fortheschema,see“vShieldManagertovCenterServerSynchronizationSchema”onpage 65.

FortheDNSschema,see“DNSServiceSchema”onpage 66.

Example 2-1. Synchronizing the vShield Manager with vCenter Server and Identify DNS Services

Request:

POST <vshield_manager-uri>/api/1.0/global/config

YoucanalsosynchronizethevShieldManagerwiththevCenterServerwithoutspecifyingDNS.

Example 2-2. Synchronizing the vShield Manager with vCenter Server without DNS

Request:

POST <vshield_manager-uri>/api/1.0/global/vcInfo

vShield Manager Management

2

IMPORTANTAllvShieldRESTrequestsrequireauthorization.Youcanusethefollowingbasicauthorization:

Authorization: Basic YWRtaW46ZGVmYXVsdA==

YWRtaW46ZGVmYXVsdA==representstheBase64encodingofthevShieldManagerdefaultlogincredentials

(admin:default).

vShield API Programming Guide

14 VMware, Inc.

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-3. Getting the Tech Support Log File Path for a vShield Manager

Request:

GET <vshield_manager-uri>/api/1.0/global/techSupportLogs

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-4. Getting the Tech Support Log File Path for a vShield Edge

Request:

GET <vshield_manager-uri>/api/1.0/network/<internal-portgroup-vc-moref-id>/techSupportLogs

VMware, Inc. 15

3

YoucanextendthecapabilitiesofvShieldbyaddingthefollowingservices:vShieldApp,vShieldEndpoint,

andvShieldEdge.YoumustprepareeachESXhostinyourenvironmentfortheseservices.ThevShield

ManagerOVAfilecontainsthedriversandfilesnecessarytoinstallalladditionalservices.

Thischapterincludesthe

followingtopics:

 “InstallvShieldApp,vShieldEndpoint,andPortGroupIsolationServicesonanESXHost”onpage 15

 “GettheInstallationStatusofvShieldServicesonanESXHost”onpage 17

 “UninstallingvShieldServicesfromanESXHost”onpage 18

Install the Licenses for vShield Edge, vShield App, and vShield

Endpoint

YoumustinstalllicensesforvShieldEdge,vShieldApp,andvShieldEndpointbeforeinstallingthese

components.YoucaninstalltheselicensesbyusingthevSphereClient.

1FromavSphereClienthostthatisconnectedtoavCenterServersystem,selectHome>Licensing.

2Forthereportview,selectAsset.

3Right‐click

avShieldassetandselectChangelicensekey.

4 SelectAssignanewlicensekeyandclickEnterKey.

5Enterthelicensekey,enteranoptionallabelforthekey,andclickOK.

6ClickOK.

7RepeatthesestepsforeachvShieldcomponentforwhichyouhavealicense.

Install vShield App, vShield Endpoint, and Port Group Isolation

Services on an ESX Host

Toshortenthetimetodeployment,youcaninstallvShieldApp,vShieldEndpoint,andPortGroupIsolation

servicesonanESXhostbyusingasingleRESTcall.YoucandothisbyincludingVszInstallParams,

PortgroupIsolationInstallParams,andEpsecInstallParams inthePOSTbody.

ESX Host Preparation for vShield

App, Endpoint, and Isolation

3

IMPORTANTAllvShieldRESTrequestsrequireauthorization.Youcanusethefollowingbasicauthorization:

Authorization: Basic YWRtaW46ZGVmYXVsdA==

YWRtaW46ZGVmYXVsdA==representstheBase64encodingofthevShieldManagerdefaultlogincredentials

(admin:default).

vShield API Programming Guide

16 VMware, Inc.

PortGroupIsolationisaserviceusedbyavShieldEdgetoisolatethevirtualmachinesinavDSportgroup

fromtheexternalnetwork.WhenPortGroupIsolationisenabled,trafficisnotallowedaccesstothevirtual

machinesintheprotectedportgroupunlessNATrulesorVLANtags

areconfigured.

YoumustspecifythehostIDofthetargetESXhosttoinstallallservices.

See“ESXHostPreparationandUninstallationSchema”onpage 68.

Example 3-1. Installing a vShield App, vShield Endpoint, and Port Group Isolation on an ESX Host

Request:

POST <vshield_manager-uri>/api/1.0/vshield/<host-id>

Example:

POST /api/1.0/vshield/host-5450 HTTP/1.1

Content-type: application/xml; charset=UTF-8

Authorization: Basic YWRtaW46ZGVmYXVsdA==

Cache-Control: no-cache

Pragma: no-cache

Host: 10.112.196.244

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

Content-Length: 489

<VshieldConfiguration><VszInstallParams><DatastoreId>datastore-5035</DatastoreId>

<ManagementPortSwitchId>network-4485</ManagementPortSwitchId><MgmtInterface>

<PortgroupIsolationInstallParams><DatastoreId>datastore-5035</DatastoreId>

</PortgroupIsolationInstallParams><EpsecInstallParams>true</EpsecInstallParams>

<InstallAction>install</InstallAction></VshieldConfiguration>

ESXhostpreparationrequiresthefollowingelements:

 DatastoreId:VCMOIDofthedatastoreonwhichthevShieldAppandPortGroupIsolationservice

virtualmachinefileswillbestored.

 ManagementPortSwitchId:VCMOIDoftheportgroupthatwillhostthemanagementportofthe

vShieldApp.

 MgmtInterface

 IpAddress:IPaddresstobeassignedtothemanagementportofthevShieldApp.ThisIPaddress

mustbeabletocommunicatewiththevShieldManager.

 NetworkMask:SubnetmaskassociatedwiththeIPaddressassignedtothemanagementinterfaceof

thevShieldApp.

 DefaultGw:IPaddressofthedefaultgateway.

CAUTIONDonotinstallvShieldZones/AppontheESXhostwherevCenterServerisrunning.

NOTEPortGroupIsolationisanoptionalfeaturethatisnotrequiredforvShieldEdgeoperation.PortGroup

IsolationisavailableforvDS‐basedvShieldEdgeinstallationsonly.

VMware, Inc. 17

Chapter 3 ESX Host Preparation for vShield App, Endpoint, and Isolation

Afterinstallationofallcomponentsiscomplete,dothefollowing:

 vShieldApp:Atthispoint,vShieldAppinstallationiscomplete.EachvShieldAppinheritsglobal

firewallrulessetinthevShieldManager.Thedefaultfirewallrulesetallowsalltraffictopass.Youmust

configureblockingrulestoexplicitlyblocktraffic.ToconfigureAppFirewallrules,see“Configuring

FirewallRules

foravCenterContainer”onpage 51.

 PortGroupIsolation:YoumustenablethePortGroupIsolationfeatureoneachvDS.Afterenablement

iscomplete,installavShieldEdgeoneachportgroup.See“vNetworkPreparationandvShieldEdge

Installation”onpage 19.

 vShieldEndpoint:Tocompleteinstallation,see“vShieldEndpointManagement”onpage 61.

YoucaninstallasingleservicebyidentifyingonlythatserviceinthePOSTbody.InExample 3‐2,onlyvShield

Appisinstalled,asidentifiedbyinclusionoftheVszInstallParamselementonly.

Example 3-2. Installing a vShield App Only

Request:

POST <vshield_manager-uri>/api/1.0/vshield/<host-id>/vsz

Example:

POST /api/1.0/vshield/host-5126 HTTP/1.1

Content-type: application/xml; charset=UTF-8

Authorization: Basic YWRtaW46ZGVmYXVsdA==

Cache-Control: no-cache

Pragma: no-cache

Host: 10.112.196.244

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

Content-Length: 368

<VshieldConfiguration><VszInstallParams><DatastoreId>datastore-5131</DatastoreId>

<ManagementPortSwitchId>network-5134</ManagementPortSwitchId><MgmtInterface>

<InstallAction>install</InstallAction></VshieldConfiguration>

Get the Installation Status of vShield Services on an ESX Host

YoucanretrievetheinstallationoruninstallationstatusofvShieldservicesonanESXhosttotrackprogressas

completeornotinitiated.Ifneitheroftheseoperationsisinprogress,theresponseincludesthelistofinstalled

servicesontheESXhost.

Example 3-3. Getting vShield Service Installation Status on an ESX Host

Request:

GET <vshield_manager-uri>/api/1.0/vshield/<host-id>

CAUTIONDonotinstallvShieldZones/AppontheESXhostwherevCenterServerisrunning.

vShield API Programming Guide

18 VMware, Inc.

Uninstalling vShield Services from an ESX Host

YoucanuninstallvShieldApp,vShieldEndpoint,andPortGroupIsolationfromanESXhostbyusingasingle

request.

Beforeuninstallingtheseservices,completethefollowingtasks:

 vShieldEndpoint:YoumustunregisterSVMsbeforeuninstallingvShieldEndpointfromtheESXhost.See

“UnregisteranSVMfromvShieldEndpoint”onpage 63.

 PortGroupIsolation:YoumustdisablePortGroupIsolationbeforeuninstallingtheservice.See“Disable

PortGroupIsolationonavDS”onpage 20.

Example 3-4. Uninstalling All Three vShield Services from an ESX Host

Request:

DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>

Touninstalltwoservicesatthesametime,separatetheservicestobeuninstalledwithhyphens.

Example 3-5. Uninstalling More than One Service

Request:

DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>/<hyphen-separated-service-names>

Example:

ThisrequestuninstallsavShieldApp(zones)andPortGroupIsolation(pgi).ThevShieldEndpointservice

isshortenedtoepsec.

DELETE /api/1.0/zones/vshield/<host-id>/vsz-pgi

Youcanuninstallasingleservicebyspecifyingtheservicename.

Example 3-6. Uninstall a vShield App Only

Request:

DELETE <vshield_manager-uri>/api/1.0/vshield/<host-id>/vsz

CAUTIONUninstallinganyofthesevShieldservicesplacestheESXhostinmaintenancemode.After

uninstallationiscomplete,theESXhostreboots.Ifanyofthevirtualmachinesthatarerunningonthetarget

ESXhostcannotbemigratedtoanotherESXhost,thesevirtualmachinesmustbepoweredoffor

migrated

manuallybeforetheuninstallationcancontinue.IfthevShieldManagerisonthesameESXhost,thevShield

ManagermustbemigratedpriortouninstallingthevShieldApp.

BeforeuninstallingPortGroupIsolation,disabletheserviceonthehostvDS.See“DisablePortGroupIsolation

onavDS”onpage 20.

VMware, Inc. 19

4

AfterESXhostpreparationiscomplete,youcansecureinternalnetworksbyinstallingavShieldEdge.Ifyou

areinstallingvShieldEdgeinstancesonvDSportgroups,youcanisolatethoseportgroupsbyenablingPort

GroupIsolationoneachvDS.

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

 “EnablingPortGroupIsolation”onpage 19

 “InstallingavShieldEdge”onpage 21

Enabling Port Group Isolation

PortGroupIsolationcreatesabarrierbetweenthevirtualmachinesprotectedbyavShieldEdgeandthe

externalnetwork.WhenyouenablePortGroupIsolationandinstallavShieldEdgeonavDSportgroup,you

isolateeachsecuredvDSportgroupfromtheexternalnetwork.WhenPortGroupIsolationis

enabled,traffic

isnotallowedaccesstothevirtualmachinesinthesecuredportgroupunlessNATrulesorVLANtagsare

configured

To enable Port Group Isolation on a vDS

1EnablePortGroupIsolationoneachvDS.

2InstallavShieldEdgeoneachvDSportgroupyouplantosecure.

3MovethevirtualmachinestosecuredvDSport

groups.

vNetwork Preparation and vShield

Edge Installation

4

IMPORTANTIfyouintendtousethePortGroupIsolationfeature,youshouldinstallPortGroupIsolationon

allESXhostsinyourvCenterenvironmentbeforeyouinstallanyvShieldEdgevirtualmachines.Ifyoudonot

installPortGroupIsolationandattempttoenablethefeatureduringvShieldEdgeinstallation,

PortGroup

Isolationdoesnotwork.See“InstallvShieldApp,vShieldEndpoint,andPortGroupIsolationServicesonan

ESXHost”onpage 15.

I

MPORTANTAllvShieldRESTrequestsrequireauthorization.Youcanusethefollowingbasicauthorization:

Authorization: Basic YWRtaW46ZGVmYXVsdA==

YWRtaW46ZGVmYXVsdA==representstheBase64encodingofthevShieldManagerdefaultlogincredentials

(admin:default).

NOTEPortGroupIsolationisanoptionalfeaturethatisnotrequiredforvShieldEdgeoperation.PortGroup

IsolationisavailableforvDS‐basedvShieldEdgeinstallationsonly.

vShield API Programming Guide

20 VMware, Inc.

Enable Port Group Isolation on a vDS

AfterPortGroupIsolationisinstalledoneachESXhost,youmustenablePortGroupIsolationoneachvDS

whereyouwillinstallavShieldEdge.

Example 4-1. Enabling Port Group Isolation on a vDS

Request:

PUT <vshield_manager-uri>/api/1.0/network/portgroupIsolation/dvs/<dvs-Moid>

Example:

PUT /api/1.0/portgroupIsolation/dvs/dvs-1069 HTTP/1.1

Content-type: application/xml; charset=UTF-8

Authorization: Basic YWRtaW46ZGVmYXVsdA==

Cache-Control: no-cache

Pragma: no-cache

Host: 10.112.196.244

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

Get the Port Group Isolation Debug Statistics from an ESX Host

YoucanretrievethestatisticsonPortGroupIsolationactivityfromanESXhostfordebugpurposes.

ThequeryreturnsXMLwiththepathofthelocationofthestatisticsfileonthevShieldManager.Thispathcan

beusedtodownloadthefileoverHTTP.

See“PortGroupIsolationStatistics

Schema”onpage 71.

Example 4-2. Getting the Port Group Isolation Debug Statistics from an ESX Host

Request:

GET <vshield_manager-uri>/api/1.0/network/portgroupIsolation/<host-Id>/statsLocation

Disable Port Group Isolation on a vDS

BeforeuninstallingPortGroupIsolation,disabletheserviceonthehostvDS.

Example 4-3. Disabling Port Group Isolation on a vDS

Request:

DELETE <vshield_manager-uri>/api/1.0/network/portgroupIsolation/dvs/<dvs-Moid>

Example:

DELETE /api/1.0/portgroupIsolation/dvs/dvs-1069 HTTP/1.1

Content-type: application/xml; charset=UTF-8

Authorization: Basic YWRtaW46ZGVmYXVsdA==

Cache-Control: no-cache

Pragma: no-cache

Host: 10.112.196.244

Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2

Connection: keep-alive

Page is loading ...

VMware VSHIELD MANAGER 4.1.0 UPDATE 1 - API User guide

This manual is also suitable for

VMware VSHIELD MANAGER 4.1.0 UPDATE 1 - API User guide

Related papers

Other documents