VMware ESXI ESXI 6.5 User guide

vSphere SDK for Perl Programming

Guide

ESXi 6.5

vCenter Server 6.5

This document supports the version of each product listed and

supports all subsequent versions until the document is replaced

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

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

EN-002349-00

VMware, Inc.

3401 Hillview Ave.

Palo Alto, CA 94304

www.vmware.com

2 VMware, Inc.

vSphere SDK for Perl 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

IntendedAudience 7

1 GettingStartedwithvSphere SDK for Perl 9

vSphereSDKforPerlArchitecture 9

UsingvSphereSDKforPerl 10

GettingStarted 10

CommonvSphereSDKforPerlTasks 11

vSphereSDKforPerlProgrammingConventions 11

vSphereSDKforPerlCommonOptions 12

SpecifyingOptions 12

AuthenticatingThroughvCenterServerandvCenterSingleSign‐On 13

Example 13

UsingaSessionFile 13

PassingParametersattheCommandLine 14

SettingEnvironmentVariables 14

Usinga

ConfigurationFile 15

UsingMicrosoftWindowsSecuritySupportProviderInterface(SSPI) 15

CommonOptionsReference 16

HelloHost:RunningYourFirstScript 17

2 WritingvSphereSDKforPerlScripts 19

BasicvSphereSDKforPerlScript 19

Step1:ImportthevSphereSDKforPerlModules 20

Step2:(Optional)DefineScript‐SpecificCommand‐LineOptions 20

Step3:ConnecttotheServer 22

Step4:ObtainViewObjectsofServer‐SideManagedObjects 22

Step5:ProcessViewsandReportResults 22

Step6:ClosetheServerConnection 23

Understanding

Server‐SideObjects 24

UsetheManagedObjectBrowsertoExploreServer‐SideObjects 24

TypesofManagedObjectsandtheManagedObjectHierarchy 25

ManagedObjectHierarchy 26

ManagedEntitiesintheInventory 26

AccessingServer‐SideInventoryObjects 27

UnderstandingPerlViewObjects 28

WorkingwithViewObjectPropertyValues 28

AccessingPropertyValues 28

AccessingSimplePropertyValues 29

AccessingEnumerationPropertyValues 29

ModifyingPropertyValues 29

CreatingDataObjectswithProperties 30

UnderstandingOperationsandMethods 30

Non‐BlockingandBlockingMethods 30

ExamplesofOperations 31

CallingMethods 31

OmittingOptionalArgumentsinMethodCalls 31

vSphere SDK for Perl Programming Guide

4 VMware, Inc.

UpdatingViewObjects 32

3 RefiningvSphereSDKforPerlScripts 33

CreatingandUsingFilters 33

UsingFilterswithVim::find_entity_view()orVim::find_entity_views() 33

FilteringViewsSelectivelyUsingProperties 34

UsingViewSubroutineswithaPropertiesArgument 35

UsingFiltersontheUtilityApplicationCommandLine 35

RetrievingtheServiceInstanceObjectonavSphereHost 36

SavingandUsingSessions 36

SavingSessions 36

LoadingSessions 36

UsingMultipleSessions 37

LearningAboutObjectStructureUsingData::Dumper 38

Specifying

UntypedArgumentsinScheduledTasksandCallbacks 39

UsingAdvancedSubroutines 40

Opts::get_config() 40

4 vSphereSDKforPerlSubroutineReference 41

SubroutinesintheOptsPackage 42

add_options 42

get_option 42

option_is_set 43

parse 43

validate 43

usage 43

SubroutinesintheUtilPackage 43

connect 44

disconnect 44

get_inventory_path 44

trace 44

SubroutinesintheVimPackage 45

clear_session 45

find_entity_view 45

find_entity_views 46

get_service_instance 47

get_service_content 47

get_session_id 48

get_view 48

get_views 48

load_session 48

logout 49

save_session 49

update_view_data 50

A WebServicesforManagementPerlLibrary 51

WebServicesforManagementOverview 51

RequiredPerlModules 52

SampleScripts 53

SOAPMessageConstructionwithWSMan::WSBasic 53

WSMan::WSBasic‐>new 54

register_xml_ns 54

register_class_ns 55

Identify 55

VMware, Inc. 5

Contents

Enumerate 55

PullRelease 56

Get 56

WSMan::WSBasicExamples 56

GenericCIMOperationswithWSMan::GenericOps 57

WSMan::GenericOps‐>new 58

register_xml_ns 58

register_class_ns 58

Identify 59

EnumerateInstances 59

EnumerateInstanceNames 59

EnumerateAssociatedInstances 59

EnumerateAssociatedInstanceNames 60

EnumerateAssociationInstances 60

EnumerateAssociationInstanceNames 60

GetInstance 60

B CredentialStorePerlLibrary 61

CredentialStoreOverview 61

CredentialStoreComponents 62

ManagingtheCredentialStore 62

UsingtheCredentialStore 62

vSphereCredentialStoreSubroutineReference 63

init 63

get_password 63

add_password 64

remove_password 64

clear_passwords 64

get_hosts 64

get_usernames 64

close 65

credstore_admin.plUtilityApplication 65

Index 67

vSphere SDK for Perl Programming Guide

6 VMware, Inc.

VMware, Inc. 7

ThevSphereSDKforPerlProgrammingGuide,providesinformationaboutwritingandrunningVMware

®

vSphereSDKforPerlscriptsonESX/ESXiorvCenterServersystems.

BecauseSDKsubroutinesallowyoutomanagevSpherehostsusingvSphereAPIcalls,abriefdescriptionof

theserver‐sideobjectmodelisincluded.Thisguidefocusesonexplaininghowtoaccessandmodify

server‐sideobjectsusingthevSphere

SDKforPerlandondiscussingsomeprogrammingtechniques.

Intended Audience

ThisbookisintendedforadministratorswithdifferentlevelsofPerlscriptingexperience:

 AlladministratorscanusetheutilityapplicationsandsamplescriptsincludedwiththevSphereSDKfor

PerltomanageandmonitorthehostsinthevSphereenvironment.

 ExperiencedPerlprogrammerscanexaminethesourcecodefortheavailablescripts.Theycanthen

modifythosescriptsorwritenewscriptsusingthevSphereSDKforPerlsubroutinestoaccesstheobjects

onthevSpherehostandmanipulatethoseobjectsusingPerl.Thisdocumentincludesadiscussionofthe

vSphere

objectmodelandexplainshowyoucanpreviewandretrievetheobjectsandtheirattributesand

methods.

About This Book

IMPORTANTThisbookdiscussestheSDKforPerlthatallowsyoutoaccessvSpherebyusingthevSphereWeb

ServicesSDK,whichisavailableforallsupportedversionsofvSphere.ThisbookdoesnotdiscussPerl

bindingstovAPI,whichwasreleasedwithvSphere6.0forthefirsttime.

vSphere SDK for Perl Programming Guide

8 VMware, Inc.

VMware, Inc. 9

ThevSphereSDKforPerlletsyouautomateawidevarietyofadministrative,provisioning,andmonitoring

tasksinthevSphereenvironment.ThischapterintroducestheSDKarchitecture,explainsthebasicusemodel,

andgetsyoustartedrunningasimplescript.

Thechapterincludesthefollowingtopics:

 “vSphereSDKforPerlArchitecture”onpage 9

 “UsingvSphereSDKforPerl”onpage 10

 “vSphereSDKforPerlCommonOptions”onpage 12

 “HelloHost:RunningYourFirstScript”onpage 17

vSphere SDK for Perl Architecture

TheinteractionmodelbetweentheSDKandthevSphereAPIonthehostdirectlyaffectshoweachscriptis

structured,andisthebasisfortroubleshooting.

vSphereSDKforPerlsubroutinesinteractwiththehostandperformvariationsofthesebasictasks:

 Connecttoaremotehostusinguser‐suppliedconnectionparameters,anddisconnect.

 Findobjectsontheremotehost(server‐sideobjects).Forexample,findallvirtualmachinesonahost.

 Retrieveormodifyserver‐sideobjects,forexample,managethevirtualmachinelifecycle(start,stop,

suspend,andsoon).

 Collectinformationfromserver‐sideobjects.

 Managesessions.

MostroutinesretrieveavSphereAPIobjectandmakeitavailableasaPerlobject(calledaviewobject)that

youcanthenmanipulatewithyourscript.

ThevSphereSDKforPerlhasthesecomponents:

 vSphereSDKforPerlRuntime–Client‐sideruntimecomponentsthatinclude:

 AcompletePerlbindingofthevSphereAPI,whichmakesallserver‐sideoperationsanddata

structuresavailable.TheSDKhandlesthedatatypemappingbetweenserver‐sideandclient‐side

objectstransparently.

 VMwarePerlmodules(VIRuntime.pmandVILib.pm)thatprovidesubroutinesforbasic

functionality.

 vSphereSDKforPerlUtilityApplications–Managementapplicationsthatyoucanrunwithout

modificationinyourvirtualdatacenter.Youruneachapplicationwithconnectionparametersandother,

application‐specificparameters.SeethevSphereSDKforPerlUtilityApplicationsReference.

Getting Started with

vSphere SDK for Perl

vSphere SDK for Perl Programming Guide

10 VMware, Inc.

 SampleScripts–ScriptsthatyoucancustomizeforyourneedsandthatillustratethevSphereSDKfor

Perl’sfunctionality.YoumustknowPerltocustomizethescripts.Unliketheutilityapplications,sample

scriptsarenotsupportedbyVMware.

AvSphereSDKforPerlinstallationalsoincludesthefollowinglibraries:

 WebServicesforManagementPerlLibraryandExamples–TheWS‐ManagementPerlLibraryallows

youtowritescriptsthatretrieveCIMdatafromtheESXihostusingCIMOM,aservicethatprovides

standardCIMmanagementfunctionsoveraWBEM(Web‐BasedEnterpriseManagement).See“Web

ServicesforManagementPerlLibrary”

onpage 51.

 CredentialStoreLibraryandExamples–AllowsvSphereSDKforPerlapplicationstomanagethe

vSpherecredentialstore.ThecredentialstoreallowsvSphereSDKforPerlscriptstoauthenticate

themselvestoESX/ESXiorvCenterServersystems.See“CredentialStorePerlLibrary”onpage 61.

 vCLICommands‐SetofhostmanagementcommandsandasetofDCLIcommandsformanaging

vCenterservices.

Using vSphere SDK for Perl

ThissectionexplainshowtogetstartedwithvSphereSDKforPerlbylookingattwotypicalusagescenarios.

ItalsolistscommonvSphereSDKforPerltasksanddiscussesprogrammingconventions.

Getting Started

IfyouwanttousetheSDKtoretrieveperformanceinformationforahost,youmightperformthefollowing

tasks:

1CheckthevSphereSDKforPerlUtilityApplicationsReferenceortheappsdirectoryforascriptthatretrieves

performanceinformation.

Check/usr/lib/vmware-vcli/appsonLinuxand

Program Files\VMware vSphere CLI\Perl\apps



onWindows.Allutilityapplicationsarefullysupported.

Theviperformance.plscriptretrievesperformancecountersfromthehost.

2Runthescriptwiththe--helpoptionorwithoutanyoptionstoseeitsonlinedocumentation.More

detailedinformationisintheUtilityApplicationsReferenceincludedinthevSphereSDKforPerl

documentation

setandavailablefromtheVMwareWebsite.

3Runtheviperformance.plscriptagainstanESXihost.

viperformance.pl --url https://<host>:<port>/sdk/vimService --username nemo --password fi\$h

--host Aquarium --countertype net --interval 30 --samples 3

Escapecharactersmustprecedespecialcharactersinpasswords.SeeTable 1‐3,“OptionsAvailableforAll

SDKforPerlCommands,”onpage 16foracompletelistofconnectionparameters.

IfyouwanttousetheSDKforataskthatnoneoftheutilityapplicationscanperform,youmightperformthe

following

tasks:

1Checkthe/samplesfolderforasamplescriptthatperformsasimilartask.Thescriptsinthesamples

folderareavailableforcustomization.

2Ifascriptthatperformsasimilartaskisavailable,modifythescript.Ifnoneofthescriptsissuitable,write

anewscriptusingthe

vSphereSDKforPerlsubroutines.

Thefollowingmaterialsareavailableformodifyingorwritingscripts:

NOTEIfyoucannotfindautilityapplication,examinethesamplescripts.Youcanusesamplescriptsas

startingpointsforyourapplication.OnLinux,/usr/share/doc/vmware-vcli/samples,onWindows,

Program Files\VMware\VMware vSphere CLI\Perl\samples.Samplescriptsarenotsupported.

VMware, Inc. 11

Chapter 1 Getting Started with vSphere SDK for Perl

3FollowtheseprogrammingconventionswhenyoumodifyorcreatevSphereSDKforPerlscripts:

 Useparameternamesfollowedbyparametervalues,asfollows:

Vim::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );

Util::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );

Opts::<subroutine>(<parameter_name>=><value>, <parameter_name>=><value> );



UsetheoptionsinTable 1‐3,“OptionsAvailableforAllSDKforPerlCommands,”onpage 16to

specifyconnectioninformation.

 Usethemechanismdiscussedin“Step2:(Optional)DefineScript‐SpecificCommand‐LineOptions”

onpage 20forspecifyingadditionalscript‐specificoptions.

Common vSphere SDK for Perl Tasks

ThevSphereSDKforPerlincludesutilityapplicationsandsamplescriptsforcommonadministrationtasks.

Sometasksrequireadditionalscripting.SeeChapter 2,“WritingvSphereSDKforPerlScripts,”onpage 19.

vSphere SDK for Perl Programming Conventions

SeveralprogrammingconventionsaredifferentthanyoumightexpectbecausetheSDKinteractswithaserver

usingSOAP/WSDL.

 Booleandatatypes–SDKapplicationssendandreceiveBooleanvaluesasfollows:

 Input(sendingfromtheclientapplication):

Source Description

“WritingvSphereSDKforPerlScripts”on

page 19.

In‐depthdiscussionofscriptsthatincludesanexample.

Chapter 4,“vSphereSDKforPerl

SubroutineReference,”onpage 41.

ReferencetovSphereSDKforPerlsubroutines.

“WebServicesforManagementPerl

Library”onpage 51.

AllowsyoutowritescriptsthatretrieveCIMdatafromthe

ESX/ESXihostusingCIMOM,aservicethatprovidesstandardCIM

managementfunctionsoveraWBEM(Web‐BasedEnterprise

Management).

“CredentialStorePerlLibrary”onpage 61. AllowsvSphereSDKforPerlapplicationstomanagethevSphere

credentialstore.

vSphereAPIReferencedocumentation. Referencetotheserver‐sideobjectyourscriptinteractswith.

Table 1-1. Common Administrative Tasks and SDK Utilities

Task Script Location

Discovery(loggingin) connect.pl /apps/general

Performancemonitoring viperformance.pl(retrieves

performancecountersfromhost)

/apps/performance

Virtualmachinepoweroperations vmcontrol.pl /apps/vm

Virtualmachinesnapshotandrestorefunctionality vmsnapshot.pl,snapshotmanager.pl /apps/vm

Virtualmachinemigration vmmigrate.pl /apps/vm

Hostoperations,forexample,addingastandalone

hosttoavCenterServersystem,shuttingdownand

rebootingahost,andsoon

hostops.pl /apps/host

Viewingorchanging

ofCPUormemoryshare

allocationonavirtualmachine

sharesmanager.pl /apps/vm

vSphere SDK for Perl Programming Guide

12 VMware, Inc.

 Output(receivingfromtheserver):

TomatchBooleanvaluesinafilter,usethestringstrueandfalse.See“CreatingandUsingFilters”on

page 33.

 Date/Time–TheserverreturnsaSOAPdateTimevalue.YoucanusetheDate::ParsePerlmoduleto

processtheseobjects.

ThevSphereSDKforPerlacceptsonlynativeSOAPdateTimevaluesusingstandarddatetimeformat

withorwithoutfractionalseconds,andwithorwithoutGMT(Z)timezone:

YYYY-MM-DDThh:mm:ssTZD,

forexample,1997-07-16T19:20:30+01:00

YYYY-MM-DDThh:mm:ss.sTZD,forexample,1997-07-16T19:20:30.45+01:00

TheSDKalwaysreturnsdateTimevaluesinthestandarddatetimeformat.

 SOAPerrormessage–Mostlikelyindicatesanerrorontheserver,notanerrorwiththecommunication

totheserver.

vSphere SDK for Perl Common Options

AnumberofoptionsareavailableforanyvSphereSDKforPerlscript.Mostoftheseoptionsallowyouto

specifythehostorhoststoconnectto.Mostoptionsrequireanoptionvalue.

perl <app_name>.pl --<option_name> <option_value>

Forexample,topoweronavirtualmachineusingthevmcontrol.plutilityapplication,youmustspecifythe

nameofthevirtualmachinetopoweron,asfollows:

perl vmcontrol.pl --server <myserver> --username <admin> --password <mypassword> --operation

poweron --vmname <virtual_machine_name>

Runanyapplicationorsamplewithoutanyoptionsorwith--helptoseeitsparametersandexecution

examples.Informationaboutcommonandscript‐specificoptionsisincluded.

Specifying Options

Youcanspecifythecommonoptionsinseveralways,discussedinthissection.

WhenyourunavSphereCLIcommand,authenticationhappensinthefollowingorderofprecedence:

false: Use0,ʹ0ʹ,orʹfalseʹ(capitalizationignored)

true: Use1,ʹ1ʹ,orʹtrueʹ(capitalizationignored)

false: Returnvalueis0

true: Returnvalueis1

MPORTANTIfthehostyouaretargetingisinlockdownmode,youcannotexecutePerlscriptsagainstthe

host.

Table 1-2. vSphere CLI Authentication Precedence

Authentication Description See

TargetingvCenter

ServerandUsing

vCenterSingle

Sign‐On

Ifyouareworkinginanenvironmentthatis

managedbyvCenterSingleSign‐On,youcan

specifythevCenterSingleSign‐Onserverand

ausername,password,andtargethost.

“UsingaSessionFile”onpage 13

Commandline Password(--password),

sessionfile

(--sessionfile),orconfigurationfile

(--config) specifiedonthecommandline.

“UsingaSessionFile”onpage 13

Configurationfile Passwordsspecifiedina.visdkrc

configurationfile.

“UsingaConfigurationFile”onpage 15

VMware, Inc. 13

Chapter 1 Getting Started with vSphere SDK for Perl

Thisorderofprecedencealwaysapplies.Thatmeans,forexample,thatyoucannotoverrideanenvironment

variablesettinginaconfigurationfile.

Authenticating Through vCenter Server and vCenter Single Sign-On

ForallESXihoststhat aremanagedbyavCenterServersystemthatisintegratedwithvCenterSingleSign‐On

6.0andlater,youcanauthenticatedirectlytothevCenterServersystem,oryoucanauthorizetovCenter

ServerthroughvCenterSingleSign‐On.

BestpracticeistoauthenticatethroughvCenter

SingleSign‐On.ThevCenterSingleSign‐Onserviceis

includedinthePlatformServicesController.ThePlatformServicesControllercanbeembeddedinyour

vCenterServerinstallation,oronePlatformServicesControllercanhandleauthentication,certificate

management,andsomeothertasksformultiplevCenterServersystems.

Youusethe

--pscoptionand,optionally,the--server option.

 psc‐SpecifiesthePlatformServicesControllerinstanceassociatedwiththevCenterServersystemthat

managesthehost.

 server‐SpecifiesthevCenterServersystemthatmanagesthehost.RequiredifthePlatformServices

ControllerinstanceisassociatedwithmorethanonevCenterServersystem.

 vihost‐SpecifiestheESXihost,asinearlierversionsofvCLI.

Example

vminfo.pl --server <vc_HOSTNAME_OR_IP> --psc <psc_HOSTNAME_OR_IP> --vihost

<esxi_HOSTNAME_OR_IP>--username root --password vmware --vihost <esxi_host>

IfthespecifieduserisknowntovCenterSingleSign‐On,asessioniscreated.Youcansavethesessionwiththe

--savesessionfileargument,andlaterusethatsessionwiththe--sessionfile argument.

UsingasessionfileresultsinlessoverheadandbetterperformancethanconnectingtothePlatformServices

Controller

repeatedly.

Using a Session File

Thesave_session.plscriptintheapps/sessiondirectoryillustrateshowtocreateasessionfile.Youcan

modifythescriptandincludeitinyourownapplication,orcreateasessionfileusingthescriptonthe

commandline,andthenpassinthatsessionfilewhenrunningvSphereSDKforPerl

commands.See“Saving

Sessions”onpage 36.

Thesessionfiledoesnotrevealpasswordinformation.Ifasessionfileisnotusedfor30minutes,thesession

expires.

To create and use a session file

1 Connecttothedirectorywherethescriptislocated,forexample,onWindows:

cd C:\Program Files\VMware\VMware vSphere CLI\Perl\apps\session

Environment

variable

Passwordspecifiedinanenvironment

variable.

“SettingEnvironmentVariables”onpage 14

Credentialstore Passwordretrievedfromthecredentialstore. “CredentialStorePerlLibrary”onpage 61

Currentaccount

(ActiveDirectory)

Currentaccountinformationus edtoestablish

anSSPIconnection.Windowsonly.

.“UsingMicrosoftWindowsSecuritySupport

ProviderInterface(SSPI)”onpage 15



Prompttheuserfora

password.

NOTEYoucannotusethisapproachifvCenterServerisintegratedwithvCenterSingleSign‐On5.0.

Table 1-2. vSphere CLI Authentication Precedence (Continued)

Authentication Description See

vSphere SDK for Perl Programming Guide

14 VMware, Inc.

2Runsave_session.pl.Youmustsupplyconnectionparametersandthenameofasessionfileinwhich

thescriptcansaveanauthenticationcookie.

perl save_session.pl --savesessionfile <location> --server <esxi_host>

Forexample:

perl save_session.pl --savesessionfile C:\Temp\my_session --server my_server

Ifyouspecifyaserverbutnousernameorpassword,thescriptpromptsyou.

3Youcannowrunscriptsinthe\appsor\samplesdirectoryoryourownscriptsandpassinthesession

fileusingthe--sessionfileparameterasfollows:

<command> --sessionfile <sessionfile_location> <command_options>

Forexample:

perl hostinfo.pl --sessionfile C:\Temp\my_session

Youcanusethecodeinthe\apps\session\save_session.plutilityapplicationinsideyourownvSphere

SDKforPerlapplication.Ifacalltotheserverthrowsanexception,yourapplicationshouldterminatethe

sessiontoavoidsessionleaks.Youcoulddothiswithanerrorhandlerthatrunsdisconnect()orlogout(),

forexample:

eval {

# ... insert program here ...

};

if ($@) {

print "Fatal error: $@";

Util::disconnect();

exit(1);

}

Youcanalsousethe_END_pseudo‐signalhandlertoperformadisconnect,asfollows:

$SIG{__END__} = sub { Util::disconnect(); }

Passing Parameters at the Command Line

Passparametersatthecommandlineusingoptionnameandoptionvaluepairs(someoptionshavenovalue).

--<optionname> <optionvalue>

Thefollowingexampleconnectstotheserverasusersnow-whitewithpassworddwarf$.Thefirstexample

(Linux)usesanescapecharacterbeforeeachspecialcharacter,theotherexamplesusesinglequotes(Linux)

anddoublequotes(Windows).

Linux

vminfo.pl --server <server> --username snow\-white --password dwarf\$ --vmname <name>

vminfo.pl --server <server> --username ‘snow-white’ --password ‘dwarf$’ --vmname <name>

Windows

vminfo.pl --server <server> --username “snow-white” --password “dwarf$” --vmname <name>

Setting Environment Variables

YoucansetenvironmentvariablesinaLinuxprofile,intheEnvironmentpropertiesdialogboxofthe

MicrosoftWindowsSystemcontrolpanel,or,forthecurrentsession,atthecommandline.Environment

variablesarelistedwhenyourunacommandwith--help.

Thefollowingexampleshowsthecontentsofa

/root/.visdkrc filethatusesenvironmentvariables:

VI_SERVER = <server>

VI_USERNAME = <usr>

VI_PASSWORD = <root_password>

NOTEIfyouuseasessionfile,anyotherconnectionparametersareignored.

VMware, Inc. 15

Chapter 1 Getting Started with vSphere SDK for Perl

VI_PROTOCOL = https

VI_PORTNUMBER = 443

Donotescapespecialcharactersinthefilethatspecifiesenvironmentvariables.

Ifyouhavesetupyoursystemtorunthisfile,youcanrunscriptsonthespecifiedserverafterwards.

Using a Configuration File

Aconfigurationfileisatextfilethatcontainsvariablenamesandsettings.Variablescorrespondingtothe

connectionoptionsareshowninTable 1‐3,“OptionsAvailableforAllSDKforPerlCommands,”onpage 16.

Use--configiftheconfigurationinformationissavedinadifferentfilethan./visdkrc.Ifyou

specify

--config,thesystemignoresthe./visdkrcsettings.

Youcanusethe--configoptiontorunascriptwiththeconfigurationfile,forexample:

connect.pl --config <my_saved_config> --list

Usingaconfigurationfileisusefulforrepeatedlyenteringconnectiondetails.Ifyouhavemultiple

vCenter ServerorESX/ESXisystemsandyouadministereachsystemindividually,youcancreatemultiple

configurationfileswithdifferentnames.Whenyouwanttorunacommandorasetofcommandsonaserver,

youpass

inthe--configoptionwiththeappropriatefilenameatthecommandline.

Using Microsoft Windows Security Support Provider Interface (SSPI)

Youcanusethe--passthroughauthcommand‐lineargumenttologintoavCenterServersystem(vCenter

Serverversion2.5Update2orlater).Using--passthroughauthpassesthecredentialsoftheexecutinguser

totheserver.Iftheexecutinguserisknownbyboththemachinefromwhichyouaccessthe

vCenterServer

systemandthemachinerunningthevCenterServersystem,noadditionalauthenticationisrequired.

IfSDKcommandsandthevCenterServersystemrunonthesamemachine,alocalaccountfortheexecuting

userworks.Iftheyrunondifferentmachines,thentheexecutingusermusthavean

accountinadomain

trustedbybothmachines.

SSPIsupportsanumberofprotocols.Bydefault,itselectstheNegotiateprotocol,whichindicatesthatclient

andserverattempttofindamutuallysupportedprotocol.Alternatively,youcanuse

--passthroughauthpackagetospecifyanotherprotocolsupportedbySSPI.Kerberos,theWindows

standardfor

domain‐levelauthentication,iscommonlychosen.

IfthevCenterServersystemisconfiguredtoacceptonlyaspecificprotocol,specifyingtheprotocoltovSphere

SDKforPerlcommandswith --passthroughauthpackagemightberequiredforsuccessfulauthentication

totheserver.Ifyouuse--passthroughauth,youdonothavetospecifyauthentication

informationinany

otherway.Forexample,torunconnect.plontheserver,youcanusethefollowingcommandatthe

commandline.

<command> <login_params> --passthroughauth

SeetheMicrosoftWebsiteforadetaileddiscussionofSSPI.

ThefollowingexampleconnectstoaserverthathasbeensetuptouseSSPI.Whenyourunthecommand,the

systemcallsvminfo.plwiththe--vmnameoption.Thesystemdoesnotpromptforausernameandpassword

because

thecurrentuserisknowntotheserver.

vminfo.pl --server <vc_server> --passthroughauth --passthroughauthpackage “Kerberos”

--vihost my_esx --vmname <name>

CAUTIONLimitreadaccesstoaconfigurationfile,especiallyifitcontainsusercredentials.

NOTEUsingSSPIissupportedonlywhenyouruncommandsfromWindows,anduseavCenterServer

systemasthetargetserver.

vSphere SDK for Perl Programming Guide

16 VMware, Inc.

Common Options Reference

ThefollowingtablelistsoptionsthatareavailableforallvSphereSDKforPerlscripts.Usetheparameteron

thecommandlineandthevariableortheparameterinconfigurationfiles.

Table 1-3. Options Available for All SDK for Perl Commands

Option and Environment Variable Description

--cacertsfile <certsfile>

-t <certs_file>

VI_CACERTFILE=<cert_file_path>

ESXCLIcommandsonly.

UsedtospecifytheCA(CertificateAuthority)certificatefile,inPEMformat,

toverifytheidentityofthevCenterServersystemorESXisystemtorunthe

commandon.

InvCLI6.0andlater,youcanonlyrunESXCLIcommandsifatrust

relationshipexistsbetween

thehostyouarerunningthecommandonandthe

systemyouaretargetingwiththe--serveroption(ESXihostorvCenter

Serversystem).YoucanestablishthetrustrelationshipbyspecifyingtheCA

certificatefileorbypassinginthethumbprintforeachtargetserver(ESXihost

orvCenterServer

system).

--config <cfg_file_full_path>

VI_CONFIG=<cfg_file_full_path>

Usestheconfigurationfileatthespecified location.

Specifyapaththatisreadablefromthecurrentdirectory.

--credstore <credstore>

VI_CREDSTORE=<credstore>

Nameofacredentialstorefile.Defaultsto

<HOME>/.vmware/credstore/vicredentials.xmlonLinuxand

<APPDATA>/VMware/credstore/vicredentials.xmlonWindows.

CommandsforsettingupthecredentialstoreareincludedinthevSphereSDK

for

Perl,whichisinstalledwithvCLI.ThevSphereSDKforPerlProgramming

Guideexplainshowtomanagethecredentialstore.

--encoding <encoding>

VI_ENCODING=<encoding>

Specifiestheencodingtobeused.Severalencodingsaresupported.

 utf8

 cp936(SimplifiedChinese)

 shftjis(Japanese)

 iso-885901(German).

Youcanuse--encodingtospecifytheencodingvCLIshouldmaptowhenit

isrunonaforeignlanguagesystem.

--passthroughauth

VI_PASSTHROUGHAUTH

Ifyouspecifythisoption,thesystemusestheMicrosoftWindowsSecurity

SupportProviderInterface(SSPI)forauthentication.Trustedusersarenot

promptedforausernameand

password.SeetheMicrosoftWebsitefora

detaileddiscussionofSSPI.

ThisoptionissupportedonlyifyouareconnectingtoavCenterServersystem.

--passthroughauthpackage

VI_PASSTHROUGHAUTHPACKAGE=

Usethisoptionwith--passthroughauthtospecifyadomain‐level

authenticationprotocoltobeusedbyWindows.Bydefault,SSPIusesthe

Negotiate

protocol,whichmeansthatclientandservertrytonegotiatea

protocolthatbothsupport.

IfthevCenterServersystemtowhichyouareconnectingisconfiguredtouse

aspecificprotocol,youcanspecifythatprotocolusingthisoption.

ThisoptionissupportedonlyifyouarerunningvCLIon

aWindowssystem

andconnectingtoavCenterServersystem.

--password <passwd>

VI_PASSWORD=<passwd>

Usesthespecifiedpassword(usedwith--username)tologintotheserver.

 If--serverspecifiesavCenterServersystem,theusernameandpassword

applytothatserver.IfyoucanlogintothevCenterServersystem,you

neednoadditionalauthenticationtoruncommandsontheESXihoststhat

servermanages.

 If--serverspecifiesanESXihost,theusernameandpasswordapplyto

thatserver.

Usetheemptystring(' 'onLinuxand“ “onWindows)toindicateno

password.

Ifyoudonotspecifyausernameandpasswordonthecommandline,the

systempromptsyouanddoes

notechoyourinputtothescreen.

--portnumber <number>

VI_PORTNUMBER=<number>

Usesthespecifiedporttoconnecttothesystemspecifiedby--server.Default

is443.

VMware, Inc. 17

Chapter 1 Getting Started with vSphere SDK for Perl

Hello Host: Running Your First Script

Beforeyourunyourfirstscript,youneedthefollowing:

 SuccessfulvSphereSDKforPerlinstallation.SeethevSphereSDKforPerlInstallationGuideforinformation.

 AccesstooneofthesupportedvSpherehosts.Performaconnectioncheckusingtheprocessdescribedin

“UsetheManagedObjectBrowsertoExploreServer‐SideObjects”onpage 24.

To run the connect.pl script

1Atacommandprompt,changetothe/apps/generaldirectory.

C:\Program Files\VMware\VMware vSphere CLI\Perl\apps\general

--protocol <HTTP|HTTPS>

VI_PROTOCOL=<HTTP|HTTPS>

Usesthespecifiedprotocoltoconnecttothesystemspecifiedby--server.

DefaultisHTTPS.

--psc <hostname_or_IP>

VI_PSC=<hostname_or_IP>

HostnameorIPaddressofthePlatformServicesControllerinstancethatis

associatedwiththevCenterServersystemthatmanagesthehost.Inmany

cases,thePlatformServicesControllerisembeddedin

thevCenterServer

system,butexternalPlatformServicesControllerinstancesaresupportedas

well.Forthosecases,usethe--serveroptiontospecifythevCenterServer

systemthatmanagesthehost.

Thisoptionimpliesus erauthenticationwithvCenterSingleSign‐On.Theuser

youspecifymustbeabletoauthenticateto

vCenterSingleSign‐On.

--savesessionfile <file>

VI_SAVESESSIONFILE=<file>

Savesasessiontothespecifiedfile.Thesessionexpiresifithasbeenunused

for30minutes.

--server <server>

VI_SERVER=<server>

UsesthespecifiedESXiorvCenterServersystem.Defaultislocalhost.

If--serverpointstoavCenterServersystem,youcanalsospecifythe--psc

option

tologintothevCenterServersystemwithvCenterSingleSign‐On.

Usethe--vihostoptiontospecifytheESXihostthatyouwanttorunthe

commandagainst.See“AuthenticatingThroughvCenterServerandvCenter

SingleSign‐On”onpage 13.

--servicepath <path>

VI_SERVICEPATH=<path>

Usesthespecifiedservicepathtoconnectto

theESXihost.Defaultis

/sdk/webService.

--sessionfile <file>

VI_SESSIONFILE=<file>

Usesthespecifiedsessionfiletoloadapreviouslysavedsession.Thesession

mustbeunexpired.

--thumbprint <thumbprint>

VI_THUMBPRINT=<thumbprint>

ExpectedSHA‐1hostcertificatethumbprintifnoCAcertificatesfileis

providedinthe--cacertsfile argument.Thethumbprintisreturnedbythe

serverintheerrormessage

ifyouattempttorunacommandwithout

specifyingathumbprintorcertificatefile.

--url <url>

VI_URL=<url>

ConnectstothespecifiedvSphereWebServicesSDKURL.

--username <u_name>

VI_USERNAME=<u_name>

Usesthespecifiedusername.

 If--serverspecifiesavCenterServersystem,theusernameand

passwordapplytothatserver.IfyoucanlogintothevCenterServer

system,youneednoadditionalauthenticationtoruncommandsonthe

ESXihoststhatservermanages.

 If--serverspecifiesanESXisystem,theusernameandpasswordapply

tothatsystem.

Ifyoudonotspecifyausernameandpasswordonthecommandline,the

systempromptsyouanddoesnotechoyourinputtothescreen.

--vihost <host>

-h <host>

WhenyourunavCLIcommandwiththe

--serveroptionpointingtoa

vCenterServersystem,use--vihosttospecifytheESXihosttorunthe

commandagainst.

OTE:Thisoptionisnotsupportedforeachcommand.Ifsupported,the

optionisincludedwhenyourun<cmd> --help.

Table 1-3. Options Available for All SDK for Perl Commands

Option and Environment Variable Description

vSphere SDK for Perl Programming Guide

18 VMware, Inc.

/usr/lib/vmware-vcli/apps

2Runconnect.plasfollows:

connect.pl --url https://<host>:<port>/sdk/vimService --username myuser --password mypassword

Thescriptreturnsaninformationmessageandthehosttime.

Youarenowreadytorunotherscripts,orcreatenewscripts.

OTEYoucanrunanyutilityapplicationwith--helptodisplayinformationaboutitsparameters.

VMware, Inc. 19

ThischapterusesasimpleexamplescripttoillustratehowtowriteavSphereSDKforPerlscript.Thechapter

alsoexploresthebasicsofthevSphereAPIobjectmodel.

Thechapterincludesthesetopics:

 “BasicvSphereSDKforPerlScript”onpage 19

 “UnderstandingServer‐SideObjects”onpage 24

 “UnderstandingPerlViewObjects”onpage 28

 “WorkingwithViewObjectPropertyValues”onpage 28

 “UnderstandingOperationsandMethods”onpage 30

 “UpdatingViewObjects”onpage 32

Basic vSphere SDK for Perl Script

vSphereSDKforPerlscriptsretrieveobjects,suchasvirtualmachines,fromtheserverandworkwiththese

objects.vSphereSDKforPerlscriptsfollowthebasicpatternshowninTable 2‐1.

Writing vSphere SDK for Perl Scripts

NOTEThischapterdoesnotdiscussPerlbasics.YouareexpectedtoknowPerlandtounderstandits

programmingconventions.WhenyoudevelopavSphereSDKforPerlscript,followPerlstandardsfor

filenames,imports,andgeneralprocessingflow.Usetheappropriatefilenameextensionforthetypeofscript

orapplication

youarecreating(.plonWindowsand.plornosuffixonUNIX‐likesystems).

IMPORTANTThesamplescriptdoesnotusefiltersorpropertyfiltersforefficiency.See“RefiningvSphereSDK

forPerlScripts”onpage 33forinformationaboutthosetopics.

Table 2-1. Basic vSphere SDK for Perl Script (simpleclient.pl)

Code element Discussed in

#!/usr/bin/perl

use strict;

use warnings;

use VMware::VIRuntime;

“Step1:ImportthevSphereSDKforPerl

Modules”onpage 20.

vSphere SDK for Perl Programming Guide

20 VMware, Inc.

Step 1: Import the vSphere SDK for Perl Modules

AllvSphereSDKforPerlscriptsmustusetheVMware::VIRuntimemodule:

use VMware::VIRuntime;

Thismodulehandlesallclient‐sideinfrastructuredetails.Forexample,ittransparentlymapsdatatypesand

provideslocalPerlinterfacestoserver‐sideobjects.Themodulealsoloadssubroutinesthatyoucanuseto

connecttoavCenterServerorESX/ESXisystemandtoretrieveviews.Viewsaretheclient‐side

Perlobjects

thatencapsulatethepropertiesandoperationsofserver‐sidemanagedobjects.Thesubroutinesareorganized

intodifferentpackages:

 TheOptspackagesubroutineshandlebuilt‐inoptionsandcreatingcustomoptions.

 TheUtilpackagesubroutinesfacilitateroutinetasks,suchassettingupandclosingconnectionstothe

server.

 TheVimpackagesubroutinesaccessserver‐sidemanagedobjects,instantiatelocalproxyobjects(views),

updateproperties,andrunlocalmethodsthatresultinoperationsonremoteservers.

See“vSphereSDKforPerlSubroutineReference”onpage 41.

Step 2: (Optional) Define Script-Specific Command-Line Options

Whenyourunascriptfromthecommandline,youusuallyspecifyconnectioninformationandmightalso

specifyotherinformationsuchasavirtualmachinethatyouwanttopowerofforahostforwhichyouneed

statusinformation.vSphereSDKforPerlletsyouspecifytheseoptionsina

varietyofways.See“Specifying

Options”onpage 12.

Anumberofcommoncommand‐lineoptions,mostofthemconnectionoptions,arealreadydefinedforall

utilityapplications(seeTable 1‐3,“OptionsAvailableforAllSDKforPerlCommands,”onpage 16).In

addition,mostapplicationshaveapplication‐specificoptionsyoupass

tothescriptatexecutiontime.

my %opts = (

entity => {

type => "=s",

variable => "VI_ENTITY",

help => "ManagedEntity type: HostSystem, etc",

required => 1,

);

Opts::add_options(%opts);

Opts::parse();

Opts::validate();

“Step2:(Optional)DefineScript‐Specific

Command‐LineOptions”onpage 20.

Util::connect();

“Step3:ConnecttotheServer”onpage 22.

# Obtain all inventory objects of the specified type

my $entity_type = Opts::get_option('entity');

my $entity_views = Vim::find_entity_views(

view_type => $entity_type);

“Step4:ObtainViewObjectsofServer‐Side

ManagedObjects”onpage 22.

# Process the findings and output to the console

foreach my $entity_view (@$entity_views) {

my $entity_name = $entity_view->name;

Util::trace(0, "Found $entity_type:

$entity_name\n");

}

“Step5:ProcessViewsandReportResults”

onpage 22.

# Disconnect from the server

Util::disconnect();

“Step6:ClosetheServerConnection”on

page 23.

Table 2-1. Basic vSphere SDK for Perl Script (simpleclient.pl) (Continued)

Code element Discussed in

Page is loading ...

VMware ESXI ESXI 6.5, vCenter Server 6.5 User guide

Related papers

Other documents