VMware VSHIELD APP 1.0 - API Operating instructions

vShield API Programming Guide
vShield Manager 4.1
vShield App 1.0
vShield Edge 1.0
vShield Endpoint 1.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-000434-00

VMware, Inc.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com
2VMware, 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:
[e-mail]
Copyright © 2010 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and
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
1Overview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REST 10
vShieldAPIConventions 11
RESTfulWorkflowPatterns 12
ForMoreInformationAboutREST 13
2vShieldManagerManagement 15
SynchronizethevShieldManagerwithvCenterServerandDNS 15
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
3ESXHostPreparationforvShieldApp,Endpoint,andIsolation 17
InstalltheLicensesforvShieldEdge,vShieldApp,andvShieldEndpoint 17
InstallvShieldApp,vShieldEndpoint,andPortGroupIsolationServicesonanESXHost 17
GettheInstallationStatusofvShieldServicesonanESXHost 19
UninstallingvShieldServicesfromanESXHost 20
4vNetworkPreparationandvShieldEdgeInstallation 21
EnablingPortGroupIsolation 21
EnablePortGroupIsolationonavDS 22
GetthePortGroupIsolationDebugStatisticsfromanESXHost 22
DisablePortGroupIsolationonavDS 22
InstallingavShieldEdge 23
GettheInstallParametersofavShieldEdge 24
UninstallavShieldEdge 24
5vShieldEdgeManagement 25
ForceavShieldEdgetoSynchronizewiththevShieldManager 26
ManageCLICredentialsonavShieldEdge 26
ManagingDHCP 26
GettheDHCPServerStatus 27
Start,Stop,orRestarttheDHCPService 27
PostaDHCPConfiguration 27
GettheConfigurationforAllDHCPHostsandPools 28
GetTimestampsofLast10DHCPConfigurations 28
GetaDHCPConfigurationbyTimestamp 28

vShield API Programming Guide
4VMware, Inc.
ReverttoaDHCPConfigurationbyTimestamp 29
DeletetheDHCPConfigurationonavShieldEdge 29
ManagingNAT 29
ManagingSNATRules 29
GettheSNATRuleSet 29
PostanSNATRuleSet 30
GetTimestampsofLast10SNATRuleConfigurationsforavShieldEdge 31
GetSNATConfigurationbySnapshotTimestamp 31
ReverttoanSNATConfigurationbySnapshotTimestamp 31
DeleteAllSNATRulesonavShieldEdge 32
ManagingDNATRules 32
GettheDNATRuleSet 32
PostaDNATRuleSet 32
GetTimestampsofLast10DNATRuleConfigurationsforavShieldEdge 34
GetDNATConfigurationbySnapshotTimestamp 34
ReverttoanDNATConfigurationbySnapshotTimestamp 34
DeleteAllDNATRules 35
ConfiguringthevShieldEdgeFirewall 35
GettheFirewallRuleSetforavShieldEdge 35
PostaFirewallRuleSet 35
GettheStatusoftheDefaultPolicyforavShieldEdge 37
ChangetheDefaultFirewallPolicyAction 37
GetDetailsofaSpecificFirewallRule 37
GetTimestampsofLast10FirewallRuleSetsforavShieldEdge 38
GetFirewallRuleSetbyTimestamp 38
ReverttoaFirewallRuleSetbyTimestamp 38
DeleteAllFirewallRulesonavShieldEdge 38
ConfiguringVPNs 39
GettheStatusofVPNService 39
StartorStoptheVPNServiceonavShieldEdge 40
ConfigureVPNParametersonavShieldEdge 40
AddaRemoteSite 41
AddTunnelsforaVPNSite 42
GettheDetailedIPSecConfigurationsforaNetwork 42
GettheDetailedConfigurationforaVPNSite 42
GettheDetailedTunnelConfiguration 43
DeleteaTunnelforaVPNSite 43
DeleteaRemoteSite 43
GettheCurrentVPNConfigurationonavShieldEdge 43
GetTimestampsofLast10VPNConfigurations 44
GetaVPNConfigurationbyTimestamp 44
ReverttoaVPNConfigurationbyTimestamp 44
DeletetheVPNConfigurationonavShieldEdge 44
LoadBalancer 45
GettheStatusofLoadBalancerServiceonavShieldEdge 45
StartorStoptheLoadBalancerServiceonavShieldEdge 46
AddaListenerforLoadBalancingService 46
GettheCurrentLoadBalancerConfigurationonavShieldEdge 47
GettheConfigurationofaSpecificLoadBalancingServer 47
GetTimestampsofLast10LoadBalancerConfigurations 47
GetaLoadBalancerConfigurationbyTimestamp 48
ReverttoaLoadBalancerConfigurationbyTimestamp 48
DeletetheLoadBalancerConfigurationonavShieldEdge 48
ManagingtheMTUThresholdforavShieldEdge 48
ViewTrafficStatistics 49

VMware, Inc. 5
DebugvShieldEdgeServicesUsingServiceStatistics 49
ManagingtheConnectiontoaSyslogServer 50
PostaSyslogServerConfiguration 50
GettheCurrentSyslogServerConfiguration 50
GetTimestampsofLast10SyslogServerConfigurations 50
GetaSyslogServerConfigurationbyTimestamp 51
ReverttoaSyslogServerConfigurationbyTimestamp 51
DeletetheCurrentSyslogServerConfiguration 51
6vShieldAppManagement 53
ConfiguringFirewallRulesforavCenterContainer 53
ViewAllFirewallRulesforaContainer 53
PostanAppFirewallRuleSetforaContainer 54
ViewaListofTimestampsIdentifyingAppFirewallRuleSetChanges 57
ViewaPreviousFirewallRuleSetbyTimestamp 57
ReverttoaPreviousFirewallRuleSet 57
DeleteAllFirewallRulesunderaContainer 58
ManagingSecurityGroups 58
AddaSecurityGroup 58
AddaVirtualMachinetoaSecurityGroup 59
GettheListofAllSecurityGroupsunderaBaseNode 60
GettheDetailsforaSingleSecurityGroupunderaBaseNode 60
GetIPAddressesfortheVirtualMachinesinaSecurityGroup 60
GetthePropertiesfromaVirtualMachine 60
DeleteaVirtualMachinefromaSecurityGroup 61
DeleteaSingleSecurityGroup 61
DeleteAllSecurityGroupsunderaBaseNode 61
ConfiguringSyslogServiceforavShieldApp 62
7vShieldEndpointManagement 63
RegisteranSVMwiththevShieldEndpointServiceonanESXHost 63
RetrieveSVM‐SpecificNetworkInformation 64
RetrievevShieldEndpointServiceStatusonanESXHost 65
UninstallingthevShieldEndpointServicefromanESXHost 65
UnregisteranSVMfromvShieldEndpoint 65
UninstallvShieldEndpointfromthevShieldManager 66
ErrorSchema 66
8Appendix:RESTAPISchemas 67
vShieldManagerSchemas 67
vShieldManagertovCenterServerSynchronizationSchema 67
DNSServiceSchema 68
VirtualMachineInformationSchema 68
SecurityGroupsSchema 69
ESXHostPreparationandUninstallationSchema 70
vShieldAppSchemas 71
vShieldAppConfigurationSchema 71
vShieldAppFirewallSchema 72
PortGroupIsolationManagementSchema 73
PortGroupIsolationStatisticsSchema 74
vShieldEdgeSchemas 74
BasevShieldEdgeConfigurationSchema 74
vShieldEdgeInstallationSchema 74
vShieldEdgeGlobalConfigurationSchema 75
vShieldEdgeCLILoginCredentialsSchema 76

VMware, Inc. 6
vShieldEdgeFirewallSchema 77
NATSchema 79
DHCPSchema 81
VPNSchema 83
LoadBalancerSchema 86
MTUThresholdSchema 87
TrafficStatsSchema 87
SyslogSchema 88
ErrorMessageSchema 89
Index 91

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[e-mail].
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
8VMware, 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.
Using REST
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.

VMware, Inc. 11
Chapter 1 Overview of VMware vShield
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.
vShield API Conventions
ThevShieldAPIadherestothefollowingconventions:
AllvShieldAPIrequestsmustbesentthroughthevShieldManager.YoumustencrypteachHTTPrequest
intoHTTPSbeforesendingtherequesttothevShieldManager.
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).
Formostrequests,youmustknowthemanagedobjectID(MOID)ofavCenterobject.Eachsampleinthis
documentshowsthetherequiredMOIDasavariable.YoucangetanMOIDbyusingyourvCenter’s
ManagedObjectBrowser(https://vcenter‐ipaddress/mob).YoumusthavevCenterpermissionstoaccess
theMOB.
Table 1-1. Description of Managed Object IDs Required for vShield REST API Requests
Variable Description
base-node-moid Thebasenodecontainer,suchasadatacenter,onwhichyouwanttocreateor
manageaSecurityGroup.Forexample,datacenter-7.
container-moid Thedatacenter,cluster,orportgrouponwhichyouwanttoconfigurevShield
Appsettings.Forexample,datacenter-7ordomain-c14(cluster).
dvs-moid ThevDSonwhichyouwanttoenableordisablePortGroupIsolation.For
example,dvs-1069.
host-moid TheESXhostonwhichyouwanttoinstallvShieldservices.Forexample,
host-5450.
portgroup-moid Thenetwork—portgrouporvDSportgroup—onwhichyouwanttoinstall
orconfigureavShieldEdge.Forexample,network-25isaportgroupMOID,
anddvportgroup-25isavDSportgroupMOID.
vm-moid TheMOIDofavirtualmachine.

vShield API Programming Guide
12 VMware, Inc.
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.

VMware, Inc. 13
Chapter 1 Overview of VMware vShield
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

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:
“SynchronizethevShieldManagerwithvCenterServerandDNS”onpage 15
“RetrievingTechSupportLogs”onpage 16
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 67.
FortheDNSschema,see“DNSServiceSchema”onpage 68.
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
16 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/<portgroup-moid>/techSupportLogs

VMware, Inc. 17
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 17
“GettheInstallationStatusofvShieldServicesonanESXHost”onpage 19
“UninstallingvShieldServicesfromanESXHost”onpage 20
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
18 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 70.
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-moid>
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><ManagementPortS
witchId>network-4485</ManagementPortSwitchId><MgmtInterface><IpAddress>10.112.196.
245</IpAddress><NetworkMask>255.255.252.0</NetworkMask><DefaultGw>10.112.199.253</
DefaultGw></MgmtInterface></VszInstallParams><PortgroupIsolationInstallParams><Dat
astoreId>datastore-5035</DatastoreId></PortgroupIsolationInstallParams><EpsecInsta
llParams>true</EpsecInstallParams><InstallAction>install</InstallAction></VshieldC
onfiguration>
ESXhostpreparationrequiresthefollowingelements:
DatastoreId:vCenterMOIDofthedatastoreonwhichthevShieldAppandPortGroupIsolationservice
virtualmachinefileswillbestored.
ManagementPortSwitchId:vCenter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.
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. 19
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 53.
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 21.
vShieldEndpoint:Tocompleteinstallation,see“vShieldEndpointManagement”onpage 63.
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-moid>/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><ManagementPortS
witchId>network-5134</ManagementPortSwitchId><MgmtInterface><IpAddress>10.112.196.
245</IpAddress><NetworkMask>255.255.252.0</NetworkMask><DefaultGw>10.112.199.253</
DefaultGw></MgmtInterface></VszInstallParams><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-moid>

vShield API Programming Guide
20 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 65.
PortGroupIsolation:YoumustdisablePortGroupIsolationbeforeuninstallingtheservice.See“Disable
PortGroupIsolationonavDS”onpage 22.
Example 3-4. Uninstalling All Three vShield Services from an ESX Host
Request:
DELETE <vshield_manager-uri>/api/1.0/vshield/<host-moid>
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-moid>/<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-moid>/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-moid>/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 22.