Getting Started with vSphere

Command-Line Interfaces
ESXi 5.0
vCenter Server 5.0

This document supports the version of each product listed and

supports all subsequent versions until the document is replaced
by a new edition. To check for more recent editions of this
document, see http://www.vmware.com/support/pubs.

EN-000488-00

Getting Started with vSphere Command-Line Interfaces

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

Copyright 2010, 2011 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.
3401 Hillview Ave.
Palo Alto, CA 94304
www.vmware.com

VMware, Inc.

Contents

AboutThisBook

1 ManagingvSpherewithCommandLineInterfaces 7
OverviewofvSphereCommandLineInterfaces 7
UsingthevSphereCommandLineInterface 8
UsingESXCLI 8
ESXCLISyntax 9
RunningESXCLIvCLICommands 9
RunningESXCLIvCLICommandsAgainstESXi4.xHosts 9
RunningESXCLICommandsintheESXiShell 9
ESXiShellAccesswiththeDirectConsole 10
EnablingLocalESXiShellAccess 10
UsingtheLocalESXiShell 11
RemoteESXiShellAccesswithSSH 11
EnablingSSHfortheESXiShell 11
UsingtheESXiShellwithSSH 12

2 InstallingvCLI 13
InstallationOverview 13
InstallingandUninstallingvCLIonLinux 14
InstallationPrerequisites 14
InstallationProcess 14
InstallingRequiredPrerequisiteSoftwareforYourLinuxPlatform 16
InstallingthevCLIPackage 16
UninstallingthevCLIPackageonLinux 17
InstallingandUninstallingvCLIonWindows 17
RunningCommandsonWindows 18
UninstallingthevCLIPackageonWindows 18
EnablingCertificateVerification 19
DeployingvMA 19

3 UsingthevSphereCommandLineInterface 21
OverviewofRunningCommands 21
SpecifyingAuthenticationInformation 22
OrderofPrecedenceforvCLIAuthentication 22
UsingaSessionFile 22
UsingEnvironmentVariables 23
UsingaConfigurationFile 23
UsingCommandLineOptions 24
UsingMicrosoftWindowsSecuritySupportProviderInterface 25
vCLIandLockdownMode 25
CommonOptionsforvCLIExecution 25
UsingvCLICommandsinScripts 27

ESXCLICommandHierarchies 29
esxcliesxcliNamespace 29
esxclifcoeNamespace 29

VMware, Inc.

Getting Started with vSphere Command-Line Interfaces

esxclihardwareNamespace 30
esxcliiscsiNamespace 30
esxclilicenseNamespace 30
esxclinetworkNamespace 31
esxclisoftwareNamespace 31
esxclistorageNamespace 32
esxclisystemNamespace 33
esxclivmNamespace 33

VMware, Inc.

About This Book

GettingStartedwithvSphereCommandLineInterfacesgivesanoverviewofcommandlineinterfacesin
vSphere 5.0andgetsyoustartedwithESXiShellcommandsandvCLI(VMwarevSphereCommandLine
Interface)commands.ThisbookalsoincludesinstructionsforinstallingvCLIandareferencetoconnection
parameters.

Intended Audience
ThisbookisforexperiencedWindowsorLinuxsystemadministratorswhoarefamiliarwithvSphere
administrationtasksanddatacenteroperations.

VMware Technical Publications Glossary

VMwareTechnicalPublicationsprovidesaglossaryoftermsthatmightbeunfamiliartoyou.Fordefinitions
oftermsastheyareusedinVMwaretechnicaldocumentation,gotohttp://www.vmware.com/support/pubs.

Document Feedback
VMwarewelcomesyoursuggestionsforimprovingourdocumentation.Ifyouhavecomments,sendyour
feedbacktodocfeedback@vmware.com.

Related Documentation
ThedocumentationforvCLIisavailableinthevSphereDocumentationCenterandonthevCLI
documentationpage.Gotohttp://www.vmware.com/support/pubs,selectVMwareAdministration
Products,andselectvSphereCommandLineInterface.

CommandLineManagementinvSphere5.0forServiceConsoleUsersisatechnicalnoteforuserswhoare
currentlyusingESXserviceconsolecommands,scripts,agents,orlogs.Youlearnhowtotransitiontoan
offhostimplementationortousetheESXiShellinspecialcases.

vSphereCommandLineInterfaceConceptsandExamplespresentsusageexamplesformanycommands,such
assettingupsoftwareandhardwareiSCSI,addingvirtualswitches,settingupActiveDirectory
authentication,andsoon.Thedocumentincludesthesameexamplewiththevicfg-commandandthe
ESXCLIcommandwheresupported.

vSphereCommandLineInterfaceReferenceisareferencetobothvicfg-commandsandESXCLIcommands.
Thevicfg-commandhelpisgeneratedfromthePODavailableforeachcommand,runpod2htmlfor
anyvicfg-commandtogenerateindividualHTMLfilesinteractively.TheESXCLIreferenceinformation
isgeneratedfromtheESXCLIhelp.

ThedocumentationforPowerCLIisavailableinthevSphereDocumentationCenterandonthePowerCLI
documentationpage.Gotohttp://www.vmware.com/support/pubs,selectVMwareAdministration
Products,andselectvSpherePowerCLIdocumentation.

VMware, Inc.

Getting Started with vSphere Command-Line Interfaces

ThevSphereSDKforPerldocumentationexplainshowyoucanusethevSphereSDKforPerlandrelated
utilityapplicationstomanageyourvSphereenvironment.Thedocumentationincludesinformationaboutthe
vSphereSDKforPerlUtilityApplications.
ThevSphereManagementAssistantGuideexplainshowtoinstallandusethevSphereManagementAssistant
(vMA).vMAisavirtualmachinethatincludesvCLIandotherprepackagedsoftware.SeeDeployingvMA
onpage 19.
BackgroundinformationforthetasksdiscussedinthisbookisavailableinthevSpheredocumentationset.The
vSpheredocumentationconsistsofthecombinedVMwarevCenterServerandESXidocumentation.

Technical Support and Education Resources

Thefollowingsectionsdescribethetechnicalsupportresourcesavailabletoyou.Toaccessthecurrentversion
ofthisbookandotherbooks,gotohttp://www.vmware.com/support/pubs.

Online and Telephone Support

Touseonlinesupporttosubmittechnicalsupportrequests,viewyourproductandcontractinformation,and
registeryourproducts,gotohttp://www.vmware.com/support.
Customerswithappropriatesupportcontractsshouldusetelephonesupportforthefastestresponseon
priority1issues.Gotohttp://www.vmware.com/support/phone_support.

Support Offerings
TofindouthowVMwaresupportofferingscanhelpmeetyourbusinessneeds,goto
http://www.vmware.com/support/services.

VMware Professional Services

VMwareEducationServicescoursesofferextensivehandsonlabs,casestudyexamples,andcoursematerials
designedtobeusedasonthejobreferencetools.Coursesareavailableonsite,intheclassroom,andlive
online.Foronsitepilotprograms andimplementationbestpractices,VMwareConsultingServicesprovides
offeringsto helpyouassess,plan,build,andmanageyourvirtualenvironment.Toaccessinformationabout
educationclasses,certificationprograms,andconsultingservices,gotohttp://www.vmware.com/services.

VMware, Inc.

Managing vSphere with

Command-Line Interfaces

vSpheresupportsseveralcommandlineinterfacesformanagingyourvirtualinfrastructureincludingthe
vSphereCommandLineInterface(vCLI),asetofESXiShellcommands,andPowerCLI.Youcanchoosethe
CLIsetbestsuitedforyourneeds,andwritescriptstoautomateyourCLItasks.
Thischapterincludesthefollowingtopics:

OverviewofvSphereCommandLineInterfacesonpage 7

UsingthevSphereCommandLineInterfaceonpage 8

UsingESXCLIonpage 8

ESXiShellAccesswiththeDirectConsoleonpage 10

RemoteESXiShellAccesswithSSHonpage 11

Overview of vSphere Command-Line Interfaces

vSphereincludescommandsformanagingdifferentaspectsofyourenvironment,eitherlocallyorremotely.
Command set

Description

ESXCLIcommands

ManagemanyaspectsofanESXihost.YoucanrunESXCLI
commandsremotelyorintheESXiShell.

vCLIpackage.InstallthevCLIpackageontheserverofyour
choice,ordeployavMAvirtualmachineandtargettheESXi
systemthatyouwantmanipulate.YoucanrunESXCLI
commandsagainstavCenterServersystemandtargetthe
hostindirectly.RunningagainstvCenterServersystemsby
usingthe-vihostparameterisrequiredifthehostisin
lockdownmode.
ESXishell.RunESXCLIcommandsinthelocalESXishellto
managethathost.

See
UsingESXCLIonpage 8
InstallingvCLIon
page 13
vSphereCommandLine
ConceptsandExamples
vSphereManagement
AssistantGuide
vSphereCommandLine
InterfaceReference

YoucanalsorunESXCLIcommandsfromthevSpherePowerCLI
promptbyusingtheGet-EsxClicmdlet.
esxcfg-commands

AvailableintheESXiShell.esxcfg-commandsarestillincluded
inthisreleasebutaredeprecated.MigratetoESXCLIwhere
possible.ESXCLIreplacementsexistformostcommands.

CommandLineManagement
ofvSphere5.0forService
ConsoleUsers

vicfg-andother
vCLIcommands

IntroducedinvSphere3toallowuserstomanagehostsremotely.
InstallthevCLIpackageontheserverofyourchoice,ordeploya
vMAvirtualmachineandtargettheESXisystemthatyouwant
manipulate.

vSphereCommandLine
ConceptsandExamples

YoucanrunthecommandsagainstESXisystemsoragainsta
vCenterServersystem.IfyoutargetavCenterServersystem,use
the--vihostoptiontospecifythetargetESXisystem.

InstallingvCLIonpage 13

vSphereCommandLine
InterfaceReference

Note:IftheESXisystemisinlockdownmode,youmustrun
commandsagainstthevCenterServersystemthatmanagesyour
ESXisystem.

VMware, Inc.

Getting Started with vSphere Command-Line Interfaces

Command set

Description

See

VMwarePowerCLI
cmdlets

VMwarevSpherePowerCLIprovidesaWindowsPowerShell
interfacetothevSphereAPI.vSpherePowerCLIincludes
PowerShellcmdletsforadministeringvSpherecomponents.In
addition,thevSpherePowerCLIpackageincludesthevSphere
SDKfor.NETfordeveloperswhowanttocreatetheirown
applications.

VMwarePowerCLI
documentationset.

vSpherePowerCLIincludesmorethan200cmdlets,asetof
samplescripts,andafunctionlibraryformanagementand
automation.ThevSphereImageBuilderPowerCLIandthe
vSphereAutoDeployPowerCLIareincludedwhenyouinstall
thevSpherePowerCLI.
localclicommands

SetofcommandsforusewithVMwareTechnicalSupport.
localclicommandsareequivalenttoESXCLIcommands,but
bypasshostd.Thelocalclicommandsareonlyforsituations
whenhostdisunavailableandcannotberestarted.Afteryourun
alocalclicommand,youmustrestarthostd.RunESXCLI
commandsaftertherestart.
Ifyouusealocalclicommandinothersituations,an
inconsistentsystemstateandpotentialfailurecanresult.

Using the vSphere Command-Line Interface

ThevCLIcommandsetincludesvicfg-commandsandESXCLIcommands.TheESXCLIcommands
includedinthevCLIpackageareequivalenttotheESXCLIcommandsavailableontheESXiShell.Thevicfg-
commandsetissimilartothedeprecatedesxcfg-commandsetintheESXiShell.
IMPORTANTESXiShellisintendedforexperiencedusersonly.Minorerrorsintheshellcanresultin
seriousproblems.InsteadofrunningcommandsdirectlyintheESXiShell,usevCLIorPowerCLI.
YoucanrunvCLIcommandsfromaWindowsorLinuxsystem,orusevMA.

InstallthevCLIcommandsetontheWindowsorLinuxsystemfromwhichyouwanttoadministeryour
ESXisystemsandrunvCLIcommands.SeeInstallingvCLIonpage 13.

DeployavMAvirtualmachinetoanESXisystemandrunvCLIcommandsfromthere.

AfteryouhaveinstalledthevCLIpackageyoucanrunthecommandsinthesetagainstESXihosts.Youmust
specifyconnectionparameterswhenyourunavCLIcommand.SeeUsingthevSphereCommandLine
Interfaceonpage 21.

Using ESXCLI
YoucanmanagemanyaspectsofanESXihostwiththeESXCLIcommandset.YoucanrunESXCLIcommands
asvCLIcommandsorrunthemintheESXiShellintroubleshootingsituations.
YoucanalsorunESXCLIcommandsfromthePowerCLIshellbyusingtheGet-EsxClicmdlet.SeethevSphere
PowerCLIAdministrationGuideandthevSpherePowerCLIReference.
ThesetofESXCLIcommandsavailableonahostdependsonthehostconfiguration.ThevSphere
CommandLineInterfaceReferencelistshelpinformationforallESXCLIcommands.Runesxcli --server
<MyESXi> --helpbeforeyourunacommandonahosttoverifythatthecommandisdefinedonthehostyou
aretargeting.

VMware, Inc.

Chapter 1 Managing vSphere with Command-Line Interfaces

ESXCLI Syntax
EachESXCLI5.0commandusesthesamesyntax.
esxcli [dispatcher options] <namespace> [<namespace> ...] <cmd> [cmd options]

dispatcheroptions.Predefinedoptionsforconnectioninformationsuchastargethost,username,andso
on.SeeCommonOptionsforvCLIExecutiononpage 25.Notrequiredwhenyourunthecommandin
theESXiShell.

namespace.GroupsESXCLIcommands.vSphere5.0supportsnestednamespaces.

command.Reportsonormodifiesstateonthesystem.

Running ESXCLI vCLI Commands

YoucanrunanESXCLIvCLIcommandremotelyagainstaspecifichostoragainstavCenterServersystem.
Youhavethefollowingchoices:

DeploythevMAapplianceonanESXisystemandauthenticateagainstasetoftargetservers.Youcan
thenrunESXCLIcommandsagainstanytargetserverbyspecifyingthe--hostdispatcheroption.No
additionalauthenticationisrequired.SeethevSphereManagementAssistantGuide.

InstallthevCLIpackageononeofthesupportedWindowsorLinuxsystems.TheESXCLIcommandset
isincluded.YoucanruncommandsagainstanESXiorvCenterServersystemifyouspecifyconnection
options.SeeInstallingvCLIonpage 13.

Afterinstallation,runESXCLIcommandsagainstaspecifichostbyfirstspecifyingalldispatcheroptions.If
thetargetserverisavCenterServersystem,specifythetargetESXihostbeforeanyESXCLInamespaces,
commands,andsupportedoptions.
esxcli --server myESXi --username user1 --password 'my_password' storage nfs list
esxcli --server myVCServer --username user1 --password 'my_pwd' --vihost myESXi.mycompany.com
storage nfs list

Eachtimeyourunacommand,youmustspecifyauthenticationinformation.SeeUsingthevSphere
CommandLineInterfaceonpage 21.

Running ESXCLI vCLI Commands Against ESXi 4.x Hosts

WhenyourunanESXCLIvCLIcommand,youmustknowthecommandssupportedonthetargethost
specifiedwith--serverorasavMAtarget.

IfyouruncommandsagainstESXi4.xhosts,ESXCLI4.xcommandsaresupported.

IfyouruncommandsagainstESXi5.0hosts,ESXCLI5.0commandsaresupported.

VMwarepartnersmightdevelopcustomESXCLIcommandsthatyoucanrunonhostswherethepartnerVIB
hasbeeninstalled.
Runesxcli --server <target> --helpforalistofnamespacessupportedonthetarget.Youcandrill
downintothenamespacesforadditionalhelp.
IMPORTANTESXCLIonESX4.xhostsdoesnotsupporttargetingavCenterServersystem.Youcantherefore
notruncommandswith--serverpointingtoavCenterServersystemevenifyouinstallvCLI5.0.

Running ESXCLI Commands in the ESXi Shell

ESXCLIcommandsintheESXiShellarefullysupportedunlesstheyaremarkedasinternalintheonlinehelp.
TheESXiShellisdisabledbydefault.YoumustenabletheESXiShellbeforeyoucanruncommandsinthe
shell.SeeESXiShellAccesswiththeDirectConsoleonpage 10.

VMware, Inc.

Getting Started with vSphere Command-Line Interfaces

To run an ESXCLI command in the shell

1

Logintotheshell.

Runthecommand.Forexample,tolistNASstoragedevices,runthefollowingcommand.
esxcli storage nfs list

Youcanuse--helpatanylevelofesxcliforhelponavailablenamespaces,commands,oroptions.

ESXi Shell Access with the Direct Console

AnESXisystemincludesadirectconsole(alsocalledDCUI)thatallowsyoutostartandstopthesystemand
toperformalimitedsetofmaintenanceandtroubleshootingtasks.ThedirectconsoleincludestheESXiShell,
whichisdisabledbydefault.YoucanenabletheESXiShellinthedirectconsoleorbyusingthevSphereClient.
Youcanenablelocalshellaccessorremoteshellaccess:

LocalshellaccessallowsyoutologintotheshelldirectlyfromtheDirectConsole.SeeEnablingLocal
ESXiShellAccessonpage 10.

Remoteshell(SSH)accessallowsyoutoconnecttothehostusingashellsuchasPuTTY,specifyauser
nameandpassword,andruncommandsintheshell.

TheESXiShellincludesallESXCLIcommands,asetofdeprecatedesxcfg-commands,andasetof
commandsfortroubleshootingandremediation.
IMPORTANTAllESXCLIcommandsthatareavailableintheESXiShellarealsoincludedinthevCLIpackage.
VMwarerecommendsyouinstallthevCLIpackageonasupportedWindowsorLinuxsystemordeploythe
vMAvirtualappliance,andruncommandsagainstyourESXihosts.RuncommandsdirectlyintheESXiShell
introubleshootingsituationsonly.

Enabling Local ESXi Shell Access

YoucanenabletheESXiShellfromthedirectconsoleorfromthevSphereClient.
Ifyouhaveaccesstothedirectconsole,youcanenabletheESXiShellfromthere.
To enable the ESXi Shell in the direct console
1

AtthedirectconsoleoftheESXihost,pressF2andprovidecredentialswhenprompted.

ScrolltoTroubleshootingOptionsandpressEnter.

ChooseEnableESXiShellandpressEnter.
Ontheleft,EnableESXiShellchangestoDisableESXiShell.Ontheright,ESXiShellisDisabled
changestoESXiShellisEnabled.

PressEscuntilyoureturntothemaindirectconsolescreen.

Ifyoudonothaveaccesstothedirectconsole,youcanenabletheESXiShellfromthevSphereClient.
To enable the local or remote ESXi Shell from the vSphere Client
1

Selectthehost,clicktheConfigurationtab,andclickSecurityProfileintheSoftwarepanel.

IntheServicessection,clickProperties.

SelectESXiShellandclickOptions.

ChangetheESXiShelloptions.

10

TochangetheStartuppolicyacrossreboots,clickStartandstopwithhostandrebootthehost.

Totemporarilystartorstoptheservice,clicktheStartorStopbutton.

ClickOK.

VMware, Inc.

Chapter 1 Managing vSphere with Command-Line Interfaces

AfteryouhaveenabledtheESXiShell,youcanuseitfromthatmonitororthroughaserialport.
TheESXiShelltimeoutsettingspecifieshowlong,inminutes,youcanleaveanunusedsessionopen.By
default,thetimeoutfortheESXiShellis0,whichmeansthesessionremainsopenevenifitisunused.Ifyou
changethetimeout,forexample,to30minutes,youhavetologinagainafterthetimeoutperiodhaselapsed.
NOTEIfyouareloggedinwhenthetimeoutperiodelapses,yoursessionwillpersist.However,theESXiShell
willbedisabled,preventingotherusersfromloggingin.
YoucanmodifythetimeoutfromtheDirectConsoleorfromthevSphereClient.
To modify the ESXi Shell Timeout

IntheDirectConsole,followthesesteps.
a

SelectModifyESXiShelltimeoutandpressEnter.

EnterthetimeoutvalueinminutesandpressEnter.

InthevSphereClient,followthesesteps.
a

IntheConfigurationtabsSoftwarepanel,clickAdvancedSettings.

Intheleftpanel,clickUserVars.

LocateUserVars.ESXiShellTimeOutandenterthetimeoutvalueinminutes.

ClickOK.

Using the Local ESXi Shell

AfteryouenabletheESXiShellinthedirectconsole,youcanuseitfrommaindirectconsolescreenorremotely
throughaserialport.
To use the local ESXi Shell
1

Atthemaindirectconsolescreen,pressAltF1toopenavirtualconsolewindowtothehost.

Providecredentialswhenprompted.
Whenyoutypethepassword,charactersarenotdisplayedontheconsole.

Entershellcommandstoperformmanagementtasks.

Tologout,typeexitintheshell.

Toreturntothedirectconsole,typeAltF2.

SeevSphereInstallationandSetupdocumentationforinformationonserialportsetup.

Remote ESXi Shell Access with SSH

IfSecureShellisenabledfortheESXiShell,youcanrunshellcommandsbyusingaSecureShellclientsuch
asSSHorPuTTY.

Enabling SSH for the ESXi Shell

Bydefault,remotecommandexecutionisdisabledonanESXihost,andyoucannotlogintothehostusinga
remoteshell.YoucanenableremotecommandexecutionfromthedirectconsoleorfromthevSphereClient.
To enable SSH access in the direct console
1

AtthedirectconsoleoftheESXihost,pressF2andprovidecredentialswhenprompted.

ScrolltoTroubleshootingOptionsandpressEnter.

VMware, Inc.

11

Getting Started with vSphere Command-Line Interfaces

ChooseEnableSSHandpressEnteronce.
Ontheleft,EnableSSHchangestoDisableSSH.Ontheright,SSHisDisabledchangestoSSHis
Enabled.

PressEscuntilyoureturntothemaindirectconsolescreen.

To enable SSH from the vSphere Client

1

SelectthehostandclicktheConfigurationtab.

ClickSecurityProfileintheSoftwarepanel.

IntheServicessection,clickProperties.

SelectSSHandclickOptions.

ChangetheSSHoptions.

TochangetheStartuppolicyacrossreboots,clickStartandstopwithhostandrebootthehost.

Totemporarilystartorstoptheservice,clicktheStartorStopbutton.

ClickOK.

AfteryouhaveenabledSSH,youlogintotheESXiShellremotelyandrunESXiShellcommands.

Using the ESXi Shell with SSH

IfSSHisenabledonyourESXihost,youcanruncommandsonthatshellusinganSSHclient.
To access the remote ESXi Shell
1

OpenanSSHclient.

SpecifytheIPaddressordomainnameoftheESXihost.
PrecisedirectionsvarydependingontheSSHclientthatyouareusing.Seevendordocumentationand
support.

12

Providecredentialswhenprompted.

VMware, Inc.

Installing vCLI

YoucaninstallavCLIpackageonaLinuxoraMicrosoftWindowssystem,ordeploythevSphere
ManagementAssistant(vMA)onanESXihost.
Thischapterincludesthefollowingtopics:

InstallationOverviewonpage 13

InstallingandUninstallingvCLIonLinuxonpage 14

InstallingandUninstallingvCLIonWindowsonpage 17

EnablingCertificateVerificationonpage 19

DeployingvMAonpage 19

Installation Overview
YoucaninstallavCLIpackageonasupportedplatformofyourchoiceordeploythevMAvirtualmachineon
anESXihost.

vCLIpackages.InstallavCLIpackageonaphysicalorvirtualmachine.SeeInstallingandUninstalling
vCLIonLinuxonpage 14andInstallingandUninstallingvCLIonWindowsonpage 17.
ThevCLIinstalleralsoinstallsvSphereSDKforPerlbecausevCLIcommandsrunontopofthevSphere
SDKforPerl.OnWindows,theinstallationpackageincludesvCLI,vSphereSDKforPerl,and
prerequisitePerlmodules.OnLinux,theinstallationpackageincludesvCLIandvSphereSDKforPerl.
Youareresponsibleforinstallingrequiredprerequisitesoftware.
Afteryouhaveinstalledthepackage,youcanrunvCLIcommandsandvSphereSDKforPerlutility
applicationsfromtheoperatingsystemcommandline.Eachtimeyourunacommand,youspecifythe
targetserverconnectionoptionsdirectlyorindirectly.SeeSpecifyingAuthenticationInformationon
page 22.YoucanalsowritescriptsandmanageyourvSphereenvironmentusingthosescripts.

vMA.DeployvMA,avirtualmachinethatadministratorscanusetorunscriptsthatmanagevSphere,on
anESXihost.vMAincludesvCLI,vSphereSDKforPerl,andotherprepackagedsoftwareinaLinux
environment.
vMAsupportsnoninteractivelogin.IfyouestablishanESXihostasatargetserver,youcanrunvCLIand
vSphereSDKforPerlcommandsagainstthatserverwithoutadditionalauthentication.Ifyouestablisha
vCenterServersystemasatargetserver,youcanrunmostvCLIcommandsagainstallESXisystemsthat
servermanageswithoutadditionalauthentication.SeeDeployingvMAonpage 19.

VMware, Inc.

13

vSphere SDK for Perl Installation Guide

Installing and Uninstalling vCLI on Linux

TheinstallationscriptforthevCLIissupportedonthefollowingLinuxdistributions:

RedHatEnterpriseLinux5.5Server(32bitand64bit)

SLES10SP1(32bitand64bit)

SLES11(32bitand64bit)

Ubuntu10.04(32bitand64bit)

TheLinuxinstallerforvCLI5.0.0stopsifyoudonothaverequiredsoftwareinstalled.TheinstallerusesCPAN
todownloadandinstallotherprerequisitePerlmodulesfromCPANsites.YoumusthaveanInternet
connectiontoallowtheinstallertodownloadandinstallPerlmodulesfromCPAN.
InstallvCLIonLinuxonlyifyouareanexperiencedLinuxadministratorwhoknowshowtousethesystems
packagemanager.Otherwise,usevMA.SeeDeployingvMAonpage 19.

Installation Prerequisites
InstallthevCLIpackageonaLinuxsystemthatmeetsthefollowingprerequisites.

Internetaccess.YoumusthaveInternetaccesswhenyouruntheinstallerbecausetheinstalleruses
CPANtoinstallprerequisitePerlmodules.

DevelopmentToolsandLibraries.YoumustinstalltheDevelopmentToolsandLibrariesfortheLinux
platformthatyouareworkingwithbeforeyouinstallvCLIandprerequisitePerlmodules.

Proxysettings.IfyoursystemisusingaproxyforInternetaccess,youmustsetthehttp://andftp://
proxies,asfollows:
export http_proxy=<proxy_server>:port
export ftp_proxy=<proxy_server>:port

Installation Process
ThevCLIpackageinstallerinstallsthevCLIscriptsandthevSphereSDKforPerl.Theinstallationproceedsas
follows.
1

Theinstallercheckswhetherthefollowingrequiredprerequisitepackagesareinstalledonthesystem:
Perl

Perlversion5.8.8orversion5.10mustbeinstalledonyoursystem.

OpenSSL

ThevCLIrequiresSSLbecausemostconnectionsbetweenthesystemonwhichyourunthecommand
andthetargetvSpheresystemareencryptedwithSSL.
TheOpenSSLlibrary(libssl-devpackage)isnotincludedinthedefaultLinuxdistribution.See
InstallingRequiredPrerequisiteSoftwareforYourLinuxPlatformonpage 16.

LibXML2

UsedforXMLparsing.ThevCLIclientrequires2.6.26orhigherversion.Ifyouhaveanolderversion
installed,pleaseupgradeto2.6.26orhigher.
Thelibxml2packageisnotincludedinthedefaultLinuxdistribution.InstallingRequired
PrerequisiteSoftwareforYourLinuxPlatformonpage 16.

uuid

14

Includedinuuid-devforSLES11andine2fsprogsforotherLinuxplatforms.RequiredbytheUUID
Perlmodule.

Iftherequiredsoftwareisfound,theinstallerproceeds.Otherwise,theinstallerstopsandinformsyou
thatyoumustinstallthesoftware.SeeInstallingRequiredPrerequisiteSoftwareforYourLinux
Platformonpage 16forinstructions.

TheinstallercheckswhetherthefollowingPerlmodulesarefound,andwhetherthecorrectversionis
installed.

CryptSSLeay0.55(0.550.9.7or0.550.9.8)

IOCompressBase2.005

CompressZlib2.005

VMware, Inc.

Chapter 2 Installing vCLI

IOCompressZlib2.005

CompressRawZlib2.017

ArchiveZip1.26

DataDumper2.121

XMLLibXML1.63

libwwwperl5.805

LWPProtocolhttps6.02

XMLLibXMLCommon0.13

XMLNamespaceSupport1.09

XMLSAX0.16

DataDump1.15

URI1.37

UUID0.02

SOAPLite0.710.08

HTMLParser3.60

version0.78

EarlierversionsoflibwwwperlincludetheLWPProtocolhttpsmodule.Veryrecentversionsof
libwwwperldonotincludetheLWPProtocolhttpsmodule.
4

TheinstallerproceedsdependingonwhetherthePerlmodulesarefound.

IfarecommendedPerlmoduleisnotfoundatall,theinstallerinstallsitusingCPAN.Youmustmeet
theinstallationprerequisitesortheinstallercannotinstallthePerlmodulesandstops.See
InstallationPrerequisitesonpage 14.

Ifalowerversionofarecommendedmoduleisfound,theinstallerdoesnotinstalladifferentversion
fromCPANandproceedswithinstallation.Aftercompletinginstallation,theinstallerdisplaysa
messagethattheversiononthesystemdoesnotmatchtherecommendedversion,andrecommends
thatyouinstalltheversionvCLIwastestedwith.Youcaninstallthemodulesusingthepackage
installerforyourplatform,theinstallationCD,orCPAN.

Ifahigherversionofarecommendedmoduleisfound,theinstallerproceedswithinstallationand
doesnotdisplayamessageafterinstallation.

IMPORTANTTheinstallerdoesnotoverwriteexistingversionsofrecommendedPerlmodules.Youmust
explicitlyupdatethosemodulesyourself.
5

AfterallrequiredsoftwareandallprerequisitePerlmodulesareinstalled,youcaninstallvCLI.See
InstallingthevCLIPackageonpage 16.

IfapreviousversionofvCLI,RemoteCLI,orvSphereSDKforPerlisinstalledonyoursystem,andyouinstall
vCLIinadifferentdirectory,youmustresetthePATHenvironmentvariable.Youcandosobeforeorafterthe
installation,usingthecommandappropriateforyourdistributionandshell(setenv,export,andsoon).If
youdonotresetthepath,thesystemmightstilllookforexecutablesintheoldlocation.

VMware, Inc.

15

vSphere SDK for Perl Installation Guide

Installing Required Prerequisite Software for Your Linux Platform

Ifrequiredprerequisitesoftwareisnotinstalled,theinstallerstopsandrequeststhatyouinstallit.Installation
dependsontheplatformthatyouareusing.
Table 2-1. Installing Required Prerequisite Software
Platform

Installation

RedHatEnterpriseLinux
5.5,32bitand64bit

Installprerequisitesusingyum,theRHELpackageinstaller(recommended),orfromtheinstallation
DVD.Forexample:
yum install openssl-devel libxml2-dev e2fsprogs-dev

SLES10,32bit

InstalltheprerequisitepackagesfromtheSLES10andSLES11SDKDVD.WhenyouinserttheDVD,
itofferstoautorun.Canceltheautorundialogboxandusetheyastpackageinstallertoinstall
OpenSSLorothermissingrequiredpackages.

SLES10,64bit

SLES10,64bit.yast -i openssl-devel libxml2-devel-32bit e2fsprogs-devel-32bit

SLES10,32bit.yast -i openssl-devel libxml2-devel e2fsprogs-devel

SomeusersmightbeauthorizedtousetheNovellCustomerCenteranduseyasttoretrievemissing
packagesfromthere.
NotethatSLES10includeslibxml2version2.6.23.ThevCLIclientrequire2.6.26orhigher.Upgrade
to2.6.26orhigher.
SLES11,32bit

InstalltheprerequisitepackagesfromtheSLES10andSLES11SDKDVD.WhenyouinserttheDVD,
itofferstoautorun.Canceltheautorundialogboxandusetheyastpackageinstallertoinstall
OpenSSLorothermissingrequiredpackages.

SLES11,64bit

SLES1164bit.yast -i openssl-devel libuuid-devel libuuid-devel-32bit

SLES1132bit.yast -i openssl-devel libuuid-devel

SomeusersmightbeauthorizedtousetheNovellCustomerCenteranduseyasttoretrievemissing
packagesfromthere.
Ubuntu10.04,32bit

1.ConnecttotheInternet.

Ubuntu10.04,64bit

2.Updatethelocalrepositoryoflibrariesfromaterminalwindow.
sudo apt-get update
3.Installtherequiredlibrariesfromaterminalwindow.

32bit.sudo apt-get install build-essential gcc uuid uuid-dev perl libssl-dev

perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl

64bit.sudo apt-get install ia32-libs build-essential gcc uuid uuid-dev perl

libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl

ForUbuntu10.0464bit,youmustinstallthe32bitcompatibilitylibrariesortheresxtopand

ESXCLIcommandsdonotwork.

Installing the vCLI Package

InstallthevCLIpackageandrunacommandtoverifyinstallationwassuccessful.
To install vCLI on Linux
1

Loginasroot.

UntarthevCLIbinarythatyoudownloaded.
tar zxvf VMware-vSphere-CLI-5.X.X-XXXXX.i386.tar.gz

Avmware-vsphere-vcli-distribdirectoryiscreated.
3

(Optional)IfyourserverusesaproxytoaccesstheInternet,andifyourhttp://andftp://proxywere
notsetwhenyouinstalledprerequisitesoftware,setthemnow.
export http_proxy=<proxy_server>:port
export ftp_proxy=<proxy_server>:port

Runtheinstaller:
/sudo vmware-vsphere-cli-distrib/vmware-install.pl

Toacceptthelicenseterms,typeyesandpressEnter.
TheinstallerconnectstoCPANandinstallsprerequisitesoftware.Thismighttakealongtime.

16

VMware, Inc.

Chapter 2 Installing vCLI

Specifyaninstallationdirectory,orpressEntertoacceptthedefault,whichis/usr/bin.
Acompleteinstallationprocesshasthefollowingresult:

Asuccessmessageappears.

Theinstallerlistsdifferentversionnumbersforrequiredmodules(ifany).

Thepromptreturnstotheshellprompt.

Ifyouacceptedthedefaultsduringinstallation,youcanfindtheinstalledsoftwareinthefollowinglocations:

vCLIscripts/usr/bin

vSphereSDKforPerlutilityapplications/usr/lib/vmware-vcli/apps

vSphereSDKforPerlsamplescripts/usr/share/doc/vmware-vcli/samples

SeethevSphereSDKforPerldocumentationforareferencetoallutilityapplications.AfteryouinstallvCLI,
youcantesttheinstallationbyrunningavCLIcommandorvSphereSDKforPerlutilityapplicationfromthe
commandprompt.
To run a vCLI command on Linux
1

Openacommandprompt.

(Optional)ChangetothedirectorywhereyouinstalledthevCLI(defaultis/usr/bin).

Runthecommand,includingtheconnectionoptions.
<command> <conn_options> <params>

Specifyconnectionoptionsinaconfigurationfileorpassthemonthecommandline.Theextension.pl
isnotrequiredonLinux.Forexample:
vicfg-nas --server my_esxserver --list

Thesystempromptsyouforausernameandpasswordforthetargetserver.
SeeTable 32,vCLIConnectionOptions,onpage 26foracompletelistofconnectionoptions.

Uninstalling the vCLI Package on Linux

YoucanuseascriptincludedintheinstallationtouninstallthevCLIpackage.
To uninstall vCLI on Linux
1

ChangetothedirectorywhereyouinstalledvCLI(defaultis/usr/bin).

Runthevmware-uninstall-vSphere-CLI.pl script.
ThecommanduninstallsvCLIandthevSphereSDKforPerl.

Installing and Uninstalling vCLI on Windows

BeforeyoucanrunvCLIcommandsfromyourWindowsystem,youmustinstallthevCLIpackageandtest
theinstallationbyrunningacommand.
ThevCLIinstallationpackageforWindowsincludestheActivePerlruntimefromActiveStateSoftwareand
requiredPerlmodulesandlibraries.ThevCLIissupportedonthefollowingWindowsplatforms:

WindowsVistaEnterpriseSP132bitand64bit

Windows200864bit

Windows732bitand64bit

IMPORTANTIfyouwanttorunESXCLIcommandsincludedinvCLIfromaWindowssystem,youmusthave
theVisualC++2008redistributablefor32bitinstalledonthatsystem.Findvcredist_x86.exeforVisualC++
2008andinstallitonyourWindowssystem.

VMware, Inc.

17

vSphere SDK for Perl Installation Guide

To install the vCLI Package on Windows

1

DownloadthevCLIWindowsinstallerpackage.
YoucanfindtheinstallerontheVMwareCommunitiespage.

Starttheinstaller.

(Optional)IfpromptedtoremoveolderversionsofvSphereSDKforPerlorvCLI,youcaneitheraccept
orcanceltheinstallationandinstallthevCLIpackageonadifferentsystem.
IMPORTANTTheinstallerreplacesboththevSphereSDKforPerlandvCLI.Tokeepanolderversion,
installthispackageonadifferentsystem.

ClickNextintheWelcomepage.

ToinstallthevCLIinanondefaultdirectory,clickChangeandselectthedirectory.
ThedefaultlocationisC:\Program Files\VMware\VMware vSphere CLI.

ClickNext.

ClickInstalltoproceedwiththeinstallation.
Theinstallationmighttakeseveralminutestocomplete.

Rebootyoursystem.
Withoutreboot,pathsettingsmightnotbecorrectonyourWindowsplatform.

Running Commands on Windows

AfteryouinstallvCLIandrebootyoursystem,youcantesttheinstallationbyrunningavCLIorSDKforPerl
commandfromtheWindowscommandprompt.
To run a vCLI command on Windows
1

FromtheWindowsStartmenu,choosePrograms>VMware>VMwarevSphereCLI>Command
Prompt.
AcommandpromptshellforthelocationwherevCLIisinstalledappears.YouhaveeasyaccesstovCLI
andtovSphereSDKforPerlcommandsfromthatlocation.

Runthecommand,passinginconnectionoptionsandotheroptions.
OnWindows,theextension.plisrequiredforvicfg-commands,butnotforESXCLI.
<command>.pl <conn_options> <params>

Forexample:
vicfg-nas.pl --server my_esxhost --list

Thesystempromptsyouforausernameandpassword.
SeeTable 32,vCLIConnectionOptions,onpage 26foracompletelistofconnectionoptions.

Uninstalling the vCLI Package on Windows

YoucanuninstallthevCLIpackageasyouwouldotherprograms.
To uninstall vCLI on Windows
1

FindtheoptionforaddingandremovingprogramsontheWindowsoperatingsystemyouareusing.

Inthepanelthatappears,selectVMwarevSphereCLI,andclickRemove.

ClickYeswhenprompted.

ThesystemuninstallsthevSphereSDKforPerl,thevCLI,andallprerequisitesoftware.

18

VMware, Inc.

Chapter 2 Installing vCLI

Enabling Certificate Verification

ThevSphereSDKforPerlandvCLIuseCrypt::SSLEaytosupportcertificateverification.Crypt::SSLEay
allowsverificationofcertificatessignedbyaCertificateAuthority(CA)ifyousetthefollowingtwovariables:

HTTPS_CA_FILETheCAfile.

HTTPS_CA_DIRTheCAdirectory.

SeetheCrypt::SSLEaydocumentationfordetailsonsetup.
CAUTIONIfthetwoenvironmentvariablesHTTPS_CA_FILEandHTTPS_CA_DIRaresetincorrectlyorifa
problemwiththecertificateexists,vCLIcommandsdonotcomplete,anddonotprinterrororwarning
messages.UseHTTPS_DEBUGfortroubleshootingbeforerunningvCLIcommands.

Deploying vMA
Asanalternativetoapackageinstallation,youcandeployvMAonanESXihostandrunvCLIcommands
fromthere.vMAisavirtualmachineyoucanusetorunscriptstomanageESXisystems.vMAincludesa
Linuxenvironment,vCLI,andotherprepackagedsoftware.
SettingupvMAconsistsofafewtasks.ThevSphereManagementAssistantGuidediscusseseachtaskindetail.
1

DeployvMAtoanESXisystemthatmeetsthehardwareprerequisites.
SeethevSphereManagementAssistantGuideforprerequisitesanddeploymentdetails.

ConfigurevMA.
WhenyoubootvMA,youmustspecifythefollowingrequiredconfigurationinformationwhen
prompted:

Networkinformation(thedefaultisoftenacceptable)

HostnameforvMA.

Passwordfortheviadminuser.TheviadminuserhassuperuserprivilegesonvMA.Youcannotlog
intovMAastherootuser.

(Optional)AddavCenterServersystemoroneormoreESXisystemsastargets.YouconfigurevMAfor
ActiveDirectoryauthenticationandcanthenaddESXiandvCenterServersystemstovMAwithout
havingtostorepasswordsinthevMAcredentialstore.SeethevSphereManagementAssistantGuide.

VMware, Inc.

19

vSphere SDK for Perl Installation Guide

20

VMware, Inc.

3f

Using the vSphere Command-Line

Interface

YoucanrunvSphereCommandLineInterface(vCLI)commandsfromthecommandlineofthesystemwhere
youinstalledthepackage,fromthevMAcommandline,andfromscripts.Eachcommandrequiresata
minimumthetargetservertorunthecommandon.Usersauthorizedtoruncommandsonthetargetserver
donothavetospecifyauthenticationinformation.Otherusersmustspecifyauthenticationinformation.
Thischapterincludesthefollowingtopics:

OverviewofRunningCommandsonpage 21

SpecifyingAuthenticationInformationonpage 22

CommonOptionsforvCLIExecutiononpage 25

UsingvCLICommandsinScriptsonpage 27

IMPORTANTIfanESXisystemthatyoutargetisinlockdownmode,youcannotrunvCLIcommandsagainst
thatsystemdirectly.YoumusttargetavCenterServersystemthatmanagestheESXisystemandusethe
--vihostoptiontospecifytheESXitarget.SeevCLIandLockdownModeonpage 25.

Overview of Running Commands

YoucanrunvCLIcommandsinteractivelyorinscriptsinseveralways.

OpenacommandpromptonaLinuxorWindowssystemonwhichyouinstalledvCLI.Entercommands
intothatcommandprompt,specifyingconnectionoptions.

AccessthevMALinuxconsole.SetuptargetserversandrunvCLIcommandsagainstthetargetswithout
additionalauthentication.

PreparescriptsthatcontainvCLIcommands.Thenrunthescriptsfromaremoteadministrationserver
thathasthevCLIpackageinstalledorfromthevMALinuxconsole.SeeUsingvCLICommandsin
Scriptsonpage 27.

WhenyouruncommandsagainstanESXihost,youmustbeauthenticatedforthathost.Whenyourun
commandsagainstavCenterServersystem,andyouareauthenticatedforthatsystem,youcantargetallESXi
hoststhatvCenterServermanageswithoutadditionalauthentication.SeeSpecifyingAuthentication
Informationonpage 22.
CAUTIONIfyouspecifypasswordsinplaintext,youriskexposingthepasswordtootherusers.Thepassword
mightalsobecomeexposedinbackupfiles.Donotprovideplaintextpasswordsonproductionsystems.

VMware, Inc.

21

Getting Started with vSphere Command-Line Interfaces

Followoneofthefollowingapproachesforprotectingpasswords.

IfyouuseavCLIcommandinteractivelyanddonotspecifyausernameandpassword,youareprompted
forthem.Thescreendoesnotechothepasswordyoutype.

Fornoninteractiveuse,youcancreateasessionfileusingthesave_sessionscriptincludedinthe
apps/sessiondirectory.SeeUsingaSessionFileonpage 22.

IfyouarerunningonaWindowssystem,youcanusethe--passthroughauthoption.Iftheuserwho
runsthecommandwiththatoptionisknown,nopasswordisrequired.

IfyouarerunningvMA,youcansetuptargetserversandrunmostvCLIcommandsagainsttargetservers
withoutadditionalauthentication.SeethevSphereManagementAssistantGuide.

Specifying Authentication Information

vCLIallowsyoutorunagainstmultipletargetserversfromthesameadministrationserver.Youmusthave
thecorrectprivilegestoperformtheactionsoneachtarget.
IMPORTANTvCLI4.1andlaterallowsadministratorstoplaceESXihostsinlockdownmodeforenhanced
security.OnlyavCLIcommandoravSphereClientconnectedtoavCenterServersystemcanmakechanges
toESXihostsinlockdownmode.Nousers,noteventherootuser,canrunvCLIcommandsagainstESXihosts
inlockdownmode.SeevCLIandLockdownModeonpage 25andtheDatacenterAdministrationGuide.

Order of Precedence for vCLI Authentication

WhenyourunavCLIcommand,authenticationhappensintheorderofprecedenceshowninTable 31.This
orderofprecedencealwaysapplies.Thatmeans,forexample,thatyoucannotoverrideanenvironment
variablesettinginaconfigurationfile.
Table 3-1. vCLI Authentication Precedence
Authentication

Description

See

Commandline

Password(--password),sessionfile
(--sessionfile),orconfigurationfile
(--config)specifiedonthecommandline.

UsingaSessionFileonpage 22

Environment
variable

Passwordspecifiedinanenvironmentvariable.

UsingEnvironmentVariablesonpage 23

Configurationfile

Passwordspecifiedinaconfigurationfile.

UsingaConfigurationFileonpage 23

Currentaccount
(ActiveDirectory)

Currentaccountinformationusedtoestablish
anSSPIconnection.AvailableonlyonWindows.

UsingMicrosoftWindowsSecuritySupport
ProviderInterfaceonpage 25

Credentialstore

Passwordretrievedfromthecredentialstore.

vSphereWebServicesSDKProgrammingGuide
andvSphereSDKforPerlProgrammingGuide.

Prompttheuserfor
apassword.

Passwordisnotechoedtoscreen.

Using a Session File

Youcancreateasessionfilewiththesave_sessionscript.Thescriptisinthe/apps/sessiondirectoryof
thevSphereSDKforPerl,whichisincludedinthevCLIpackage.Youcanusethesessionfile,whichdoesnot
revealpasswordinformation,whenyourunvCLIcommands.Ifthesessionfileisnotusedfor30 minutes,it
expires.
Ifyouuseasessionfile,otherconnectionoptionsareignored.

22

VMware, Inc.

Chapter 3 Using the vSphere Command-Line Interface

To create and use a session file

1

Connecttothedirectorywherethescriptislocated.
Forexample:

Windows:

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

Linux:

cd /usr/share/lib/vmware-vcli/apps/session

Runsave_session.
Youcanusethesave_session.plscriptorthe--savesessionfileoptiontothevCLIcommand.You
mustspecifytheservertoconnecttoandthenameofasessionfileinwhichthescriptsavesan
authenticationcookie.
save_session --savesessionfile <location> --server <server>

Forexample:
Windows:

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

--username <username> --password <password>

Linux:

save_session --savesessionfile /tmp/vimsession --server <servername_or_address>

--username <username> --password <password>

Ifyouspecifyaserver,butnousernameorpassword,thescriptpromptsyou.
3

WhenyourunvCLIcommands,passinthesessionfileusingthe--sessionfileoption.
<command> --sessionfile <sessionfile_location> <command_options>

Forexample:
Windows:

esxcli --sessionfile C:\Temp\my_session network ip interface list

vicfg-mpath.pl --sessionfile C:\Temp\my_session --list

Linux:

esxcli --sessionfile /tmp/vimsession network ip interface list

vicfg-mpath --sessionfile /tmp/vimsession --list

Using Environment Variables

OnLinux,youcansetenvironmentvariablesinaLinuxbashprofileoronthecommandlinebyusinga
commandlikethefollowing:
export VI_SERVER=<your_server_name_or_address>

OnWindows,youcansetenvironmentvariablesintheEnvironmentpropertiesdialogboxoftheSystem
controlpanel.Forthecurrentsession,youcansetenvironmentvariablesatthecommandlinebyusinga
commandlikethefollowing:
set VI_SERVER=<your_server_name_or_address>

IMPORTANTDonotuseescapecharactersinenvironmentvariables.
SeeUsingvCLICommandsinScriptsonpage 27foranenvironmentvariableexample.

Using a Configuration File

Youcanuseatextfilethatcontainsvariablenamesandsettingsasaconfigurationfile.Variablescorresponding
totheoptionsareshowninTable 32,vCLIConnectionOptions,onpage 26.
CAUTIONLimitreadaccesstoaconfigurationfilethatcontainsusercredentials.

VMware, Inc.

23

Getting Started with vSphere Command-Line Interfaces

PassintheconfigurationfilewhenyourunvCLIcommands,asfollows:
<command> --config <my_saved_config> <option>

Forexample:
esxcli --config <my_saved_config> network ip interface list
vicfg-mpath --config <my_saved_config> --list

IfyouhavemultiplevCenterServerorESXisystemsandyouadministereachsystemindividually,youcan
createmultipleconfigurationfileswithdifferentnames.Torunacommandorasetofcommandsonaserver,
youpassinthe--configoptionwiththeappropriatefilenameatthecommandline.
Thefollowingexampleillustratesthecontentsofaconfigurationfile:
VI_SERVER = XX.XXX.XXX.XX
VI_USERNAME = root
VI_PASSWORD = my_password
VI_PROTOCOL = https
VI_PORTNUMBER = 443

Ifyouhavesetupyoursystemtorunthisfile,youcanrunscriptsonthespecifiedserverafterwards.

Using Command-Line Options

Youcanpassincommandlineoptionsusingoptionnameandoptionvaluepairsinmostcases.ForESXCLI
commands,youcanuselongorshortoptions.Anequalsignbetweenoptionnameandoptionvalueis
optional.
esxcli --server <vc_server> --username <privileged_user> --password <pw> --vihost <esx_host>
<namespace> [<namespace]...> <command> --<option_name=option_value>

ForothervCLIcommands,uselongorshortoptions.Anequalsignisnotsupported.
<vicfg- command> --server <vc_server> --username <privileged_user> --password <pw>
--vihost <esx_host> --<option_name option_value>

Someoptions,suchas--help,havenovalue.
IMPORTANTEnclosepasswordsandothertextwithspecialcharactersinquotationmarks.
WhenrunningcommandsonWindows,usedoublequotes( ).WhenrunningcommandsonLinux,use
singlequotes( )orabackslash(\)asanescapecharacter.
Thefollowingexamplesconnecttotheserverasusersnow-whitewithpassworddwarf$.
Linux
esxcli --server <server> --username snow\-white --password dwarf\$ network ip interface list
esxcli --server <server> --username snow\-white --password dwarf$ network ip interface list
vicfg-mpath --server <server> --username snow\-white --password dwarf\$ --list
vicfg-mpath --server <server> --username snow-white --password dwarf$ --list

Windows
esxcli --server <server> --username snow-white --password dwarf$ network ip interface list
vicfg-mpath.pl --server <server> --username snow-white --password dwarf$ --list

24

VMware, Inc.

Chapter 3 Using the vSphere Command-Line Interface

Using Microsoft Windows Security Support Provider Interface

The--passthroughauthoption,whichisavailableifyourunvCLIcommandsfromaMicrosoftWindows
system,allowsyoutousetheMicrosoftWindowsSecuritySupportProviderInterface(SSPI).SeetheMicrosoft
WebsiteforadetaileddiscussionofSSPI.
Youcanuse--passthroughauthtoestablishaconnectionwithavCenterServersystem(vCenterServer
systemorVirtualCenterServer3.5Update2orlater).Aftertheconnectionhasbeenestablished,authentication
forthevCenterServersystemoranyESXisystemitmanagesisnolongerrequired.Using
--passthroughauthpassesthecredentialsoftheuserwhorunsthecommandtothetargetvCenterServer
system.Noadditionalauthenticationisrequirediftheuserwhorunsthecommandisknownbythecomputer
fromwhichyouaccessthevCenterServersystemandbythecomputerrunningthevCenterServersoftware.
IfvCLIcommandsandthevCenterServersoftwarerunonthesamecomputer,theuserneedsonlyalocal
accounttorunthecommand.IfthevCLIcommandandthevCenterServersoftwarerunondifferent
machines,theuserwhorunsthecommandmusthaveanaccountinadomaintrustedbybothmachines.
SSPIsupportsseveralprotocols.Bydefault,itselectstheNegotiateprotocol,whereclientandservertryto
findaprotocolthatbothsupport.Youcanuse--passthroughauthpackagetoexplicitlyspecifyaprotocol
thatissupportedbySSPI.Kerberos,theWindowsstandardfordomainlevelauthentication,isused
frequently.IfthevCenterServersystemisconfiguredtoacceptonlyaspecificprotocol,specifyingtheprotocol
with --passthroughauthpackagemightberequiredforsuccessfulauthentication.Ifyouuse
--passthroughauth,youdonothavetospecifyauthenticationinformationbyusingotheroptions.
Example
esxcli --server <vc_server> --passthroughauth --passthroughauthpackage Kerberos
--vihost my_esx network ip interface list
vicfg-mpath.pl --server <vc_server> --passthroughauth --passthroughauthpackage Kerberos
--vihost my_esx --list

ConnectstoaserverthatissetuptouseSSPI.Whenatrusteduserrunsthecommand,thesystemcallsthe
ESXCLIcommandorvicfg-mpathwiththe--listoption.Thesystemdoesnotpromptforausernameand
password.

vCLI and Lockdown Mode

LockdownmodedisablesalldirectrootaccesstoESXimachines.TomakechangestoESXisystemsin
lockdownmodeyoumustgothroughavCenterServersystemthatmanagestheESXisystem.Youcanusethe
vSphereClientorvCLIcommandsthatsupportthe--vihostoption.Thefollowingcommandscannotrun
againstvCenterServersystemsandarethereforenotavailableinlockdownmode:

vicfg-snmp

vifs

vicfg-user

vicfg-cfgbackup

vihostupdate

vmkfstools

vicfg-ipsec

IfyouhaveproblemsrunningacommandonanESXihostdirectly(withoutspecifyingavCenterServer
target),checkwhetherlockdownmodeisenabledonthathost.SeethevSphereSecuritydocumentation.

Common Options for vCLI Execution

Table 32listsoptionsthatareavailableforallvCLIcommandsinalphabeticalorder.Thetableincludes
optionsforuseonthecommandlineandvariablesforuseinconfigurationfiles.
IMPORTANTForconnections,vCLIsupportsonlytheIPv4protocol,nottheIPv6protocol.Youcan,however,
configureIPv6onthetargethostwithseveralofthenetworkingcommands.
VMware, Inc.

25

Getting Started with vSphere Command-Line Interfaces

SeeTorunavCLIcommandonLinuxonpage 17andTorunavCLIcommandonWindowsonpage 18
forusageexamples.
Table 3-2. vCLI Connection Options
Option and Environment Variable

Description

--cacertsfile <certsfile>

ESXCLIcommandsonly.

-t <certs_file>
VI_CACERTFILE=<cert_file_path>

UsedtospecifytheCA(CertificateAuthority)certificatefile,inPEMformat,
toverifytheidentityofthevCenterServersystemorESXisystemtorunthe
commandon.Canbeused,forexample,topreventmaninthemiddleattacks.

--config <cfg_file_full_path>

Usestheconfigurationfileatthespecifiedlocation.

VI_CONFIG=<cfg_file_full_path>

Specifyapaththatisreadablefromthecurrentdirectory.

--credstore <credstore>

Nameofacredentialstorefile.Defaultsto
<HOME>/.vmware/credstore/vicredentials.xmlonLinuxand
<APPDATA>/VMware/credstore/vicredentials.xmlonWindows.
CommandsforsettingupthecredentialstoreareincludedinthevSphereSDK
forPerl,whichisinstalledwithvCLI.ThevSphereSDKforPerlProgramming
Guideexplainshowtomanagethecredentialstore.

--encoding <encoding>

Specifiestheencodingtobeused.Severalencodingsaresupported.

VI_ENCODING=<encoding>

cp936(SimplifiedChinese)

shftjis(Japanese)

cp850(GermanandFrench).

Youcanuse--encodingtospecifytheencodingvCLIshouldmaptowhenit
isrunonaforeignlanguagesystem.
--passthroughauth
VI_PASSTHROUGHAUTH

Ifyouspecifythisoption,thesystemusestheMicrosoftWindowsSecurity
SupportProviderInterface(SSPI)forauthentication.Trustedusersarenot
promptedforausernameandpassword.SeetheMicrosoftWebsitefora
detaileddiscussionofSSPI.
ThisoptionissupportedonlyifyouarerunningvCLIonaWindowssystem
andareconnectingtoavCenterServersystem.

--passthroughauthpackage
<package>
VI_PASSTHROUGHAUTHPACKAGE=
<package>

Usethisoptionwith--passthroughauthtospecifyadomainlevel
authenticationprotocoltobeusedbyWindows.Bydefault,SSPIusesthe
Negotiateprotocol,whichmeansthatclientandservertrytonegotiatea
protocolthatbothsupport.
IfthevCenterServersystemtowhichyouareconnectingisconfiguredtouse
aspecificprotocol,youcanspecifythatprotocolusingthisoption.
ThisoptionissupportedonlyifyouarerunningvCLIonaWindowssystem
andconnectingtoavCenterServersystem.

--password <passwd>

Usesthespecifiedpassword(usedwith--username)tologintotheserver.

VI_PASSWORD=<passwd>

If--serverspecifiesavCenterServersystem,theusernameandpassword
applytothatserver.IfyoucanlogintothevCenterServersystem,you
neednoadditionalauthenticationtoruncommandsontheESXihoststhat
servermanages.

If--serverspecifiesanESXihost,theusernameandpasswordapplyto
thatserver.

Usetheemptystring(' 'onLinuxand onWindows)toindicateno

password.
Ifyoudonotspecifyausernameandpasswordonthecommandline,the
systempromptsyouanddoesnotechoyourinputtothescreen.
--portnumber <number>
VI_PORTNUMBER=<number>
--protocol <HTTP|HTTPS>
VI_PROTOCOL=<HTTP|HTTPS>
--savesessionfile <file>
VI_SAVESESSIONFILE=<file>

26

Usesthespecifiedporttoconnecttothesystemspecifiedby--server.Default
is443.
Usesthespecifiedprotocoltoconnecttothesystemspecifiedby--server.
DefaultisHTTPS.
Savesasessiontothespecifiedfile.Thesessionexpiresifithasbeenunused
for30minutes.

VMware, Inc.

Chapter 3 Using the vSphere Command-Line Interface

Table 3-2. vCLI Connection Options (Continued)

Option and Environment Variable

Description

--server <server>

UsesthespecifiedESXiorvCenterServersystem.Defaultislocalhost.

VI_SERVER=<server>

If--serverpointstoavCenterServersystem,youusethe--vihostoption
tospecifytheESXihostonwhichyouwanttorunthecommand.Acommand
issupportedforvCenterServerifthe--vihostoptionisdefined.

--servicepath <path>

UsesthespecifiedservicepathtoconnecttotheESXihost.Defaultis
/sdk/webService.

VI_SERVICEPATH=<path>

VI_SESSIONFILE=<file>

Usesthespecifiedsessionfiletoloadapreviouslysavedsession.Thesession
mustbeunexpired.

--url <url>

ConnectstothespecifiedvSphereWebServicesSDKURL.

--sessionfile <file>

VI_URL=<url>
--username <u_name>

Usesthespecifiedusername.

VI_USERNAME=<u_name>

If--serverspecifiesavCenterServersystem,theusernameand
passwordapplytothatserver.IfyoucanlogintothevCenterServer
system,youneednoadditionalauthenticationtoruncommandsonthe
ESXihoststhatservermanages.

If--serverspecifiesanESXisystem,theusernameandpasswordapply
tothatsystem.

Ifyoudonotspecifyausernameandpasswordonthecommandline,the
systempromptsyouanddoesnotechoyourinputtothescreen.
WhenyourunavCLIcommandwiththe--serveroptionpointingtoa
vCenterServersystem,use--vihosttospecifytheESXihosttorunthe
commandagainst.

--vihost <host>
-h <host

NOTE:Thisoptionisnotsupportedforeachcommand.Ifsupported,the
optionisincludedwhenyourun<cmd> --help.

Table 33listsoptionsnotusedasconnectionoptionsthatyoucanusewhenyourunavicfg-vCLI
command.
Table 3-3. vCLI Common Options
Option

Description

--help

Printsabriefusagemessage.Themessagelistsfirsteachcommandspecificoptionandthen
eachofthecommonoptions.

--verbose

Displaysadditionaldebugginginformation.

--version

Displaysversioninformation.

Using vCLI Commands in Scripts

Mostadministratorsrunscriptstoperformthesametaskrepeatedlyortoperformataskonmultiplehosts.
YoucanrunvCLIcommandsfromoneadministrationserveragainstmultipletargetservers.
Forexample,whenanewdatastorebecomesavailableinyourenvironment,youmustmakethatdatastore
availabletoeachESXihost.ThefollowingsamplescriptillustrateshowtomakeaNASdatastoreavailableto
threehosts(esxi_server_a,esx_server_b,andesxi_server_c).
Thesampleassumesthataconfigurationfile/home/admin/.visdkrc.<hostname>existsforeachhost.For
example,theconfigurationfileforesxi_server_ahasthefollowingcontents:
VI_SERVER = esxi_server_a
VI_USERNAME = root
VI_PASSWORD = xysfdjkat

VMware, Inc.

27

Getting Started with vSphere Command-Line Interfaces

ThescriptitselfaddstheNASdatastorebycallingthedifferentconfigurationfiles.
#!bin/sh
for i in {"esxi_server_a","esx_server_b","esxi_server_c"}
do
echo "Adding NAS datastore for $i..."
esxcli --config /host.conf storage nfs add -H <hostname> -s <sharepoint> -v <volumename>
esxcli --config <config.file> storage nfs list
done

28

VMware, Inc.

ESXCLI Command Hierarchies

Thisappendixconsistsoftablesofcommandsummariesthatillustratethehierarchyofnamespacesand
commands(inbold)foreachESXCLInamespace.Thisappendixisnotmeanttobeareferencebutfacilitates
locatingtheonlinehelpforindividualcommands.
Theappendixincludesthefollowingtopics:

esxcliesxcliNamespaceonpage 29

esxclifcoeNamespaceonpage 29

esxclihardwareNamespaceonpage 30

esxcliiscsiNamespaceonpage 30

esxclilicenseNamespaceonpage 30

esxclinetworkNamespaceonpage 31

esxclisoftwareNamespaceonpage 31

esxclistorageNamespaceonpage 32

esxclisystemNamespaceonpage 33

esxclivmNamespaceonpage 33

esxcli esxcli Namespace

Theesxcli esxclinamespaceincludestheesxcli esxcli command listcommand.

esxcli fcoe Namespace

adapter[list]
nic[disable|discover|list]

VMware, Inc.

29

Getting Started with vSphere Command-Line Interfaces

esxcli hardware Namespace

The esxcli hardwarenamespaceincludesthefollowingnamespacesandcommands.
cpu[list]

cpuid[get]
global[get|set]

bootdevice[list]
clock[get|set]
memory[get]
pci[list]
platform[get]

esxcli iscsi Namespace

Theesxcli iscsinamespaceincludesthefollowingnamespacesandcommands.
adapter[get|list|set]

auth

chap[set|get]

discovery
[rediscover]

sendtarget
[add|list|remove]

auth

chap[get|set]

param[get|set]
statictarget
[add|list|remove]
statusget
target[list]

portal[list]

auth

chap[get|set]

param[get|set]
capabilitiesget
firmware[get|set]
param[get|set]
networkportal[add|list|remove]

ipconfig[get|set]

physicalnetworkportal[list]

param[get|set]

session[add|list|remove]

connectionlist

ibftboot[get|import]
logicalnetworkportallist
pluginlist
software[get|set]

esxcli license Namespace

Theesxcli licensenamespaceincludestheesxcli license oem updatecommand.

30

VMware, Inc.

ESXCLI Command Hierarchies

esxcli network Namespace

Theesxcli networknamespaceincludesthefollowingnamespacesandcommands.
fence[list]

network[list]

bte[list]
port[list]

firewall
[get|load|refresh|set|unload]

ruleset[list|set]

allowedip[add|
list|remove]
rule[list]

ip[get|set]

dns

search
[add|list|remove]
server
[add|list|remove]

interface
[add|list|remove|
set]

ipv6[get|set]

ipv4[get|set]
address
[add|list|remove]
connection[list]
neighbor[list]
vswitch

dvs

vmware[list]

standard[add|
list|remove|set]

policy[get]

failover[set]
security[get|set]
shaping[set]

portgroup
[add|list|remove
|set]

policy[set]

failover[set]

security[get|set]
shaping[set]
uplink
[add|remove]
nic[down|get|list|set|up]

esxcli software Namespace

Theesxcli softwarenamespaceincludesthefollowingnamespacesandcommands.
sources

profile[get|list]
vib[get|list]

acceptance[get|set]
profile[get|install|update|validate]
vib[get|install|list|remove|update]

VMware, Inc.

31

Getting Started with vSphere Command-Line Interfaces

esxcli storage Namespace

Theesxcli storagenamespaceincludesthefollowingnamespacesandcommands.
core

adapter[list|rescan]

stats[get]

device
[list|set|setconfig]

vaai[status]
detached
[list|remove]
partition[list]
stats[get]
world[list]

path[list|set]

stats[get]

claiming
[reclaim|unclaim]
claimrule[add|
convert|list|load|
move|remove|run]
plugin[list]
nmp

psp[list]

fixed

deviceconfig
[get|set]

generic

deviceconfig
[get|set]
pathconfig
[get|set]

satp[list|set]

roundrobin

deviceconfig
[get|set]

generic

deviceconfig
[get|set]
pathconfig
[get|set]

rule
[add|list|remove]
device[list|set]
path[list]
vmfs[upgrade]

snapshot[list|mount|
resignature]

extent[list]

extent[list]
filesystem[automount|
list|mount|rescan|
unmount]
nfs[add|list|remove]

32

VMware, Inc.

ESXCLI Command Hierarchies

esxcli system Namespace

Theesxcli systemnamespaceincludesthefollowingnamespacesandcommands.
boot

device[get]

coredump

network[get|set]
partition
[get|list|set]

module[get|list|load|set]

parameters[list|set]

process[list]

stats
load[get]
running[get]

secpolicy

domain[list|set]

settings

keyboard

layout[get|list|set]

advanced[list|set]
kernel[list|set]
stats

uptime[get]

syslog[mark|reload]

config[get|set]

visorfs[get]

ramdisk[add|list|
remove]

logger[list|set]

tardisk[list]
hostname[get|set]
time[get|set]
uuid[get]
version[get]
welcomemsg[get|set]

esxcli vm Namespace
Theesxcli vmnamespaceincludesaprocessnamespacewithalistcommandandakillcommand.

VMware, Inc.

33

Getting Started with vSphere Command-Line Interfaces

34

VMware, Inc.

Index

Active Directory 19
authentication information 22

Perl 13
precedence 22

command-line connection parameters 24

configuration files
for authentication 23
usage 23
connection options 22, 25
cp936 encoding 26
creating session files 23
credential store precedence 22

required parameters 22
running commands
from vMA 19
Linux 14, 22
Windows 17

D
DCUI 10
deploying vMA 19
direct console 10

E
encoding
cp936 26
Shift_JIS 26
ESXCLI command hierarchies 29
execution options 25

I
installing vCLI
Linux 14, 22
Windows 17
installing vMA 19

L
Linux
installing vCLI 14, 22
running vCLI commands 17, 24
vCLI 14
lockdown mode 25

M
Microsoft Windows Security Support Provider
Interface 25

O
options 25
order of precedence 22

S
scripts with vCLI commands 27
session files 22, 23
Shift_JIS encoding 26
SSPI protocol 25

U
uninstalling
Linux 17
on Linux 17
on Windows 18
Using 24
using session files 23

V
vCLI
command-line 24
configuration files 23
environment variables 23
execution options 25
installing on Linux 14, 22
installing on Windows 17
vCLI package
installing on Linux 14
installing on Windows 18
uninstalling 17
unpacking 16
vMA 19
environment variables 23
installing 19
multiple configuration files 24
vSphere Management Assistant 19
vSphere SDK for Perl 13

W
Windows

VMware, Inc.

35

Getting Started with vSphere Command-Line Interfaces

executing commands 24
installing vCLI 17
running vCLI commands 18
using vCLI 17

36

VMware, Inc.