You are on page 1of 148

vSphere Command-Line Interface Concepts and Examples

ESXi 5.1 vCenter Server 5.1

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

EN-000887-00

vSphere Command-Line Interface Concepts and Examples

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 20082012 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 vSphereCLICommandOverviews 11
Introduction 11 Documentation 12 CommandLineHelp 12 ListofAvailableCommands 12 SupportedProtocolsandPlatformsforCommands 14 RunningESXCLICommandsAgainstESXi4.xHosts 16 CommandswithanesxcfgPrefix 16 UsingESXCLIOutput 17 ConnectionOptions 17 vCLIandLockdownMode 19

2 ManagingHosts 21
Stopping,Rebooting,andExaminingHosts 21 StoppingandRebootingHostswithESXCLI 21 Stopping,Rebooting,andExaminingHostswithvicfghostops 21 EnteringandExitingMaintenanceMode 22 EnteringandExitingMaintenanceModewithESXCLI 22 EnteringandExitingMaintenanceModewithvicfghostops 23 BackingUpConfigurationInformationwithvicfgcfgbackup 23 BackupTasks 23 BackingUpConfigurationData 24 RestoringConfigurationData 24 UsingvicfgcfgbackupfromvMA 24 ManagingVMkernelModules 24 ManagingModuleswithesxclisystemmodule 25 ManagingModuleswithvicfgmodule 25 UsingvicfgauthconfigforActiveDirectoryConfiguration 25 UpdatingHosts 26

3 ManagingFiles 27
IntroductiontoVirtualMachineFileManagement 27 ManagingtheVirtualMachineFileSystemwithvmkfstools 28 UpgradingVMFS3VolumestoVMFS5 29 ManagingVMFSVolumes 29 ManagingDuplicateVMFSDatastores 29 MountingDatastoreswithExistingSignatures 29 MountingandUnmountingwithESXCLI 30 MountingandUnmountingwithvicfgvolume 30 ResignaturingVMFSCopies 30 ResignaturingaVMFSCopywithESXCLI 31 ResignaturingaVMFSCopywithvicfgvolume 31 DetachingDevicesandRemovingaLUN 32 WorkingwithPermanentDeviceLoss 33

VMware, Inc.

vSphere Command-Line Interface Concepts and Examples

UsingvifstoManipulateFilesonRemoteESXiHosts Examples 35 ExampleScenario 37

33

4 ManagingStorage 39
IntroductiontoStorage 39 HowVirtualMachinesAccessStorage 40 Datastores 41 StorageDeviceNaming 41 ExaminingLUNs 42 TargetandDeviceRepresentation 42 ExaminingLUNswithesxclistoragecore 42 ExaminingLUNswithvicfgscsidevs 43 ManagingPaths 44 MultipathingwithLocalStorageandFCSANs 44 ListingPathInformation 45 ListingPathInformationwithESXCLI 45 ListingPathInformationwithvicfgmpath 46 ChangingtheStateofaPath 47 ChangingPathStatewithESXCLI 47 ChangingPathStatewithvicfgmpath 47 ManagingPathPolicies 47 MultipathingConsiderations 48 ChangingPathPolicies 49 ChangingPathPolicieswithESXCLI 49 ChangingPathPolicieswithvicfgmpath 49 SettingPolicyDetailsforDevicesthatUseRoundRobin 50 ManagingNFS/NASDatastores 50 CapabilitiesSupportedbyNFS/NAS 51 AddingandDeletingNASFileSystems 51 ManagingNASFileSystemswithESXCLI 51 ManagingNASFileSystemswithvicfgnas 51 MonitoringandManagingSANStorage 52 MigratingVirtualMachineswithsvmotion 52 StoragevMotionUses 52 StoragevMotionRequirementsandLimitations 53 RunningsvmotioninInteractiveMode 53 RunningsvmotioninNoninteractiveMode 53 ConfiguringFCoEAdapters 54 ScanningStorageAdapters 55 RetrievingSMARTInformation 55

5 ManagingiSCSIStorage 57
iSCSIStorageOverview 57 DiscoverySessions 58 DiscoveryTargetNames 59 ProtectinganiSCSISAN 59 ProtectingTransmittedData 59 SecuringiSCSIPorts 60 SettingiSCSICHAP 60 CommandSyntaxforesxcliiscsiandvicfgiscsi esxcliiscsiCommandSyntax 61 KeytoesxcliiscsiShortOptions 62 vicfgiscsiCommandSyntax 63

61

VMware, Inc.

Contents

iSCSIStorageSetupwithESXCLI 66 SettingUpSoftwareiSCSIwithESXCLI 66 SettingUpDependentHardwareiSCSIwithESXCLI 68 SettingUpIndependentHardwareiSCSIwithESXCLI 70 iSCSIStorageSetupwithvicfgiscsi 71 SettingUpSoftwareiSCSIwithvicfgiscsi 71 SettingUpDependentHardwareiSCSIwithvicfgiscsi 73 SettingUpIndependentHardwareiSCSIwithvicfgiscsi 74 ListingandSettingiSCSIOptions 75 ListingiSCSIOptionswithESXCLI 75 SettingMTUwithESXCLI 75 ListingandSettingiSCSIOptionswithvicfgiscsi 76 ListingandSettingiSCSIParameters 76 ListingandSettingiSCSIParameterswithESXCLI 77 ReturningParameterstoDefaultInheritance 78 ListingandSettingiSCSIParameterswithvicfgiscsi 78 ReturningParameterstoDefaultInheritance 79 EnablingiSCSIAuthentication 80 EnablingiSCSIAuthenticationwithESXCLI 80 EnablingiSCSIAuthenticationwithvicfgiscsi 81 SettingUpPortsforiSCSIMultipathing 81 ManagingiSCSISessions 82 IntroductiontoiSCSISessionManagement 82 ListingiSCSISessions 83 LoggingintoiSCSISessions 83 RemovingiSCSISessions 83

6 ManagingThirdPartyStorageArrays 85
ManagingNMPwithesxclistoragenmp 85 DeviceManagementwithesxclistoragenmpdevice 86 esxclistoragenmpdevicelist 86 esxclistoragenmpdeviceset 86 ListingPathswithesxclistoragenmppath 86 ManagingPathSelectionPolicyPluginswithesxclistoragenmppsp 86 RetrievingPSPInformation 87 SettingConfigurationParametersforThirdPartyExtensions 87 FixedPathSelectionPolicyOperations 88 RetrievingthePreferredPath 88 SettingthePreferredPath 88 CustomizingRoundRobinSetup 88 RetrievingPathSelectionSettings 89 SpecifyingConditionsforPathChanges 89 ManagingSATPs 89 RetrievingInformationAboutSATPs 89 AddingSATPRules 90 RemovingSATPRules 91 RetrievingandSettingSATPConfigurationParameters 91 PathClaimingwithesxclistoragecoreclaiming 92 UsingtheReclaimTroubleshootingCommand 92 UnclaimingPathsorSetsofPaths 92 ManagingClaimRules 93 AddingClaimRules 93 ConvertingESX3.5LUNMaskstoClaimRuleFormat 95 RemovingClaimRules 96 ListingClaimRules 96
VMware, Inc. 5

vSphere Command-Line Interface Concepts and Examples

LoadingClaimRules 96 MovingClaimRules 97 RunningPathClaimingRules 97

7 ManagingUsers 99
UsersinthevSphereEnvironment 99 vicfguserCommandSyntax 99 ManagingUserswithvicfguser 100 102

8 ManagingVirtualMachines 103
vmwarecmdOverview 103 ConnectionOptionsforvmwarecmd 104 GeneralOptionsforvmwarecmd 104 FormatforSpecifyingVirtualMachines 104 ListingandRegisteringVirtualMachines 104 RetrievingVirtualMachineAttributes 105 ManagingVirtualMachineSnapshotswithvmwarecmd 106 TakingVirtualMachineSnapshots 107 RevertingandRemovingSnapshots 107 PoweringVirtualMachinesOnandOff 107 ConnectingandDisconnectingVirtualDevices 108 WorkingwiththeAnswerVMAPI 109 ForciblyStoppingVirtualMachineswithEXCLI 109

9 ManagingvSphereNetworking 111
IntroductiontovSphereNetworking 111 NetworkingUsingvSphereStandardSwitches 112 NetworkingUsingvSphereDistributedSwitches 113 RetrievingBasicNetworkingInformation 113 NetworkTroubleshooting 114 SettingUpvSphereNetworkingwithvSphereStandardSwitches 115 SettingUpVirtualSwitchesandAssociatingaSwitchwithaNetworkInterface 115 RetrievingInformationAboutVirtualSwitches 116 RetrievingInformationaboutVirtualSwitcheswithESXCLI 116 RetrievingInformationaboutVirtualSwitcheswithvicfgvswitch 116 AddingandDeletingVirtualSwitches 117 AddingandDeletingVirtualSwitcheswithESXCLI 117 AddingandDeletingVirtualSwitcheswithvicfgvswitch 117 SettingSwitchAttributeswithesxclinetworkvswitchstandard 117 SettingSwitchAttributeswithvicfgvswitch 118 Checking,Adding,andRemovingPortGroups 118 ManagingPortGroupswithESXCLI 118 ManagingPortGroupswithvicfgvswitch 118 ManagingUplinksandPortGroups 119 ConnectingandDisconnectingUplinkAdaptersandPortGroupswithESXCLI 119 ConnectingandDisconnectingUplinksandPortGroupswithvicfgvswitch 119 SettingthePortGroupVLANID 119 SettingthePortGroupVLANIDwithESXCLI 119 SettingthePortGroupVLANIDwithvicfgvswitch 120 ManagingUplinkAdapters 120 ManagingUplinkAdapterswithesxclinetworknic 120 SpecifyingMultipleUplinkswithESXCLI 121

VMware, Inc.

Contents

ManagingUplinkAdapterswithvicfgnics 122 LinkingandUnlinkingUplinkAdapterswithESXCLI 122 LinkingandUnlinkingUplinkAdapterswithvicfgvswitch 122 AddingandModifyingVMkernelNetworkInterfaces 123 ManagingVMkernelNetworkInterfaceswithESXCLI 123 ManagingVMkernelNetworkInterfaceswithvicfgvmknic 124 SettingUpvSphereNetworkingwithvSphereDistributedSwitch 126 ManagingStandardNetworkingServicesinthevSphereEnvironment 126 SettingtheDNSConfiguration 126 SettingtheDNSConfigurationwithESXCLI 126 SettingtheDNSConfigurationwithvicfgdns 128 AddingandStartinganNTPServer 129 ManagingtheIPGateway 129 SettingUpIPsec 130 UsingIPsecwithESXi 130 ManagingSecurityAssociations 131 ManagingSecurityPolicies 132 ManagingtheESXiFirewall 133

10 MonitoringESXiHosts 135
UsingresxtopforPerformanceMonitoring 135 ManagingDiagnosticPartitions 135 DiagnosticPartitionCreation 136 DiagnosticPartitionManagement 136 ManagingCoreDumps 136 ManagingLocalCoreDumpswithESXCLI 136 ManagingCoreDumpswithESXiDumpCollector 137 ManagingCoreDumpswithvicfgdumppart 137 ConfiguringESXiSyslogServices 138 ManagingESXiSNMPAgents 139 ConfiguringSNMPCommunities 140 ConfiguringtheSNMPAgenttoSendTraps 140 ConfiguringtheSNMPAgentforPolling 141 RetrievingHardwareInformation 141 ESX,ESXi,andVirtualMachineLogs 142

Index 143

VMware, Inc.

Contents

VMware, Inc.

About This Book

ThevSphereCommandLineInterfaceConceptsandExamplesdocumentationexplainshowtousetheVMware vSphereCommandLineInterface(vCLI)andincludescommandoverviewsandexamples.

Intended Audience
ThisbookisforexperiencedWindowsorLinuxsystemadministratorswhoarefamiliarwithvSphere administrationtasksanddatacenteroperationsandknowhowtousecommandsinscripts.

VMware Technical Publications Glossary


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

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

Related Documentation
ThevSphereCommandLineInterfaceReference,availableinthevSphereDocumentationCenter,includes referenceinformationforvicfg-commandsandESXCLIcommands. GettingStartedwithvSphereCommandLineInterfacesincludesinformationaboutavailableCLIs,enablingthe ESXiShell,andinstallingandrunningvCLIcommands.AnappendixsuppliestheESXCLInamespaceand commandhierarchies. CommandLineManagementinvSphere5forServiceConsoleUsersisforcustomerswhocurrentlyusethe ESX ServiceConsole. ThevSphereSDKforPerldocumentationexplainshowyoucanusethevSphereSDKforPerlandrelated utilityapplicationstomanageyourvSphereenvironment.ThedocumentationincludesanInstallationGuide,a ProgrammingGuide,andareferencetothevSphereSDKforPerlUtilityApplications. BackgroundinformationforthetasksdiscussedinthismanualisavailableinthevSpheredocumentationset. ThevSpheredocumentationconsistsofthecombinedvCenterServerandESXidocumentationandincludes informationaboutmanagingstorage,networkingvirtualmachines,andmore.

Technical Support and Education Resources


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

VMware, Inc.

vSphere Command-Line Interface Concepts and Examples

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.

10

VMware, Inc.

vSphere CLI Command Overviews

Thischapterintroducesthecommandset,presentssupportedcommandsfordifferentversionsofvSphere, listsconnectionoptions,anddiscussesvCLIandlockdownmode. Thischapterincludesthefollowingtopics:


Introductiononpage 11 ListofAvailableCommandsonpage 12 SupportedProtocolsandPlatformsforCommandsonpage 14 RunningESXCLICommandsAgainstESXi4.xHostsonpage 16 CommandswithanesxcfgPrefixonpage 16 UsingESXCLIOutputonpage 17 ConnectionOptionsonpage 17 vCLIandLockdownModeonpage 19

Introduction
ThevSphereCLIcommandset,availablesinceESX/ESXi3.5,allowsyoutoperformvSphereconfiguration tasksusingavCLIpackageinstalledonsupportedplatforms,orusingvMA.Thesetconsistsofseveral commandsets. Table 1-1. Components of the vSphere CLI Command Set
vCLI Commands ESXCLIcommands Description ComprehensivesetofcommandsformanagingmostaspectsofvSphere.InvSphere5.0,this commandsethasbeenunified.Eventually,ESXCLIcommandswillreplaceothercommands inthevCLIset. CompletelyequivalentESXCLIcommandsareavailableintheESXiShell.UsevCLIESXCLI commandsforasaferenvironment. vicfg- commands SetofcommandsformanyaspectsofvSphere.InvSphere5.0,onlyminorchangesweremade tothiscommandset.Eventually,thesecommandswillbereplacedbyESXCLIcommands. Asetofesxcfg-commandsthatpreciselymirrorsthevicfg-commandsisalsoincludedin thevCLIpackage. Othercommands (vmware-cmd,vifs, vmkfstools) CommandsimplementedinPerlthatdonothaveavicfg-prefix.AllvCLIcommandsare scheduledtobereplacedbyESXCLIcommands.

YoucaninstallthevSphereCLIcommandsetonasupportedLinuxorWindowssystem.SeeGettingStarted withvSphereCommandLineInterfaces.YoucanalsodeploythevSphereManagementAssistant(vMA)toan ESXisystemofyourchoice.ManageESXihostsfromtheLinuxorWindowssystemorfromvMAbyrunning vCLIcommandswithconnectionoptionssuchasthetargethost,user,andpasswordoraconfigurationfile. SeeConnectionOptionsonpage 17.


VMware, Inc. 11

vSphere Command-Line Interface Concepts and Examples

Documentation
GettingStartedwithvSphereCommandLineInterfacesincludesinformationaboutavailableCLIs,enablingthe ESXiShell,andinstallingandrunningvCLIcommands.Anappendixsuppliesthenamespaceandcommand hierarchiesforESXCLI. ReferenceinformationforvCLIcommandsisavailableonthevCLIdocumentationpage http://www.vmware.com/support/developer/vcli/.

vSphereCommandLineInterfaceReferenceisareferencetovicfg-andrelatedvCLIcommandsand includesreferenceinformationforESXCLIcommands.Allreferenceinformationisgeneratedfromthe help. AreferencetoesxtopandresxtopisincludedintheResourceManagementdocumentation.

Command-Line Help
Availablecommandlinehelpdiffersforthedifferentcommands.
Command set vicfgcommands Available Command-Line Help Run<vicfg-cmd> --helpforanoverviewofeachoptions. RunPod2Htmlwithavicfgcommandasinputandpipetheoutputtoafileformoredetailed helpinformation. pod2html vicfg-authconfig.pl > vicfg-authconfig.html ThisoutputcorrespondstotheinformationavailableinthevSphereCommandLineInterface Reference. ESXCLIcommands Run--helpatanylevelofthehierarchyforinformationaboutbothcommandsand namespacesavailablefromthatlevel.

List of Available Commands


Table 12listsallESX/ESXi4.1vCLIcommandsinalphabeticalorderandthecorrespondingESXCLIcommand ifavailable.NonewvicfgcommandswereaddedinvSphere5.0.Manynewnamespaceswereaddedto ESXCLIinvSphere5.0.AnadditionalsetofnewcommandsandnamespaceswasaddedinvSphere5.1. Table 1-2. vCLI and ESXCLI Commands
vCLI 4.1 Command esxcli vCLI 5.1 Command esxcli(newsyntax) Comment AllvCLI4.1commandshavebeenrenamed.Significantadditionshavebeen madetoESXCLI.Manytaskspreviouslyperformedwithavicfg-command isnowperformedwithESXCLI. MonitorsinrealtimehowESXihostsuseresources.Runsininteractiveor batchmode. SeeUsingresxtopforPerformanceMonitoringonpage 135.SeethevSphere ResourceManagementdocumentationforadetailedreference. Movesavirtualmachinesconfigurationfile,and,optionally,itsdisks,while thevirtualmachineisrunning. SeeMigratingVirtualMachineswithsvmotiononpage 52. Performsadvancedconfiguration. TheadvancedsettingsareasetofVMkerneloptions.Theseoptionsare typicallyinplaceforspecificworkaroundsordebugging. UsethiscommandasinstructedbyVMware. vicfg-authconfig vicfg-authconfig(No ESXCLIequivalent). vicfg-cfgbackup(No ESXCLIequivalent), Cannotrunagainsta vCenterServersystem. RemotelyconfiguresActiveDirectorysettingsforanESXihost. SeeUsingvicfgauthconfigforActiveDirectoryConfigurationonpage 25. BacksuptheconfigurationdataofanESXisystemandrestorespreviously savedconfigurationdata. SeeBackingUpConfigurationInformationwithvicfgcfgbackupon page 23.
VMware, Inc.

resxtop

resxtop(NoESXCLI equivalent) Supportedonlyon Linux.

svmotion

svmotion(NoESXCLI equivalent) Mustrunagainsta vCenterServersystem.

vicfg-advcfg

esxcli system settings advanced

vicfg-cfgbackup

12

Chapter 1 vSphere CLI Command Overviews

Table 1-2. vCLI and ESXCLI Commands (Continued)


vCLI 4.1 Command vicfg-dns vicfg-dumppart vCLI 5.1 Command esxcli network ip dns esxcli system coredump Comment SpecifiesanESXihostsDNS(DomainNameServer)configuration.See SettingtheDNSConfigurationonpage 126. Setsboththepartition(esxcli system coredump partition)andthe network(esxcli system coredump network)touseforcoredumps.Use thiscommandtosetupESXiDumpCollector. ManagingDiagnosticPartitionsonpage 135. vicfg-hostops esxcli system maintenancemode esxcli system shutdown vicfg-ipsec esxcli network ip ipsec Manageshosts. Stopping,Rebooting,andExaminingHostsonpage 21. EnteringandExitingMaintenanceModeonpage 22. SetsupIPsec(InternetProtocolSecurity),whichsecuresIPcommunications comingfromandarrivingatESXihosts.ESXihostssupportIPsecusingIPv6. SeeSettingUpIPseconpage 130. vicfg-iscsi esxcli iscsi ManageshardwareandsoftwareiSCSIstorage. SeeManagingiSCSIStorageonpage 57. vicfg-module esxcli system module EnablesVMkerneloptions.Usethiscommandwiththeoptionslistedinthis document,orasinstructedbyVMware. SeeManagingVMkernelModulesonpage 24. vicfg-mpath vicfg-mpath35 vicfg-nas vicfg-nics vicfg-ntp vicfg-rescan vicfg-route vicfg-scsidevs vicfg-snmp esxcli storage core path esxcli storage nfs esxcli network nic vicfg-ntp(NoESXCLI equivalent) esxcli storage core adapter rescan esxcli network ip route) esxcli storage core device esxcli system snmp Configuresstoragearrays. ManagingPathsonpage 44. ManagesNAS/NFSfilesystems.SeeManagingNFS/NASDatastoreson page 50. ManagestheESXihostsuplinkadapters.SeeManagingUplinkAdapters onpage 120. DefinestheNTP(NetworkTimeProtocol)server.SeeAddingandStartingan NTPServeronpage 129. Rescansthestorageconfiguration.SeeScanningStorageAdapterson page 55. ManagestheESXihostsrouteentry.SeeManagingtheIPGatewayon page 129. FindsandexaminesavailableLUNs.SeeExaminingLUNsonpage 42. ManagestheSNMPagent.ManagingESXiSNMPAgentsonpage 139. UsingSNMPinavSphereenvironmentisdiscussedindetailinthevSphere MonitoringandPerformancedocumentation. NewoptionsaddedinvCLI5.0. ExpandedSNMPsupportaddedinvCLI5.1. vicfg-syslog esxcli system syslog SpecifieslogsettingsforESXihostsincludinglocalstoragepoliciesandserver andportinformationfornetworklogging.SeeConfiguringESXiSyslog Servicesonpage 138. ThevCenterServerandHostManagementdocumentationexplainshowtosetup systemlogsusingthevSphereWebClient. vicfg-user vicfg-user(No ESXCLIequivalent) Creates,modifies,deletes,andlistslocaldirectaccessusersandgroupsof users.SeeManagingUsersonpage 99. ThevSphereSecuritydocumentationdiscussessecurityimplicationsofuser managementandcustomroles. vicfg-vmknic vicfg-volume esxcli network ip interface. esxcli storage filesystem Adds,deletes,andmodifiesVMkernelnetworkinterfaces.SeeAddingand ModifyingVMkernelNetworkInterfacesonpage 123. SupportsresignaturingthecopyofaVMFSvolume,andmountingand unmountingthecopy.SeeManagingDuplicateVMFSDatastoreson page 29.

VMware, Inc.

13

vSphere Command-Line Interface Concepts and Examples

Table 1-2. vCLI and ESXCLI Commands (Continued)


vCLI 4.1 Command vicfg-vswitch vCLI 5.1 Command esxcli network vswitch vifs(NoESXCLI equivalent) Runesxcli software vibagainstESXi5.0and later. Runvihostupdate againstESX/ESXi4.x. Runvihostupdate35 againstESX/ESXi3.5. vmkfstools vmkfstools(No ESXCLIequivalent) vmware-cmd(No ESXCLIequivalent) Createsandmanipulatesvirtualdisks,filesystems,logicalvolumes,and physicalstoragedevicesonanESXihost.SeeManagingtheVirtualMachine FileSystemwithvmkfstoolsonpage 28. Performsvirtualmachineoperationsremotely.Thisincludes,forexample, creatingasnapshot,poweringthevirtualmachineonoroff,andgetting informationaboutthevirtualmachine.SeeManagingVirtualMachineson page 103. Comment Addsorremovesvirtualswitchesormodifiesvirtualswitchsettings.See SettingUpVirtualSwitchesandAssociatingaSwitchwithaNetwork Interfaceonpage 115. Performsfilesystemoperationssuchasretrievinganduploadingfilesonthe ESXisystem.SeeManagingtheVirtualMachineFileSystemwith vmkfstoolsonpage 28. UpdatesESXihoststoadifferentversionofthesamemajorrelease. YoucannotrunvihostupdateagainstESXi5.0andlaterhosts. SeeManagingVMkernelModulesonpage 24.

vifs

vihostupdate vihostupdate35

vmware-cmd

Supported Protocols and Platforms for Commands


TheresxtopcommandrequiresanHTTPSconnection.AllothercommandssupportHTTPandHTTPS. MostvCLIcommandscanrunagainstanESXisystemoragainstvCenterServer.vCenterServersupport meansthatyoucanconnecttoavCenterServersystemanduse--vihosttospecifytheESXihosttorunthe commandagainst.Theonlyexceptionissvmotion,whichyoucanrunagainstvCenterServersystems,but notagainstESXisystems. ThefollowingcommandsmusthaveanESXisystem,notavCenterServersystemtarget.

vicfg-snmp vifs vicfg-user vicfg-cfgbackup vihostupdate vmkfstools vicfg-ipsec

YoucannotrunthevihostupdatecommandagainstanESXi5.0orlatersystem. Youcannotrunthevihostupdateandvicfg-mpathcommandsthatareinavCLI4.0orlaterinstallation againstESX/ESXi3.5orvCenter2.5systems.Instead,runvihostupdate35andvicfg-mpath35,includedin thevCLI4.xinstallation,againstthosesystems.vihostupdate35issupportedforESXi,butnotforESX. Youcannotrunvicfg-syslog --setserverorvicfg-syslog --setportwithanESXi5.0orlatertarget.

14

VMware, Inc.

Chapter 1 vSphere CLI Command Overviews

IMPORTANTIfyourunvCLI4.xcommandsagainstESX/ESXi3.5systems,youcanuseonlytheoptions supportedbythosesystems. SeetheVMwareInfrastructureRemoteCommandLineInterfaceInstallationandReferenceGuideforESX/ESXi3.5 Update2foralistofsupportedoptions.Toaccessthatdocument,selectResources>Documentationfromthe VMwarewebsite.FindthevSpheredocumentationsetandopenthearchive.AfewvCLI4.xoptionsare supportedagainsthostsrunningESX/ESXi3.5Update2orlatereventhoughtheywerenotsupportedinRCLI version3.5. RunavCLI4.xcommandwith--helpforinformationaboutoptionsupportwithESX/ESXi3.5Update 2,or seetheVMwareknowledgebasearticleathttp://kb.vmware.com/kb/1008940formoredetail. Table 13listsplatformsupportforthedifferentvCLI5.xcommands.Thesecommandshavenotbeentested againstVirtualCenter2.5Update2systems.Youcan,however,connecttoavCenterServer4.xsystemand targetESX/ESXi3.5Update2hosts. Table 1-3. Platform Support for vCLI 5.x Commands
Command esxcli resxtop svmotion vicfg-advcfg vicfg-authconfig vicfg-cfgbackup vicfg-dns vicfg-dumppart vicfg-hostops vicfg-ipsec vicfg-iscsi vicfg-module vicfg-mpath vicfg-nas vicfg-nics vicfg-ntp vicfg-rescan vicfg-route vicfg-scsidevs vicfg-snmp vicfg-syslog vicfg-user vicfg-vmhbadevs vicfg-vmknic vicfg-volume vicfg-vswitch vifs ESXi 5.x Yes Yes(from Linux) No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes VC 5.x Yes Yes(from Linux) Yes Yes Yes No Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes Yes No Nofor5.0 target No ESXi 4.x Yes Yes(from Linux) No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes ESX 4.x Yes Yes(from Linux) No Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes VC 4.x No Yes(from Linux) Yes Yes Yes No Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes Yes No Yes No ESXi 3.5 U2+ No Yes(from Linux) No Yes No Yes Yes Yes No No No Yes ESX 3.5 U2+ No Yes(from Linux) No Yes No No Yes Yes No No No Yes

Usevicfg-mpath35instead. Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes No Yes No Yes Yes Yes No Yes Yes

NotincludedinvCLI4.xandvCLI5.0.Usevicfg-scsidevsinstead. Yes Yes Yes Yes Yes Yes Yes No Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes Yes No

VMware, Inc.

15

vSphere Command-Line Interface Concepts and Examples

Table 1-3. Platform Support for vCLI 5.x Commands (Continued)


Command vihostupdate ESXi 5.x VC 5.x ESXi 4.x Yes ESX 4.x Yes VC 4.x No ESXi 3.5 U2+ Use vihostupdate35 instead Yes Yes Yes Yes ESX 3.5 U2+ No

Useesxcli software vibinstead. Yes Yes No No No Yes No No

vmkfstools vmware-cmd vicfg-mpath35 vihostupdate35

Yes Yes No No

Yes Yes No No

No Yes No No

Yes Yes Yes No

Running ESXCLI Commands Against ESXi 4.x Hosts


WhenyourunanESXCLIvCLIcommand,youmustknowthecommandssupportedonthetargethost.

IfyouruncommandsagainstESXi4.xhosts,ESXCLI4.xcommandsaresupported. IfyouruncommandsagainstESXi5.0hosts,ESXCLI5.0commandsaresupported.

Youspecifythetargethostwith--serverorsetupavMAtarget. Somecommandsorcommandoutputsaredeterminedbythehosttype.Inaddition,VMwarepartnersmight developcustomESXCLIcommandsthatyoucanrunonhostswherethepartnerVIBhasbeeninstalled. Runesxcli --server <target> --helpforalistofnamespacessupportedonthetarget.Youcandrill downintothenamespacesforadditionalhelp. IMPORTANTESXCLIonESX4.xhostsdoesnotsupporttargetingavCenterServersystem.Youcantherefore notrunESXCLIcommandswith--serverpointingtoavCenterServersystemevenifyouinstallvCLI5.0.

Commands with an esxcfg Prefix


FormanyofthevCLIcommands,youmighthaveusedscriptswithcorrespondingserviceconsolecommands startingwithanesxcfgprefixtomanageESX3.xhosts.TofacilitateeasymigrationfromESX/ESXi3.xtolater versionsofESXi,thevCLIpackageincludesacopyofeachvicfg-commandthatusesanesxcfg-prefix. IMPORTANTVMwarerecommendsthatyouuseESXCLIorthevCLIcommandswiththevicfgprefix. Commandswiththeesxcfgprefixareavailablemainlyforcompatibilityreasonsandmightbecomeobsolete. vCLIesxcfg-commandsareequivalenttovicfg-commands,butnotcompletelyequivalenttothe deprecatedesxcfg- serviceconsolecommands. Table 14listsallvCLIcommandsforwhichavCLIcommandwithanesxcfgprefixisavailable. Table 1-4. Commands with an esxcfg Prefix
Command with vicfg prefix vicfg-advcfg vicfg-cfgbackup vicfg-dns vicfg-dumppart vicfg-module vicfg-mpath vicfg-nas vicfg-nics vicfg-ntp Command with esxcfg prefix esxcfg-advcfg esxcfg-cfgbackup esxcfg-dns esxcfg-dumppart esxcfg-module esxcfg-mpath esxcfg-nas esxcfg-nics esxcfg-ntp

16

VMware, Inc.

Chapter 1 vSphere CLI Command Overviews

Table 1-4. Commands with an esxcfg Prefix (Continued)


Command with vicfg prefix vicfg-rescan vicfg-route vicfg-scsidevs vicfg-snmp vicfg-syslog vicfg-vmknic vicfg-volume vicfg-vswitch Command with esxcfg prefix esxcfg-rescan esxcfg-route esxcfg-scsidevs esxcfg-snmp esxcfg-syslog esxcfg-vmknic esxcfg-volume esxcfg-vswitch

Using ESXCLI Output


ManyESXCLIcommandsgenerateoutputyoumightwanttouseinyourapplication.Youcanrunesxcli withthe--formatterdispatcheroptionandsendtheresultingoutputasinputtoaparser. The--formatteroptionssupportsthreevalues,csv,xml,andkeyvalueandisusedbeforeanynamespace.
esxcli --formatter=csv storage filesystem list

ListsallfilesysteminformationinCSVformat. Youcanpipetheoutputtoafile.
esxcli --formatter=keyvalue storage filesystem list > myfilesystemlist.txt

IMPORTANTAlwaysuseaformatterforconsistentoutput.

Connection Options
Table 15listsoptionsthatareavailableforallvCLIcommandsinalphabeticalorder.Examplesinthisbook use<conn_options>toindicatethepositionofconnectionoptions. Forexample,esxcli <conn_options> filesystem nfs listmeansthatyoucoulduseaconfiguration file,asessionfile,orjustspecifyatargetserverandrespondwithausernameandpasswordwhenprompted. Thetableincludesoptionsforuseonthecommandlineandvariablesforuseinconfigurationfiles. IMPORTANTForconnections,vCLIsupportsonlytheIPv4protocol,nottheIPv6protocol.Youcan,however, configureIPv6onthetargethostwithseveralofthenetworkingcommands. SeetheGettingStartedwithvSphereCommandLineInterfacesdocumentationforadditionalinformationand examples. Table 1-5. vCLI Connection Options
Option and Environment Variable --cacertsfile <certsfile> -t <certs_file> VI_CACERTFILE=<cert_file_path> --config <cfg_file_full_path> VI_CONFIG=<cfg_file_full_path> Description ESXCLIcommandsonly. UsedtospecifytheCA(CertificateAuthority)certificatefile,inPEMformat, toverifytheidentityofthevCenterServersystemorESXisystemtorunthe commandon.Canbeused,forexample,topreventmaninthemiddleattack. Usestheconfigurationfileatthespecifiedlocation. Specifyapaththatisreadablefromthecurrentdirectory.

VMware, Inc.

17

vSphere Command-Line Interface Concepts and Examples

Table 1-5. vCLI Connection Options (Continued)


Option and Environment Variable --credstore <credstore> Description Nameofacredentialstorefile.Defaultsto <HOME>/.vmware/credstore/vicredentials.xmlonLinuxand <APPDATA>/VMware/credstore/vicredentials.xmlonWindows. CommandsforsettingupthecredentialstoreareincludedinthevSphere SDKforPerl,whichisinstalledwithvCLI.ThevSphereSDKforPerl ProgrammingGuideexplainshowtomanagethecredentialstore. Specifiestheencodingtobeused.Thefollowingencodingsaresupported.

--encoding <encoding> 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> VI_PASSWORD=<passwd> Usesthespecifiedpassword(usedwith--username)tologintotheserver.

If--serverspecifiesavCenterServersystem,theusernameand passwordapplytothatserver.IfyoucanlogintothevCenterServer system,youneednoadditionalauthenticationtoruncommandsonthe ESXihoststhatservermanages. 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> --server <server> VI_SERVER=<server> Usesthespecifiedporttoconnecttothesystemspecifiedby--server. Defaultis443. Usesthespecifiedprotocoltoconnecttothesystemspecifiedby--server. DefaultisHTTPS. Savesasessiontothespecifiedfile.Thesessionexpiresifitisnotusedfor30 minutes. UsesthespecifiedESXiorvCenterServersystem.Defaultislocalhost. If--serverpointstoavCenterServersystem,youusethe--vihostoption tospecifytheESXihostonwhichyouwanttorunthecommand.Acommand issupportedforvCenterServerifthe--vihostoptionisdefined. UsesthespecifiedservicepathtoconnecttotheESXihost.Defaultis /sdk/webService. Usesthespecifiedsessionfiletoloadapreviouslysavedsession.Thesession mustbeunexpired. ConnectstothespecifiedvSphereWebServicesSDKURL.

--servicepath <path> VI_SERVICEPATH=<path> --sessionfile <file> VI_SESSIONFILE=<file> --url <url> VI_URL=<url>

18

VMware, Inc.

Chapter 1 vSphere CLI Command Overviews

Table 1-5. vCLI Connection Options (Continued)


Option and Environment Variable --username <u_name> VI_USERNAME=<u_name> Description Usesthespecifiedusername.

If--serverspecifiesavCenterServersystem,theusernameand passwordapplytothatserver.IfyoucanlogintothevCenterServer system,youneednoadditionalauthenticationtoruncommandsonthe ESXihoststhatservermanages. If--serverspecifiesanESXisystem,theusernameandpasswordapply tothatsystem.

Ifyoudonotspecifyausernameandpasswordonthecommandline,the systempromptsyouanddoesnotechoyourinputtothescreen. --vihost <host> -h <host WhenyourunavSphereCLIcommandwiththe--serveroptionpointing toavCenterServersystem,use--vihosttospecifytheESXihosttorunthe commandagainst. NOTE:Thisoptionisnotsupportedforeachcommand.Ifsupported,the optionisincludedintheindividualcommandoptionlist.

vCLI and Lockdown Mode


Foradditionalsecurity,anadministratorcanplaceoneormorehostsmanagedbyavCenterServersystemin lockdownmode.LockdownmodeaffectsloginprivilegesfortheESXihost.

UsersthatwereloggedintotheESXiShellbeforelockdownmodewasenabledremainloggedinandcan runcommands,however,thoseuserscannotdisablelockdownmode. Nootherusers,includingtherootusers,canlogintoanESXiShellinlockdownmode.Youcannolonger accesstheshellfromthedirectconsoleorbyusingaremoteshell.

Youcandisablelockdownmodeasfollows.

TheadministratoruseronthevCenterServersystemcandisablelockdownmodeforhostsitmanages fromthevCenterServersystem. TherootusercanalwayslogindirectlytotheESXihostsdirectconsoletodisablelockdownmode.Ifthe directconsoleisdisabled,theadministratoronthevCenterServersystemcandisablelockdownmode.If thehostisnotmanagedbyavCenterServersystemorifthehostisunreachable,youmustreinstallESXi.

TomakechangestoESXisystemsinlockdownmode,youmustgothroughavCenterServersystemthat managestheESXisystemastheuservpxuser. esxcli --server MyVC --vihost MyESXi storage filesystem list ThecommandpromptsforthevCenterServersystemusernameandpassword. YoucanusethevSphereWebClientorvCLIcommandsthatsupportthe--vihostoption.Thefollowing commandscannotrunagainstvCenterServersystemsandarethereforenotavailableinlockdownmode:

vicfg-snmp vifs vicfg-user vicfg-cfgbackup vihostupdate vmkfstools vicfg-ipsec

IfyouhaveproblemsrunningacommandonanESXihostdirectly(withoutspecifyingavCenterServer target),checkwhetherlockdownmodeisenabledonthathost. ThevSphereSecuritydocumentationdiscusseslockdownmodeindetail.

VMware, Inc.

19

vSphere Command-Line Interface Concepts and Examples

20

VMware, Inc.

Managing Hosts

HostmanagementcommandscanstopandrebootESXihosts,backupconfigurationinformation,andmanage hostupdates.YoucanalsouseahostmanagementcommandtomakeyourhostjoinanActiveDirectory domainorexitfromadomain. Thechapterincludesthefollowingtopics:


Stopping,Rebooting,andExaminingHostsonpage 21 EnteringandExitingMaintenanceModeonpage 22 BackingUpConfigurationInformationwithvicfgcfgbackuponpage 23 ManagingVMkernelModulesonpage 24 UsingvicfgauthconfigforActiveDirectoryConfigurationonpage 25 UpdatingHostsonpage 26

ForinformationonupdatingESXi5.0hostswiththeesxcli softwarecommandandonchangingthehost acceptanceleveltomatchthelevelofaVIBthatyoumightwanttouseforanupdate,seethevSphereUpgrade documentation.

Stopping, Rebooting, and Examining Hosts


Youcanstop,reboot,andexaminehostswithESXCLIorwithvicfg-hostops.

Stopping and Rebooting Hosts with ESXCLI


YoucanshutdownorrebootanESXihostusingthevSphereWebClientorvCLIcommands(ESXCLIor vicfg-hostops). ShuttingdownamanagedhostdisconnectsitfromthevCenterServersystem,butdoesnotremovethehost fromtheinventory.Youcanshutdownasinglehostorallhostsinadatacenterorcluster.Specifyoneofthe optionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. Toshutdownahost,runesxcli system shutdown poweroff.Youmustspecifythe--reasonoptionand supplyareasonfortheshutdown.A--delayoptionallowsyoutospecifyadelayinterval,inseconds. Torebootahost,runsystem shutdown reboot. Youmustspecifythe--reasonoptionandsupplyareason fortheshutdown.A--delayoptionallowsyoutospecifyadelayinterval,inseconds.

Stopping, Rebooting, and Examining Hosts with vicfg-hostops


YoucanshutdownorrebootanESXihostusingthevSphereWebClient,orESXCLIorvicfg-hostopsvCLI command.

VMware, Inc.

21

vSphere Command-Line Interface Concepts and Examples

ShuttingdownamanagedhostdisconnectsitfromthevCenterServersystem,butdoesnotremovethehost fromtheinventory.Youcanshutdownasinglehostorallhostsinadatacenterorcluster.Specifyoneofthe optionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Singlehost.Runvicfg-hostopswith--operationshutdown.

Ifthehostisinmaintenancemode,runthecommandwithoutthe--forceoption.
vicfg-hostops <conn_options> --operation shutdown

Ifthehostisnotinmaintenancemode,use--forcetoshutdownthehostandallrunningvirtual machines.
vicfg-hostops <conn_options> --operation shutdown --force

Allhostsindatacenterorcluster.Toshutdownallhostsinaclusterordatacenter,specify--clusteror --datacenter.
vicfg-hostops <conn_options> --operation shutdown --cluster <my_cluster> vicfg-hostops <conn_options> --operation shutdown --datacenter <my_datacenter>

Youcanrebootasinglehostorallhostsinadatacenterorcluster.

Singlehost.Runvicfg-hostopswith--operationreboot.

Ifthehostisinmaintenancemode,runthecommandwithoutthe--forceoption.
vicfg-hostops <conn_options> --operation reboot

Ifthehostisnotinmaintenancemode,use--forcetoshutdownthehostandallrunningvirtual machines.
vicfg-hostops <conn_options> --operation reboot --force

Allhostsindatacenterorcluster.Youcanspecify--clusteror--datacentertorebootallhostsina clusterordatacenter.
vicfg-hostops <conn_options> --operation reboot --cluster <my_cluster> vicfg-hostops <conn_options> --operation reboot --datacenter <my_datacenter>

Youcandisplayinformationaboutahostbyrunningvicfg-hostopswith--operationinfo.
vicfg-hostops <conn_options> --operation info

Thecommandreturnsthehostname,manufacturer,model,processortype,CPUcores,memorycapacity,and boottime.ThecommandalsoreturnswhethervMotionisenabledandwhetherthehostisinmaintenance mode.

Entering and Exiting Maintenance Mode


YoucaninstructyourhosttoenterorexitmaintenancemodewithESXCLIorwithvicfg-hostops.

Entering and Exiting Maintenance Mode with ESXCLI


Youplaceahostinmaintenancemodetoserviceit,forexample,toinstallmorememory.Ahostentersor leavesmaintenancemodeonlyastheresultofauserrequest. esxcli system maintenanceMode setallowsyoutoenableordisablemaintenancemode. Whenyourunthevicfg-hostopsvCLIcommand,youcanspecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To enter and exit maintenance mode 1 Runesxcli <conn_options> system maintenanceMode set --enable true toentermaintenance mode. Afterallvirtualmachinesonthehosthavebeensuspendedormigrated,thehostentersmaintenance mode.Youcannotdeployorpoweronavirtualmachineonhostsinmaintenancemode.

22

VMware, Inc.

Chapter 2 Managing Hosts

Runesxcli <conn_options> system maintenanceMode set --enable false tohaveahost existingmaintenancemode.

Ifyouattempttoexitmaintenancemodewhenthehostisnolongerinmaintenancemode,anerrorinforms youthatmaintenancemodeisalreadydisabled.

Entering and Exiting Maintenance Mode with vicfg-hostops


Youplaceahostinmaintenancemodetoserviceit,forexample,toinstallmorememory.Ahostentersor leavesmaintenancemodeonlyastheresultofauserrequest. vicfg-hostopssuspendsvirtualmachinesbydefault,orpowersoffthevirtualmachineifyourun vicfg-hostops --action poweroff. NOTEvicfg-hostopsdoesnotworkwithVMwareDRS.Virtualmachinesarealwayssuspended. ThehostisinastateofEnteringMaintenanceModeuntilallrunningvirtualmachinesaresuspendedor migrated.Whenahostisenteringmaintenancemode,youcannotpoweronvirtualmachinesonitormigrate virtualmachinestoit. Whenyourunthevicfg-hostopsvCLIcommand,youcanspecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To enter maintenance mode 1 2 Runvicfg-hostops <conn_options> --operation entertoentermaintenancemode. Runvicfg-hostops <conn_options> --operation infotocheckwhetherthehostisinmaintenance modeorintheEnteringMaintenanceModestate.

Afterallvirtualmachinesonthehosthavebeensuspendedormigrated,thehostentersmaintenancemode. Youcannotdeployorpoweronavirtualmachineonhostsinmaintenancemode. Youcanputallhostsinaclusterordatacenterinmaintenancemodebyusingthe--clusteror --datacenteroption.Donotusethoseoptionsunlesssuspendingallvirtualmachinesinthatclusteror datacenterisnoproblem. Youcanlaterrunvicfg-hostops <conn_options> --operation exittoexitmaintenancemode.

Backing Up Configuration Information with vicfg-cfgbackup


AfteryouconfigureanESXihost,youcanbackupthehostconfigurationdata.Alwaysbackupyourhost configurationafteryouchangetheconfigurationorupgradetheESXiimage. IMPORTANTThevicfg-cfgbackupcommandisavailableonlyforESXihosts.Thecommandisnotavailable throughavCenterServersystemconnection.NoequivalentESXCLIcommandissupported.

Backup Tasks
Duringaconfigurationbackup,theserialnumberisbackedupwiththeconfiguration.Thenumberisrestored whenyourestoretheconfiguration.ThenumberisnotpreservedwhenyouruntheRecoveryCD(ESXi Embedded)orperformarepairoperation(ESXiInstallable). Youcanbackupandrestoreconfigurationinformationasfollows. 1 2 3 Backuptheconfigurationbyusingthevicfg-cfgbackupcommand. RuntheRecoveryCDorrepairoperation Restoretheconfigurationbyusingthevicfg-cfgbackupcommand.

Whenyourestoreaconfiguration,youmustmakesurethatallvirtualmachinesonthehostarestopped.

VMware, Inc.

23

vSphere Command-Line Interface Concepts and Examples

Backing Up Configuration Data


Youcanbackupconfigurationdatabyrunningvicfg-cfgbackupwiththe-soption.
vicfg-cfgbackup <conn_options> -s /tmp/ESXi_181842_backup.txt

Forthebackupfilename,includethenumberofthebuildthatisrunningonthehostthatyouarebackingup. IfyouarerunningvCLIonvMA,thebackupfileissavedlocallyonvMA.Backupfilescansafelybestored locallybecausevirtualappliancesarestoredinthe/vmfs/volumes/<datastore>directoryonthehost, whichisseparatefromtheESXiimageandconfigurationfiles.

Restoring Configuration Data


Ifyouhavecreatedabackup,youcanlaterrestoreESXiconfigurationdata.Whenyourestoreconfiguration data,thenumberofthebuildrunningonthehostmustbethesameasthenumberofthebuildthatwas runningwhenyoucreatedthebackupfile.Tooverridethisrequirement,includethe-f (force)option. To restore ESXi configuration data 1 2 3 Poweroffallvirtualmachinesthatarerunningonthehostthatyouwanttorestore. LogintoahostonwhichvCLIisinstalled,orlogintovMA. Runvicfg-cfgbackupwiththe-lflagtoloadthehostconfigurationfromthespecifiedbackupfile. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Ifyourunthefollowingcommand,youarepromptedforconfirmation.
vicfg-cfgbackup <conn_options> -l /tmp/ESXi_181842_backup.tgz

Ifyourunthefollowingcommand,youarenotpromptedforconfirmation.
vicfg-cfgbackup <conn_options> -l /tmp/ESXi_181842_backup.tgz -q

Torestorethehosttofactorysettings,runvicfg-cfgbackupwiththe-roption:
vicfg-cfgbackup <conn_options> -r

Using vicfg-cfgbackup from vMA


Tobackupahostconfiguration,youcanrunvicfg-cfgbackupfromavMAinstance.ThevMAinstancecan runonthetargethost(thehostthatyouarebackinguporrestoring),oronaremotehost. Torestoreahostconfiguration,youmustrunvicfg-cfgbackup fromavMAinstancerunningonaremote host.Thehostmustbeinmaintenancemode,whichmeansallvirtualmachines(includingvMA)mustbe suspendedonthetargethost. Forexample,abackupoperationfortwoESXihosts(host1andhost2)withvMAdeployedonbothhosts worksasfollows:

Tobackuponeofthehostsconfiguration(host1orhost2),runvicfg-cfgbackupfromthevMA appliancerunningoneitherhost1orhost2.Usethe--serveroptiontospecifythehostforwhichyou wantbackupinformation.TheinformationisstoredonvMA. Torestorethehost1configuration,runvicfg-cfgbackupfromthevMAappliancerunningonhost2.Use the--serveroptiontopointtohost1torestoretheconfigurationtothathost. Torestorethehost2configuration,runvicfg-cfgbackupfromthevMAappliancerunningonhost1.Use the--serveroptiontopointtohost2torestoretheconfigurationtothathost.

Managing VMkernel Modules


Theesxcli system moduleandvicfg-modulecommandssupportsettingandretrievingVMkernelmodule options.

24

VMware, Inc.

Chapter 2 Managing Hosts

vicfg-moduleandesxcli system modulecommandsareimplementationsofthedeprecated esxcfg-moduleserviceconsolecommand.Thetwocommandssupportmostoftheoptionsesxcfg-module supports.vicfg-moduleandesxcli system modulearecommonlyusedwhenVMwareTechnicalSupport, aKnowledgeBasearticle,orVMwaredocumentationinstructyoutodoso.

Managing Modules with esxcli system module


NotallVMkernelmoduleshavesettablemoduleoptions.Thefollowingexampleillustrateshowtoexamine andenableaVMkernel.SpecifyoneoftheconnectionoptionslistedinConnectionOptionsonpage 17in placeof<conn_options>. To examine, enable, and set a VMkernel modules 1 Listinformationaboutthemodule.
esxcli <conn_options> system module list -module=module_name

Thesystemreturnsthename,type,value,anddescriptionofthemodule. 2 (Optional)Listallenabledorloadedmodules.
esxcli <conn_options> system module list --enabled=true esxcli <conn_options> system module list --loaded=true

Enablethemodel.
esxcli <conn_options> system module set --module=module_name --enabled=true

Settheparameter.
esxcli system module parameters set --module module_name --parameter-string="parameter_string"

Verifythatthemoduleisconfigured.
esxcli <conn_options> system module parameters list --module=module_name

Managing Modules with vicfg-module


NotallVMkernelmoduleshavesettablemoduleoptions.Thefollowingexampleillustrateshowtheexamine andenableaVMkernelmodules.SpecifyoneoftheconnectionoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. To examine and set a VMkernel modules 1 Runvicfg-module --listtolistthemodulesonthehost.
vicfg-module <conn_options> --list

Runvicfg-module --set-optionswithconnectionoptions,theoptionstringtobepassedtoamodule, andthemodulename.Forexample:


vicfg-module <conn_options> --set-options 'parameter_name=value' module_name

Toretrievetheoptionstringthatisconfiguredtobepassedtoamodulewhenthemoduleisloaded,run vicfg-module --get-options.Thisstringisnotnecessarilytheoptionstringcurrentlyinusebythe module.


vicfg-module <conn_options> --get-options module_name

Verifiesthatamoduleisconfigured.

Using vicfg-authconfig for Active Directory Configuration


vSphere5.0istightlyintegratedwithActiveDirectory.ActiveDirectoryprovidesauthenticationforalllocal servicesandforremoteaccessthroughthevSphereWebServicesSDK,vSphereWebClient,PowerCLI,and vSphereCLI.YoucanconfigureActiveDirectorysettingswiththevSphereWebClient,asdiscussedinthe vCenterServerandHostManagementdocumentation,orusevicfg-autconfig.

VMware, Inc.

25

vSphere Command-Line Interface Concepts and Examples

vicfg-authconfigallowsyoutoremotelyconfigureActiveDirectorysettingsonESXihosts.Youcanlist supportedandactiveauthenticationmechanisms,listthecurrentdomain,andjoinorpartfromanActive Directorydomain.BeforeyourunthecommandonanESXihost,youmustpreparethehost. IMPORTANTAllhoststhatjoinActiveDirectorymustalsobemanagedbyanNTPServertoavoidissueswith clockskewsandKerberostickets. To prepare ESXi hosts for Active Directory Integration 1 MakesuretheESXisystemandtheActiveDirectoryserverareusingthesametimezonebyconfiguring ESXiandADtousesameNTPserver. TheESXisystemstimezoneisalwayssettoUTC. 2 ConfiguretheESXisystemsDNStobeintheActiveDirectorydomain.

Youcanrunvicfg-authconfigtoaddthehosttothedomain.Auserwhorunsvicfg-authconfigto configureActiveDirectorysettingsmusthavetheappropriateActiveDirectorypermissions,andmusthave administrativeprivilegesontheESXihost.Youcanrunthecommanddirectlyagainstthehostoragainsta vCenterServersystem,specifyingthehostwith--vihost. To set up Active Directory 1 2 3 4 InstalltheESXihost,asexplainedinthevSphereInstallationandSetupdocumentation. InstallWindowsActiveDirectoryonaWindowsServerthatrunsWindows2000,Windows2003,or Windows2008.SeetheMicrosoftWebsiteforinstructionsandbestpractices. SynchronizetimebetweentheESXisystemandWindowsActiveDirectory(AD). TestthattheWindowsADServercanpingtheESXihostbyusingthehostname.
ping <ESX_hostname>

Runvicfg-authcofigtoaddthehosttotheActiveDirectorydomain.
vicfg-authconfig --server=<ESXi Server IP Address> --username=<ESXi Server Admin Username> --password=<ESXi Server Admin User's Password> --authscheme AD --joindomain <AD Domain Name> --adusername=<Active Directory Administrator User Name> --adpassword=<Active Directory Administrator User's Password>

Thesystempromptsforusernamesandpasswordsifyoudonotspecifythemonthecommandline. Passwordsarenotechoedtothescreen. 6 7 CheckthataSuccessfully Joined <Domain Name>messageappears. VerifytheESXihostisintheintendedWindowsADdomain.


vicfg-authconfig --server XXX.XXX.XXX.XXX --authscheme AD -c

YouarepromptedforausernameandpasswordfortheESXisystem.

Updating Hosts
Whenyouaddcustomdriversorpatchestoahost,theprocessiscalledanupdate.

UpdateESXi4.0andESXi4.1hostswiththevihostupdatecommand,asdiscussedinthevSphere CommandLineInterfaceInstallationandReferenceGuideincludedinthevSphere4.1documentationset. UpdateESXi5.0hostswithesxcli software vibcommandsdiscussedinthevSphereUpgrade documentationincludedinthevSphere5.0documentationset.Youcannotrunthevihostupdate commandagainstanESXi5.0host.

26

VMware, Inc.

Managing Files

ThevSphereCLIincludestwocommandsforfilemanipulation.vmkfstoolsallowsyoutomanipulateVMFS (VirtualMachineFileSystem)andvirtualdisks.vifssupportsremoteinteractionwithfilesonyourESXihost. NOTESeeManagingStorageonpage 39forinformationaboutstoragemanipulationcommands. Thischapterincludesthefollowingtopics:


IntroductiontoVirtualMachineFileManagementonpage 27 ManagingtheVirtualMachineFileSystemwithvmkfstoolsonpage 28 UpgradingVMFS3VolumestoVMFS5onpage 29 ManagingVMFSVolumesonpage 29 DetachingDevicesandRemovingaLUNonpage 32 WorkingwithPermanentDeviceLossonpage 33 UsingvifstoManipulateFilesonRemoteESXiHostsonpage 33

Introduction to Virtual Machine File Management


YoucanusethevSphereWebClientorvCLIcommandstoaccessdifferenttypesofstoragedevicesthatyour ESXihostdiscoversandtodeploydatastoresonthosedevices. NOTEDatastoresarelogicalcontainers,analogoustofilesystems,thathidespecificsofeachstoragedevice andprovideauniformmodelforstoringvirtualmachinefiles.DatastorescanbeusedforstoringISOimages, virtualmachinetemplates,andfloppyimages.ThevSphereWebClientusesthetermdatastoreexclusively. ThismanualusesthetermdatastoreandVMFS(orNFS)volumetorefertothesamelogicalcontaineronthe physicaldevice. Dependingonthetypeofstorageyouuse,datastorescanbebackedbythefollowingfilesystemformats:

VirtualMachineFileSystem(VMFS).Highperformancefilesystemthatisoptimizedforstoringvirtual machines.YourhostcandeployaVMFSdatastoreonanySCSIbasedlocalornetworkedstoragedevice, includingFibreChannelandiSCSISANequipment.AsanalternativetousingtheVMFSdatastore,your virtualmachinecanhavedirectaccesstorawdevicesanduseamappingfile(RDM)asaproxy. YoumanageVMFSandRDMswiththevSphereWebClient,orthevmkfstoolscommand.

NetworkFileSystem(NFS).FilesystemonaNASstoragedevice.ESXisupportsNFSversion3over TCP/IP.ThehostcanaccessadesignatedNFSvolumelocatedonanNFSserver,mountthevolume,and useitforanystorageneeds. YoumanageNASstoragedeviceswiththeesxcli storage nfscommand.

VMware, Inc.

27

vSphere Command-Line Interface Concepts and Examples

Figure 3-1. Virtual Machines Accessing Different Types of Storage


Host requires TCP/IP connectivity virtual machine virtual machine virtual machine virtual machine virtual machine

local ethernet SCSI bre channel HBA SAN iSCSI hardware initiator LAN software initiator ethernet NIC LAN ethernet NIC LAN

VMFS

Key
physical disk

datastore VMFS fibre array VMFS iSCSI array NFS NAS appliance

virtual disk

Managing the Virtual Machine File System with vmkfstools


VMFSdatastoresprimarilyserveasrepositoriesforvirtualmachines.Youcanstoremultiplevirtualmachines onthesameVMFSvolume.Eachvirtualmachine,encapsulatedinasetoffiles,occupiesaseparatesingle directory.Fortheoperatingsysteminsidethevirtualmachine,VMFSpreservestheinternalfilesystem semantics. Inaddition,youcanusetheVMFSdatastorestostoreotherfiles,suchasvirtualmachinetemplatesandISO images.VMFSsupportsfileandblocksizesthatenablevirtualmachinestorundataintensiveapplications, includingdatabases,ERP,andCRM,invirtualmachines.SeethevSphereStoragedocumentation. YouusethevmkfstoolsvCLItocreateandmanipulatevirtualdisks,filesystems,logicalvolumes,and physicalstoragedevicesonanESXihost.Youcanusevmkfstoolstocreateandmanageavirtualmachinefile system(VMFS)onaphysicalpartitionofadiskandtomanipulatefiles,suchasvirtualdisks,storedon VMFS3andNFS.Youcanalsousevmkfstoolstosetupandmanagerawdevicemappings(RDMs). IMPORTANTThevmkfstoolsvCLIsupportsmostbutnotalloftheoptionsthatthevmkfstoolsESXiShell commandsupports.SeeVMwareKnowledgeBasearticle1008194. Youcannotrunvmkfstoolswith--serverpointingtoavCenterServersystem. ThevSphereStoragedocumentationincludesacompletereferencetothevmkfstoolscommandthatyoucan useintheESXiShell.YoucanusemostofthesameoptionswiththevmkfstoolsvCLIcommand.Specifyone oftheconnectionoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. ThefollowingoptionssupportedbythevmkfstoolsESXiShellcommandarenotsupportedbythe vmkfstoolsvCLIcommand.

--breaklock -B --chainConsistent -e --eagerzero -k --fix -x --lock -L --migratevirtualdisk -M --parseimage -Y --punchzero -K --snapshotdisk -I --verbose -v

28

VMware, Inc.

Chapter 3 Managing Files

Upgrading VMFS3 Volumes to VMFS5


vSphere5.0supportsVMFS5volumes,whichhaveimprovedscalabilityandperformance.Youcanupgrade fromVMFS3toVMFS5byusingthevSphereWebClient,thevmkfstoolsESXiShellcommand,ortheesxcli storage vmfs upgradecommand.PassthevolumelabelorthevolumeUUIDtotheESXCLIcommand. IMPORTANTYoucannotupgradeVMFS3volumestoVMFS5withthevmkfstoolscommandincludedin vSphereCLI.

Managing VMFS Volumes


Differentcommandsareavailableforlisting,mounting,andunmountingVMFSvolumesandforlisting, mounting,andunmountingVMFSsnapshotvolumes.

ManagingVMFSvolumes esxcli storage filesystem listshowsallvolumes,mountedandunmounted,thatareresolved, thatis,thatarenotsnapshotvolumes. esxcli storage filesystem unmountunmountsacurrentlymountedfilesystem.Usethiscommand forsnapshotvolumesorresolvedvolumes.

Managingsnapshotvolumes esxcli storage vmfs snapshotcommandscanbeusedforlisting,mounting,andresignaturing snapshotvolumes.SeeMountingDatastoreswithExistingSignaturesonpage 29andResignaturing VMFSCopiesonpage 30.

Managing Duplicate VMFS Datastores


EachVMFSdatastorecreatedinaLUNhasauniqueUUIDthatisstoredinthefilesystemsuperblock.When theLUNisreplicatedorwhenasnapshotismade,theresultingLUNcopyisidentical,byteforbyte,tothe originalLUN.Asaresult,iftheoriginalLUNcontainsaVMFSdatastorewithUUIDX,theLUNcopyappears tocontainanidenticalVMFSdatastore,oraVMFSdatastorecopy,withthesameUUIDX. ESXihostscandeterminewhetheraLUNcontainstheVMFSdatastorecopy,andeithermountthedatastore copywithitsoriginalUUIDorchangetheUUIDtoresignaturethedatastore. WhenaLUNcontainsaVMFSdatastorecopy,youcanmountthedatastorewiththeexistingsignatureor assignanewsignature.ThevSphereStoragedocumentationdiscussesvolumeresignaturingindetail.

Mounting Datastores with Existing Signatures


YoucanmountaVMFSdatastorecopywithoutchangingitssignatureiftheoriginalisnotmounted.For example,youcanmaintainsynchronizedcopiesofvirtualmachinesatasecondarysiteaspartofadisaster recoveryplan.Intheeventofadisasterattheprimarysite,youcanmountthedatastorecopyandpoweron thevirtualmachinesatthesecondarysite. IMPORTANTYoucanmountaVMFSdatastoreonlyifitdoesnotconflictwithanalreadymountedVMFS datastorethathasthesameUUID. WhenyoumounttheVMFSdatastore,ESXiallowsbothreadandwriteoperationstothedatastorethatresides ontheLUNcopy.TheLUNcopymustbewritable.Thedatastoremountsarepersistentandvalidacross systemreboots. Youcanmountadatastorewithvicfg-volume(seeTomountadatastorewithvicfgvolumeonpage 30)or withESXCLI(seeTomountadatastorewithESXCLIonpage 30).

VMware, Inc.

29

vSphere Command-Line Interface Concepts and Examples

Mounting and Unmounting with ESXCLI


Theesxcli storage filesystemcommandssupportmountingandunmountingvolumes.Youcanalso specifywhethertopersistthemountedvolumesacrossrebootsbyusingthe--no-persistoption. Usetheesxcli storage filesystemcommandtolistmountedvolumes,mountnewvolumes,and unmountavolume.SpecifyoneoftheconnectionoptionslistedinConnectionOptionsonpage 17inplace of<conn_options>. To mount a datastore with ESXCLI 1 Listallvolumesthathavebeendetectedassnapshots.
esxcli <conn_options> storage filesystem list

Runesxcli storage filesystem mountwiththevolumelabelorvolumeUUID. Bydefault,thevolumeismountedpersistently,use--no-persisttomountpersistently.


esxcli <conn_options> storage filesystem volume mount --volume-label=<label>|--volume-uuid=<VMFS-UUID>

Thiscommandfailsiftheoriginalcopyisonline. Youcanlaterrunesxcli storage filesystem volume unmounttounmountthesnapshotvolume.


esxcli <conn_options> storage filesystem volume unmount --volume-label=<label>|--volume-uuid=<VMFS-UUID>

Mounting and Unmounting with vicfg-volume


Usethevicfg-volumecommandtolistmountedvolumes,mountnewvolumes,andunmountavolume. SpecifyoneoftheconnectionoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. To mount a datastore with vicfg-volume 1 Listallvolumesthathavebeendetectedassnapshotsorreplicas.
vicfg-volume <conn_options> --list

Runvicfg-volume --persistent-mount withtheVMFSUUIDorlabelasanargumenttomounta volume.


vicfg-volume <conn_options> --persistent-mount <VMFS-UUID|label>

Thiscommandfailsiftheoriginalcopyisonline. Youcanlaterrunvicfg-volume --unmounttounmountthesnapshotorreplicavolume.


vicfg-volume <conn_options> --unmount <VMFS-UUID|label>

Thevicfg-volumecommandsupportsresignaturingasnapshotvolumeandmountingandunmountingthe volume.Youcanalsomakethemountedvolumepersistentacrossrebootsandqueryalistofsnapshot volumesandoriginalvolumes.

Resignaturing VMFS Copies


UsedatastoreresignaturingtoretainthedatastoredontheVMFSdatastorecopy.WhenresignaturingaVMFS copy,theESXihostassignsanewUUIDandanewlabeltothecopy,andmountsthecopyasadatastore distinctfromtheoriginal.BecauseESXipreventsyoufromresignaturingthemounteddatastore,unmountthe datastorebeforeresignaturing. Thedefaultformatofthenewlabelassignedtothedatastoreissnap-<snapID>-<oldLabel>,where <snapID>isanintegerand<oldLabel>isthelabeloftheoriginaldatastore. Whenyouperformdatastoreresignaturing,considerthefollowingpoints:

Datastoreresignaturingisirreversible. TheLUNcopythatcontainstheVMFSdatastorethatyouresignatureisnolongertreatedasaLUNcopy.

30

VMware, Inc.

Chapter 3 Managing Files

Aspanneddatastorecanberesignaturedonlyifallitsextentsareonline. Theresignaturingprocessiscrashandfaulttolerant.Iftheprocessisinterrupted,youcanresumeitlater. YoucanmountthenewVMFSdatastorewithoutariskofitsUUIDconflictingwithUUIDsofanyother datastore,suchasanancestororchildinahierarchyofLUNsnapshots.

YoucanresignatureaVMFScopywithESXCLI(seeResignaturingaVMFSCopywithESXCLIonpage 31) orwithvicfg-volumeseeResignaturingaVMFSCopywithvicfgvolumeonpage 31.

Resignaturing a VMFS Copy with ESXCLI


Theesxcli storage vmfs snapshotcommandssupportresignaturingasnapshotvolume.Specifyoneof theconnectionoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. To resignature a VMFS copy with ESXCLI 1 Listunresolvedsnapshotsorreplicavolumes.
esxcli <conn_options> storage vmfs snapshot list

(Optional)Unmountthecopy.
esxcli <conn_options> storage filesystem unmount

Runtheresignaturecommand.
esxcli <conn_options> storage vmfs snapshot resignature --volume-label=<label>|--volume-uuid=<id>

Thecommandreturnstothepromptorsignalsanerror. Afterresignaturing,youmighthavetodothefollowing:

Iftheresignatureddatastorecontainsvirtualmachines,updatereferencestotheoriginalVMFSdatastore inthevirtualmachinefiles,including.vmx,.vmdk,.vmsd,and.vmsn. Topoweronvirtualmachines,registerthemwiththevCenterServersystem.

Resignaturing a VMFS Copy with vicfg-volume


Youcanusevicfg-volumetomount,unmount,andresignatureVMFSvolumes. To resignature a VMFS copy with vicfg-volume 1 2 Makesurethecopyisnotmounted. Runvicfg-volumewiththeresignatureoption.
vicfg-volume <conn_options> --resignature <VMFS-UUID|label>

Thecommandreturnstothepromptorsignalsanerror.

VMware, Inc.

31

vSphere Command-Line Interface Concepts and Examples

Detaching Devices and Removing a LUN


BeforeyoucanremoveaLUN,youmustdetachthecorrespondingdevicebyusingthevSphereWebClient, ortheesxcli storage core device setcommand.Detachingadevicebringsadeviceoffline.Detaching adevicedoesnotimpactpathstates.IftheLUNisstillvisible,thepathstateisnotsettodead. To detach a device and remove a LUN 1 Migratevirtualmachinesfromthedeviceyouplantodetach. Forinformationonmigratingvirtualmachines,seethevCenterServerandHostManagement documentation. 2 Unmountthedatastoredeployedonthedevice.SeeMountingDatastoreswithExistingSignatureson page 29. Iftheunmountfails,ESXCLIreturnsanerror.Ifyouignorethaterror,youwillgetanerrorinstep4when youattempttodetachadevicewithaVMFSpartitionstillinuse. 3 Iftheunmountfailed,checkwhetherthedeviceisinuse.
esxcli storage core device world list -d <device>

IfaVMFSvolumeisusingthedeviceindirectly,theworldnameincludesthestringidle0.Ifavirtual machineusesthedeviceasanRDM,thevirtualmachineprocessnameisdisplayed.Ifanyotherprocess isusingtherawdevice,theinformationisdisplayed. 4 Detachthestoragedevice.


esxcli storage core device set -d naa.xxx... --state=off

Detachispersistentacrossrebootsanddeviceunregistration.Anydevicethatisdetachedremains detacheduntilamanualattachoperation.Rescandoesnotbringpersistentlydetacheddevicesback online.Apersistentlydetacheddevicecomesbackintheoffstate. ESXimaintainsthepersistentinformationaboutthedevicesofflinestateevenifthedeviceis unregistered.Youcanremovethedeviceinformationbyrunningesxcli storage core device detached remove -d naa.12. 5 (Optional)Totroubleshootthedetachoperation,listalldevicesthatweredetachedmanually.
esxcli storage core device detached list

Performarescan.
esxcli <conn_options> storage core adapter rescan

Whenyouhavecompletedstoragereconfiguration,youcanreattachthestoragedevice,mountthedatastore, andrestartthevirtualmachines. To reattach the device 1 (Optional)Checkthatthedeviceisdetached.


esxcli storage core device detached list

Attachthedevice.
esxcli storage core device set -d naa.XXX --state=on

Mountthedatastoreandrestartvirtualmachines.SeeMountingDatastoreswithExistingSignatureson page 29.

32

VMware, Inc.

Chapter 3 Managing Files

Working with Permanent Device Loss


WithearlierESX/ESXireleases,anAPD(AllPathsDown)eventresultswhentheLUNbecomesunavailable. Theeventisdifficultforadministratorsbecausetheydonothaveenoughinformationaboutthestateofthe LUNtoknowwhichcorrectiveactionisappropriate. InESXi5.0,theESXihostcandeterminewhetherthecauseofanAllPathsDown(APD)eventistemporary,or whetherthecauseispermanentdeviceloss.APLDstatusoccurswhenthestoragearrayreturnsSCSIsense codesindicatingthattheLUNisnolongeravailableorthatasevere,unrecoverablehardwareproblemexist withit.ESXihasanimprovedinfrastructurethatcanspeedupoperationsofupperlayerapplicationsina devicelossscenario. IMPORTANTDonotplanforAPD/PDLevents,forexample,whenyouwanttoupgradeyourhardware. Instead,performanorderlyremovalofLUNsfromyourESXiserver,whichisdescribedinDetachingDevices andRemovingaLUNonpage 32,performtheoperation,andaddtheLUNback. To Remove a PDL LUN HowyouremoveaPDLLUNdependsonwhetheritwasinuse.

IftheLUNthatgoesintoPDLisnotinusebyanyuserprocessorbytheVMkernel,theLUNdisappears byitselfafteraPDL. IftheLUNwasinusewhenitenteredPLD,deletetheLUNmanuallybyfollowingtheprocessdescribed inDetachingDevicesandRemovingaLUNonpage 32.

To Reattach a PDL LUN 1 2 ReturntheLUNtoworkingorder. Removeanyusersofthedevice. Youcannotbringadevicebackwithoutremovingactiveusers.TheESXihostcannotknowwhetherthe devicethatwasaddedbackhaschanged.ESXimustbeabletotreatthedevicesimilarlytoanewdevice beingdiscovered. 3 Performarescantogetthedevicebackinworkingorder.

Using vifs to Manipulate Files on Remote ESXi Hosts


Inmostcases,vmkfstoolsandothercommandsareusedtomanipulatevirtualmachinefiles.Insomecases, youmighthavetoviewandmanipulatefilesonremoteESXihostsdirectly. CAUTIONIfyoumanipulatefilesdirectly,yourvSpheresetupmightendupinaninconsistentstate.Usethe vSphereWebClientoroneoftheothervCLIcommandstomanipulatevirtualmachineconfigurationfilesand virtualdisks. Thevifscommandperformscommonoperationssuchascopy,remove,get,andputonESXifilesand directories.ThecommandissupportedagainstESXihostsbutnotagainstvCenterServersystems. SomesimilaritiesbetweenvifsandDOSorUNIX/Linuxfilesystemmanagementutilitiesexist,butthereare manydifferences.Forexample,vifsdoesnotsupportwildcardcharactersorcurrentdirectoriesand,asa result,relativepathnames.Usevifsonlyasdocumented. Insteadofusingthevifscommand,youcanbrowsedatastorecontentsandhostfilesbyusingaWebbrowser. Connecttothefollowinglocation:
http://ESX_host_IP_Address/host http://ESX_host_IP_Address/folder

YoucanviewdatacenteranddatastoredirectoriesfromthisrootURL.Forexample:
http://<ESXi_addr>/folder?dcPath=ha-datacenter http://<ESXi_host_name>/folder?dcPath=ha-datacente

VMware, Inc.

33

vSphere Command-Line Interface Concepts and Examples

TheESXihostpromptsforausernameandpassword. Thevifscommandsupportsdifferentoperationsforthefollowinggroupsoffilesanddirectories.Different operationsareavailableforeachgroup,andyouspecifylocationswithadifferentsyntax.Thebehaviordiffers forvSphere4.xandvSphere5.0.


vSphere 4.x Host Hostconfigurationfiles.Youmustspecifythe filesuniquenameidentifier. Specifyhostlocationsbyusingthe /host/<path>syntax. Temp The/tmpdirectoryandfilesinthatdirectory. Specifytemplocationsbyusingthe /tmp/dir/subdirsyntax. Datastores vSphere 5.0 Hostconfigurationfiles.Youmustspecifythe filesuniquenameidentifier. Specifyhostlocationsbyusingthe /host/<path>syntax. Youcannotlistsubdirectoriesof/host. Notsupported.

Datastorefilesanddirectories.Youhavetwochoicesforspecifyingadatastore:

Datastoreprefixstyle:'[ds_name] relative_path'.Forexample: '[myStorage1] testvms/VM1/VM1.vmx'(Linux) or "[myStorage1] testvms/VM1/VM1.vmx" (Windows)

URLstyle:/folder/dir/subdir/file?dsName=<name>.Forexample: '/folder/testvms/VM1/VM1.vmx?dsName=myStorage1' (Linux) "/folder/testvms/VM1/VM1.vmx?dsName=myStorage1" (Windows) Thetwoexamplepathsrefertoavirtualmachineconfigurationfileforthevirtualmachine VM1inthetestvms/VM1directoryofthemyStorage1datastore.

Toavoidproblemswithdirectorynamesthatusespecialcharactersorspaces,enclosethepathinquotesfor bothoperatingsystems. Whenyourunvifs,youcanspecifytheoperationnameandargumentandoneofthestandardconnection options.Usealiases,symboliclinks,orwrapperscriptstosimplifytheinvocationsyntax. IMPORTANTTheconceptsofworkingdirectoryandlastdirectoryorfileoperatedonarenotsupportedwith vifs. Options vifscommandspecificoptionsallowyoutoretrieveanduploadfilesfromtheremotehostandperforma numberofotheroperations.Allvifsoptionsworkondatastorefilesordirectories.Someoptionsalsowork onhostfilesandfilesinthetempdirectory.Youmustalsospecifyconnectionoptions.
Command --copy -c <source> <target> Description Copiesafileinadatastoretoanotherlocation inadatastore.The<source>mustbearemote sourcepath,the<target>aremotetarget pathordirectory. The--forceoptionreplacesexisting destinationfiles. --dir -D <remote_dir> --force -F --get -g <remote_path> <local_path> Liststhecontentsofadatastoredirectory. Overwritesthedestinationfile.Usedwith --moveand--copy. DownloadsafilefromtheESXihosttothe machineonwhichyourunvCLI.This operationusesHTTP GET. ListsthedatacenterpathsavailableonanESXi system. Datastore Temp Datastore Temp Datastore Host Target Datastore Temp Syntax copy src_file_path dst_directory_path [force] copy src_file_path dst_file_path [force]

dir datastore_directory_path copy src_file_path dst_file_path [force] get src_dstore_file_path dst_local_file_path get src_d store_dir_path dst_local_file_path

--listdc -C

Datastore Host

34

VMware, Inc.

Chapter 3 Managing Files

Command --listds -S

Description ListsthedatastorenamesontheESXisystem. Whenmultipledatacentersareavailable,use the--dc (-Z)argumenttospecifythename ofthedatacenterfromwhichyouwanttolist thedatastore. Createsadirectoryinadatastore.This operationfailsiftheparentdirectoryof dst_datastore_file_pathdoesnotexist. Movesafileinadatastoretoanotherlocation inadatastore.The<source>mustbearemote sourcepath,the<target>aremotetarget pathordirectory. The--forceoptionreplacesexisting destinationfiles.

Target Datastore Host

Syntax vifs --listds

--mkdir -M <remote_dir> --move -m <source> <target>

Datastore Temp Datastore Temp

mkdir dst_directory_path

move src_file_path dst_directory_path [force] move src_file_path dst_file_path [force]

--put -p <local_path> <remote_path>

Uploadsafilefromthemachineonwhichyou runvCLItotheESXihost.Thisoperationuses HTTP PUT. Thiscommandcanreplaceexistinghostfiles butcannotcreatenewfiles.

Datastore Host Temp

put src_local_file_path dst_file_path put src_local_file_path dst_directory_path rm dst_file_path rmdir dst_directory_path

--rm -r <remote_path> --rmdir -R <remote_dir>

Deletesadatastorefile. Deletesadatastoredirectory.Thisoperation failsifthedirectoryisnotempty.

Datastore Temp Datastore Temp

Examples
YoucanusevifstointeractwiththeremoteESXiorvCenterServersysteminavarietyofways.Specifyone oftheconnectionoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.The examplesillustrateuseonaLinuxsystem,usedoublequotesinsteadofsinglequoteswhenonaWindows system. Listing Remote Information

ListalldatacentersonavCenterServersystemwith--listdc,using--servertopointtothevCenter Serversystem.
vifs --server <my_vc>--username administrator --password <pswd> --listdc

ListalldatastoresonavCenterServersystemwith--listds.
vifs --server <my_vc> --username administrator --password <pswd> --dc kw-dev --listds

ListalldatastoresonanESXihostwith--listds.
vifs --server <my_ESXi> --username root --password <pswd> --listds

Thecommandliststhenamesofalldatastoresonthespecifiedserver. Youcanuseeachnamethathasbeenreturnedtorefertodatastorepathsbyusingsquarebracketnotation, asfollows:


'[my_datastore] dir/subdir/file'

Listthecontentofadirectoryinadatastore.
vifs --server <my_ESXi> --username root --password <pswd>--dir '[Storage1]' vifs --server <my_ESXi> --username root --password <pswd> --dir '[Storage1] WindowsXP'

Thecommandliststhedirectorycontent.Inthisexample,thecommandliststhecontentsofavirtual machinedirectory.
Content Listing _________________ vmware-37.log

VMware, Inc.

35

vSphere Command-Line Interface Concepts and Examples

vmware-38.log ... vmware.log ... winxpPro-sp2.vmdk winxpPro-sp2.vmx winxpPro-sp2.vmxf ...

Listthecontentsofoneofthedatastores.
vifs <conn_options> --dir '[osdc-cx700-02]'

Thecommandliststhecompletecontentsofthedatastore. Working with Directories and Files on the Remote Server

Createanewdirectoryinadatastorewith--mkdir <remote_dir>.
vifs --server <my_ESXi> --username root --password <pswd> --mkdir '[Storage1] test'

Removeadirectorywith--rmdir <remote_dir>.
vifs --server <my_ESXi> --username root --password <pswd> --rmdir '[Storage1] test'.

Forciblyremoveadirectorywith--rmdir --force <remote_dir>.


vifs --server <my_ESXi> --username root --password <pswd> --rmdir '[Storage1] test2' --force

Updateafileontheremoteserverwith--put <local_path> <remote_path>.


vifs --server <my_ESXi> --username root --password <pswd> --put /tmp/testfile '[Storage1] test/testfile'

Retrieveafilefromtheremoteserverwith--get <remote_path> <local_path>|<local_dir>.The commandoverwritesthelocalfileifitexists.Ifyoudonotspecifyafilename,thefilenameoftheremote fileisused.


vifs --server <my_ESXi> --username root --password <pswd> --get '[Storage1] test/testfile' /tmp/tfile vifs --server <my_ESXi> --username root --password <pswd> --get '[Storage1] test/testfile' /tmp

Deleteafileontheremoteserverwith-rm <remote_path>.
vifs --server <my_ESXi> --username root --password <pswd> --rm '[Storage1] test2/testfile'

Forciblyremoveafileontheremoteserverwith--rm <remote_path> --force.


vifs --server <my_ESXi> --username root --password <pswd> --rm '[Storage1] test2/testfile2' --force

Moveafilefromonelocationontheremoteservertoanotherlocationwith--move <remote_source_path> <remote_target_path>.Ifyouspecifyafilename,thefileismovedand renamedatthesametime.


vifs --server <my_ESXi> --username root --password <pswd> --move '[Storage1] test/tfile' '[Storage1] newfile'

Ifthetargetfilealreadyexistsontheremoteserver,thecommandfailsunlessyouuse--force.
vifs --server <my_ESXi> --username root --password <pswd> --move '[Storage1] test/tfile2' '[Storage1] test2/tfile' --force

Createacopyofafileontheremoteserveratadifferentlocationontheremoteserver.
vifs --server <my_ESXi> --username root --password <pswd> --copy '[Storage1] test/tfile' '[Storage1] test/tfile2'

Ifthetargetfilealreadyexistsontheremoteserver,thecommandfailsunlessyouuse--force.
vifs --server <my_ESXi> --username root --password <pswd> --copy '[Storage1] test/tfile' '[Storage1] test/tfile2' --force

36

VMware, Inc.

Chapter 3 Managing Files

Example Scenario
Thefollowingexamplescenarioillustratesotherusesofvifs.Specifyoneoftheconnectionoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>. To manage files and directories on the remote ESXi system 1 Createadirectoryinthedatastore.
vifs <conn_options> --mkdir '[osdc-cx700-03] vcli_test'

Youmustspecifytheprecisepath;thereisnoconceptofarelativepath. 2 Placeafilethatisonthesystemfromwhichyouarerunningthecommandsintothenewlycreated directory.


vifs <conn_options> --put /tmp/test_doc '[osdc-cx700-03] vcli_test/test_doc'

Moveafileintoavirtualmachinedirectory.
vifs <conn_options> --move '[osdc-cx700-03] vcli_test/test_doc' '[osdc-cx700-03] winxpPro-sp2/test_doc

Amessageindicatessuccessorfailure. 4 RetrieveoneofthefilesfromtheremoteESXisystem. Thefollowingexampleretrievesalogfileforanalysis.


vifs <conn_options> --get '[osdc-cx700-03] winxpPro-sp2/vmware.log' ~user1/vmware.log

Cleanupbyremovingthefileanddirectoryyoucreatedearlier.
vifs <conn_options> --rm '[osdc-cx700-03] vcli_test/test_doc' vifs <conn_options> --rmdir '[osdc-cx700-03] vcli_test'

VMware, Inc.

37

vSphere Command-Line Interface Concepts and Examples

38

VMware, Inc.

Managing Storage

Avirtualmachineusesavirtualdisktostoreitsoperatingsystem,programfiles,andotherdataassociated withitsactivities.Avirtualdiskisalargephysicalfile,orasetoffiles,thatcanbecopied,moved,archived, andbackedup. Tostorevirtualdiskfilesandmanipulatethefiles,ahostrequiresdedicatedstoragespace.ESXistorageis storagespaceonavarietyofphysicalstoragesystems,localornetworked,thatahostusestostorevirtual machinedisks. Thischapterincludesthefollowingtopics:


IntroductiontoStorageonpage 39 ExaminingLUNsonpage 42 ManagingPathsonpage 44 ManagingPathPoliciesonpage 47 ManagingNFS/NASDatastoresonpage 50 MonitoringandManagingSANStorageonpage 52 MigratingVirtualMachineswithsvmotiononpage 52 ConfiguringFCoEAdaptersonpage 54 ScanningStorageAdaptersonpage 55 RetrievingSMARTInformationonpage 55

Chapter 5,ManagingiSCSIStorage,onpage 57discussesiSCSIstoragemanagement.Chapter 6,Managing ThirdPartyStorageArrays,onpage 85explainshowtomanagethePluggableStorageArchitecture, includingPathSelectionPlugin(PSP)andStorageArrayTypePlugin(SATP)configuration. ForinformationonmaskingandunmaskingpathswithESXCLI,seethevSphereStoragedocumentation.

Introduction to Storage
FibreChannelSANarrays,iSCSISANarrays,andNASarraysarewidelyusedstoragetechnologiessupported byVMwarevSpheretomeetdifferentdatacenterstorageneeds.Thestoragearraysareconnectedtoand sharedbetweengroupsofserversthroughstorageareanetworks.Thisarrangementallowsaggregationofthe storageresourcesandprovidesmoreflexibilityinprovisioningthemtovirtualmachines.

VMware, Inc.

39

vSphere Command-Line Interface Concepts and Examples

Figure 4-1. vSphere Datacenter Physical Topology


vCenter Server vSphere Client Web access terminal

server group 1

server group 2

server group 3

virtual machines VM VM VM VM VM VM fibre channel switch fabric / IP network

ESX/ESXi

fibre channel storage array

iSCSI storage array

NAS storage array

How Virtual Machines Access Storage


Avirtualdiskhidesthephysicalstoragelayerfromthevirtualmachinesoperatingsystem.Regardlessofthe typeofstoragedevicethatyourhostuses,thevirtualdiskalwaysappearstothevirtualmachineasamounted SCSIdevice.Asaresult,youcanrunoperatingsystemsthatarenotcertifiedforspecificstorageequipment, suchasSAN,inthevirtualmachine. Whenavirtualmachinecommunicateswithitsvirtualdiskstoredonadatastore,itissuesSCSIcommands. Becausedatastorescanexistonvarioustypesofphysicalstorage,thesecommandsareencapsulatedintoother forms,dependingontheprotocolthattheESXihostusestoconnecttoastoragedevice. Figure 42depictsfivevirtualmachinesthatusedifferenttypesofstoragetoillustratethedifferencesbetween eachtype. Figure 4-2. Virtual Machines Accessing Different Types of Storage
Host requires TCP/IP connectivity virtual machine virtual machine virtual machine virtual machine virtual machine

local ethernet SCSI bre channel HBA SAN iSCSI hardware initiator LAN software initiator ethernet NIC LAN ethernet NIC LAN

VMFS

Key
physical disk

datastore VMFS fibre array VMFS iSCSI array NFS NAS appliance

virtual disk

40

VMware, Inc.

Chapter 4 Managing Storage

YoucanusevCLIcommandstomanagethevirtualmachinefilesystemandstoragedevices.

VMFS.Usevmkfstoolstocreate,modify,andmanageVMFSvirtualdisksandrawdevicemappings. SeeManagingtheVirtualMachineFileSystemwithvmkfstoolsonpage 28foranintroductionandthe vSphereStoragedocumentationforadetailedreference. Datastores.Severalcommandsallowyoutomanagedatastoresandareusefulformultipleprotocols.

LUNs.Useesxcli storage coreorvicfg-scsidevscommandstodisplayavailableLUNsand mappingsforeachVMFSvolumetoitscorrespondingpartition.SeeExaminingLUNsonpage 42. Pathmanagement.Useesxcli storage coreorvicfg-mpathcommandstolistinformationabout FibreChanneloriSCSILUNsandtochangeapathsstate.SeeManagingPathsonpage 44.Usethe ESXCLIcommandtoviewandmodifypathpolicies.SeeManagingPathPoliciesonpage 47. Rescan.Useesxcli storage coreorvicfg-rescanadapter rescantoperformarescan operationeachtimeyoureconfigureyourstoragesetup.SeeScanningStorageAdapterson page 55.

Storagedevices.Severalcommandsmanageonlyspecificstoragedevices.

NFSstorage.Useesxcli storage nfsorvicfg-nastomanageNASstoragedevices.See ManagingNFS/NASDatastoresonpage 50. iSCSIstorage.Useesxcli iscsiorvicfg-iscsitomanagebothhardwareandsoftwareiSCSI. SeeManagingiSCSIStorageonpage 57.

Datastores
ESXihostsusestoragespaceonavarietyofphysicalstoragesystems,includinginternalandexternaldevices andnetworkedstorage.Ahostcandiscoverstoragedevicestowhichithasaccessandformatthemas datastores.Eachdatastoreisaspeciallogicalcontainer,analogoustoafilesystemonalogicalvolume,where thehostplacesvirtualdiskfilesandothervirtualmachinefiles.Datastoreshidespecificsofeachstorage productandprovideauniformmodelforstoringvirtualmachinefiles. Dependingonthetypeofstorageyouuse,datastorescanbebackedbythefollowingfilesystemformats:

VirtualMachineFileSystem(VMFS).Highperformancefilesystemoptimizedforstoringvirtual machines.YourhostcandeployaVMFSdatastoreonanySCSIbasedlocalornetworkedstoragedevice, includingFibreChannelandiSCSISANequipment. AsanalternativetousingtheVMFSdatastore,yourvirtualmachinecanhavedirectaccesstorawdevices anduseamappingfile(RDM)asaproxy.SeeManagingtheVirtualMachineFileSystemwith vmkfstoolsonpage 28.

NetworkFileSystem(NFS).FilesystemonaNASstoragedevice.ESXisupportsNFSversion3over TCP/IP.ThehostcanaccessadesignatedNFSvolumelocatedonanNFSserver,mountthevolume,and useitforanystorageneeds.

Storage Device Naming


Eachstoragedevice,orLUN,isidentifiedbyseveralnames.

Name.AfriendlynamethattheESXihostassignstoadevicebasedonthestoragetypeandmanufacturer, forexample,DGCFibreChannelDisk.ThisnameisvisibleinthevSphereWebClient. DeviceUID.Auniversallyuniqueidentifierassignedtoadevice.Thetypeofstoragedeterminesthe algorithmusedtocreatetheidentifier.Theidentifierispersistentacrossrebootsandisthesameforall hostssharingthedevice.Theformatisoftennaa.xxxxxxxoreui.xxxxxxxx. VMLName.AlegacySCSIdevicenamespecifictoVMware.UsethedeviceUIDinstead.

Theruntimenameofthefirstpathtothedeviceisapathidentifierandnotareliableidentifierforthedevice. Runtimenamesarecreatedbythehost,andarenotpersistent.Theruntimenamehastheformat vmhba#:C#:T#:L#.YoucanviewtheruntimenameusingthevSphereWebClient.

VMware, Inc.

41

vSphere Command-Line Interface Concepts and Examples

Examining LUNs
ALUN(LogicalUnitNumber)isanidentifierforadiskvolumeinastoragearraytarget.

Target and Device Representation


IntheESXicontext,thetermtargetidentifiesasinglestorageunitthatahostcanaccess.Thetermsdeviceand LUNdescribealogicalvolumethatrepresentsstoragespaceonatarget.ThetermsdeviceandLUNmeana SCSIvolumepresentedtothehostfromastoragetarget. DifferentstoragevendorspresenttheirstoragesystemstoESXihostsindifferentways.Somevendorspresent asingletargetwithmultipleLUNsonit.Othervendors,especiallyiSCSIvendors,presentmultipletargets withoneLUNeach. Figure 4-3. Target and LUN Representations
target LUN LUN LUN target LUN target LUN target LUN

storage array

storage array

InFigure 43,threeLUNsareavailableineachconfiguration.Ontheleft,thehostseesonetarget,butthat targethasthreeLUNsthatcanbeused.EachLUNrepresentsanindividualstoragevolume.Ontheright,the hostseesthreedifferenttargets,eachhavingoneLUN.

Examining LUNs with esxcli storage core


Useesxcli storage coretodisplayinformationaboutavailableLUNsonESXi5.0.ForESX/ESXi4.xhosts, usevicfg-scsidevs.ForESX/ESXi3.5systems,thecorrespondingcommandisvicfg-vmhbadevs. YoucanrunoneofthefollowingcommandstoexamineLUNs.Specifyoneoftheconnectionoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>.

Listalllogicaldevicesknownonthissystemwithdetailedinformation.
esxcli <conn_options> storage core device list

Thecommandlistsdeviceinformationforalllogicaldevicesonthissystem.Theinformationincludesthe name(UUID),devicetype,displayname,andmultipathingplugin.Specifythe--deviceoptiontoonly listinformationaboutaspecificdevice.


naa.5000c50006ee9cc7 Display Name: Local SEAGATE Disk (naa.5000c50006ee9cc7) Has Settable Display Name: true Size: 286102 Device Type: Direct-Access Multipath Plugin: NMP Devfs Path: /vmfs/devices/disks/naa.5000c50006ee9cc7 Vendor: SEAGATE Model: ST3300555SS Revision: T211 SCSI Level: 5 Is Pseudo: false Status: on Is RDM Capable: true Is Local: true Is Removable: false Is SSD: false Thin Provisioning Status: unknown Attached Filters: VAAI Status: unknown VAAI Plugin Name: Other UIDs: vml.02000000005000c50006ee9cc7535433333030 mpx.vmhba0:C0:T0:L0
42 VMware, Inc.

Chapter 4 Managing Storage

... Attached Filters: VAAI Status: unsupported VAAI Plugin Name: Other UIDs: vml.0005000000766d686261303a303a30

Listaspecificlogicaldevicewithitsdetailedinformation.
esxcli <conn_options> storage core device list -d mpx.vmhba32:C0:T1:L0

Listalldeviceuniqueidentifiers.
esxcli <conn_options> storage core device list

ThecommandliststheprimaryUIDforeachdevice(naa.xxxorotherprimaryname)andanyotherUIDs foreachUID(VMLname).Youcanspecify--devicetoonlylistinformationforaspecificdevice.

PrintmappingsforVMFSvolumestothecorrespondingpartition,pathtothatpartition,VMFSUUID, extentnumber,andvolumenames.
esxcli <conn_option> storage filesystem list

PrintHBAdeviceswithidentifyinginformation.
esxcli <conn_options> storage core adapter list

ThereturnvalueincludesadapterandUIDinformation.

PrintamappingbetweenHBAsandthedevicesitprovidespathsto.
esxcli <conn_options> storage core path list

Examining LUNs with vicfg-scsidevs


Usevicfg-scsidevstodisplayinformationaboutavailableLUNsonESX/ESXi 4.xhosts.ForESX/ESXi3.5 systems,thecorrespondingcommandisvicfg-vmhbadevs. IMPORTANTYoucanrunvicfg-scsidevs--queryandvicfg-scsidevs --vmfsagainstESX/ESXi version3.5.TheotheroptionsaresupportedonlyagainstESX/ESXiversion4.0andlater. YoucanrunoneofthefollowingcommandstoexamineLUNs.Specifyoneoftheconnectionoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>.

Listalllogicaldevicesknownonthissystemwithdetailedinformation.
vicfg-scsidevs <conn_options> --list

Thecommandlistsdeviceinformationforalllogicaldevicesonthissystem.Theinformationincludesthe name(UUID),devicetype,displayname,andmultipathingplugin.Specifythe--deviceoptiontoonly listinformationaboutaspecificdevice.Thefollowingexampleshowsoutputfortwodevices;theactual listingmightincludemultipledevicesandthepreciseformatdiffersbetweenreleases.


mpx.vmhba2:C0:T1:L0 Device Type: cdrom Size: 0 MB Display Name: Local HL-DT-ST (mpx.vmhba2:C0:T1:L0) Plugin: NMP Console Device: /vmfs/devices/cdrom/mpx.vmhba2:C0:T1:L0 Devfs Path: /vmfs/devices/cdrom/mpx.vmhba2:C0:T1:L0 Vendor: SONY Model: DVD-ROM GDRXX8XX Revis: 3.00 SCSI Level: 5 Is Pseudo: Status: Is RDM Capable: Is Removable: Other Names: vml.000N000000XXXdXXXXXXXXaXXXaXX VAAI Status: nnnn naa.60060... Device Type: disk Size: 614400 MB Display Name: DGC Fibre Channel Disk (naa.60060...) ...

VMware, Inc.

43

vSphere Command-Line Interface Concepts and Examples

Listalllogicaldeviceswithabbreviatedinformation.
vicfg-scsidevs <conn_options> --compact-list

TheinformationincludesthedeviceID,devicetype,size,plugin,anddevicedisplayname.

Listalldeviceuniqueidentifiers.
vicfg-scsidevs <conn_options> --uids

ThecommandliststheprimaryUIDforeachdevice(naa.xxxorotherprimaryname)andanyotherUIDs foreachUID(VMLname).Youcanspecify--devicetoonlylistinformationforaspecificdevice.

Listaspecificlogicaldevicewithitsdetailedinformation.
vicfg-scsidevs <conn_options> -l -d mpx.vmhba32:C0:T1:L0

PrintmappingsforVMFSvolumestothecorrespondingpartition,pathtothatpartition,VMFSuuid, extentnumber,andvolumenames.
vicfg-scsidevs <conn_options> --vmfs

PrintHBAdeviceswithidentifyinginformation.
vicfg-scsidevs <conn_options> --hbas

ThereturnvalueincludestheadapterID,driverID,adapterUID,PCI,vendor,andmodel.

PrintamappingbetweenHBAsandthedevicesitprovidespathsto.
vicfg-scsidevs <conn_options> --hba-device-list

Managing Paths
TomaintainaconstantconnectionbetweenanESXihostanditsstorage,ESXisupportsmultipathing.With multipathingyoucanusemorethanonephysicalpathfortransferringdatabetweentheESXihostandthe externalstoragedevice. IncaseoffailureofanelementintheSANnetwork,suchasanHBA,switch,orcable,theESXihostcanfail overtoanotherphysicalpath.Onsomedevices,multipathingalsooffersloadbalancing,whichredistributes I/Oloadsbetweenmultiplepathstoreduceoreliminatepotentialbottlenecks. ThestoragearchitectureinvSphere4.0andlatersupportsaspecialVMkernellayer,PluggableStorage Architecture(PSA).ThePSAisanopenmodularframeworkthatcoordinatesthesimultaneousoperationof multiplemultipathingplugins(MPPs).YoucanmanagePSAusingESXCLIcommands.SeeManaging ThirdPartyStorageArraysonpage 85.ThissectionassumesyouareusingonlyPSApluginsincludedin vSpherebydefault.

Multipathing with Local Storage and FC SANs


Inasimplemultipathinglocalstoragetopology,youcanuseoneESXihostwithtwoHBAs.TheESXihost connectstoadualportlocalstoragesystemthroughtwocables.Thisconfigurationensuresfaulttoleranceif oneoftheconnectionelementsbetweentheESXihostandthelocalstoragesystemfails. TosupportpathswitchingwithFCSAN,theESXihosttypicallyhastwoHBAsavailablefromwhichthe storagearraycanbereachedthroughoneormoreswitches.Alternatively,thesetupcanincludeoneHBAand twostorageprocessorssothattheHBAcanuseadifferentpathtoreachthediskarray. InFigure 44,multiplepathsconnecteachhostwiththestoragedevice.Forexample,ifHBA1orthelink betweenHBA1andtheswitchfails,HBA2takesoverandprovidestheconnectionbetweentheserverandthe switch.TheprocessofoneHBAtakingoverforanotheriscalledHBAfailover.

44

VMware, Inc.

Chapter 4 Managing Storage

Figure 4-4. FC Multipathing


Host 1 Host 2

HBA2

HBA1

HBA3

HBA4

switch

switch

SP1

SP2

storage array

IfSP1orthelinkbetweenSP1andtheswitchbreaks,SP2takesoverandprovidestheconnectionbetweenthe switchandthestoragedevice.ThisprocessiscalledSPfailover.ESXimultipathingsupportsHBAandSP failover. Afteryouhavesetupyourhardwaretosupportmultipathing,youcanusethevSphereWebClientorvCLI commandstolistandmanagepaths.Youcanperformthefollowingtasks.

Listpathinformationwithvicfg-mpathoresxcli storage core path.SeeListingPathInformation onpage 45. Changepathstatewithvicfg-mpathoresxcli storage core path.SeeChangingtheStateofaPath onpage 47. IMPORTANTUseESXCLIforESXi5.0.Usevicfg-mpathforESX/ESXi4.0orlater.Usevicfg-mpath35 forESX/ESXi3.5.

ChangepathpolicieswithESXCLI.SeeSettingPolicyDetailsforDevicesthatUseRoundRobinon page 50. MaskpathswithESXCLI.SeethevSphereStoragedocumentation. Manipulatetherulesthatmatchpathstomultipathingpluginstonewlydiscovereddeviceswithesxcli claimrule.SeeManagingClaimRulesonpage 93. Runorrerunclaimrulesorunclaimpaths.SeeManagingClaimRulesonpage 93. Rescanwithvicfg-rescan.SeeScanningStorageAdaptersonpage 55.

Listing Path Information


YoucanlistpathinformationwithESXCLIorwithvicfg-mpath.

Listing Path Information with ESXCLI


Youcanrunesxcli storage core pathtodisplayinformationaboutFibreChanneloriSCSILUNs. IMPORTANTUseindustrystandarddevicenames,withformateui.xxxornaa.xxxtoensureconsistency. DonotuseVMLLUNnamesunlessdevicenamesarenotavailable. NamesofvirtualmachineHBAsarenotguaranteedtobevalidacrossreboots.

VMware, Inc.

45

vSphere Command-Line Interface Concepts and Examples

Youcandisplayinformationaboutpathsbyrunningesxcli storage core path.Specifyoneoftheoptions listedinConnectionOptionsonpage 17inplaceof<conn_options>.

Listalldeviceswiththeircorrespondingpaths,stateofthepath,adaptertype,andotherinformation.
esxcli <conn_options> storage core path list

Limitthedisplaytoonlyaspecifiedpathordevice.
esxcli <conn_options> storage core path list --path <path> esxcli <conn_options> storage core path list --device <device>

ListthestatisticsfortheSCSIpathsinthesystem.Youcanlistallpathsorlimitthedisplaytoaspecific path.
esxcli <conn_options> storage core path stats get esxcli <conn_options> storage core path stats get --path <path

Listdetailedinformationforthepathsforthedevicespecifiedwith--device.
esxcli <conn_options> storage core path list -d <naa.xxxxxx>

Listalladapters.
esxcli <conn_options> storage core adapter list

Rescanalladapters.
esxcli <conn_options> storage core adapter rescan

Listing Path Information with vicfg-mpath


Youcanrunvicfg-mpathtolistinformationaboutFibreChanneloriSCSILUNs. IMPORTANTUseindustrystandarddevicenames,withformateui.xxxornaa.xxxtoensureconsistency. DonotuseVMLLUNnamesunlessdevicenamesarenotavailable. NamesofvirtualmachineHBAsarenotguaranteedtobevalidacrossreboots. Youcandisplayinformationaboutpathsbyrunningvicfg-mpathwithoneofthefollowingoptions.Specify oneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Listalldeviceswiththeircorrespondingpaths,stateofthepath,adaptertype,andotherinformation.
vicfg-mpath <conn_options> --list-paths

Displayashortlistingofallpaths.
vicfg-mpath <conn_options> --list-compact

Listallpathswithadapteranddevicemappings.
vicfg-mpath <conn_options> --list-map

ListpathsanddetailedinformationbyspecifyingthepathUID(longpath).ThepathUIDisthefirstitem inthevicfg-mpath --listdisplay.


vicfg-mpath <conn_options> --list -P sas.5001c231c79c4a00-sas.1221000001000000-naa.5000c5000289c61b

Listpathsanddetailedinformationbyspecifyingthepathruntimename.
vicfg-mpath <conn_options> -l -P vmhba32:C0:T0:L0

Thereturninformationincludestheruntimename,device,devicedisplayname,adapter,adapter identifier,targetidentifier,plugin,state,transport,andadapterandtargettransportdetails.

Listdetailedinformationforthepathsforthedevicespecifiedwith--device.
vicfg-mpath <conn_options> -l -d mpx.vmhba32:C0:T1:L0 vicfg-mpath <conn_options> --list --device naa.60060...

46

VMware, Inc.

Chapter 4 Managing Storage

Changing the State of a Path


YoucanchangethestateofapathwithESXCLIorwithvicfg-mpath.

Changing Path State with ESXCLI


Youcantemporarilydisablepathsformaintenanceorotherreasons,andenablethepathwhenyouneedit again.YoucandisablepathswithESXCLI.SpecifyoneoftheoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. Ifyouarechangingapathsstate,thechangeoperationfailsifI/Oisactivewhenthepathsettingischanged. Reissuethecommand.YoumustissueatleastoneI/Ooperationbeforethechangetakeseffect. To disable a path with ESXCLI 1 (Optional)Listalldevicesandcorrespondingpaths.
esxcli <conn_options> storage core path list

Thedisplayincludesinformationabouteachpathsstate. 2 SetthestateofaLUNpathtooff.
esxcli <conn_options> storage core path set --state off --path vmhba32:C0:T1:L0

Whenyouareready,setthepathstatetoactiveagain.
esxcli <conn_options> storage core path set --state active --path vmhba32:C0:T1:L0

Changing Path State with vicfg-mpath


Youcandisablepathswithvicfg-mpath.SpecifyoneoftheoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. Ifyouarechangingapathsstate,thechangeoperationfailsifI/Oisactivewhenthepathsettingischanged. Reissuethecommand.YoumustissueatleastoneI/Ooperationbeforethechangetakeseffect. To disable a path with vicfg-mpath 1 (Optional)Listalldevicesandcorrespondingpaths.
vicfg-mpath <conn_options> --list-paths

Thedisplayincludesinformationabouteachpathsstate. 2 SetthestateofaLUNpathtooff.
vicfg-mpath <conn_options> --state off --path vmhba32:C0:T1:L0

Whenyouareready,setthepathstatetoactiveagain.
vicfg-mpath <conn_options> --state active --path vmhba32:C0:T1:L0

Managing Path Policies


ForeachstoragedevicemanagedbyNMP(notPowerPath),anESXihostusesapathselectionpolicy.Ifyou haveathirdpartyPSPinstalledonyourhost,itspolicyalsoappearsonthelist.Thefollowingpathpolicies aresupportedbydefault.

VMware, Inc.

47

vSphere Command-Line Interface Concepts and Examples

Table 4-1. Supported Path Policies


Policy VMW_PSP_FIXED Description Thehostusesthedesignatedpreferredpath,ifithasbeenconfigured.Otherwise,thehost selectsthefirstworkingpathdiscoveredatsystemboottime.Ifyouwantthehosttousea particularpreferredpath,specifyitthroughthevSphereWebClient,orbyusingesxcli storage nmp psp fixed deviceconfig set.SeeChangingPathPoliciesonpage 49. ThedefaultpolicyforactiveactivestoragedevicesisVMW_PSP_FIXED. VMW_PSP_MRU Thehostselectsthepaththatitusedmostrecently.Whenthepathbecomesunavailable,the hostselectsanalternativepath.Thehostdoesnotrevertbacktotheoriginalpathwhenthat pathbecomesavailableagain.ThereisnopreferredpathsettingwiththeMRUpolicy.MRU isthedefaultpolicyforactivepassivestoragedevices. Thehostusesanautomaticpathselectionalgorithmthatrotatesthroughallactivepaths whenconnectingtoactivepassivearrays,orthroughallavailablepathswhenconnectingto activeactivearrays.Automaticpathselectionimplementsloadbalancingacrossthephysical pathsavailabletoyourhost.LoadbalancingistheprocessofspreadingI/Orequestsacross thepaths.ThegoalistooptimizethroughputperformancesuchasI/Opersecond,megabytes persecond,orresponsetimes. VMW_PSP_RRisthedefaultforanumberofarraysandcanbeusedwithbothactiveactiveand activepassivearraystoimplementloadbalancingacrosspathsfordifferentLUNs.

VMW_PSP_RR

Thetypeofarrayandthepathpolicydeterminethebehaviorofthehost. Table 4-2. Path Policy Effects


Policy MostRecentlyUsed Fixed Active/Active Array Administratoractionisrequiredtofail backafterpathfailure. VMkernelresumesusingthepreferred pathwhenconnectivityisrestored. Active/Passive Array Administratoractionisrequiredtofailback afterpathfailure. VMkernelattemptstoresumebyusingthe preferredpath.Thisactioncancausepath thrashingorfailurewhenanotherSPnow ownstheLUN. Nextpathinroundrobinschedulingis selected.

RoundRobin

Nofailback.

Multipathing Considerations
Thefollowingconsiderationshelpyouwithmultipathing:

IfnoSATPisassignedtothedevicebytheclaimrules,thedefaultSATPforiSCSIorFCdevicesis VMW_SATP_DEFAULT_AA.ThedefaultPSPisVMW_PSP_FIXED. WhenthesystemsearchestheSATPrulestolocateaSATPforagivendevice,itsearchesthedriverrules first.Ifthereisnomatch,thevendor/modelrulesaresearched,andfinallythetransportrulesare searched.Ifnomatchoccurs,NMPselectsadefaultSATPforthedevice. IfVMW_SATP_ALUAisassignedtoaspecificstoragedevice,butthedeviceisnotALUAaware,noclaim rulematchoccursforthisdevice.ThedeviceisclaimedbythedefaultSATPbasedonthedevices transporttype. ThedefaultPSPforalldevicesclaimedbyVMW_SATP_ALUAisVMW_PSP_MRU.TheVMW_PSP_MRUselectsan active/optimizedpathasreportedbytheVMW_SATP_ALUA,oranactive/unoptimizedpathifthereis noactive/optimizedpath.Thispathisuseduntilabetterpathisavailable(MRU).Forexample,ifthe VMW_PSP_MRUiscurrentlyusinganactive/unoptimizedpathandanactive/optimizedpathbecomes available,theVMW_PSP_MRUwillswitchthecurrentpathtotheactive/optimizedone.

48

VMware, Inc.

Chapter 4 Managing Storage

WhileVMW_PSP_MRUistypicallyselectedforALUAarraysbydefault,certainALUAstoragearraysneed touseVMW_PSP_FIXED.TocheckwhetheryourstoragearrayrequiresVMW_PSP_FIXED,seetheVMware CompatibilityGuideorcontactyourstoragevendor.WhenusingVMW_PSP_FIXEDwithALUAarrays, unlessyouexplicitlyspecifyapreferredpath,theESXihostselectsthemostoptimalworkingpathand designatesitasthedefaultpreferredpath.Ifthehostselectedpathbecomesunavailable,thehostselects analternativeavailablepath.However,ifyouexplicitlydesignatethepreferredpath,itwillremain preferrednomatterwhatitsstatusis. Bydefault,thePSAclaimrule101masksDellarraypseudodevices.Donotdeletethisrule,unlessyou wanttounmaskthesedevices.

Changing Path Policies


YoucanchangepathpolicieswithESXCLIorwithvicfg-mpath.

Changing Path Policies with ESXCLI


YoucanchangethepathpolicywithESXCLI.SpecifyoneoftheoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. To change the path policy with ESXCLI 1 EnsureyourdeviceisclaimedbytheNMPplugin.OnlyNMPdevicesallowyoutochangethepath policy.
esxcli <conn_options> storage nmp device list

Retrievethelistofpathselectionpoliciesonthesystemtoseewhichvaluesarevalidforthe--pspoption whenyousetthepathpolicy.
esxcli storage core plugin registration list --plugin-class="PSP"

Setthepathpolicyusingesxcli.
esxcli <conn_options> storage nmp device set --device naa.xxx --psp VMW_PSP_RR

SeeTable 41,SupportedPathPolicies,onpage 48. 4 (Optional)IfyouspecifiedtheVMW_PSP_FIXEDpolicy,youmustmakesurethepreferredpathisset correctly. a Checkwhichpathisthepreferredpathforadevice.


esxcli <conn_options> storage nmp psp fixed deviceconfig get --device naa.xxx

Ifnecessary,changethepreferredpath.
esxcli <conn_options> storage nmp psp fixed deviceconfig set --device naa.xxx --path vmhba3:C0:T5:L3

Thecommandsetsthepreferredpathtovmhba3:C0:T5:L3.Runthecommandwith--defaultto clearthepreferredpathselection.

Changing Path Policies with vicfg-mpath


Youcanchangethepathpolicywithvicfg-mpath.SpecifyoneoftheoptionslistedinConnectionOptions onpage 17inplaceof<conn_options>. To change the path policy with vicfg-mpath 1 Listallmultipathingpluginsloadedintothesystem.
vicfg-mpath <conn_options> --list-plugins

Ataminimum,thiscommandreturnsNMP(NativeMultipathingPlugin)andMASK_PATH.IfotherMPP pluginshavebeenloaded,theyarelistedaswell. 2 SetthepathpolicybyusingESXCLI.

VMware, Inc.

49

vSphere Command-Line Interface Concepts and Examples

esxcli <conn_options> nmp device set --device naa.xxx --psp VMW_PSP_RR

SeeTable 41,SupportedPathPolicies,onpage 48. 3 (Optional)IfyouspecifiedtheVMW_PSP_FIXEDpolicy,youmustmakesurethepreferredpathisset correctly. a Firstcheckwhichpathisthepreferredpathforadevice.


esxcli <conn_options> storage nmp psp fixed deviceconfig get -d naa.xxxx

Ifnecessary,changethepreferredpath.
esxcli <conn_options> storage nmp psp fixed deviceconfig set --device naa.xxx --path vmhba3:C0:T5:L3

Thecommandsetsthepreferredpathtovmhba3:C0:T5:L3

Setting Policy Details for Devices that Use Round Robin


ESXihostscanusemultipathingforfailover.Withcertainstoragedevices,ESXihostscanalsouse multipathingforloadbalancing.Toachievebetterloadbalancingacrosspaths,administratorscanspecifythat theESXihostshouldswitchpathsundercertaincircumstances.Differentsettableoptionsdeterminewhenthe ESXihostswitchespathsandwhatpathsarechosen.Onlyalimitednumberofstoragearrayssupportround robin. Youcanuseesxcli nmp roundrobintoretrieveandsetroundrobinpathoptionsonadevicecontrolledby theroundrobinPSP.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>. Novicfg-commandexistsforperformingtheoperations.TheESXCLIcommandsforsettingroundrobin pathoptionshavechanged.ThecommandssupportedinESX/ESXi4.xisnolongersupported. To view and manipulate round robin path selection settings with ESXCLI 1 RetrievepathselectionsettingsforadevicethatisusingtheroundrobinPSP.
esxcli <conn_options> storage nmp psp roundrobin deviceconfig get --device na.xxx

Setthepathselection.Youcanspecifywhenthepathshouldchange,andwhetherunoptimizedpaths shouldbeincluded.

Use--bytesor--iopstospecifywhenthepathshouldchange,asinthefollowingexamples:
esxcli <conn_options> storage nmp psp roundrobin deviceconfig set --type "bytes" -B 12345 --device naa.xxx

Setsthedevicespecifiedby--devicetoswitchtothenextpatheachtime12345byteshavebeensent alongthecurrentpath.
esxcli <conn_options> storage nmp psp roundrobin deviceconfig set --type=iops --iops 4200 --device naa.xxx

Setsthedevicespecifiedby--devicetoswitchafter4200I/Ooperationshavebeenperformedona path.

UseuseanotospecifythattheroundrobinPSPshouldincludepathsintheactive,unoptimizedstate intheroundrobinset(1)orthatthePSPshoulduseactive,unoptimizedpathsonlyifnoactive optimizedpathsareavailable(0).Ifyoudonotincludethisoption,thePSPincludesonlyactive optimizedpathsintheroundrobinpathset.

Managing NFS/NAS Datastores


ESXihostscanaccessadesignatedNFSvolumelocatedonaNAS(NetworkAttachedStorage)server,can mountthevolume,andcanuseitforitsstorageneeds.YoucanuseNFSvolumestostoreandbootvirtual machinesinthesamewaythatyouuseVMFSdatastores.

50

VMware, Inc.

Chapter 4 Managing Storage

Capabilities Supported by NFS/NAS


ESXihostssupportthefollowingsharedstoragecapabilitiesonNFSvolumes:

VMwarevMotion VMwareDRSandVMwareHA ISOimages,whicharepresentedasCDROMstovirtualmachines Virtualmachinesnapshots

NASstoresvirtualmachinefilesonremotefileserversthatareaccessedoverastandardTCP/IPnetwork.The NFSclientbuiltintotheESXisystemusesNFSversion3tocommunicatewithNAS/NFSservers.Fornetwork connectivity,thehostrequiresastandardnetworkadapter. InadditiontostoringvirtualdisksonNFSdatastores,youcanalsouseNFSasacentralrepositoryforISO images,virtualmachinetemplates,andsoon. TouseNFSasasharedrepository,youcreateadirectoryontheNFSserverandthenmountthedirectoryas adatastoreonallhosts.IfyouusethedatastoreforISOimages,youcanconnectthevirtualmachines CDROMdevicetoanISOfileonthedatastoreandinstallaguestoperatingsystemfromtheISOfile.

Adding and Deleting NAS File Systems


Youcanlist,add,anddeleteaNASfilesystemwithESXCLIorwithvicfg-nas.

Managing NAS File Systems with ESXCLI


YoucanuseESXCLIasavCLIcommandwithconnectionoptions(seeConnectionOptionsonpage 17)or intheESXishell. To manage a NAS file system 1 ListallknownNASfilesystems.
esxcli <conn_options> storage nfs list

ForeachNASfilesystem,thecommandliststhemountname,sharename,andhostnameandwhether thefilesystemismounted. IfnoNASfilesystemsareavailable,thesystemdoesnotreturnaNASfilesystemandreturnstothe commandprompt. 2 AddanewNASfilesystemtotheESXihost.SpecifytheNASserverwith--host,thevolumetousefor themountwith--volume-name,andthesharenameontheremotesystemtouseforthisNASmount pointwith--share.


esxcli <conn_options> storage nfs add --host=dir42.eng.vmware.com --share=/<mount_dir> --volume-name=nfsstore-dir42

ThiscommandaddsanentrytotheknownNASfilesystemlistandsuppliesthesharenameofthenew NASfilesystem.Youmustsupplythehostname,sharename,andvolumenameforthenewNASfile system. 3 AddasecondNASfilesystemwithreadonlyaccess.


esxcli <conn_options> storage nfs add --host=dir42.eng.vmware.com --share=/home --volume-name=FileServerHome2 --readonly

DeleteoneoftheNASfilesystems.
esxcli <conn_options> storage nfs remove --volume-name=FileServerHome2

ThiscommandunmountstheNASfilesystemandremovesitfromthelistofknownfilesystems.

Managing NAS File Systems with vicfg-nas


Youcanusevicfg-nasasavCLIcommandwithconnectionoptions.SeeConnectionOptionsonpage 17.

VMware, Inc.

51

vSphere Command-Line Interface Concepts and Examples

To manage a NAS file system 1 ListallknownNASfilesystems.


vicfg-nas <conn_options> -l

ForeachNASfilesystem,thecommandliststhemountname,sharename,andhostnameandwhether thefilesystemismounted.IfnoNASfilesystemsareavailable,thesystemreturnsthefollowingmessage:
No NAS datastore found

AddanewNASfilesystemtotheESXihost.
vicfg-nas <conn_options --add nfsstore-dir42

--nasserver dir42.eng.vmware.com -s /<mount_dir>

ThiscommandaddsanentrytotheknownNASfilesystemlistandsuppliesthesharenameofthenew NASfilesystem.YoumustsupplythehostnameandthesharenameforthenewNASfilesystem. 3 AddasecondNASfilesystemwithreadonlyaccess.


vicfg-nas <conn_options> -a -y --n esx42nas2 -s /home FileServerHome2

DeleteoneoftheNASfilesystems.
vicfg-nas <conn_options> -d FileServerHome1

ThiscommandunmountstheNASfilesystemandremovesitfromthelistofknownfilesystems.

Monitoring and Managing SAN Storage


Theesxcli storage sancommandshelpadministratorstroubleshootissueswithI/Odevicesandfabric, andincludeFibreChannel,FCoE,iSCSI,SASprotocolstatistics.Thecommandsallowyoutoretrievedevice informationandI/Ostatisticsfromthosedevice.YoucanalsoissueLoopInitializationPrimitivesLIPto FC/FCoEdevicesandyoucanresetSASdevices. ForFCandFCoEdevices,youcanretrieveFCeventssuchasRSCN,LINKUP,LINKDOWN,FrameDropandFCoE CVL.ThecommandslogawarningintheVMkernellogifitencounterstoomanyLinkTogglingorframedrops To retrieve and reset the IO Device Management module 1 RetrievealleventsforaFibreChannelI/Odevice.
esxcli storage san fc events get

ClearallI/ODeviceManagementeventsforthespecifiedadapter.
esxcli storage san fc events clear --adapter adapter

Migrating Virtual Machines with svmotion


StoragevMotionmovesavirtualmachinesconfigurationfile,and,optionally,itsdisks,whilethevirtual machineisrunning.YoucanperformStoragevMotiontasksfromthevSphereWebClientorwiththe svmotioncommand. IMPORTANTNoESXCLIcommandforStoragevMotionisavailable. Youcanplacethevirtualmachineandallofitsdisksinasinglelocation,orchooseseparatelocationsforthe virtualmachineconfigurationfileandeachvirtualdisk.Youcannotchangethevirtualmachinesexecution hostduringamigrationwithsvmotion.

Storage vMotion Uses


StoragevMotionhasseveralusesinadministeringyourvSphereenvironment.

UpgradeESXiwithoutvirtualmachinedowntimeinsituationswherevirtualmachinedisksmustbe movedtosharedstoragetoallowmigrationwithvMotion.
VMware, Inc.

52

Chapter 4 Managing Storage

Performstoragemaintenanceandreconfiguration.YoucanuseStoragevMotiontomovevirtual machinesoffastoragedevicetoallowmaintenanceorreconfigurationofthestoragedevicewithout virtualmachinedowntime. Redistributestorageload.YoucanuseStoragevMotiontomanuallyredistributevirtualmachinesor virtualdiskstodifferentstoragevolumestobalancecapacityorimproveperformance.

Storage vMotion Requirements and Limitations


YoucanmigratevirtualmachinediskswithStoragevMotionifthevirtualmachineanditshostmeetthe followingresourceandconfigurationrequirements:

ForESXi5.0hosts,youcanmigratevirtualmachinesthathavesnapshots.ForearlierversionsofESXi,you cannotmigratevirtualmachinesthathavesnapshots. Virtualmachinedisksmustbeinpersistentmodeorberawdevicemappings(RDMs).Forphysicaland virtualcompatibilitymodeRDMs,youcanmigratethemappingfileonly.Forvirtualcompatibilitymode RDMs,youcanusethevSphereWebClienttoconverttothickprovisionedorthinprovisioneddisks duringmigrationaslongasthedestinationisnotanNFSdatastore.Youcannotusethesvmotion commandtoperformthisconversion. ThehostonwhichthevirtualmachineisrunningmusthavealicensethatincludesStoragevMotion. ESX/ESXi3.5hostsmustbelicensedandconfiguredforvMotion.ESX/ESXi4.0andlaterhostsdonot requirevMotionconfigurationtoperformmigrationwithStoragevMotion. Thehostthevirtualmachineisrunningonmusthaveaccesstoboththesourceandtargetdatastores. AparticularhostcanbeinvolvedinuptofourmigrationswithvMotionorStoragevMotionatonetime. SeeLimitsonSimultaneousMigrationsinthevCenterServerandHostManagementdocumentationfor details.

IfyouusethevSphereWebClientformigrationwithsvmotion,thesystemperformsseveralcompatibility checks.ThesechecksarenotsupportedbythesvmotionvCLIcommand.

Running svmotion in Interactive Mode


Youcanrunsvmotionininteractivemodeusingthe--interactiveoption.Thecommandpromptsyoufor theinformationitneedstocompletethestoragemigration.
svmotion <conn_options> --interactive

Whenyouuse--interactive,allotheroptionsareignored. IMPORTANTWhenrespondingtotheprompts,usequotesaroundinputstringswithspecialcharacters.

Running svmotion in Noninteractive Mode


IMPORTANTWhenyourunsvmotion,--servermustpointtoavCenterServersystem. Innoninteractivemode,thesvmotioncommandusesthefollowingsyntax:
svmotion [standard vCLI options] --datacenter=<datacenter_name> --vm <VM config datastore path>:<new datastore> [--disks <virtual disk datastore path>:<new datastore>, <virtual disk datastore path>:<new datastore>]

Squarebracketsindicateoptionalelements,notdatastores. The--vmoptionspecifiesthevirtualmachineanditsdestination.Bydefault,allvirtualdisksarerelocatedto thesamedatastoreasthevirtualmachine.Thisoptionrequiresthecurrentvirtualmachineconfigurationfile location.SeeTodeterminethepathtothevirtualmachineconfigurationfileanddiskfileonpage 54.

VMware, Inc.

53

vSphere Command-Line Interface Concepts and Examples

The--disksoptionrelocatesindividualvirtualdiskstodifferentdatastores.The--disksoptionrequiresthe currentvirtualdiskdatastorepathasanoption.SeeTodeterminethepathtothevirtualmachine configurationfileanddiskfileonpage 54. To determine the path to the virtual machine configuration file and disk file 1 Runvmware-cmd -ltolistallvirtualmachineconfigurationfiles(VMXfiles).
vmware-cmd -H <vc_server> -U <login_user> -P <login_password> -h <esx_host> -l

ChoosetheVMXfileforthevirtualmachineofinterest. Bydefault,thevirtualdiskfilehasthesamenameastheVMXfilebuthasa.vmdkextension.

(Optional)UsevifstoverifythatyouareusingthecorrectVMDKfile.

To relocate a virtual machines storage (including disks) 1 2 Determinethepathtothevirtualmachineconfigurationfile. Runsvmotion:


svmotion --url=https://myvc.mycorp.com/sdk --datacenter=DC1 --vm=[storage1] myvm/myvm.vmx:new_datastore

TheexampleisforWindows.UsesinglequotesonLinux. To relocate a virtual machines configuration file, but leave virtual disks 1 2 Determinethepathtothevirtualdiskfilesandthevirtualmachineconfigurationfile. Runsvmotion,forexample:
svmotion <conn_options> --datacenter='My DC' --vm='[old_datastore] myvm/myvm.vmx:new_datastore' --disks='[old_datastore] myvm/myvm_1.vmdk:old_datastore, [old_datastore] myvm/myvm_2.vmdk: old_datastore'

Thiscommandrelocatesthevirtualmachinesconfigurationfiletonew_datastore,butleavesthetwodisks (myvm_1.vmdkandmyvm_2.vmdk)inold_datastore.TheexampleisforLinux.Usedoublequoteson Windows.Thesquarebracketssurroundthedatastorenameanddonotindicateanoptionalelement.

Configuring FCoE Adapters


ESXicanuseFibreChanneloverEthernet(FCoE)adapterstoaccessFibreChannelstorage. TheFCoEprotocolencapsulatesFibreChannelframesintoEthernetframes.Asaresult,yourhostdoesnot needspecialFibreChannellinkstoconnecttoFibreChannelstorage,butcanuse10GbitlosslessEthernetto deliverFibreChanneltraffic. TouseFCoE,youneedtoinstallFCoEadapters.TheadaptersthatVMwaresupportsgenerallyfallintotwo categories,hardwareFCoEadaptersandsoftwareFCoEadapters.

HardwareFCoEAdapters.HardwareFCoEadaptersincludecompletelyoffloadedspecialized ConvergedNetworkAdapters(CNAs)thatcontainnetworkandFibreChannelfunctionalitiesonthe samecard.Whensuchanadapterisinstalled,yourhostdetectsandcanusebothCNAcomponents.In thevSphereWebClient,thenetworkingcomponentappearsasastandardnetworkadapter(vmnic)and theFibreChannelcomponentasaFCoEadapter(vmhba).YoudonothavetoconfigureahardwareFCoE adaptertobeabletouseit. SoftwareFCoEAdapters.AsoftwareFCoEadapterisasoftwarecodethatperformssomeoftheFCoE processing.TheadaptercanbeusedwithanumberofNICsthatsupportpartialFCoEoffload.Unlikethe hardwareFCoEadapter,thesoftwareadaptermustbeactivated.

54

VMware, Inc.

Chapter 4 Managing Storage

Scanning Storage Adapters


Youmustperformarescanoperationeachtimeyoureconfigureyourstoragesetup.Youcanscanusingthe vSphereWebClientthevicfg-rescanvCLIcommand,ortheesxcli storage core adapter rescan command.

esxcli storage core adapter rescansupportsthefollowingadditionaloptions:


-a|--allor-A|--adapter=<string>Scanalladaptersoraspecifiedadapter. -S|--skip-claimSkipclaimingofnewdevicesbytheappropriatemultipathplugin. -F|--skip-fs-scanSkipfilesystemscan -t|--typeSpecifythetypeofscantoperform.Thecommandeitherscansforallchanges(all)or foradded,deleted,orupdatedadapters(add,delete,update)

vicfg-rescansupportsonlyasimplerescanoperationonaspecifiedadapter.

To rescan a storage adapter with vicfg-rescan Runvicfg-rescan,specifyingtheadaptername.


vicfg-rescan <conn_options> vmhba1

Thecommandreturnsanindicationofsuccessorfailure,butnodetailedinformation. To rescan a storage adapter with ESXCLI Thefollowingcommandscansaspecificadapterandskipsthefilesystemscanthatisperformedbydefault.


esxcli <conn_options> storage core adapter rescan --adapter=vmhba33 --skip-claim

Thecommandreturnsanindicationofsuccessorfailure,butnodetailedinformation.

Retrieving SMART Information


YoucanuseESXCLItoretrieveinformationrelatedtoSMART.SMARTisamonitoringsystemforcomputer harddisksthatreportsinformationaboutthedisks.
esxcli storage core device smart get -d device

WhatthecommandreturnsdependsonthelevelofSMARTinformationthatthedevicesupports.Ifno informationisavailableforaparameter,theoutputdisplaysN/A,asinthefollowingsampleoutput.
Parameter Value Threshold Worst ----------------------------------------------------Health Status OK N/A N/A Media Wearout Indicator N/A N/A N/A Write Error Count N/A N/A N/A Read Error Count 119 6 74 Power-on Hours 57 0 57 Power Cycle Count 100 20 100 Reallocated Sector Count 100 36 100 Raw Read Error Rate 119 6 74 Drive Temperature 38 0 49 Driver Rated Max Temperature 62 45 51 Write Sectors TOT Count 200 0 200 Read Sectors TOT Count 100 0 253 Initial Bad Block Count N/A N/A N/A

VMware, Inc.

55

vSphere Command-Line Interface Concepts and Examples

56

VMware, Inc.

53

Managing iSCSI Storage

ESXisystemsincludeiSCSItechnologytoaccessremotestorageusinganIPnetwork.YoucanusethevSphere WebClient,commandsintheesxcliiscsinamespace,orthevicfg-iscsicommandtoconfigureboth hardwareandsoftwareiSCSIstorageforyourESXisystem. Thischapterincludesthefollowingtopics:


iSCSIStorageOverviewonpage 57 ProtectinganiSCSISANonpage 59 CommandSyntaxforesxcliiscsiandvicfgiscsionpage 61 iSCSIStorageSetupwithESXCLIonpage 66 iSCSIStorageSetupwithvicfgiscsionpage 71 ListingandSettingiSCSIOptionsonpage 75 ListingandSettingiSCSIParametersonpage 76 EnablingiSCSIAuthenticationonpage 80 SettingUpPortsforiSCSIMultipathingonpage 81 ManagingiSCSISessionsonpage 82

SeethevSphereStoragedocumentationforadditionalinformation.

iSCSI Storage Overview


WithiSCSI,SCSIstoragecommandsthatyourvirtualmachineissuestoitsvirtualdiskareconvertedinto TCP/IPprotocolpacketsandtransmittedtoaremotedevice,ortarget,onwhichthevirtualdiskislocated.To thevirtualmachine,thedeviceappearsasalocallyattachedSCSIdrive. Toaccessremotetargets,theESXihostusesiSCSIinitiators.InitiatorstransportSCSIrequestsandresponses betweenESXiandthetargetstoragedeviceontheIPnetwork.ESXisupportsthesetypesofinitiators:

SoftwareiSCSIadapter.VMwarecodebuiltintotheVMkernel.AllowsanESXihosttoconnecttothe iSCSIstoragedevicethroughstandardnetworkadapters.ThesoftwareinitiatorhandlesiSCSIprocessing whilecommunicatingwiththenetworkadapter. HardwareiSCSIadapter.OffloadsalliSCSIandnetworkprocessingfromyourhost.HardwareiSCSI adaptersarebrokenintotwotypes.

DependenthardwareiSCSIadapter.LeveragestheVMwareiSCSImanagementandconfiguration interfaces. IndependenthardwareiSCSIadapter.LeveragesitsowniSCSImanagementandconfiguration interfaces.

SeethevSphereStoragedocumentationfordetailsonsetupandfailoverscenarios.

VMware, Inc.

57

vSphere Command-Line Interface Concepts and Examples

YoumustconfigureiSCSIinitiatorsforthehosttoaccessanddisplayiSCSIstoragedevices. Figure 51depictshoststhatusedifferenttypesofiSCSIinitiators.


ThehostontheleftusesanindependenthardwareiSCSIadaptertoconnecttotheiSCSIstoragesystem. ThehostontherightusessoftwareiSCSI.

DependenthardwareiSCSIcanbeimplementedindifferentwaysandisnotshown.iSCSIstoragedevices fromthestoragesystembecomeavailabletothehost.YoucanaccessthestoragedevicesandcreateVMFS datastoresforyourstorageneeds. Figure 5-1. iSCSI Storage


hardware iSCSI host 1 software adapter HBA2 HBA1 NIC2 NIC1 software iSCSI host 2

IP network

SP

iSCSI storage

Discovery Sessions
AdiscoverysessionispartoftheiSCSIprotocol.Thediscoverysessionreturnsthesetoftargetsthatyoucan accessonaniSCSIstoragesystem.ESXisystemssupportdynamicandstaticdiscovery.

Dynamicdiscovery.AlsoknownasSendTargetsdiscovery.EachtimetheESXihostcontactsaspecified iSCSIstorageserver,itsendsaSendTargetsrequesttotheserver.Inresponse,theiSCSIstorageserver suppliesalistofavailabletargetstotheESXihost.Monitorandmanagewithesxcli iscsi adapter discovery sendtargetorvicfg-iscsicommands. Staticdiscovery.TheESXihostdoesnothavetoperformdiscovery.Instead,theESXihostusestheIP addressesordomainnamesandiSCSItargetnames(IQNorEUIformatnames)tocommunicatewiththe iSCSItarget.Monitorandmanagewithesxcli iscsi adapter discovery statictargetor vicfg-iscsicommands.

Foreithercase,yousetuptargetdiscoveryaddressessothattheinitiatorcandeterminewhichstorage resourceonthenetworkisavailableforaccess.Youcandothissetupwithdynamicdiscoveryorstatic discovery.Withdynamicdiscovery,alltargetsassociatedwithanIPaddressorhostnameandtheiSCSIname arediscovered.Withstaticdiscovery,youmustspecifytheIPaddressorhostnameandtheiSCSInameofthe targetyouwanttoaccess.TheiSCSIHBAmustbeinthesameVLANasbothportsoftheiSCSIarray.

58

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Discovery Target Names


ThetargetnameiseitheranIQNnameoranEUIname.

TheIQNnameusesthefollowingformat:
iqn.yyyy-mm.{reversed domain name}:id_string

Forexample:iqn.2007-05.com.mydomain:storage.tape.sys3.abc TheESXihostgeneratesanIQNnameforsoftwareiSCSIanddependenthardwareiSCSIadapters.You canchangethatdefaultIQNname.

TheEUInameisdescribedinIETFrfc3720asfollows: TheIEEERegistrationAuthorityprovidesaserviceforassigninggloballyuniqueidentifiers[EUI].The EUI64formatisusedtobuildaglobalidentifierinothernetworkprotocols.Forexample,FibreChannel definesamethodofencodingitintoaWorldWideName. Theformatiseui.followedbyanEUI64identifier(16ASCIIencodedhexadecimaldigits). Forexample:


Type EUI-64 identifier (ASCII-encoded hexadecimal) +--++--------------+ | || | eui.02004567A425678D

TheIEEEEUI64iSCSInameformatcanbeusedwhenamanufacturerisregisteredwiththeIEEE RegistrationAuthorityandusesEUI64formattedworldwideuniquenamesforitsproducts. CheckintheUIofthestoragearraywhetheranarrayusesanIQNnameoranEUIname.

Protecting an iSCSI SAN


YouriSCSIconfigurationisonlyassecureasyourIPnetwork.Byenforcinggoodsecuritystandardswhenyou setupyournetwork,youhelpsafeguardyouriSCSIstorage.

Protecting Transmitted Data


AprimarysecurityriskiniSCSISANsisthatanattackermightsnifftransmittedstoragedata.Neitherthe iSCSIadapternortheESXihostiSCSIinitiatorencryptsthedatathatittransmitstoandfromthetargets, makingthedatavulnerabletosniffingattacks.Youmustthereforetakeadditionalmeasurestoprevent attackersfromeasilyseeingiSCSIdata. AllowingyourvirtualmachinestosharevirtualswitchesandVLANswithyouriSCSIconfiguration potentiallyexposesiSCSItraffictomisusebyavirtualmachineattacker.Tohelpensurethatintruderscannot listentoiSCSItransmissions,makesurethatnoneofyourvirtualmachinescanseetheiSCSIstoragenetwork. ProtectyoursystembygivingtheiSCSISANadedicatedvirtualswitch.

IfyouuseanindependenthardwareiSCSIadapter,makesurethattheiSCSIadapterandESXiphysical networkadapterarenotinadvertentlyconnectedoutsidethehost.Suchaconnectionmightresultfrom sharingaswitch. Ifyouusedependenthardwareorsoftwareiscsiadapter,whichusesESXinetworking,configureiSCSI storagethroughadifferentvirtualswitchthantheoneusedbyyourvirtualmachines.

YoucanalsoconfigureyouriSCSISANonitsownVLANtoimproveperformanceandsecurity.Placingyour iSCSIconfigurationonaseparateVLANensuresthatnodevicesotherthantheiSCSIadaptercansee transmissionswithintheiSCSISAN.WithadedicatedVLAN,networkcongestionfromothersourcescannot interferewithiSCSItraffic.

VMware, Inc.

59

vSphere Command-Line Interface Concepts and Examples

Securing iSCSI Ports


WhenyouruniSCSIdevices,theESXihostdoesnotopenportsthatlistenfornetworkconnections.This measurereducesthechancesthatanintrudercanbreakintotheESXihostthroughspareportsandgaincontrol overthehost.Therefore,runningiSCSIdoesnotpresentanadditionalsecurityrisksattheESXihostendof theconnection. AniSCSItargetdevicemusthaveoneormoreopenTCPportstolistenforiSCSIconnections.Ifsecurity vulnerabilitiesexistintheiSCSIdevicesoftware,yourdatacanbeatriskthroughnofaultoftheESXisystem. Tolowerthisrisk,installallsecuritypatchesthatyourstorageequipmentmanufacturerprovidesandlimitthe devicesconnectedtotheiSCSInetwork.

Setting iSCSI CHAP


iSCSIstoragesystemsauthenticateaninitiatorusinganameandkeypair.ESXisystemssupportChallenge HandshakeAuthenticationProtocol(CHAP),whichVMwarerecommendsforyourSANimplementation. TheESXihostandtheiSCSIstoragesystemmusthaveCHAPenabledandmusthavecommoncredentials. DuringiSCSIlogin,theiSCSIstoragesystemexchangesitscredentialswiththeESXisystemandchecksthem. YoucansetupiSCSIauthenticationbyusingthevSphereWebClient,asdiscussedinthevSphereStorage documentationorbyusingtheesxclicommand,discussedinEnablingiSCSIAuthenticationonpage 80. TouseCHAPauthentication,youmustenableCHAPonboththeinitiatorsideandthestoragesystemside. Afterauthenticationisenabled,itappliesfortargetstowhichnoconnectionhasbeenestablished,butdoesnot applytotargetstowhichaconnectionisestablished.Afterthediscoveryaddressisset,thenewvolumesto whichyouaddaconnectionareexposedandcanbeused. ForsoftwareiSCSIanddependenthardwareiSCSI,ESXihostssupportperdiscoveryandpertargetCHAP credentials.ForindependenthardwareiSCSI,ESXihostssupportonlyonesetofCHAPcredentialsper initiator.YoucannotassigndifferentCHAPcredentialsfordifferenttargets. WhenyouconfigureindependenthardwareiSCSIinitiators,ensurethattheCHAPconfigurationmatches youriSCSIstorage.IfCHAPisenabledonthestoragearray,itmustbeenabledontheinitiator.IfCHAPis enabled,youmustsetuptheCHAPauthenticationcredentialsontheESXihosttomatchthecredentialson theiSCSIstorage. Supported CHAP Levels TosetCHAPlevelswithesxcli iscsi adapter setauthorvicfg-iscsi,specifyoneofthevaluesin Table 51for<level>.OnlytwolevelsaresupportedforindependenthardwareiSCSI. MutualCHAPissupportedforsoftwareiSCSIandfordependenthardwareiSCSI,butnotforindependent hardwareiSCSI. IMPORTANTEnsurethatCHAPissettochapRequiredbeforeyousetmutualCHAP,andusecompatible levelsforCHAPandmutualCHAP.UsedifferentpasswordsforCHAPandmutualCHAPtoavoidsecurity risks. Table 5-1. Supported Levels for CHAP
Level chapProhibited Description HostdoesnotuseCHAPauthentication.Ifauthenticationis enabled,specifychapProhibitedtodisableit. Supported SoftwareiSCSI DependenthardwareiSCSI IndependenthardwareiSCSI chapDiscouraged HostusesanonCHAPconnection,butallowsaCHAP connectionasfallback. HostusesCHAPiftheCHAPconnectionsucceeds,butuses nonCHAPconnectionsasfallback. SoftwareiSCSI DependenthardwareiSCSI SoftwareiSCSI DependenthardwareiSCSI IndependenthardwareiSCSI chapRequired HostrequiressuccessfulCHAPauthentication.Theconnection failsifCHAPnegotiationfails. SoftwareiSCSI DependenthardwareiSCSI

chapPreferred

60

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Returning Authentication to Default Inheritance ThevaluesofiSCSIauthenticationsettingsassociatedwithadynamicdiscoveryaddressorastaticdiscovery targetareinheritedfromthecorrespondingsettingsoftheparent.Forthedynamicdiscoveryaddress,the parentistheadapter.Forthestatictarget,theparentistheadapterordiscoveryaddress.

IfyouusethevSphereWebClienttomodifyauthenticationsettings,youmustdeselecttheInheritfrom Parentcheckboxbeforeyoucanmakeachangetothediscoveryaddressordiscoverytarget. Ifyouusevicfg-iscsi,thevalueyousetoverridestheinheritedvalue. Ifyouuseesxcli iscsicommands,thevalueyousetoverridestheinheritedvalue.YoucansetCHAP attheselevels:


esxcli iscsi adapter auth chap [get|set] esxcli iscsi adapter discovery sendtarget auth chap [get|set] esxcli iscsi adapter target portal auth chap [get|set]

Inheritanceisrelevantonlyifyouwanttoreturnadynamicdiscoveryaddressorastaticdiscoverytargetto itsinheritedvalue.Inthatcase,useoneofthefollowingcommands:

Dynamicdiscovery:esxcli iscsi adapter discovery sendtarget auth chap set --inherit Staticdiscovery:esxcli iscsi adapter target portal auth chap set --inherit.

NOTEYoucansettargetlevelCHAPauthenticationpropertiestobeinheritedfromthesendtargetleveland setsendtargetlevelCHAPauthenticationpropertiestobeinheritedfromtheadapterlevel.Resetting adapterlevelpropertiesisnotsupported.

Command Syntax for esxcli iscsi and vicfg-iscsi


InvSphere5.0,youcanmanageiSCSIstoragebyusingeitheresxcli iscsicommandsorvicfg-iscsi options.SeethevSphereCommandLineInterfaceReference.esxcliiscsiCommandSyntaxonpage 61and vicfgiscsiCommandSyntaxonpage 63provideanoverview.

esxcli iscsi Command Syntax


Theesxcli iscsicommandincludesanumberofnestednamespaces.Thefollowingtableillustratesthe namespacehierarchy.Commandsateachlevelareincludedinbold.Manynamespacesincludeboth commandsandnamespaces. Table 5-2. esxcli iscsi Command Overview
adapter[get|list|set] auth discovery [rediscover] chap[set|get] sendtarget [add|list|remove] auth param[get|set] statictarget [add|list|remove] statusget target[list] portal[list] auth param[get|set] capabilitiesget firmware[get|set] param[get|set] chap[get|set] chap[get|set]

VMware, Inc.

61

vSphere Command-Line Interface Concepts and Examples

Table 5-2. esxcli iscsi Command Overview


networkportal [add|list|remove] physicalnetworkportal [list] session[add|list|remove] ibftboot[get|import] logicalnetworkportallist pluginlist software[get|set] ipconfig[get|set] param[get|set] connectionlist

Key to esxcli iscsi Short Options


ESXCLIcommandsforiSCSImanagementconsistentlyusethesameshortoptions.Forseveraloptions,the associatedfulloptiondependsonthecommand. Table 5-3. Short Options for iSCSI ESXCLI Command Options
Lower-case Option a c d f g i k l m n o p s v Option --address, alias --cid --direction --file, force --gateway --ip --key --level --method --nic --option --plugin --isid, subnet, switch --value S --state, secret M N --module --authname, --name I --inherit D --default Upper-case Option A Option --adapter Number 1 2 Option --dns1 --dns2

62

VMware, Inc.

Chapter 5 Managing iSCSI Storage

vicfg-iscsi Command Syntax


vicfg-iscsisupportsacomprehensivesetofoptions,listedinTable 54. Table 5-4. Options for vicfg-iscsi
Option Suboptions Description

-A --authentication -c <level> -m <auth_method> -b -v <ma_username> -x <ma_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name>]] <adapter_name> --level <level> --method <auth_method> --mutual --mchap_username <ma_username> --mchap_password <ma_password> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name>]] <adapter_name> -A --authentication -c <level> -m <auth_method> -u <auth_u_name> -w <a_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name>]] <adapter_name> --level <level> --method <auth_method> --chap_password <auth_u_name> --chap_username <chap_password> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name>]] <adapter_name> -A --authentication -l <adapter_name> --list <adapter_name> -D --discovery -a -i <stor_ip_addr|stor_hostname[:<portnum>] <adapter_name> --add --ip <stor_ip_addr|stor_hostname> [:<portnum>] <adapter_name> -D --discovery -l <adapter_name> --list <adapter_name> -D --discovery -r -i <stor_ip_addr|stor_hostname>[:<portnum>] <adapter_name> --remove --ip <stor_ip_addr|stor_hostname> [:<portnum>] <adapter_name> -H -l [<adapter_name>] --list [<adapter_name>] -L --lun -l <adapter_name> --list <adapter_name> ListsLUNinformation. ListsalliSCSIadaptersora specifiedadapter. Removesadynamicdiscovery address. Listsdynamicdiscovery addresses. Addsadynamicdiscovery address. Listssupportedauthentication methods. Enablesauthenticationusingthe specifiedoptions. Enablesmutualauthentication. Youmustenableauthentication beforeyoucanenablemutual authentication.

VMware, Inc.

63

vSphere Command-Line Interface Concepts and Examples

Table 5-4. Options for vicfg-iscsi (Continued)


Option -L --lun -l -t <target_ID> <adapter_name> --list --target_id <target_id> <adapter_name> -N --network (Independent hardware iSCSI only) -l <adapter_name> --list <adapter_name> -N --network (Independent hardware iSCSI only) -i <ip_addr> <adapter_name> --ip <ip_addr> <vmhba> -N --network (Independent hardware iSCSI only) -s <subnet_mask> <adapter_name> --subnetmask <subnet_mask> <adapter_name> -N --network (Independent hardware iSCSI only) -g <default_gateway> <adapter_name> --gateway <default_gateway> <adapter_name> -N --network (Independent hardware iSCSI only) -i <ip_addr> -s <subnet mask> -g <default_gateway> <adapter_name> --ip <ip_addr> --subnetmask <subnet_mask> --gateway <default_gateway> <adapter_name> -p --pnp (Independent hardware iSCSI only) -l <adapter_name> --list <adapter_name> -p --pnp (Independent hardware iSCSI only) -M <mtu_size> <adapter_name> --mtu <mtu-size> <adapter_name> -I --iscsiname -a <alias_name> <adapter_name> --alias <alias_name> <adapter_name> -I --iscsiname -n <iscsi_name> <adapter_name> --name <iscsi_name> <adapter_name> -I --iscsiname -l <adapter_name> --list <adapter_name> -M --mtu -p -M <mtu_size> <adapter_name> --pnp --mtu <mtu-size> <adapter_name> -S --static -l <adapter_name> --list <adapter_name> -S --static -r -i <stor_ip_addr|stor_hostname> [:<portnum>] -n <target_name> <adapter_name> --remove --ip <stor_ip_addr|stor_hostname> [:<portnum>] -name <target_name> <adapter_name> Removesastaticdiscovery address. Listsstaticdiscoveryaddresses. SetsMTUsize.Usedwiththe --pnpoption. ListsiSCSIinitiatoroptions. SetstheiSCSIinitiatorname. SetstheiSCSIinitiatoralias. Setsphysicalnetworkportal options. Listsphysicalnetworkportal options. SetstheIPaddress,subnetmask, anddefaultgatewayinone command. SetstheHBAgatewayto default_gateway. SetstheHBAnetworkmaskto subnet_mask. SetstheHBAIPv4addressto ip_addr. Listsnetworkproperties. ListsLUNinformationfora specifictarget. Suboptions Description

64

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Table 5-4. Options for vicfg-iscsi (Continued)


Option Suboptions Description

-S --static -a -i <stor_ip_addr|stor_hostname> [:<portnum>] -n <target_name> <adapter_name> --add --ip <stor_ip_addr|stor_hostname> [:<portnum>] -name <target_name> <adapter_name> -P --phba -l <adapter_name> --list <adapter_name> -T --target -l <adapter_name> --list <adapter_name> -W parameter -l [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name> --list [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name]] <adapter_name> -W parameter -l -k [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name> --list --detail [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name]] <adapter_name> -W parameter -W -j <name>=<value> -i <stor_ip_addr|stor_hostname> [:port_num>] [-n <iscsi_name>]] <adapter_name> --parameter --set <name>=<value> --ip <stor_ip_addr|stor_hostname> [:port_num>] [--name <iscsi_name>]] <adapter_name> -W parameter -W -o <param_name> -i <stor_ip_addr|stor_hostname> [:port_num>] [-n <iscsi_name>]] <adapter_name> -parameter --reset <param_name> -ip <stor_ip_addr|stor_hostname> [:port_num>] [-name <iscsi_name>]] <adapter_name> -z --reset_auth -a -z -m <auth_method> -b [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name>]] <adapter_name> --authentication --reset_auth --method <auth_method> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name>]] <adapter_name> Resetstargetlevelauthentication propertiestobeinheritedfrom adapterlevel.Usedwiththe --authenticationoption. Returnsparametersindiscovery targetorsendtargettodefault inheritancebehavior. SetsiSCSIparameters. ListsiSCSIparameterdetails. ListsiSCSIparameter information. Liststargetinformation. Listsexternal,vendorspecific propertiesofaniSCSIadapter. Addsastaticdiscoveryaddress.

VMware, Inc.

65

vSphere Command-Line Interface Concepts and Examples

iSCSI Storage Setup with ESXCLI


YoucansetupiSCSIstorageusingvSphereWebClient,commandsintheesxcli iscsinamespace,or vicfg-iscsicommands(seeiSCSIStorageSetupwithvicfgiscsionpage 71).

Setting Up Software iSCSI with ESXCLI


SoftwareiSCSIsetuprequiresseveraltasks.Foreachtask,seethediscussionofthecorrespondingcommand inthischapterorthereferenceinformationavailablefromesxcli iscsi --helpandtheVMware DocumentationCenter.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options> 1 EnablesoftwareiSCSI.
esxcli <conn_options> iscsi software set --enabled=true

Checkwhetheranetworkportal,thatis,aboundport,existsforiSCSItraffic.
esxcli <conn_options> iscsi adapter list

Ifnoadapterexists,addone.SoftwareiSCSIdoesnotrequireportbinding,butrequiresthatatleastone VMkernelNICisavailableandcanbeusedasaniSCSINIC.Youcannametheadapterasyouaddit.
esxcli <conn_options> iscsi networkportal add -n <portal_name> -A <vmhba>

(Optional)Checkthestatus.
esxcli <conn_options> iscsi software get

ThesystemprintstrueifsoftwareiSCSIisenabled,orfalseifitisnotenabled. 5 (Optional)SettheiSCSInameandalias.
esxcli <conn_options> iscsi adapter set --adapter=<iscsi adapter> --name=<name> esxcli <conn_options> iscsi adapter set --adapter=<iscsi adapter> --alias=<alias>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithahostnameorIPaddressarediscovered. Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

Withstaticdiscovery,youmustspecifythehostnameorIPaddressandtheiSCSInameofthestorage target.Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]> --adapter=<adapter_name> --name=<target_name>

Whenyoulaterremoveadiscoveryaddress,itmightstillbedisplayedastheparentofastatictarget.You canaddthediscoveryaddressandrescantodisplaythecorrectparentforthestatictargets. 7 (Optional)SettheauthenticationinformationforCHAP(seeSettingiSCSICHAPonpage 60and EnablingiSCSIAuthenticationonpage 80).YoucansetpertargetCHAPforstatictargets,peradapter CHAP,orapplythecommandtothediscoveryaddress.

66

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Adapterlevel CHAP

esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address> esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Discoverylevel CHAP

Targetlevel CHAP

Table 51,SupportedLevelsforCHAP,onpage 60listswhateachsupportedleveldoes. Forexample:


esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

(Optional)SettheauthenticationinformationformutualCHAPbyrunningesxcli iscsi adapter auth chap set againwith--directionsettomutualandadifferentauthenticationusernameand secret. Adapterlevel CHAP
esxcli iscsi adapter auth chap set --direction=mutual --mchap_username=<name2> --mchap_password=<pwd2> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> esxcli iscsi adapter discovery sendtarget auth chap set --direction=mutual --mchap_username=<name2> --mchap_password=<pwd2> --level=[prohibited, required] --secret=<string2> --adapter=<vmhba> --address=<sendtarget_address> eesxcli iscsi adapter target portal auth chap set --direction=mutual --mchap_username=<nam2e> --mchap_password=<pwd2> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> --name=<iscsi_iqn_name>

Discoverylevel CHAP

Targetlevel CHAP

IMPORTANTYouareresponsibleformakingsurethatCHAPissetbeforeyousetmutualCHAP,andfor usingcompatiblelevelsforCHAPandmutualCHAP. 9 (Optional)SetiSCSIparameters. Adapterlevel parameters Discoverylevel parameters Targetlevel parameters


esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value> esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address> esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

SeeListingandSettingiSCSIParametersonpage 76 10 Aftersetupiscomplete,performrediscoveryandrescanallstoragedevices.Forexample:
esxcli <conn_options> iscsi adapter discovery rediscover esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

VMware, Inc.

67

vSphere Command-Line Interface Concepts and Examples

11

(Optional)IfyouwanttomakeadditionaliSCSIloginparameterchanges(seeListingandSettingiSCSI Parametersonpage 76),youmustlogoutofthecorrespondingiSCSIsessionandlogbackin. a b Runesxcli iscsi session removetologout. Runesxcli iscsi session addorrescantheadaptertoaddthesessionback.

Setting Up Dependent Hardware iSCSI with ESXCLI


DependenthardwareiSCSIsetuprequiresseveralhighleveltasks.Foreachtask,seethediscussionofthe correspondingcommandinthischapterorthereferenceinformationavailablefromesxcli iscsi --help andtheVMwareDocumentationCenter.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17 inplaceof<conn_options>. 1 DeterminetheiSCSIadaptertypeandretrievetheiSCSIadapterID.
esxcli <conn_options> iscsi adapter list

(Optional)SettheiSCSInameandalias.
esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --name=<name> esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --alias=<alias>

Setupportbindingbyfollowingthesesteps: a IdentifytheVMkernelportofthedependenthardwareiSCSIadapter.
esxcli <conn_options> iscsi logicalnetworkportal list --adapter=<adapter_name>

ConnectthedependenthardwareiSCSIinitiatortotheiSCSIVMkernelportsbyrunningthe followingcommandforeachport.
esxcli <conn_options> iscsi networkportal add --nic=<bound_vmknic> --adapter=<iscsi_adapter>

VerifythattheportswereaddedtothedependenthardwareiSCSIinitiator.
esxcli <conn_options> iscsi physicalnetworkportal list --adapter=<adapter_name>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithahostnameorIPaddressarediscovered. Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

Withstaticdiscovery,youmustspecifythehostnameorIPaddressandtheiSCSInameofthestorage target.Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]> --adapter=<adapter_name> --name=<target_name>

Whenyoulaterremoveadiscoveryaddress,itmightstillbedisplayedastheparentofastatictarget.You canaddthediscoveryaddressandrescantodisplaythecorrectparentforthestatictargets. 5 (Optional)SettheauthenticationinformationforCHAP(seeSettingiSCSICHAPonpage 60and EnablingiSCSIAuthenticationonpage 80).YoucansetpertargetCHAPforstatictargets,peradapter CHAP,orapplythecommandtothediscoveryaddress.

68

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Adapterlevel CHAP

esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address> esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Discoverylevel CHAP

Targetlevel CHAP

Table 51,SupportedLevelsforCHAP,onpage 60listswhateachsupportedleveldoes. Forexample:


esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

(Optional)SettheauthenticationinformationformutualCHAPbyrunningesxcli iscsi adapter auth chap set againwith--directionsettomutualandadifferentauthenticationusernameand secret. Adapterlevel CHAP
esxcli iscsi adapter auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> esxcli iscsi adapter discovery sendtarget auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited, required] --secret=<string2> --adapter=<vmhba> --address=<sendtarget_address> esxcli iscsi adapter target portal auth chap set --direction=mutual --mchap_username=<name> --mchap_password=<pwd> --level=[prohibited required] --secret=<string2> --adapter=<vmhba> --name=<iscsi_iqn_name>

Discoverylevel CHAP

Targetlevel CHAP

IMPORTANTYouareresponsibleformakingsurethatCHAPissetbeforeyousetmutualCHAP,andfor usingcompatiblelevelsforCHAPandmutualCHAP. 7 (Optional)SetiSCSIparameters. Adapterlevel parameters Discoverylevel parameters Targetlevel parameters


esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value> esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address> esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

SeeListingandSettingiSCSIParametersonpage 76 8 Aftersetupiscomplete,performrediscoveryandrescanallstoragedevices.Forexample:
esxcli <conn_options> iscsi adapter discovery rediscover esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

VMware, Inc.

69

vSphere Command-Line Interface Concepts and Examples

(Optional)IfyouwanttomakeadditionaliSCSIloginparameterchanges(seeListingandSettingiSCSI Parametersonpage 76),youmustlogoutofthecorrespondingiSCSIsessionandlogbackin. a b Runesxcli iscsi session removetologout. Runesxcli iscsi session addorrescantheadaptertoaddthesessionback.

Setting Up Independent Hardware iSCSI with ESXCLI


WithindependenthardwarebasediSCSIstorage,youuseaspecializedthirdpartyadaptercapableof accessingiSCSIstorageoverTCP/IP.ThisiSCSIinitiatorhandlesalliSCSIandnetworkprocessingand managementforyourESXisystem. YoumustinstallandconfiguretheindependenthardwareiSCSIadapterforyourhostbeforeyoucanaccess theiSCSIstoragedevice.Forinstallationinformation,seevendordocumentation. HardwareiSCSIsetuprequiresanumberofhighleveltasks.Foreachtask,seethediscussionofthe correspondingcommandlineoptioninthischapterorthereferenceinformation.Specifyoneoftheoptions listedinConnectionOptionsonpage 17inplaceof<conn_options>. 1 DeterminetheiSCSIadaptertypeandretrievetheiSCSIadapterID.
esxcli <conn_options> iscsi adapter list

Configurethehardwareinitiator(HBA)byrunningesxcli iscsi networkportal ipconfig withone ormoreofthefollowingoptions.


-A|--adapter=<str> -1|--dns1=<str> -2|--dns2=<str> -g|--gateway=<str> -i|--ip=<str> -n|--nic=<str> -s|--subnet=<str> iSCSIadaptername.(required). iSCSInetworkportalprimaryDNSaddress. iSCSInetworkportalsecondaryDNSaddress. iSCSInetworkportalgatewayaddress. iSCSInetworkportalIPaddress(required). iSCSInetworkportal(vmknic). iSCSInetworkportalsubnetmask(required).

(Optional)SettheiSCSInameandalias.
esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --name=<name> esxcli <conn_options> iscsi adapter set --adapter <adapter_name> --alias=<alias>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithahostnameorIPaddressarediscovered. Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery sendtarget add --address=<ip/dns[:port]> --adapter=<adapter_name>

Withstaticdiscovery,youmustspecifythehostnameorIPaddressandtheiSCSInameofthestorage target.Yourunthefollowingcommand.
esxcli <conn_options> iscsi adapter discovery statictarget add --address=<ip/dns[:port]>

(Optional)SettheauthenticationinformationforCHAP(seeSettingiSCSICHAPonpage 60and EnablingiSCSIAuthenticationonpage 80).YoucansetpertargetCHAPforstatictargets,peradapter CHAP,orapplythecommandtothediscoveryaddress.

70

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Adapterlevel CHAP

esxcli iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> esxcli iscsi adapter discovery sendtarget auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --address<sendtarget_address> esxcli iscsi adapter target portal auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<vmhba> --name<iscsi_iqn_name>

Discoverylevel CHAP

Targetlevel CHAP

Table 51,SupportedLevelsforCHAP,onpage 60listswhateachsupportedleveldoes. Forexample:


esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=preferred --secret=uni_secret --adapter=vmhba33

MutualCHAPisnotsupportedforindependenthardwareiSCSIstorage. 6 (Optional)SetiSCSIparameters. Adapterlevel parameters Discoverylevel parameters Targetlevel parameters


esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value> esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<sendtarget_address> esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name>

SeeListingandSettingiSCSIParametersonpage 76 7 8 Aftersetupiscomplete,runesxcli storage core adapter rescan --adapter=<iscsi_adapter> torescanallstoragedevices. Aftersetupiscomplete,performrediscoveryandrescanallstoragedevices.Forexample:


esxcli <conn_options> iscsi adapter discovery rediscover esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

iSCSI Storage Setup with vicfg-iscsi


YoucansetupiSCSIstorageusingthevSphereWebClient,commandsintheesxcli iscsinamespace(see iSCSIStorageSetupwithESXCLIonpage 66)orthevicfg-iscsicommand.

Setting Up Software iSCSI with vicfg-iscsi


SoftwareiSCSIsetuprequiresanumberofhighleveltasks.Foreachtask,seethediscussionofthe correspondingcommandlineoptioninthischapterorthereferenceinformation.Specifyoneoftheoptions listedinConnectionOptionsonpage 17inplaceof<conn_options>. 1 DeterminetheHBAtypeandretrievetheHBAID.
vicfg-iscsi <conn_options> --adapter --list

EnablesoftwareiSCSIfortheHBA.
vicfg-iscsi <conn_options> --swiscsi --enable

VMware, Inc.

71

vSphere Command-Line Interface Concepts and Examples

(Optional)Checkthestatus.
vicfg-iscsi <conn_options> --swiscsi --list

ThesystemprintsSoftware iSCSI is enabledorSoftware iSCSI is not enabled. 4 (Optional)SettheiSCSInameandalias.


vicfg-iscsi vicfg-iscsi vicfg-iscsi vicfg-iscsi <conn_options> <conn_options> <conn_options> <conn_options> -I -n <iscsi_name> <adapter_name> --iscsiname --name <iscsi_name> <adapter_name> -I -a <alias_name> <adapter_name> --iscsiname --alias <alias_name> <adapter_name>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithahostnameorIPaddressarediscovered. Yourunthefollowingcommand:
vicfg-iscsi <conn_options> --discovery --add --ip <ip_addr | domain_name> <adapter_name>

Withstaticdiscovery,youmustspecifythehostnameorIPaddressandtheiSCSInameofthestorage target.Yourunthefollowingcommand:
vicfg-iscsi <conn_options> --static --add --ip <ip_addr | domain_name> --name <iscsi_name> <adapter_name>

Whenyoulaterremoveadiscoveryaddress,itmightstillbedisplayedastheparentofastatictarget.You canaddthediscoveryaddressandrescantodisplaythecorrectparentforthestatictargets. 6 (Optional)SettheauthenticationinformationforCHAP(seeSettingiSCSICHAPonpage 60and EnablingiSCSIAuthenticationonpage 80).


vicfg-iscsi <conn_options> -A -c <level> -m <auth_method> -u <auth_u_name> -w <chap_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name> vicfg-iscsi <conn_options> --authentication --level <level> --method <auth_method> --chap_username <auth_u_name> --chap_password <chap_password> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [-name <iscsi_name]] <adapter_name>

Thetarget(-i)andname(-n)optiondeterminewhatthecommandappliesto.
Option -iandn Onlyi Neither-inorn Result CommandappliestopertargetCHAPforstatictargets. Commandappliestothediscoveryaddress. CommandappliestoperadapterCHAP.

(Optional)SettheauthenticationinformationformutualCHAPbyrunningvicfg-iscsi -Aagainwith the-boptionandadifferentauthenticationusernameandpassword. For<level>,specifychapProhibitedorchapRequired.

chapProhibitedThehostdoesnotuseCHAPauthentication.Ifauthenticationisenabled,specify chapProhibitedtodisableit. chapRequiredThehostrequiressuccessfulCHAPauthentication.TheconnectionfailsifCHAP negotiationfails.YoucansetthisvalueformutualCHAPonlyifCHAPissettochapRequired.

For<auth_method>,CHAPistheonlyvalidvalue. IMPORTANTYouareresponsibleformakingsurethatCHAPissetbeforeyousetmutualCHAP,andfor usingcompatiblelevelsforCHAPandmutualCHAP. 8 9 (Optional)SetiSCSIparametersbyrunningvicfg-iscsi -W. Aftersetupiscomplete,runvicfg-rescantorescanallstoragedevices.

72

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Setting Up Dependent Hardware iSCSI with vicfg-iscsi


DependenthardwareiSCSIsetuprequiresanumberofhighleveltasks.Foreachtask,seethediscussionof thecorrespondingcommandlineoptioninthischapter,orthereferenceinformation.Specifyoneofthe optionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. 1 DeterminetheHBAtypeandretrievetheHBAID.
vicf-iscsi <conn_options> --adapter --list

(Optional)SettheiSCSInameandalias.
vicfg-iscsi vicfg-iscsi vicfg-iscsi vicfg-iscsi <conn_options> <conn_options> <conn_options> <conn_options> -I -n <iscsi_name> <adapter_name> --iscsiname --name <iscsi_name> <adapter_name> -I -a <alias_name> <adapter_name> --iscsiname --alias <alias_name> <adapter_name>

Setupportbindingbyfollowingthesesteps: a IdentifytheVMkernelportofthedependenthardwareiSCSIadapter.
esxcli <conn_options> swiscsi vmknic list -d <vmhba>

ConnectthedependenthardwareiSCSIinitiatortotheiSCSIVMkernelportsbyrunningthe followingcommandforeachport.
esxcli <conn_options> swiscsi nic add -n <port_name> -d <vmhba>

VerifythattheportswereaddedtothedependenthardwareiSCSIinitiator.
esxcli <conn_options> swiscsi nic list -d <vmhba>

RescanthedependenthardwareSCSIinitiator.
vicfg-rescan <conn_options> <vmhba>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithahostnameorIPaddressarediscovered. Yourunthefollowingcommand:
vicfg-iscsi <conn_options> --discovery --add --ip <ip_addr | domain_name> <adapter_name>

Withstaticdiscovery,youmustspecifythehostnameorIPaddressandtheiSCSInameofthestorage target.Yourunthefollowingcommand:
vicfg-iscsi <conn_options> --static --add --ip <ip_addr | domain_name> --name <iscsi_name> <adapter_name>

Whenyoulaterremoveadiscoveryaddress,itmightstillbedisplayedastheparentofastatictarget.You canaddthediscoveryaddressandrescantodisplaythecorrectparentforthestatictargets. 5 (Optional)SettheauthenticationinformationforCHAP(seeSettingiSCSICHAPonpage 60and EnablingiSCSIAuthenticationonpage 80).


vicfg-iscsi <conn_options> -A -c <level> -m <auth_method> -u <auth_u_name> -w <chap_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name> vicfg-iscsi <conn_options> --authentication --level <level> --method <auth_method> --chap_username <auth_u_name> --chap_password <chap_password> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [-name <iscsi_name]] <adapter_name>

Thetarget(-i)andname(-n)optiondeterminewhatthecommandappliesto.
Option -iandn Onlyi Neither-inorn Result CommandappliestopertargetCHAPforstatictargets. Commandappliestothediscoveryaddress. CommandappliestoperadapterCHAP.

VMware, Inc.

73

vSphere Command-Line Interface Concepts and Examples

(Optional)SettheauthenticationinformationformutualCHAPbyrunningvicfg-iscsi -Aagainwith the-boptionandadifferentauthenticationusernameandpassword. For<level>,specifychapProhibitedorchapRequired.

chapProhibitedThehostdoesnotuseCHAPauthentication.Ifauthenticationisenabled,specify chapProhibitedtodisableit. chapRequiredThehostrequiressuccessfulCHAPauthentication.TheconnectionfailsifCHAP negotiationfails.YoucansetthisvalueformutualCHAPonlyifCHAPissettochapRequired.

For<auth_method>,CHAPistheonlyvalidvalue. IMPORTANTYouareresponsibleformakingsurethatCHAPissetbeforeyousetmutualCHAP,andfor usingcompatiblelevelsforCHAPandmutualCHAP. 7 8 (Optional)SetiSCSIparametersbyrunningvicfg-iscsi -W. Aftersetupiscomplete,runvicfg-rescantorescanallstoragedevices.

Setting Up Independent Hardware iSCSI with vicfg-iscsi


WithindependenthardwarebasediSCSIstorage,youuseaspecializedthirdpartyadaptercapableof accessingiSCSIstorageoverTCP/IP.ThisiSCSIinitiatorhandlesalliSCSIandnetworkprocessingand managementforyourESXisystem. YoumustinstallandconfiguretheindependenthardwareiSCSIadapterforyourhostbeforeyoucanaccess theiSCSIstoragedevice.Forinstallationinformation,seevendordocumentation. HardwareiSCSIsetuprequiresanumberofhighleveltasks.Foreachtask,seethediscussionofthe correspondingcommandlineoptioninthischapter,themanpage(Linux),orthereferenceinformation. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. 1 DeterminetheHBAtypeandretrievetheHBAID.
vicf-iscsi <conn_options> --adapter --list

Configurethehardwareinitiator(HBA)byrunningvicfg-iscsi -Nwithoneormoreofthefollowing options.


--listListnetworkproperties. --ip <ip_addr>SetHBAIPv4address. --subnetmask <subnet_mask>SetHBAnetworkmask. --gateway <default_gateway>SetHBAgateway. --set ARP=true|falseEnableordisableARPredirect.

YoucanalsosettheHBAIPv4addressandnetworkmaskandgatewayinonecommand.
vicfg-iscsi <conn_options> --ip <ip_addr> --subnetmask <subnet_mask> --gateway <default_gateway>

(Optional)SettheiSCSInameandalias.
vicfg-iscsi vicfg-iscsi vicfg-iscsi vicfg-iscsi <conn_options> <conn_options> <conn_options> <conn_options> -I -n <iscsi_name> <adapter_name> --iscsiname --name <iscsi_name> <adapter_name> -I -a <alias_name> <adapter_name> --iscsiname --alias <alias_name> <adapter_name>

Addadynamicdiscoveryaddressorastaticdiscoveryaddress. Thetwotypesoftargetdifferasfollows:

Withdynamicdiscovery,allstoragetargetsassociatedwithanIPaddressarediscovered.Runthe followingcommand:
vicfg-iscsi <conn_options> --discovery --add --ip <ip_addr> <adapter_name>

74

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Withstaticdiscovery,youmustspecifytheIPaddressandtheiSCSInameofthestoragetargettobe added.Runthefollowingcommand:
vicfg-iscsi <conn_options> --static --add --ip <ip_addr> --name <iscsi_name> <adapter_name>

Whenyoulaterremoveadiscoveryaddress,itmightstillbedisplayedastheparentofastatictarget.You canlateraddthediscoveryaddressandrescantodisplaythecorrectparentforthestatictargets. 5 (Optional)SettheauthenticationinformationforCHAPbyrunningvicfg-iscsi -A. Youcansettheinformationforperadapter,perdiscovery,andpertargetCHAP.SeeSettingiSCSI CHAPonpage 60andEnablingiSCSIAuthenticationonpage 80.


vicfg-iscsi <conn_options> --authentication --level <level> --method <auth_method> --chap_username <auth_u_name> --chap_password <chap_password> [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [-name <iscsi_name]] <adapter_name>

Thetarget(-i)andname(-n)optiondeterminewhatthecommandappliesto.
Option -iandn Onlyi Neither-inorn Result CommandappliestopertargetCHAPforstatictargets. Commandappliestothediscoveryaddress. CommandappliestoperadapterCHAP.

MutualCHAPisnotsupportedforindependenthardwareiSCSIstorage. 6 7 (Optional)SetadditionaliSCSIparametersbyrunningvicfg-iscsi -W. Aftersetupiscomplete,callvicfg-rescantorescanallstoragedevices.

Listing and Setting iSCSI Options


YoucanlistandsetiSCSIoptionswithESXCLIorwithvicfg-iscsi.Youcanalsomanageparameters.See ListingandSettingiSCSIParametersonpage 76.

Listing iSCSI Options with ESXCLI


Useesxcli iscsi informationretrievalcommandstolistexternalHBAproperties,informationabout targets,andLUNs.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>.

Runesxcli iscsi adapter firmwaretolistoruploadthefirmwarefortheiSCSIadapter.


esxcli <conn_options> iscsi adapter firmware get --adapter=<adapter_name> esxcli <conn_options> iscsi adapter firmware set --file=<firmware_file_path>

Thesystemreturnsinformationaboutthevendor,model,description,andserialnumberoftheHBA.

Runcommandsintheesxcli iscsi adapter targetnamespace.


esxcli iscsi adapter target portallistsandsetsauthenticationandportalparameters. esxcli iscsi adapter target listlistsLUNinformation.

Setting MTU with ESXCLI


IfyouwanttochangetheMTUusedforyouriSCSIstorage,youmustmakethechangeintwoplaces.

Runesxcli network vswitch standard settochangetheMTUofthevirtualswitch. Runesxcli network ip interface settochangetheMTUofthenetworkinterface.

VMware, Inc.

75

vSphere Command-Line Interface Concepts and Examples

Listing and Setting iSCSI Options with vicfg-iscsi


Usevicfg-iscsiinformationretrievaloptionstolistexternalHBAproperties,informationabouttargets,and LUNs.Youcanusethefollowingvicfg-iscsioptionstolistiSCSIparameters.Specifyoneoftheoptions listedinConnectionOptionsonpage 17inplaceof<conn_options>.

Runvicfg-iscsi -P|--phbatolistexternal(vendorspecific)propertiesofaniSCSIadapter.
vicfg-iscsi <conn_options> -P -l <adapter_name> vicfg-iscsi <conn_options> --phba --list <adapter_name>

Thesystemreturnsinformationaboutthevendor,model,description,andserialnumberoftheHBA.

Runvicfg-iscsi -T| --targettolisttargetinformation.


vicfg-iscsi <conn_options> -T -l <adapter_name> vicfg-iscsi <conn_options> --target --list <adapter_name>

Thesystemreturnsinformationabouttargetsforthespecifiedadapter,includingtheiSCSIname(IQNor EUIformat)andalias.SeeDiscoveryTargetNamesonpage 59.

Runvicfg-iscsi -L|--luntolistLUNinformation.
vicfg-iscsi <conn_options> -L -l <adapter_name> vicfg-iscsi <conn_options> --lun --list <adapter_name>

Thecommandreturnstheoperatingsystemdevicename,busnumber,targetID,LUNID,andLUNsize fortheLUN.

Runvicfg-iscsi -Lwith-ttolistonlyLUNsonaspecifiedtarget.
vicfg-iscsi <conn_options> -L -l -t <target_ID> <adapter_name> vicfg-iscsi <conn_options> --lun --list --target_id <target_id> <adapter_name>

ThesystemreturnstheLUNsonthespecifiedtargetandthecorrespondingdevicename,devicenumber, LUNID,andLUNsize.

Runvicfg-iscsi -p|--pnptolistphysicalnetworkportalinformationforindependenthardwareiSCSI devices.Youalsousethisoptionwith--mtu.


vicfg-iscsi <conn_options> -p -l <adapter_name> vicfg-iscsi <conn_options> --pnp --list <adapter_name>

ThesystemreturnsinformationabouttheMACaddress,MTU,andcurrenttransferrate.

Runvicfg-iscsi -I -ltolistinformationabouttheiSCSIinitiator.ESXisystemsuseasoftwarebased iSCSIinitiatorintheVMkerneltoconnecttostorage.ThecommandreturnstheiSCSIname,aliasname, andaliassettablebitfortheinitiator.


vicfg-iscsi <conn_options> -I -l vmhba42

Runvicfg-iscsi -p -MtosettheMTUfortheadapter.Youspecifythesizeandadaptername.
vicfg-iscsi <conn_options> -p -M <mtu_size> <adapter_name> vicfg-iscsi <conn_options> --pnp --mtu <mtu-size> <adapter_name>

Listing and Setting iSCSI Parameters


YoucanlistandsetiSCSIparametersforsoftwareiSCSIandfordependenthardwareiSCSIwithESXCLIor withvicfg-iscsi.

76

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Listing and Setting iSCSI Parameters with ESXCLI


YoucanretrieveandsetiSCSIparametersbyrunningoneofthefollowingcommands.
Adapterlevel parameters Targetlevel parameters Discoverylevel parameters esxcli iscsi adapter param set --adapter=<vmhba> --key=<key> --value=<value>

esxcli iscsi adapter target portal param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address> --name=<iqn.name> esxcli iscsi adapter discovery sendtarget param set --adapter=<vmhba> --key=<key> --value=<value> --address=<address>

Table 56listsallsettableparameters.TheseparametersarealsodescribedintheIETFrfc3720.Youcanrun esxcli iscsi adapter param gettodeterminewhetheraparameterissettableornot. TheparametersinTable 56applytosoftwareiSCSIanddependenthardwareiSCSI. Table 5-5. Settable iSCSI Parameters
Parameter DataDigestType Description Increasesdataintegrity.Whendatadigestisenabled,thesystemperformsachecksumover eachPDUsdatapartandverifiesusingtheCRC32Calgorithm. Note:SystemsthatuseIntelNehalemprocessorsoffloadtheiSCSIdigestcalculationsfor softwareiSCSI,thusreducingtheimpactonperformance. ValidvaluesaredigestProhibited,digestDiscouraged,digestPreferred,or digestRequired. HeaderDigest Increasesdataintegrity.Whenheaderdigestisenabled,thesystemperformsachecksumover theheaderpartofeachiSCSIProtocolDataUnit(PDU)andverifiesusingtheCRC32C algorithm. MaxOutstandingR2TdefinestheReadytoTransfer(R2T)PDUsthatcanbeintransitionbefore anacknowledgementPDUisreceived. MaximumamountofunsoliciteddataaniSCSIinitiatorcansendtothetargetduringthe executionofasingleSCSIcommand,inbytes. MaximumSCSIdatapayloadinaDataInorasolicitedDataOutiSCSIsequence,inbytes. Maximumdatasegmentlength,inbytes,thatcanbereceivedinaniSCSIPDU. Timeinterval,inseconds,betweenNOPOutrequestssentfromyouriSCSIinitiatortoaniSCSI target.TheNOPOutrequestsserveasthepingmechanismtoverifythataconnectionbetween theiSCSIinitiatorandtheiSCSItargetisactive. Supportedonlyattheinitiatorlevel. NoopTimeout Amountoftime,inseconds,thatcanlapsebeforeyourhostreceivesaNOPInmessage.The messageissentbytheiSCSItargetinresponsetotheNOPOutrequest.Whenthe NoopTimeoutlimitisexceeded,theinitiatorterminatesthecurrentsessionandstartsanew one. Supportedonlyattheinitiatorlevel. RecoveryTimeout DelayedAck Amountoftime,inseconds,thatcanlapsewhileasessionrecoveryisperformed.Ifthetimeout exceedsitslimit,theiSCSIinitiatorterminatesthesession. Allowssystemstodelayacknowledgmentofreceiveddatapackets.

MaxOutstandingR2T FirstBurstLength MaxBurstLength MaxRecvDataSegLen NoopInterval

YoucanusethefollowingESXCLIcommandstolistparameteroptions.

Runesxcli iscsi adapter param gettolistparameteroptionsfortheiSCSIadapter. Runesxcli iscsi adapter discovery sendtarget param getoresxcli iscsi adapter target portal param settoretrieveinformationaboutiSCSIparametersandwhethertheyaresettable. Runesxcli iscsi adapter discovery sendtarget param getoresxcli iscsi adapter target portal param settosetiSCSIparameteroptions.

Ifspecialcharactersareinthe<name>=<value>sequence,forexample,ifyouaddaspace,youmustsurround thesequencewithdoublequotes(<name> = <value>).


VMware, Inc. 77

vSphere Command-Line Interface Concepts and Examples

Returning Parameters to Default Inheritance


ThevaluesofiSCSIparametersassociatedwithadynamicdiscoveryaddressorastaticdiscoverytargetare inheritedfromthecorrespondingsettingsoftheparent.Forthedynamicdiscoveryaddress,theparentisthe adapter.Forthestatictarget,theparentistheadapterordiscoveryaddress.

IfyouusethevSphereWebClienttomodifyauthenticationsettings,youdeselecttheInheritfromParent checkboxbeforeyoucanmakeachangetothediscoveryaddressordiscoverytarget. Ifyouuseesxcli iscsi,thevalueyousetoverridestheinheritedvalue.

Inheritanceisrelevantonlyifyouwanttoreturnadynamicdiscoveryaddressorastaticdiscoverytargetto itsinheritedvalue.Inthatcase,usethefollowingcommand,whichrequiresthe--nameoptionforstatic discoveryaddresses,butnotfordynamicdiscoverytargets.


Dynamictarget:esxcli iscsi adapter discovery sendtarget param set Statictarget:esxcli iscsi adapter target portal param set

Listing and Setting iSCSI Parameters with vicfg-iscsi


YoucanlistandsetiSCSIparametersbyrunningvicfg-iscsi -W.Table 56listsallsettableparameters. TheseparametersarealsodescribedintheIETFrfc3720.Youcanalsorunvicfg-iscsi --parameter --list --detailstodeterminewhetheraparameterissettableornot. TheparametersinTable 56applytosoftwareiSCSIanddependenthardwareiSCSI. Table 5-6. Settable iSCSI Parameters
Parameter DataDigestType Description Increasesdataintegrity.Whendatadigestisenabled,thesystemperformsachecksumover eachPDUsdatapartandverifiesusingtheCRC32Calgorithm. Note:SystemsthatuseIntelNehalemprocessorsoffloadtheiSCSIdigestcalculationsfor softwareiSCSI,thusreducingtheimpactonperformance. ValidvaluesaredigestProhibited,digestDiscouraged,digestPreferred,or digestRequired. HeaderDigest Increasesdataintegrity.Whenheaderdigestisenabled,thesystemperformsachecksumover theheaderpartofeachiSCSIProtocolDataUnit(PDU)andverifiesusingtheCRC32C algorithm. MaxOutstandingR2TdefinestheReadytoTransfer(R2T)PDUsthatcanbeintransitionbefore anacknowledgementPDUisreceived. MaximumamountofunsoliciteddataaniSCSIinitiatorcansendtothetargetduringthe executionofasingleSCSIcommand,inbytes. MaximumSCSIdatapayloadinaDataInorasolicitedDataOutiSCSIsequence,inbytes. Maximumdatasegmentlength,inbytes,thatcanbereceivedinaniSCSIPDU. Timeinterval,inseconds,betweenNOPOutrequestssentfromyouriSCSIinitiatortoaniSCSI target.TheNOPOutrequestsserveasthepingmechanismtoverifythataconnectionbetween theiSCSIinitiatorandtheiSCSItargetisactive. Supportedonlyattheinitiatorlevel. NoopTimeout Amountoftime,inseconds,thatcanlapsebeforeyourhostreceivesaNOPInmessage.The messageissentbytheiSCSItargetinresponsetotheNOPOutrequest.Whenthe NoopTimeoutlimitisexceeded,theinitiatorterminatesthecurrentsessionandstartsanew one. Supportedonlyattheinitiatorlevel. RecoveryTimeout DelayedAck Amountoftime,inseconds,thatcanlapsewhileasessionrecoveryisperformed.Ifthetimeout exceedsitslimit,theiSCSIinitiatorterminatesthesession. Allowssystemstodelayacknowledgmentofreceiveddatapackets.

MaxOutstandingR2T FirstBurstLength MaxBurstLength MaxRecvDataSegLen NoopInterval

78

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Youcanusethefollowingvicfg-iscsioptionstolistparameteroptions.Specifyoneoftheoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>.

Runvicfg-iscsi -W -ltolistparameteroptionsfortheHBA.
vicfg-iscsi <conn_options> -W -l [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name>]] <adapter_name> vicfg-iscsi <conn_options> --parameter --list [--ip <stor_ip_addr|stor_hostname> [:<portnum>] [--name <iscsi_name>]] <adapter_name>

Thetarget(-i)andname(-n)optiondeterminewhatthecommandappliesto.
Option -iandn Onlyi Neither-inorn Result Commandappliestostatictargets. Commandappliestothediscoveryaddress. Commandappliestoperadapterparameters.

Runvicfg-iscsi -W -l -k tolistiSCSIparametersandwhethertheyaresettable.
vicfg-iscsi <conn_options> -W -l -k [-i <stor_ip_addr|stor_hostname>[:<port_num>] [-n <iscsi_name>]] <adapter_name>

vicfg-iscsi <conn_options> --parameter --list --detail [--ip <stor_ip_addr|stor_hostname>[:<port_num>][--name <iscsi_name>]] <adapter_name>

Runvicfg-iscsi -W -jtosetiSCSIparameteroptions.
vicfg-iscsi <conn_options> -W -j <name>=<value> -i <stor_ip_addr|stor_hostname>[:port_num>][-n <iscsi_name>]] <adapter_name> vicfg-iscsi <conn_options> --parameter --set <name>=<value> --ip <stor_ip_addr|stor_hostname>[:port_num>][--name <iscsi_name>]] <adapter_name>

Thetarget(-i)andname(-n)optiondeterminewhatthecommandappliesto.
Option -iandn Onlyi Neither-inorn Result CommandappliestopertargetCHAPforstatictargets. Commandappliestothediscoveryaddress. CommandappliestoperadapterCHAP.

Ifspecialcharactersareinthe<name>=<value>sequence,forexample,ifyouaddaspace,youmustsurround thesequencewithdoublequotes(<name> = <value>).

Returning Parameters to Default Inheritance


ThevaluesofiSCSIparametersassociatedwithadynamicdiscoveryaddressorastaticdiscoverytargetare inheritedfromthecorrespondingsettingsoftheparent.Forthedynamicdiscoveryaddress,theparentisthe adapter.Forthestatictarget,theparentistheadapterordiscoveryaddress.

IfyouusethevSphereWebClienttomodifyauthenticationsettings,youdeselecttheInheritfromParent checkboxbeforeyoucanmakeachangetothediscoveryaddressordiscoverytarget. Ifyouusevicfg-iscsi,thevalueyousetoverridestheinheritedvalue.

Inheritanceisrelevantonlyifyouwanttoreturnadynamicdiscoveryaddressorastaticdiscoverytargetto itsinheritedvalue.Inthatcase,usethe--reset <param_name>option,whichrequiresthe--nameoptionfor staticdiscoveryaddresses,butnotfordynamicdiscoverytargets.


vicfg-iscsi <conn_options> --parameter --reset <param_name> --ip <stor_ip_addr | stor_hostname>[:port_num>] <adapter_name> vicfg-iscsi <conn_options> -W -o <param_name> -i <stor_ip_addr|stor_hostname>[:port_num>] <adapter_name>

VMware, Inc.

79

vSphere Command-Line Interface Concepts and Examples

Enabling iSCSI Authentication


YoucanenableiSCSIauthenticationwithESXCLIorwithvicfg-iscsi.

Enabling iSCSI Authentication with ESXCLI


Theesxcli iscsi adapter authcommandsenableiSCSIauthentication.Mutualauthenticationis supportedforsoftwareiSCSIanddependenthardwareiSCSI,butnotforindependenthardwareiSCSI(see SettingiSCSICHAPonpage 60). 1 (Optional)SettheauthenticationinformationforCHAP.
esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pwd> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<adapter_name>

YoucansetpertargetCHAPforstatictargets,peradapterCHAP,orapplythecommandtothediscovery address.

peradapterCHAP:esxcli iscsi adapter auth chap set perdiscoveryCHAP:esxcli iscsi adapter discovery sendtarget auth chap set pertargetCHAP:esxcli iscsi adapter target portal auth chap set

Forexample:
esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=User1 --chap_password=MySpecialPwd --level=preferred --secret=uni_secret --adapter=vmhba33

(Optional)SettheauthenticationinformationformutualCHAPbyrunningesxcli iscsi adapter auth chap set againwiththe-doptionsettomutualoptionandadifferentauthenticationusername andsecret.


esxcli <conn_options> iscsi adapter auth chap set --direction=mutual --mchap_username=<m_name> --mchap_password=<m_pwd> --level=[prohibited, required] --secret=<string> --adapter=<adapter_name>

For<level>,specifyprohibitedorrequired.

prohibitedThehostdoesnotuseCHAPauthentication.Ifauthenticationisenabled,specify chapProhibitedtodisableit. requiredThehostrequiressuccessfulCHAPauthentication.TheconnectionfailsifCHAP negotiationfails.YoucansetthisvalueformutualCHAPonlyifCHAPissettochapRequired.

Fordirection,specifymutual. IMPORTANTYouareresponsibleformakingsurethatCHAPissetbeforeyousetmutualCHAP,andfor usingcompatiblelevelsforCHAPandmutualCHAP.UseadifferentsecretinCHAPandmutualCHAP. To enable mutual authentication 1 Enableauthentication.


esxcli <conn_options> iscsi adapter auth chap set --direction=uni --chap_username=<name> --chap_password=<pw> --level=[prohibited, discouraged, preferred, required] --secret=<string> --adapter=<adapter_name>

Thespecifiedchap_usernameandsecretmustbesupportedonthestorageside. 2 ListpossibleVMkernelNICstobind.
esxcli <conn_options> iscsi logicalnetworkportal list

80

VMware, Inc.

Chapter 5 Managing iSCSI Storage

Enablemutualauthentication.
esxcli <conn_options> iscsi adapter auth chap set --direction=mutual --mchap_username=<m_name> --mchap_password=<m_pwd> --level=[prohibited, required] --secret=<string> --adapter=<adapter_name>

Thespecifiedmchap_usernameandsecretmustbesupportedonthestorageside. Makesurethefollowingrequirementsaremet.

CHAPauthenticationisalreadysetupwhenyoustartsettingupmutualCHAP. CHAPandmutualCHAPusedifferentusernamesandpasswords.Thesecondusernameand passwordaresupportedformutualauthenticationonthestorageside. CHAPandmutualCHAPusecompatibleCHAPlevels.

Aftersetupiscomplete,performrediscoveryandrescanallstoragedevices.Forexample:
esxcli <conn_options> iscsi adapter discovery rediscover esxcli <conn_options> storage core adapter rescan --adapter=vmhba36

Enabling iSCSI Authentication with vicfg-iscsi


Thevicfg-iscsi-A -coptionsenableiSCSIauthentication.Mutualauthenticationissupportedforsoftware iSCSIanddependenthardwareiSCSI,butnotforindependenthardwareiSCSI.SeeSettingiSCSICHAPon page 60. To enable mutual authentication 1 EnableauthenticationontheESXihost.
vicfg-iscsi <conn_options> -A -c <level> -m <auth_method> -u <auth_u_name> -w <chap_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name>

Thespecifiedusernameandpasswordmustbesupportedonthestorageside. 2 EnablemutualauthenticationontheESXihost.
vicfg-iscsi <conn_options> -A -c <level> -m <auth_method> -b -u <ma_username> -w <ma_password> [-i <stor_ip_addr|stor_hostname> [:<portnum>] [-n <iscsi_name]] <adapter_name>

Makesurethefollowingrequirementsaremet.

CHAPauthenticationisalreadysetupwhenyoustartsettingupmutualCHAP. CHAPandmutualCHAPusedifferentusernamesandpasswords.Thesecondusernameand passwordaresupportedformutualauthenticationonthestorageside. CHAPandmutualCHAPusecompatibleCHAPlevels.

Aftersetupiscomplete,performrediscoveryandrescanallstoragedevices.

Setting Up Ports for iSCSI Multipathing


Withportbinding,youcreateaseparateVMkernelportforeachphysicalNICusing1:1mapping.Youcanadd allnetworkadapterandVMkernelportpairstoasinglevSwitch.ThevSphereStoragedocumentationexplains indetailhowtospecifyportbinding. Youcannotsetupportsformultipathingbyusingvicfg-iscsi. Intheexamplesbelow,specifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>. IMPORTANTTheESX/ESXi4.xESXCLIcommandsforsettingupiSCSIarenolongersupported.

VMware, Inc.

81

vSphere Command-Line Interface Concepts and Examples

To specify port binding 1 FindoutwhichuplinksareavailableforusewithiSCSIadapters.


esxcli <conn_options> iscsi physicalnetworkportal list --adapter=<adapter_name>

ConnectthesoftwareiSCSIordependenthardwareiSCSIinitiatortotheiSCSIVMkernelportsby runningthefollowingcommandforeachport.
esxcli <conn_options> iscsi networkportal nic add --adapter=<adapter_name> --nic=<bound_nic>

VerifythattheportswereaddedtotheiSCSIinitiatorbyrunningthefollowingcommand:
esxcli <conn_options> iscsi networkportal list --adapter=<adapter_name>

4 5

(Optional)IfthereareactiveiSCSIsessionsbetweenyourhostandtargets,discontinuethem.See RemovingiSCSISessionsonpage 83. RescantheiSCSIinitiator.


esxcli <conn_options> storage core adapter rescan --adapter <iscsi adapter>

TodisconnecttheiSCSIinitiatorfromtheports,runthefollowingcommand.
esxcli <conn_options> iscsi networkportal remove --adapter=<adapter_name> --nic=<bound_nic>

Managing iSCSI Sessions


Tocommunicatewitheachother,iSCSIinitiatorsandtargetsestablishiSCSIsessions.Youcanuseesxcli iscsi sessiontolistandmanageiSCSIsessionsforsoftwareiSCSIanddependenthardwareiSCSI.

Introduction to iSCSI Session Management


Bydefault,softwareiSCSIanddependenthardwareiSCSIinitiatorsstartoneiSCSIsessionbetweeneach initiatorportandeachtargetport.IfyouriSCSIinitiatorortargethasmorethanoneport,yourhostcan establishmultiplesessions.Thedefaultnumberofsessionsforeachtargetequalsthenumberofportsonthe iSCSIadaptertimesthenumberoftargetports.Youcandisplayallcurrentsessionstoanalyzeanddebug them.Youmightaddsessionstothedefaultforseveralreasons.

Cloningsessions.SomeiSCSIarrayssupportmultiplesessionsbetweentheiSCSIadapterandtarget ports.Ifyoucloneanexistingsessionononeofthesearrays,thearraypresentsmoredatapathsforyour adapter.Duplicatesessionsdonotpersistacrossreboot.Additionalsessionstothetargetmighthave performancebenefits,buttheresultofcloningdependsentirelyonthearray.Youmustlogoutfroman iSCSIsessionifyouwanttocloneasession.Youcanusetheesxcli iscsi session addcommandto cloneasession. EnablingHeaderandDataDigest.IfyouareloggedintoasessionandwanttoenabletheHeaderand DataDigestparameters,youmustsettheparameter,removethesession,andaddthesessionbackforthe parameterchangetotakeeffect.YoumustlogoutfromaniSCSIsessionifyouwanttocloneasession. Establishingtargetspecificsessions.Youcanestablishasessiontoaspecifictargetport.Thiscanbe usefulifyourhostconnectstoasingleportstoragesystemthat,bydefault,presentsonlyonetargetport toyourinitiator,butcanredirectadditionalsessionstoadifferenttargetport.Establishinganewsession betweenyouriSCSIinitiatorandanothertargetportcreatesanadditionalpathtothestoragesystem.

CAUTIONSomestoragesystemsdonotsupportmultiplesessionsfromthesameinitiatornameorendpoint. AttemptstocreatemultiplesessionstosuchtargetscanresultinunpredictablebehaviorofyouriSCSI environment. Thefollowingexamplescenariousestheavailablecommands.Runesxcli iscsi session --helpandeach commandwith--helpforreferenceinformation.Theexampleusesaconfigurationfiletologintothehost. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. IMPORTANTTheESX/ESXi4.xESXCLIcommandsformanagingiSCSIsessionsarenotsupportedagainst ESXi5.0hosts.
82 VMware, Inc.

Chapter 5 Managing iSCSI Storage

Listing iSCSI Sessions

ListasoftwareiSCSIsessionattheadapterlevel.
esxcli <conn_options> iscsi session list --adapter=<iscsi_adapter>

ListasoftwareiSCSIsessionatthetargetlevel.
esxcli <conn_options> iscsi session list --name=<target> --adapter=<iscsi_adapter>

Logging in to iSCSI Sessions


Youcanuseesxcli iscsi sessiontologintoasession.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>.

LogintoasessiononthecurrentsoftwareiSCSIordependenthardwareiSCSIconfigurationatthe adapterlevel.
esxcli <conn_options> iscsi session add --adapter=<adapter_name>

Forexample:
esxcli --config /host-config-file iscsi session add --adapter=vmhba36

LogintoasessiononthecurrentsoftwareiSCSIordependenthardwareiSCSIconfigurationatthetarget level.
esxcli <conn_options> iscsi session add --name=<target> --adapter=<adapter_name>

Forexample:
esxcli --config /host-config-file iscsi session add -name=iqn.xxx --adapter=vmhba36

AddduplicatesessionswithtargetandsessionIDsincurrentsoftwareiSCSIordependenthardware iSCSIconfiguration.
esxcli <conn_options> iscsi session add --name=<iqn.xxxx> --isid=<session_id> --adapter=<iscsi_adapter>

iqn.xxxxisthetargetIQN,whichyoucandeterminebylistingallsessions.session_idisthesessions iSCSIID.Forexample:
esxcli --config /host-config-file iscsi session add -name=iqn.xxx --isid='00:02:3d:00:00:01' --adapter=vmhba36

Removing iSCSI Sessions


Youcanuseesxcli iscsi sessiontoremoveiSCSIsessions.Specifyoneoftheoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>.

RemovesessionsfromthecurrentsoftwareiSCSIordependenthardwareiSCSIconfigurationatthe adapterlevel.
esxcli <conn_options> iscsi session remove --adapter=<iscsi_adapter>

Forexample:
esxcli iscsi session remove --adapter=vmhba36

RemovesessionsfromthecurrentsoftwareiSCSIordependenthardwareiSCSIconfigurationatthetarget level.
esxcli <conn_options> iscsi session remove --name=<iqn> --adapter=<iscsi_adapter>

Forexample:
esxcli <conn_options> iscsi session remove --name=iqn.xxx --adapter=vmhba38

VMware, Inc.

83

vSphere Command-Line Interface Concepts and Examples

RemovesessionsfromthecurrentsoftwareiSCSIordependenthardwareiSCSIconfigurationwithtarget andsessionID.
esxcli <conn_options> iscsi session remove --name=<iqn.xxxx> --isid=<session id> --adapter=<iscsi_adapter>

iqn.xxxxisthetargetIQN,whichyoucandeterminebylistingallsessions.session_idisthesessions iSCSIID. Forexample:


esxcli --config /host-config-file iscsi session remove --name=iqn.xxx --session='00:02:3d:01:00:01' --adapter=vmhba36

84

VMware, Inc.

Managing Third-Party Storage Arrays

VMwarepartnersandcustomerscanoptimizeperformanceoftheirstoragearraysinconjunctionwith VMwarevSphereusingVMwarePSA(pluggablestoragearchitecture).Theesxcli storage core namespacemanagesVMwarePSAandtheesxcli storage nmpnamespacemanagestheVMwareNMP plugin. ThevSphereStoragedocumentationdiscussesPSAfunctionalityindetailandexplainshowtousethevSphere ClientorthevSphereWebClienttomanagethePSA,theassociatednativemultipathingplugin(NMP)and thirdpartyplugins. Thischapterusesthefollowingacronyms.
Acronym PSA NMP PSP SATP Meaning PluggableStorageArchitecture. NativeMultipathingPlugin.GenericVMwaremultipathingmodule. PathSelectionPlugin.Handlespathselectionforagivendevice. StorageArrayTypePlugin.Handlespathfailoverforagivenstoragearray.

Thischapterincludesthesetopics:

ManagingNMPwithesxclistoragenmponpage 85 PathClaimingwithesxclistoragecoreclaimingonpage 92 ManagingClaimRulesonpage 93

Managing NMP with esxcli storage nmp


TheNMP(NativeMultipathingPlugin)isanextensiblemultipathingmodulethatESXisupportsbydefault. Youcanuseesxcli storage nmptomanagedevicesassociatedwithNMPandtosetpathpolicies. TheNMPsupportsallstoragearrayslistedontheVMwarestorageHardwareCompatibilityList(HCL)and providesapathselectionalgorithmbasedonthearraytype.TheNMPassociatesasetofphysicalpathswith astoragedevice(LUN).AStorageArrayTypePlugin(SATP)determineshowpathfailoverishandledfora specificstoragearray.APathSelectionPlugin(PSP)determineswhichphysicalpathisusedtoissueanI/O requesttoastoragedevice.SATPsandPSPsarepluginswithintheNMPplugin.

VMware, Inc.

85

vSphere Command-Line Interface Concepts and Examples

Device Management with esxcli storage nmp device


ThedeviceoptionperformsoperationsondevicescurrentlyclaimedbytheVMwareNMPplugin.

esxcli storage nmp device list


ThelistcommandliststhedevicescontrolledbyVMwareNMPandshowstheSATPandPSPinformation associatedwitheachdevice.ToshowthepathsclaimedbyNMP,runesxcli storage nmp path listto listinformationforalldevices,orforjustonedevicewiththe--deviceoption.
Options --device <device> -d <device> Description Filterstheoutputofthecommandtoshowinformationaboutasingledevice.Defaultisall devices.

esxcli storage nmp device set


ThesetcommandsetsthePathSelectionPolicy(PSP)foradevicetooneofthepoliciesloadedonthesystem. AnydevicecanusethePSPassignedtotheSATPhandlingthatdevice,oryoucanrunesxcli storage nmp device set --device naa.xxx --psp <psp>tospecificallyoverridethePSPassignedtothedevice.

IfadevicedoesnothaveaspecificPSPset,italwaysusesthePSPassignedtotheSATP.IfthedefaultPSP fortheSATPchanges,thePSPassignedtothedevicechangesonlyafterrebootorafteradeviceis reclaimed.Adeviceisreclaimedwhenyouunclaimallpathsforthedeviceandreclaimthepaths. Ifyouuseesxcli storage nmp device settooverridetheSATPsdefaultPSPwithaspecificPSP,the PSPchangesimmediatelyandremainstheuserdefinedPSPacrossreboots.AchangeintheSATPsPSP hasnoeffect.

Usethe--defaultoptiontoreturnthedevicetousingtheSATPsPSP.
Options --default -E --device <device> -d <device> --psp <PSP> -P <PSP> Description SetsthePSPbacktothedefaultfortheSATPassignedtothisdevice. DevicetosetthePSPfor. PSPtoassigntothespecifieddevice.Callesxcli storage nmp psp listtodisplayall currentlyavailablePSPs.SeeTable 41,SupportedPathPolicies,onpage 48. SeevSphereStorageforadiscussionofpathpolicies.

TosetthepathpolicyforthespecifieddevicetoVMW_PSP_FIXED,runthefollowingcommand:
esxcli <conn_options> storage nmp device set --device naa.xxx --psp VMW_PSP_FIXED

Listing Paths with esxcli storage nmp path


UsethepathoptiontolistpathsclaimedbyNMP.Bydefault,thecommanddisplaysinformationaboutall pathsonalldevices.Youcanfilterinthefollowingways:

Onlyshowpathstoasingedevice(esxcli storage nmp path list --device <device>). Onlyshowinformationforasinglepath(esxcli storage nmp path list --path=<path>.

Tolistdevices,callesxcli storage nmp device list.

Managing Path Selection Policy Plugins with esxcli storage nmp psp
Useesxcli storage nmp psptomanageVMwarepathselectionpolicypluginsincludedwiththeVMware NMPpluginandtomanagethirdpartyPSPs. IMPORTANTWhenusedwiththirdpartyPSPs,thesyntaxdependsonthethirdpartyPSPimplementation.

86

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

Retrieving PSP Information


Theesxcli storage nmp pspgeneric deviceconfig getandesxcli storage nmp pspgeneric pathconfig getcommandretrievesPSPconfigurationparameters.ThetypeofPSPdetermineswhich commandtouse.

Usenmp pspgeneric deviceconfig getforPSPsthataresettoVMW_PSP_RR,VMW_PSP_FIXEDor VMW_PSP_MRU. Usenmp pspgeneric pathconfig getforPSPsthataresettoVMW_PSP_FIXEDorVMW_PSP_MRU.No pathconfigurationinformationisavailableforVMW_PSP_RR.

ToretrievePSPconfigurationparameters,usetheappropriatecommandforthePSP.

Deviceconfigurationinformation.
esxcli <conn_options> storage nmp psp generic deviceconfig get --device=<device> esxcli <conn_options> storage nmp psp fixed deviceconfig get --device=<device> esxcli <conn_options> storage nmp psp roundrobin deviceconfig get --device=<device>

Pathconfigurationinformation.
esxcli <conn_options> storage nmp psp generic pathconfig get --path=<path>

RetrievethePSPconfigurationforthespecifiedpath.
esxcli <conn_options> nmp psp pathconfig generic get --path vmhba4:C1:T2:L23

Theesxcli storage nmp psp listcommandshowsthelistofPathSelectionPluginsonthesystemanda briefdescriptionofeachplugin.

Setting Configuration Parameters for Third-Party Extensions


The esxcli storage nmp psp generic deviceconfig setandesxcli storage nmp psp generic pathconfig setcommandssupportfuturethirdpartyPSAexpansion.ThesetconfigcommandsetsPSP configurationparametersforthosethirdpartyextensions. NOTEThepreciseresultsofthesecommandsdependonthethirdpartyextension.Seetheextension documentationforinformation. Useesxcli storage nmp roundrobin setconfigforotherpathpolicyconfiguration.SeeCustomizing RoundRobinSetuponpage 88. Youcanrunesxcli storage nmp psp generic deviceconfig set --device=<device>tospecifyPSP informationforadevice,andesxcli storage nmp psp generic pathconfig set --path=<path>to specifyPSPinformationforapath.Foreachcommand,use--configtosetthespecifiedconfigurationstring.
Options --config <config_string> -c <config_string> --device <device> -d <device> --path <path> -p <path> Description Configurationstringtosetforthedeviceorpathspecifiedby--deviceor--path.See Table 41,SupportedPathPolicies,onpage 48. Deviceforwhichyouwanttocustomizethepathpolicy. Pathforwhichyouwanttocustomizethepathpolicy.

VMware, Inc.

87

vSphere Command-Line Interface Concepts and Examples

Fixed Path Selection Policy Operations


ThefixedoptiongetsandsetsthepreferredpathpolicyforNMPdevicesconfiguredtouseVMW_PSP_FIXED.

Retrieving the Preferred Path


Theesxclistoragenmp fixed deviceconfig getcommandretrievesthepreferredpathonaspecified devicethatisusingNMPandtheVMW_PSP_FIXEDPSP.
Options --device <device> -d <device> Description Deviceforwhichyouwanttogetthepreferredpath.Thisdevicemustbecontrolledbythe VMW_PSP_FIXEDPSP.

Toreturnthepathconfiguredasthepreferredpathforthespecifieddevice,runthefollowingcommand. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.


esxcli <conn_options> storage nmp fixed deviceconfig get --device naa.xxx

Setting the Preferred Path


Theesxcli storage nmp fixed deviceconfig setcommandsetsthepreferredpathonaspecifieddevice thatisusingNMPandtheVMW_PSP_FIXEDpathpolicy.
Options --device <device> -d <device> Description Deviceforwhichyouwanttosetthepreferredpath.Thisdevicemustbecontrolledbythe VMW_PSP_FIXEDPSP. Useesxcli storage nmp device --listtolistthepoliciesforalldevices. --path <path> -p <path> Pathtosetasthepreferredpathforthespecifieddevice.

Tosetthepreferredpathforthespecifieddevicetovmhba3:C0:T5:L3,runthefollowingcommand.Specify oneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.


esxcli <conn_options> storage nmp fixed deviceconfig set --device naa.xxx --path vmhba3:C0:T5:L3

Customizing Round Robin Setup


Theesxcli storage nmp psp roundrobincommandssetsroundrobinpathoptionsonadevicecontrolled bytheVMW_PSP_RRPSP.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>. To specify and customize round robin path policies 1 Setthepathpolicytoroundrobin.
esxcli <conn_options> storage nmp device set --device naa.xxx --psp VMW_PSP_RR

Specifywhentoswitchpaths. YoucanchoosethenumberofI/Ooperations,numberofbytes,andsoon.Forexample:
esxcli <conn_options> storage nmp psp roundrobin deviceconfig set --type "bytes" -B 12345 --device naa.xxx

Setsthedevicespecifiedby--devicetoswitchtothenextpatheachtime12345byteshavebeensent alongthecurrentpath.
esxcli <conn_options> storage nmp psp roundrobin deviceconfig set --type=iops --iops 4200 --device naa.xxx

Setsthedevicespecifiedby--devicetoswitchafter4200I/Ooperationshavebeenperformedonapath.

88

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

Retrieving Path Selection Settings


Theesxcli storage nmp psp roundrobin deviceconfig get commandretrievespathselectionsettings foradevicethatisusingtheroundrobinPSP.Youcanspecifythedevicetoretrievetheinformationfor.
Options -d <device> --device <device> Description Devicetogetroundrobinpropertiesfor.

Specifying Conditions for Path Changes


Theesxcli storage nmp psp roundrobin deviceconfig setcommandspecifiesunderwhichconditions adevicethatisusingtheVMW_PSP_RRPSPchangestoadifferentpath.Youcanuse--bytesor--iopsto specifywhenthepathshouldchange.
Options --bytes -B --device -d --iops -I --type -t Description NumberofbytestosendalongonepathforthisdevicebeforethePSPswitchestothenextpath. Youcanusethisoptiononlywhen--typeissettobytes. Devicetosetroundrobinpropertiesfor.Thisdevicemustbecontrolledbytheroundrobin (VMW_PSP_RR)PSP. NumberofI/OoperationstosendalongonepathforthisdevicebeforethePSPswitchestothe nextpath.Youcanusethisoptiononlywhen--typeissettoiops. Typeofroundrobinpathswitchingtoenableforthisdevice.Thefollowingvaluesfortypeare supported:

bytes:Setthetriggerforpathswitchingbasedonthenumberofbytessentdownapath. default:Setthetriggerforpathswitchingbacktodefaultvalues. iops:SetthetriggerforpathswitchingbasedonthenumberofI/Ooperationsonapath.

Anequalsign(=)beforethetypeordoublequotesaroundthetypeareoptional. --useANO -U Ifsetto1,theroundrobinPSPincludespathsintheactive,unoptimizedstateintheroundrobin set.Ifsetto0,thePSPusesactive,unoptimizedpathsonlyifnoactiveoptimizedpathsare available.Otherwise,thePSPincludesonlyactiveoptimizedpathsintheroundrobinpathset.

Managing SATPs
Theesxcli storage nmp satpcommandsmanageSATPs.Youcanusethesecommandstoperformthe followingtasks:

Retrieveandsetconfigurationparameters AddandremoverulesfromthelistofclaimrulesforaspecifiedSATP SetthedefaultPSPforaspecifiedSATP ListSATPsthatarecurrentlyloadedintoNMPandtheassociatedclaimrules

ThedefaultSATPforanactiveactiveFCarraywithavendorandmodelnotlistedintheSATPrulesis VMW_SATP_DEFAULT_AA.

Retrieving Information About SATPs


Theesxcli storage nmp satplistcommandliststheSATPsthatarecurrentlyavailabletotheNMP systemanddisplaysinformationaboutthoseSATPs.Thiscommandsupportsnooptionsanddisplays informationabouttheseSATPs.
esxcli <conn_options> storage nmp satp list

Therule listcommandliststheclaimrulesforSATPs. esxcli <conn_options> storage nmp satp rule list

VMware, Inc.

89

vSphere Command-Line Interface Concepts and Examples

Adding SATP Rules


Claimrulesspecifythatastoragedevicethatusesacertaindriverortransportorhasacertainvendorormodel shoulduseacertainSATP.Theesxcli storage nmp satp rule addcommandaddsarulethatperforms suchamappingtothelistofclaimrules.Theoptionsyouspecifydefinetherule.Forexample,thefollowing commandspecifiesthatifapathhasvendorVMWAREandmodelVirtual,thePSAassignsittothe VMW_SATP_LOCALSATP.
esxcli <conn_options> storage nmp satp rule add --satp="VMW_SATP_LOCAL" --vendor="VMWARE" --model="Virtual" --description="VMware virtual disk Option --driver -D --device -d --force -f --model -M ModelstringtosetwhenaddingtheSATPclaimrule.Canbethemodelnameorapattern ^mod*,whichmatchesalldevicesthatstartwithmod.Thatis,thepatternsuccessfullymatches mod1andmodz,butnotmymod1. Thecommandsupportsthestart/end(^)andwildcard(*)functionalitybutnootherregular expressions. --transport -R --vendor -V --satp -s --claim-option -c --description -e --option -o --psp -P --psp-option -O --type -t SettheclaimtypewhenaddingaSATPclaimrule. PSPoptionsfortheSATPclaimrule. OptionstringtosetwhenaddingtheSATPclaimrule.Surroundtheoptionstringindouble quotes,anduseaspace,notacomma,whenspecifyingmorethanoneoption. enable_local enable_ssd. DefaultPSPfortheSATPclaimrule. DescriptionstringtosetwhenaddingtheSATPclaimrule. ClaimoptionstringtosetwhenaddingtheSATPclaimrule. SATPforwhichtheruleisadded. TransportstringtosetwhenaddingtheSATPclaimrule.DescribesthetypeofstorageHBA, forexample,iscsiorfc. VendorstringtosetwhenaddingtheSATPclaimrule. DevicetosetwhenaddingSATPclaimrules.Devicerulesaremutuallyexclusivewith vendor/modelanddriverrules. Forceclaimrulestoignorevaliditychecksandinstalltheruleevenifchecksfail. Description DriverstringtosetwhenaddingtheSATPclaimrule.

ThefollowingexamplesillustrateaddingSATPrules.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>.

AddaSATPrulethatspecifiesthatdiskswithvendorstringVMWAREandmodelstringVirtualshould beaddedtoVMW_SATP_LOCAL.
esxcli <conn_options> storage nmp satp rule add --satp="VMW_SATP_LOCAL" --vendor="VMWARE" --model="Virtual" --description="VMware virtual disk"

AddaSATPrulethatspecifiesthatdiskswiththedriverstringsomedrivershouldbeaddedto VMW_SATP_LOCAL.
esxcli <conn_options> storage nmp satp rule add --satp="VMW_SATP_LOCAL" --driver="somedriver"

90

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

AddarulethatspecifiesthatallstoragedeviceswithvendorstringABCandamodelnamethatstartswith 120shoulduseVMW_SATP_DEFAULT_AA(VMW_SATP_DEFAULT_AAisanexample).
esxcli <conn_options> storage nmp satp rule add --satp VMW_SATP_DEFAULT_AA --vendor="ABC" --model="^120*

Removing SATP Rules


Theesxcli storage nmp satp rule removecommandremovesanexistingSATPrule.Theoptionsyou specifydefinetheruletoremove.TheoptionslistedforAddingSATPRulesonpage 90aresupported. ThefollowingexampleremovestherulethatassignsdeviceswithvendorstringVMWAREandmodelstring VirtualtoVMW_SATP_LOCAL.
esxcli <conn_options> storage nmp satp rule remove --satp="VMW_SATP_LOCAL" --vendor="VMWARE" --model="Virtual"

Retrieving and Setting SATP Configuration Parameters


Theesxcli storage nmp satp generic deviceconfig getandesxcli storage nmp satp generic pathconfig getcommandsretrieveperdeviceorperpathSATPconfigurationparameters.Youcannot retrievepathsordevicesforallSATPs,youmustretrievetheinformationonepathoronedeviceatatime. UsethiscommandtoretrieveperdeviceorperpathSATPconfigurationparameters,andtoseewhetheryou cansetcertainconfigurationparametersforadeviceorpath. Forexampleesxcli storage nmp satp generic deviceconfig get --device naa.xxxmightreturn SATP VMW_SATP_LSI does not support device configuration. esxcli storage nmp satp generic pathconfig get -path vmhba1:C0:T0:L8mightreturnINIT,AVT OFF,v5.4,DUAL ACTIVE,ESX FAILOVER Theesxcli storage nmp satp generic deviceconfigsetandesxcli storage nmp satp generic pathconfig set commandssetconfigurationparametersforSATPsthatareloadedintothesystem,ifthey supportdeviceconfiguration.YoucansetperpathorperdeviceSATPconfigurationparameters. IMPORTANTThecommandpassestheconfigurationstringtotheSATPassociatedwiththatdeviceorpath. TheconfigurationstringsmightvarybySATP.VMwaresupportsafixedsetofconfigurationstringsfora subsetofitsSATPs.Thestringsmightchangeinfuturereleases.
Options --config -c Description Configurationstringtosetforthepathspecifiedby--pathorthedevicespecifiedby--device. YoucansettheconfigurationforthefollowingSATPs:

VMW_SATP_ALUA_CX VMW_SATP_ALUA VMW_SATP_CX VMW_SATP_INV navireg_onstartsautomaticregistrationofthedevicewithNavisphere. navireg_offstopstheautomaticregistrationofthedevice. ipfilter_onstopsthesendingofthehostnameforNavisphereregistration.Usedifhostis knownaslocalhost. ipfilter_offenablesthesendingofthehostnameduringNavisphereregistration.

Youcanspecifyoneofthefollowingdeviceconfigurationstrings:

--device -d --path -p

DevicetosetSATPconfigurationfor.NotallSATPssupportthesetconfigoptionondevices. PathtosetSATPconfigurationfor.NotallSATPssupportthesetconfigoptiononpaths.

Runesxcli storage nmp device set --default --device=<device> tosetthePSPforthespecified devicebacktothedefaultfortheassignedSATPforthisdevice.

VMware, Inc.

91

vSphere Command-Line Interface Concepts and Examples

Path Claiming with esxcli storage core claiming


Theesxcli storage core claimingnamespaceincludesanumberoftroubleshootingcommands.These commandsarenotpersistentandareusefulonlytodeveloperswhoarewritingPSApluginsor troubleshootingasystem.IfI/Oisactiveonthepath,unclaimandreclaimactionsfail. IMPORTANTThehelpforesxcli storage core claiming includestheautoclaimcommand.Donotuse thiscommandunlessinstructedtodosobyVMwaresupportstaff.

Using the Reclaim Troubleshooting Command


Theesxcli storage core claiming reclaimtroubleshootingcommandisintendedforPSAplugin developersoradministratorswhotroubleshootPSAplugins.Thecommandproceedsasfollows.

Attemptstounclaimallpathstoadevice. Runstheloadedclaimrulesoneachoftheunclaimedpathstoreclaimthosepaths.

Itisnormalforthiscommandtofailifadeviceisinuse. IMPORTANTThereclaimcommandunclaimspathsassociatedwithadevice. YoucannotusethecommandtoreclaimpathscurrentlyassociatedwiththeMASK_PATHpluginbecause --deviceistheonlyoptionforreclaimandMASK_PATHpathsarenotassociatedwithadevice. YoucanusethecommandtounclaimpathsforadeviceandhavethosepathsreclaimedbytheMASK_PATH plugin.


Options --device <device> -d <device> --help Displaysthehelpmessage. Description Nameofthedeviceonwhichallpathsarereclaimed.

Unclaiming Paths or Sets of Paths


Theesxcli storage core claiming unclaimcommandunclaimsapathorsetofpaths,disassociating thosepathsfromaPSAplugin.Thecommandsfailsifthedeviceisinuse. Youcanunclaimonlyactivepathswithnooutstandingrequests.YoucannotunclaimtheESXiUSBpartition ordeviceswithVMFSvolumesonthem.Itisthereforenormalforthiscommandtofail,especiallywhenyou specifyapluginoradaptertounclaim. Unclaimingdoesnotpersist.Periodicpathclaimingreclaimsunclaimedpathsunlessclaimrulesare configuredtomaskapath.SeethevSphereStoragedocumentationfordetails. IMPORTANTTheunclaimcommandunclaimspathsassociatedwithadevice.Youcanusethiscommandto unclaimpathsassociatedwiththeMASK_PATHpluginbutcannotusethedeviceoptiontounclaimthose paths.
Options --adapter <adapter> -A <adapter> --channel <channel> -C <channel> --claimrule-class <cl> -c <cl> Description If--typeissettolocation,specifiesthenameoftheHBAforthepathsthatyouwant tounclaim.Ifyoudonotspecifythisoption,unclaimingrunsonpathsfromall adapters. If--typeissettolocation,specifiestheSCSIchannelnumberforthepathsthatyou wanttounclaim.Ifyoudonotspecifythisoption,unclaimingrunsonpathsfromall channels. Claimruleclasstouseinthisoperation.YoucanspecifyMP(Multipathing),Filter,or VAAI.Multipathingisthedefault.FilterisusedonlyforVAAI.Specifyclaimrulesfor bothVAAI_FILTERandVAAIplugintouseit.

92

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

Options --device <device> -d <device> --driver <driver> -D <driver> --lun <lun_number> -L <lun_number> --model <model> -m <model> --path <path> -p <path> --plugin <plugin> -P

Description If--typeissettodevice,attemptstounclaimallpathstothespecifieddevice.Ifthere areactiveI/Ooperationsonthespecifieddevice,atleastonepathcannotbeunclaimed. If--typeisdriver,unclaimsallpathsspecifiedbythisHBAdriver. If--typeislocation,specifiestheSCSILUNforthepathstounclaim.Ifyoudonot specify--lun,unclaimingrunsonpathswithanyLUNnumber. If--typeisvendor,attemptstounclaimallpathstodeviceswithspecificmodel information(formultipathingplugins)orunclaimthedeviceitself(forfilterplugins).If thereareactiveI/Ooperationsonthisdevice,atleastonepathfailstounclaim. If--typeispath,unclaimsapathspecifiedbyitspathUIDorruntimename. If--typeisplugin,unclaimsallpathsforaspecifiedmultipathplugin. <plugin>canbeanyvalidPSApluginonthesystem.BydefaultonlyNMPand MASK_PATHareavailable,butadditionalpluginsmightbeinstalled. If--typeislocation,unclaimsthepathswiththeSCSItargetnumberspecifiedby target.Ifyoudonotspecify--target,unclaimingrunsonpathsfromalltargets. Typeofunclaimoperationtoperform.Validvaluesarelocation,path,driver, device,plugin,andvendor. If--typeisvendor,attemptstounclaimallpathstodeviceswithspecificvendorinfo formultipathingpluginsorunclaimthedeviceitselfforfilterplugins.Ifthereareany activeI/Ooperationsonthisdevice,atleastonepathfailstounclaim

--target <target> -T <target> --type <type> -t <type> --vendor <vendor> -v <vendor>

Thefollowingtroubleshootingcommandtriestounclaimallpathsonvmhba1.
esxcli <conn_options> storage core claiming unclaim --type location -A vmhba1

Runvicfg-mpath <conn_options> -ltoverifythatthecommandsucceeded. Ifapathisthelastpathtoadevicethatwasinuse,oraifapathwasveryrecentlyinuse,theunclaimoperation mightfail.Anerrorisloggedthatnotallpathscouldbeunclaimed.Stopprocessesthatmightusethedevice andwait15secondstoletthedevicebequiesced.Retrythecommand.

Managing Claim Rules


ThePSAusesclaimrulestodeterminewhichmultipathingmoduleshouldclaimthepathstoaparticular deviceandtomanagethedevice.esxclistorage core claimrulemanagesclaimrules. ClaimrulemodificationcommandsdonotoperateontheVMkerneldirectly.Insteadtheyoperateonthe configurationfilebyaddingandremovingrules.SpecifyoneoftheoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. To change the current claim rules in the VMkernel 1 2 Runoneormoreoftheesxcli storage coreclaimrulemodificationcommands(add,remove,or move). Runesxcli storage core claimrule loadtoreplacethecurrentrulesintheVMkernelwiththe modifiedrulesfromtheconfigurationfile.

Youcanalsorunesxcli storage core plugin listtolistallloadedplugins.

Adding Claim Rules


Theesxcli storage core claimrule addcommandaddsaclaimruletothesetofclaimrulesonthe system.YoucanusethiscommandtoaddnewclaimrulesortomaskapathusingtheMASK_PATHclaimrule. Youmustloadtherulesafteryouaddthem.

VMware, Inc.

93

vSphere Command-Line Interface Concepts and Examples

Options --adapter <adapter> -A <adapter> --autoassign -u --channel <channel> -C <channel> --claimrule-class <cl> -c <cl>

Description Adapterofthepathstouse.Validonlyif--typeislocation. Addsaclaimrulebasedonitscharacteristics.Therulenumberisnotrequired. Channelofthepathstouse.Validonlyif--typeislocation. Claimruleclasstouseinthisoperation.YoucanspecifyMP(default),Filter,orVAAI. Toconfigurehardwareaccelerationforanewarray,addtwoclaimrules,oneforthe VAAIfilterandanotherfortheVAAIplugin.SeevSphereStoragefordetailed instructions. DriverfortheHBAofthepathstouse.Validonlyif--typeisdriver. Forceclaimrulestoignorevaliditychecksandinstalltherule. LUNofthepathstouse.Validonlyif--typeislocation. Modelofthepathstouse.Validonlyif--typeisvendor. ValidvaluesarevaluesoftheModelstringfromtheSCSIinquirystring.Run vicfg-scsidevs <conn_options> -loneachdevicetoseemodelstringvalues. PSAplugintouse.Currently,thevaluesareNMPorMASK_PATH,butthirdpartiescan shiptheirownPSApluginsinthefuture. MASK_PATHreferstothepluginMASK_PATH_PLUGIN.Thecommandaddsclaimrules forthispluginiftheuserwantstomaskthepath. ESX3.5includestheMaskLUNsadvancedconfigurationoption.Thisoptionisnot availableinESX/ESXi4.xandESXi5.0.Ithasbeenreplacedbythe MASK_PATH_PLUGIN.YoucanaddaclaimrulethatcausestheMASK_PATH_PLUGINto claimthepathtomaskapathorLUNfromthehost.SeethevSphereStorage documentationfordetails.

--driver <driver> -D <driver> --force -f --lun <lun_number> -L <lun_number> --model <model> -M <model> --plugin -P

--rule <rule_ID> -r <rule_ID> --target <target> -T <target> --transport <transport> -R <transport>

RuleIDtouse.Runesxcli storage core claimrule listtoseetheruleID.The ruleIDindicatestheorderinwhichtheclaimruleistobeevaluated.Userdefined claimrulesareevaluatedinnumericorderstartingwith101. Targetofthepathstouse.Validonlyif--typeislocation. Transportofthepathstouse.Validonlyif--typeistransport.Thefollowingvalues aresupported:

blockblockstorage fcFibreChannel iscsivendoriSCSI iscsinotcurrentlyused ideIDEstorage sasSASstorage sataSATAstorage usbUSBstorage parallelparallel unknown

--type <type> -t <type> --vendor -V

Typeofmatchingtousefortheoperation.Validvaluesarevendor,location, driver,andtransport. Vendorofthepathstouse.Validonlyif--typeisvendor. ValidvaluesarevaluesofthevendorstringfromtheSCSIinquirystring.Run vicfg-scsidevs <conn_options> -loneachdevicetoseevendorstringvalues. WorldWideNodeNumberforthetargettouseinthisoperation. WorldWidePortNumberforthetargettouseinthisoperation.

--wwnn --wwpn

94

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

Claimrulesarenumberedasfollows.

Rules0100arereservedforinternalusebyVMware. Rules10165435areavailableforgeneraluse.Anythirdpartymultipathingpluginsinstalledonyour systemuseclaimrulesinthisrange.Bydefault,thePSAclaimrule101masksDellarraypseudodevices. Donotremovethisrule,unlessyouwanttounmaskthesedevices. Rules6543665535arereservedforinternalusebyVMware.

Whenclaimingapath,thePSArunsthroughtherulesstartingfromthelowestnumberanddeterminesisa pathmatchestheclaimrulespecification.IfthePSAfindsamatch,itgivesthepathtothecorresponding plugin.Thisisworthnoticingbecauseagivenpathmightmatchseveralclaimrules. Thefollowingexamplesillustrateaddingclaimrules.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>.

Addrule321,whichclaimsthepathonadaptervmhba0,channel0,target0,LUN0fortheNMPplugin.
esxcli <conn_options> storage core claimrule add -r 321 -t location -A vmhba0 -C 0 -T 0 -L 0 -P NMP

Addrule429,whichclaimsallpathsprovidedbyanadapterwiththemptscsidriverfortheMASK_PATH plugin.
esxcli <conn_options> storage core claimrule add -r 429 -t driver -D mptscsi -P MASK_PATH

Addrule914,whichclaimsallpathswithvendorstringVMWAREandmodelstringVirtualfortheNMP plugin.
esxcli <conn_options> storage core claimrule add -r 914 -t vendor -V VMWARE -M Virtual -P NMP

Addrule1015,whichclaimsallpathsprovidedbyFCadaptersfortheNMPplugin.
esxcli <conn_options> storage core claimrule add -r 1015 -t transport -R fc -P NMP

Converting ESX 3.5 LUN Masks to Claim Rule Format


Theesxcli storage core claimrule convertcommandconvertsLUNmasksinESX3.5format (/adv/Disk/MaskLUNs)toclaimruleformat.ThecommandwritestheconvertedlistanderasestheoldLUN maskdata.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. To convert ESX 3.5 format LUN masks to claim rule format 1 Runesxcli storage core claimrule convertwithoutoptions. ThatcallreturnsNo /adv/Disk/MaskLUNs config entry to convertordisplaysthelistofclaimrules thatwouldresultfromtheconversion.Forexample: Rule 120 121 122 Plugin MASK_PATH MASK_PATH MASK_PATH HbaName vmhba11 vmhba11 vmhba4 Controller 0 0 0 Target 0 0 2 LUN 11 10 1

VMware, Inc.

95

vSphere Command-Line Interface Concepts and Examples

Runesxcli storage core claimrule convert --committoactuallycommitthechange.

WhenyouconvertLUNmaskingtotheclaimruleformatafteranupgradefromESX/ESXi3.5toESX/ESXi4.x, thiscommandconvertsthe/adv/Disk/MaskLUNsadvancedconfigurationentryintheesx.conffiletoclaim ruleswithMASK_PATHastheplugin. IMPORTANTThisconversiondoesnotworkforallinputMaskLUNvariations.Forexample,roleconversion forsoftwareiSCSILUNsisnotsupported. Inspectthelistofgeneratedclaimrulescarefullybeforeyoucommitthembyusing--commit. Table 6-1. esxcli storage core claimrule convert Options
Options --commit -C Description ForcesLUNmaskconfigurationchangestobesaved.Ifyoucallthecommandwithoutthis parameter,changesarenotsaved,andyoucanfirstinspectthegeneratedclaimrules.

Removing Claim Rules


Theesxcli storage core claimrule removecommandremovesaclaimrulefromthesetofclaimrules onthesystem. IMPORTANTBydefault,thePSAclaimrule101masksDellarraypseudodevices.Donotremovethisrule, unlessyouwanttounmaskthesedevices.
Option --rule <rule_ID> -r <rule_ID> Description IDoftheruletoberemoved.Runesxcli storage core claimrule listtoseetheruleID.

Thefollowingexampleremovesrule1015.
esxcli <conn_options> storage core claimrule remove -r 1015

Listing Claim Rules


Thelistcommandlistsallclaimrulesonthesystem.Youcanspecifytheclaimruleclassasanargument.
Option --claimrule-class <cl> -c <cl> Description Claimruleclasstouseinthisoperation.YoucanspecifyMP(Multipathing),Filter,or VAAI.Multipathingisthedefault.FilterisusedonlyforVAAI.Specifyclaimrulesfor bothVAAI_FILTERandVAAIplugintouseit.SeevSphereStorageforinformationabout VAAI.

Youcanrunthecommandasfollows.Theequalsignisoptional,sobothformsofthecommandhavethesame result.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.


esxcli <conn_options> storage core claimrule list -c Filter esxcli <conn_options> storage core claimrule list --claimrule-class=Filter

Loading Claim Rules


Theesxcli storage core claimrule loadcommandloadsclaimrulesfromtheesx.confconfiguration fileintotheVMkernel.Developersandexperiencedstorageadministratorsmightusethiscommandforboot timeconfiguration. Thiscommandhasnooptions;italwaysloadsallclaimrulesfromesx.conf.

96

VMware, Inc.

Chapter 6 Managing Third-Party Storage Arrays

Moving Claim Rules


Theesxcli storage core claimrule movecommandmovesaclaimrulefromoneruleIDtoanother.
Options --claimrule-class <cl> -c <cl> --new-rule <rule_ID> -n <rule_ID> --rule <rule_ID> -r <rule_ID> Description Claimruleclasstouseinthisoperation. NewruleIDyouwanttogivetotherulespecifiedbythe--ruleoption. IDoftheruletoberemoved.Runesxcli storage core claimrule listtodisplay theruleID.

Thefollowingexamplerenamesrule1016torule1015andremovesrule1016.Specifyoneoftheoptionslisted inConnectionOptionsonpage 17inplaceof<conn_options>.


esxcli <conn_options> storage core claimrule move -r 1015 -n 1016

Running Path Claiming Rules


Theesxcli storage core claimrule runcommandrunspathclaimingrules.Runthiscommandapply claimrulesthatareloaded.Ifyoudonotcallrun,thesystemchecksforclaimruleupdateseveryfiveminutes andappliesthem.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>. To load and apply claim rules 1 Modifyrulesandloadthem.
esxcli <conn_options> storage core claimrule load

Quiescethedevicesthatusepathsforwhichyouwanttochangetheruleandunclaimthosepaths.
esxcli <conn_options> storage core claiming unclaim --device=<device>

Runpathclaimingrules.
esxcli <conn_options> storage core claimrule run

Thiscommandisalsousedfortroubleshootingandboottimeconfiguration.
Options --adapter <adapter> -A <adapter> --channel <channel> -C <channel> --claimrule-class -c --lun <lun> -L <lun> --path <path_UID> -p <path_UID> --target <target> -T <target> Description If--typeislocation,nameoftheHBAforthepathstoruntheclaimruleson.To runclaimrulesonpathsfromalladapters,omitthisoption. If--typeislocation,valueoftheSCSIchannelnumberforthepathstorunthe claimruleson.Torunclaimrulesonpathswithanychannelnumber,omitthis option. Claimruleclasstouseinthisoperation. If--typeislocation,valueoftheSCSILUNforthepathstorunclaimruleson.To runclaimrulesonpathswithanyLUN,omitthisoption. If--typeispath,thisoptionindicatestheuniquepathidentifier(UID)orthe runtimenameofapathtorunclaimruleson. If--typeislocation,valueoftheSCSItargetnumberforthepathstorunclaim ruleson.Torunclaimrulesonpathswithanytargetnumber,omitthisoption

VMware, Inc.

97

vSphere Command-Line Interface Concepts and Examples

Options --type <location|path|all> -t <location|path|all> --wait -w

Description Typeofclaimtoperform.Bydefault,usesall,whichmeansclaimrulesrunwithout restrictiontospecificpathsorSCSIaddresses.Validvaluesarelocation,path,and all. Youcanusethisoptiononlyifyoualsouse--typeall. Iftheoptionisincluded,theclaimwaitsforpathstosettlebeforerunningtheclaim operation.Inthatcase,thesystemdoesnotstarttheclaimingprocessuntilitislikely thatallpathsonthesystemhaveappearedbeforestartingtheclaimprocess. Aftertheclaimingprocesshasstarted,thecommanddoesnotreturnuntildevice registrationhascompleted. Ifyouaddorremovepathsduringtheclaimingorthediscoveryprocess,thisoption mightnotworkcorrectly.

98

VMware, Inc.

Managing Users

AnESXisystemgrantsaccesstoitsresourceswhenaknownuserwithappropriatepermissionslogsontothe systemwithapasswordthatmatchestheonestoredforthatuser.YoucanusethevSphereClientorthe vSphereSDKforallusermanagementtasks.YoucannotcreateESXiuserswiththevSphereWebClient. Youcanusethevicfg-usercommandtocreate,modify,delete,andlistlocaldirectaccessusersonanESXi host.YoucannotrunthiscommandagainstavCenterServersystem. IMPORTANTStartingwithvSphere5.1,youcannolongermanagegroupswithvicfg-user. Thischapterincludesthefollowingtopics:


UsersinthevSphereEnvironmentonpage 99 vicfguserCommandSyntaxonpage 99 ManagingUserswithvicfguseronpage 100

Users in the vSphere Environment


Users,androlescontrolwhohasaccesstovSpherecomponentsandwhatactionseachusercanperform.User managementisdiscussedindetailinthevSphereSecuritydocumentation. IMPORTANTYoucannotusevicfg-usertocreateroles.Youcanmanagesystemdefinedroles. vCenterServerandESXisystemsauthenticateauserwithacombinationofusername,password,and permissions.Serversandhostsmaintainlistsofauthorizedusersandthepermissionsassignedtoeachuser. Privilegesdefinebasicindividualrightsthatarerequiredtoperformactionsandretrieveinformation.ESXi andvCenterServerusesetsofprivileges,orroles,tocontrolwhichuserscanaccessparticularvSphereobjects. ESXiandvCenterServerprovideasetofpreestablishedroles. TheprivilegesandrolesassignedonanESXihostareseparatefromtheprivilegesandrolesassignedona vCenterServersystem.WhenyoumanageahostbyusingvCenterServersystem,onlytheprivilegesandroles assignedthroughthevCenterServersystemareavailable.Ifyouconnectdirectlytothehostbyusingthe vSphereClient,onlytheprivilegesandrolesassigneddirectlyonthehostareavailable.YoucannotcreateESXi userswiththevSphereWebClient.

vicfg-user Command Syntax


Thevicfg-usersyntaxdiffersfromothervCLIcommands.Youspecifyoperationsasfollows:
vicfg-user <conn_options> -e <user> -o <add|modify|delete|list>

Ifyoucreateauserwithoutspecifyingtherole(--role),theuserhasnopermissions.Youcannotchangethe usersrole,youcanonlychangetheuserspermission.

VMware, Inc.

99

vSphere Command-Line Interface Concepts and Examples

IMPORTANTIfyoucreateauserwiththevSphereClient,youcannotmakechangestothatuserwiththe vicfg-usercommand. Options Thevicfg-usercommandspecificoptionsmanipulateusers.Youmustalsospecifyconnectionoptions.See ConnectionOptionsonpage 17.


Option --adduser <user_list> -u <user_list> --entity <user> -e <user> --login <login_id> -l <login_id> --newpassword <p_wd> -p <p_wd> --newuserid <UUID> -i <UUID> --newusername <name> -n <name> --operation -o --role <admin|read-only|no-access> -r <admin|read-only|no-access> --shell -s Description Addsthespecifiedusers.Takesacommaseparatedlistofusers. Entitytoperformtheoperationon.StartingwithvSphere5.1,entityis alwaysuser. LoginIDoftheuser. Passwordforthetargetuser. NewUUIDforthetargetuser. Newusernameforthetargetuser. Operationtoperform.Specifyadd,modify,delete,orlist. Roleforthetargetuser.Specifyoneofadmin,read-only,orno-access. Usersthatyoucreatewithoutassigningpermissionshavenopermissions. Grantshellaccesstothetargetuser.Defaultisnoshellaccess.Usethis commandtochangethedefaultortorevokeshellaccessrightsafterthey havebeengranted. Validvaluesareyesandno. ThisoptionisnotsupportedagainstvSphere5.0systems.Theoptionis supportedonlyagainstESX.TheoptionisnotsupportedagainstESXi.

Managing Users with vicfg-user


AuserisanindividualauthorizedtologintoanESXiorvCenterServersystem. vSpheredoesnotexplicitlyrestrictuserswiththesameauthenticationcredentialsfromaccessingandtaking actionwithinthevSphereenvironmentsimultaneously. YoumanageusersdefinedonthevCenterServersystemandusersdefinedonindividualhostsseparately.

ManageusersdefinedonESXiwiththevSphereClient,thevSphereWebServicesSDK,orvicfg-user. ManagevCenterServeruserswiththevSphereClient,thevSphereWebClient,orthevSphereWeb ServicesSDK.

IMPORTANTYoucannotmodifyuserscreatedwiththevSphereClientwiththevicfg-usercommand. EveniftheuserlistsofahostandavCenterServersystemappeartohavecommonusers(forinstance,auser calleddevuser),theseusersareseparateuserswiththesamename.TheattributesofdevuserinvCenter Server,includingpermissions,passwords,andsoforth,areseparatefromtheattributesofdevuserontheESXi host.IfyoulogintovCenterServerasdevuser,youmighthavepermissiontoviewanddeletefilesfroma datastore.IfyoulogintoanESXihostasdevuser,youmightnothavethesepermissions. UsersauthorizedtoworkdirectlyonanESXihostareaddedtotheinternaluserlistwhenESXiisinstalledor canbeaddedbyasystemadministratorafterinstallation.Youcanusevicfg-usertoaddusers,removeusers, changepasswords,andconfigurepermissions.

100

VMware, Inc.

Chapter 7 Managing Users

CAUTIONSeetheAuthenticationandUserManagementchapterofvSphereSecurityforinformationaboutroot usersbeforeyoumakeanychangestothedefaultusers.Mistakesregardingrootuserscanhaveseriousaccess consequences. EachESXihosthasseveraldefaultusers:

Therootuserhasfulladministrativeprivileges.Administratorsusethisloginanditsassociatedpassword tologintoahostthroughthevSphereClient.Rootuserscancontrolallaspectsofthehostthattheyare loggedonto.Rootuserscanmanipulatepermissions,creatingusers(onESXihostsonly),workingwith events,andsoon. ThevpxuseruserisavCenterServerentitywithrootrightsontheESXihost,allowingittomanage activitiesforthathost.ThesystemcreatesvpxuserwhenanESXihostisattachedtovCenterServer. vpxuserisnotpresentontheESXihostunlessthehostisbeingmanagedthroughvCenterServer. Otherusersmightbedefinedbythesystem,dependingonthenetworkingsetupandotherfactors.

Thefollowingexamplescenarioillustratessomeofthetasksthatyoucanperform.Specifyoneoftheoptions listedinConnectionOptionsonpage 17inplaceof<conn_options>. To create, modify, and delete users 1 Listtheexistingusers.


vicfg-user <conn_options> -e user -o list

Thelistdisplaysallusersthatarepredefinedbythesystemandallusersthatwereaddedlater. IMPORTANTThecommandlistsamaximumof100users. 2 Addanewuser,specifyingaloginIDandpassword.


vicfg-user <conn_options> -e user -o add -l user27 -p 27_password

Thecommandcreatestheuser.Bydefault,thecommandautogeneratesaUIDfortheuser. 3 ListtheusersagaintoverifythatthenewuserwasaddedandaUIDwasgenerated.
vicfg-user <conn_options> -e user -o list USERS ------------------Principal -: root Full Name -: root UID -: 0 Shell Access -> 1 ------------------... -------------------Principal -: user27 Full Name -: UID -: 501 Shell Access -> 0

Modifythepasswordforuseruser27.
vicfg-user <conn_options> -e user -o modify -l user27 -p 27_password2

ThesystemmightreturnUpdated user user27 successfully. 5 Assignreadonlyprivilegestotheuser(whocurrentlyhasnoaccess).


vicfg-user <conn_options> -e user -o modify -l user27 --role read-only

Thesystempromptswhetheryouwanttochangethepassword,whichmightbeadvisableiftheuserdoes notcurrentlyhaveapassword.Answeryorn.Thesystemthenupdatestheuser.
Updated user user27 successfully. Assigned the role read-only

6
VMware, Inc.

RemovetheuserwithloginIDuser27.
101

vSphere Command-Line Interface Concepts and Examples

vicfg-user <conn_options> -e user -o delete -l user27

Thesystemremovestheuserandprintsamessage.
Removed the user user27 successfully.

102

VMware, Inc.

Managing Virtual Machines

YoucanmanagevirtualmachineswiththevSphereWebClientorthevmware-cmdvCLIcommand.Using vmware-cmdyoucanregisterandunregistervirtualmachines,retrievevirtualmachineinformation,manage snapshots,turnthevirtualmachineonandoff,addandremovevirtualdevices,andpromptforuserinput. Thechapterincludesthesetopics:


vmwarecmdOverviewonpage 103 ListingandRegisteringVirtualMachinesonpage 104 RetrievingVirtualMachineAttributesonpage 105 ManagingVirtualMachineSnapshotswithvmwarecmdonpage 106 PoweringVirtualMachinesOnandOffonpage 107 ConnectingandDisconnectingVirtualDevicesonpage 108 WorkingwiththeAnswerVMAPIonpage 109 ForciblyStoppingVirtualMachineswithEXCLIonpage 109

SomevirtualmachinemanagementutilityapplicationsareincludedinthevSphereSDKforPerl. ThevSpherePowerCLIcmdlets,whichyoucaninstallforusewithMicrosoftPowerShell,managemany aspectsofvirtualmachines.

vmware-cmd Overview
vmware-cmdwasincludedinearlierversionoftheESXServiceConsole.Avmware-cmdcommandhasbeen availableinthevCLIpackagesinceESXiversion3.0. IMPORTANTvmware-cmdisnotavailableintheESXiShell.Runthevmware-cmdvCLIcommandinstead. Olderversionsofvmware-cmdsupportasetofconnectionoptionsandgeneraloptionsthatdifferfromthe optionsinothervCLIcommands.Thevmware-cmdvCLIcommandsupportstheseoptions.ThevCLI commandalsosupportsthestandardvCLI--server,--username,--password,and--vihostoptions. vmware-cmddoesnotsupportotherconnectionoptions. IMPORTANTvmware-cmdisalegacytoolandsupportstheusageofVMFSpathsforvirtualmachine configurationfiles.Asarule,usedatastorepathstoaccessvirtualmachineconfigurationfiles.

VMware, Inc.

103

vSphere Command-Line Interface Concepts and Examples

Connection Options for vmware-cmd


Thevmware-cmdvCLIcommandsupportsonlythefollowingconnectionoptions.OthervCLIconnection optionsarenotsupported,forexample,youcannotusevariablesbecausethecorrespondingoptionisnot supported.
Option --server <host> -H <host> --vihost <target> -h <target> -O <port> username <username> -U <username> password <password> -P <password> -Q <protocol> Protocoltouse,eitherhttporhttps.Defaultishttps. Passwordfortheuserspecifiedby-U. Whenyourunvmware-cmdwiththe-HoptionpointingtoavCenterServersystem,use --vihosttospecifytheESXihosttorunthecommandagainst. Alternativeconnectionport.Thedefaultportnumberis902. Userwhoisauthorizedtologintothehostspecifiedby--serveror--vihost. Description TargetESXiorvCenterServersystem.

General Options for vmware-cmd


Thevmware-cmdvCLIcommandsupportsthefollowinggeneraloptions.
Option --help -q -v Description Printsahelpmessagethatliststheoptionsforthiscommand. Runsinquietmodewithminimaloutput.Theoutputdoesnotdisplaythespecifiedoperationand arguments. Runsinverbosemode.

Format for Specifying Virtual Machines


Whenyourunvmware-cmd,thevirtualmachinepathisusuallyrequired.Youcanspecifythevirtualmachine usingoneofthefollowingformats:

Datastoreprefixstyle:'[ds_name] relative_path',forexample:
'[myStorage1] testvms/VM1/VM1.vmx'(Linux)

"[myStorage1] testvms/VM1/VM1.vmx" (Windows)

UUIDbasedpath: folder/subfolder/file,forexample:
'/vmfs/volumes/mystorage/testvms/VM1/VM1.vmx'(Linux)

"/vmfs/volumes/mystorage/testvms/VM1/VM1.vmx"(Windows)

Listing and Registering Virtual Machines


RegisteringorunregisteringavirtualmachinemeansaddingthevirtualmachinetothevCenterServerorESXi inventoryorremovingthevirtualmachine. IMPORTANTIfyouregisteravirtualmachinewithavCenterServersystem,andthenremoveitfromtheESXi host,anorphanedvirtualmachineresults.Callvmware-cmd -s unregisterwiththevCenterServersystem asthetargettoresolvetheissue. ThefollowingexamplescenariolistsallregisteredvirtualmachinesonavCenterServer,unregistersavirtual machine,andreregistersthevirtualmachine.

104

VMware, Inc.

Chapter 8 Managing Virtual Machines

To list, unregister, and register virtual machines 1 Runvmware-cmd -ltolistallregisteredvirtualmachinesonaserver.


vmware-cmd -H <vc_server> -U <login_user> -P <login_password> --vihost <esx_host> -l

ThecommandliststheVMXfileforeachvirtualmachine.
/vmfs/volumes/<storage>/winxpPro-sp2/winxpPro-sp2.vmx /vmfs/volumes/<storage>/RHEL-lsi/RHEL-lsi.vmx /vmfs/volumes/<storage>/VIMA0809/VIMA0809.vmx .....

Runvmware-cmd -s unregistertoremoveavirtualmachinefromtheinventory.
vmware-cmd -H <vc_server> -U <login_user> -P <login_password> --vihost <esx_host> -s unregister /vmfs/volumes/Storage2/testvm/testvm.vmx

Thesystemreturns0toindicatesuccess,1toindicatefailure. NOTEWhenyourunagainstavCenterServersystem,youmustspecifythedatacenterandtheresource pooltoregisterthevirtualmachinein.Thedefaultdatacenterisha-datacenterandthedefaultresource poolisResources. WhenyourunagainstanESXihost,youusuallydonotspecifytheresourcepoolanddatacenter. However,iftwovirtualmachineswiththesamenameexistintworesourcepools,youmustspecifythe resourcepool. 3 4 Runvmware-cmd -lagaintoverifythatthevirtualmachinewasremovedfromtheinventory. Runvmware-cmd -s registertoaddthevirtualmachinebacktotheinventory.
vmware-cmd -H <vc_server> -U <login_user -P <login_password --vihost <esx_host> -s register /vmfs/volumes/Storage2/testvm/testvm.vmx

Thesystemreturns0toindicatesuccess,1toindicatefailure.

Retrieving Virtual Machine Attributes


vmware-cmdincludesoptionsforretrievinginformationaboutavirtualmachine.Eachoptionrequiresthat youspecifythevirtualmachinepath(seeFormatforSpecifyingVirtualMachinesonpage 104).Youmust alsospecifyconnectionoptions,whichdifferfromothervCLIcommands(seeConnectionOptionsfor vmwarecmdonpage 104). Youcanusevmware-cmdoptionstoretrieveanumberofdifferentvirtualmachineattributes.Foracomplete listofoptions,seethevSphereCLIReference.

Theguestinfooptionallowsyoutoretrieveinformationabouttheguestoperatingsystem.Forexample, youcanretrievethenumberofremoteconsolesallowedbyavirtualmachinebyusingguestinforwith theRemoteDisplay.maxConnectionsvariable.


vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getguestinfo RemoteDisplay.maxConnections

TheHardeningGuideincludesadditionalinformationaboutvariablesyoucanuseinconjunctionwith guestinfo.Acompletelistisnotavailable.

Thegetuptimeoptionretrievestheuptimeoftheguestoperatingsystemonthevirtualmachine,in seconds.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getuptime getuptime() = 17921

Thegetproductinfo productoptionliststheVMwareproductthatthevirtualmachinerunson.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getproductinfo product

VMware, Inc.

105

vSphere Command-Line Interface Concepts and Examples

Thereturnvalueisesx(VMwareESX),embeddedESX(VMwareESXi),orunknown.

Thegetproductinfo platformoptionliststheplatformthatthevirtualmachinerunson.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getproductinfo platform

Thereturnvalueiswin32-x86(x86basedWindowssystem),linux-x86(x86basedLinuxsystem),or vmnix-x86(x86basedESXimicrokernel).

Thegetproductinfo build,getproductinfo majorversion,orgetproductinfo minorversion optionsretrieveversioninformation. Thegetstateoptionretrievestheexecutionstateofthevirtualmachine,whichcanbeon,off, suspended,orunknown.


vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getstate getstate() = on

ThegettoolslastactiveoptionindicateswhetherVMwareToolsisinstalledandwhethertheguest operatingsystemisrespondingnormally.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx gettoolslastactive

Thecommandreturnsanintegerindicatinghowmuchtimehaspassed,inseconds,sincethelast heartbeatwasdetectedfromtheVMwareToolsservice.Thisvalueisinitializedtozerowhenavirtual machinepowerson.Thevaluestaysatzerountilthefirstheartbeatisdetected.Afterthefirstheartbeat, thevalueisalwaysgreaterthanzerountilthevirtualmachineispowercycledagain.Thecommand returnsoneofthefollowingvalues:


0VMwareToolsisnotinstalledornotrunning. 1Guestoperatingsystemisrespondingnormally. 5Intermittentheartbeat.Theremightbeaproblemwiththeguestoperatingsystem. 100Noheartbeat.Guestoperatingsystemmighthavestoppedresponding.

NOTEYouusuallyusethevmware-cmd guestinfooptiononlywhenVMwareSupportinstructsyoutodo so.Thecommandisthereforenotdiscussedinthisdocument.

Managing Virtual Machine Snapshots with vmware-cmd


Asnapshotcapturestheentirestateofthevirtualmachineatthetimeyoutakethesnapshot. Virtualmachinestateincludesthefollowingaspectsofthevirtualmachine.

Memorystate.Contentsofthevirtualmachinesmemory. Settingsstate.Virtualmachinesettings. Diskstate.Stateofallthevirtualmachinesvirtualdisks.

Whenyoureverttoasnapshot,youreturntheseitemstothestatetheywereinatthetimethatyoutookthe snapshot.Ifyouwantthevirtualmachinetoberunningortobeshutdownwhenyoustartit,makesurethat itisinthatstatewhenyoutakethesnapshot. Youcanusesnapshotsasrestorationpointswhenyouinstallupdatepackages,orduringabranchingprocess, suchasinstallingdifferentversionsofaprogram.Takingsnapshotsensuresthateachinstallationbeginsfrom anidenticalbaseline.ThevSphereVirtualMachineAdministrationdocumentationdiscussessnapshotsindetail. IMPORTANTUsethevSphereWebClienttoreverttoanamedsnapshot.vmware-cmdonlysupportsreverting tothecurrentsnapshot.

106

VMware, Inc.

Chapter 8 Managing Virtual Machines

Taking Virtual Machine Snapshots


Youcantakeasnapshotwhileavirtualmachineisrunning,shutdown,orsuspended.Ifyouareintheprocess ofsuspendingavirtualmachine,waituntilthesuspendoperationhasfinishedbeforetakingasnapshot. Ifavirtualmachinehasmultipledisksindifferentdiskmodes,youmustshutdownthevirtualmachinebefore takingasnapshot.Forexample,ifyouhaveaspecialpurposeconfigurationthatrequiresyoutousean independentdisk,youmustshutdownthevirtualmachinebeforetakingasnapshot. To take a snapshot 1 (Optional)Ifthevirtualmachinehasmultipledisksindifferentdiskmodes,shutdownthevirtual machine.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx stop soft

(Optional)Checkthattheshutdownoperationhasbeencompleted.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx getstate

Runvmware-cmdwiththecreatesnapshotoption. Youmustspecifythedescription,quiesceflag(0or1)andmemoryflag(0or1).
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx createsnapshot VM1Aug09 test snapshot August 09 0 0

Checkthatthevirtualmachinehasasnapshotbyusingthehassnapshotoption. Thecallreturns1ifthevirtualmachinehasasnapshotandreturns0otherwise.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx hassnapshot hassnapshot () = 1

Reverting and Removing Snapshots


Youcanusevmware-cmdtoreverttothecurrentsnapshotortoremoveasnapshot. IMPORTANTYoucannotusevmware-cmdtoreverttoanamedsnapshot.UsethevSphereWebClienttorevert toanamedsnapshot. Runvmware-cmdwiththerevertsnapshotoptiontoreverttothecurrentsnapshot.Ifnosnapshotexists,the commanddoesnothingandleavesthevirtualmachinestateunchanged.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx revertsnapshot

Runvmware-cmdwiththeremovesnapshotsoptiontoremoveallsnapshotsassociatedwithavirtual machine.Ifnosnapshotexists,thecommanddoesnothing.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx removesnapshots

Powering Virtual Machines On and Off


Youcanstart,reboot,stop,andsuspendvirtualmachinesbyusingvmware-cmd.Youmustsupplyavaluefor thepowerop_modeflag,whichcanbesoftorhard. IMPORTANTYoumusthavethecurrentversionofVMwareToolsinstalledandrunningintheguestoperating systemtouseasoftpoweroperation.

VMware, Inc.

107

vSphere Command-Line Interface Concepts and Examples

Softpoweroperations.Whenyouspecifysoftasthepowerop_modevalue,theresultofthecalldepends ontheoperation.
Operation Stop Reset Suspend Result vmware-cmdattemptstoshutdowntheguestoperatingsystemandpowersoffthevirtualmachine. vmware-cmdattemptstoshutdowntheguestoperatingsystemandrebootsthevirtualmachine. vmware-cmdattemptstorunascriptintheguestoperatingsystembeforesuspendingthevirtual machine.

Hardpoweroperations.vmware-cmdimmediatelyandunconditionallyshutsdown,resets,orsuspends thevirtualmachine.

Thefollowingexamplesillustratehowtousevmware-cmd.

Start.Usethestartoptiontopoweronavirtualmachineortoresumeasuspendedvirtualmachine.The powerop_mode,eitherhardorsoft,isrequired.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx start soft

Reset.Whenyouresetthevirtualmachinewiththesoftpower_opmode(thedefault),theguest operatingsystemisshutdownbeforethereset. IfVMwareToolsisnotcurrentlyinstalledonthevirtualmachine,youcanperformonlyahardreset operation. a CheckthatVMwaretoolsisinstalledsothatyoucanresetthevirtualmachinewiththedefault power_opmode,whichissoft.


vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx gettoolslastactive

SeeRetrievingVirtualMachineAttributesonpage 105. b Usetheresetoptiontoshutdownandrestartthevirtualmachine.


vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx reset soft

Suspend.Youhavetwooptionsforsuspendingavirtualmachine.

Thesuspendoptionwiththehardpoweropmodeunconditionallyshutsdownavirtualmachine.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx suspend hard

Thesuspendoptionwiththesoftpoweropmoderunsscriptsthatresultinagracefulshutdownof theguestoperatingsystemandshutsdownthevirtualmachine.VMwareToolsmustbeinstalledfor softpowerop_mode.


vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx suspend soft

Connecting and Disconnecting Virtual Devices


Youcanaddandremovevirtualdevicesbyusingtheconnectdeviceanddisconnectdeviceoptions.The selectedguestoperatingsystemdetermineswhichoftheavailabledevicesyoucanaddtoagivenvirtual machine. ThevirtualhardwarethatyouaddappearsinthehardwarelistthatisdisplayedintheVirtualMachine Propertieswizard.Youcanreconfigurevirtualmachinehardwarewhilethevirtualmachineisrunning,ifthe followingconditionsaremet:

Thevirtualmachinehasaguestoperatingsystemthatsupportshotplugfunctionality.SeetheOperating SystemInstallationdocumentation.

108

VMware, Inc.

Chapter 8 Managing Virtual Machines

Thevirtualmachineisusinghardwareversion7.

Thefollowingexamplesillustrateconnectinganddisconnectingavirtualdevice.

TheconnectdeviceoptionconnectsthevirtualIDEdeviceCD/DVDDrive2tothespecifiedvirtual machine.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx connectdevice "CD/DVD Drive 2"

Thedisconnectdeviceoptiondisconnectsthevirtualdevice.
vmware-cmd -H <vc_system> -U <user> -P <password> --vihost <esx_host> /vmfs/volumes/Storage2/testvm/testvm.vmx disconnectdevice "CD/DVD Drive 2"

Working with the AnswerVM API


TheAnswerVMAPIallowsuserstoprovideinputtoquestions,therebyallowingblockedvirtualmachine operationstocomplete.Thevmware-cmd --answeroptionallowsyoutoaccesstheinput.Youmightusethis optionwhenyouwanttoconfigureavirtualmachinebasedonauserssinput.Forexample: 1 2 Theuserclonesavirtualmachineandprovidesthedefaultvirtualdisktype. Whentheuserpowersonthevirtualmachine,itpromptsforthedesiredvirtualdisktype.

Forcibly Stopping Virtual Machines with EXCLI


Insomecases,virtualmachinesdonotrespondtothenormalshutdownorstopcommands.Inthesecases,it mightbenecessarytoforciblyshutdownthevirtualmachines.Forciblyshuttingdownavirtualmachine mightresultinguestoperatingsystemdatalossandissimilartopullingthepowercableonaphysical machine. Youcanforciblystopvirtualmachinesthatarenotrespondingtonormalstopoperationwiththeesxcli vm process killcommand.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof <conn_options>. To forcibly stop a virtual machine 1 ListallrunningvirtualmachinesonthesystemtoseetheWorldIDofthevirtualmachinethatyouwant tostop.
esxcli <conn_options> vm process list

Stopthevirtualmachinebyrunningthefollowingcommand.
esxcli <conn_options> vm process kill --type <kill_type> --world-id <ID>

Thecommandsupportsthree--typeoptions.Trythetypessequentially(softbeforehard,hardbefore force).Thefollowingtypesaresupportedthroughthe--typeoption:

soft.GivestheVMXprocessachancetoshutdowncleanly(likekillorkill -SIGTERM) hard.StopstheVMXprocessimmediately(likekill -9orkill -SIGKILL) force.StopstheVMXprocesswhenotheroptionsdonotwork.

Ifallthreeoptionsdonotwork,rebootyourESXihosttoresolvetheissue.

VMware, Inc.

109

vSphere Command-Line Interface Concepts and Examples

110

VMware, Inc.

Managing vSphere Networking

ThevSphereCLInetworkingcommandsallowyoutomanagethevSpherenetworkservices.Youcanconnect virtualmachinestothephysicalnetworkandtoeachotherandconfigurevSpherestandardswitches.Limited configurationofvSpheredistributedswitchesisalsosupported.YoucanalsosetupyourvSphere environmenttoworkwithexternalnetworkssuchasSNMPorNTP. Thischapterincludesthefollowingtopics:


IntroductiontovSphereNetworkingonpage 111 RetrievingBasicNetworkingInformationonpage 113 NetworkTroubleshootingonpage 114 SettingUpvSphereNetworkingwithvSphereStandardSwitchesonpage 115 SettingUpvSphereNetworkingwithvSphereDistributedSwitchonpage 126 ManagingStandardNetworkingServicesinthevSphereEnvironmentonpage 126 SettingtheDNSConfigurationonpage 126 AddingandStartinganNTPServeronpage 129 ManagingtheIPGatewayonpage 129 SettingUpIPseconpage 130 ManagingtheESXiFirewallonpage 133

Introduction to vSphere Networking


AtthecoreofvSphereNetworkingarevirtualswitches.vSpheresupportsstandardswitches(VSS)and distributedswitches(VDS).Eachvirtualswitchhasapresetnumberofportsandoneormoreportgroups. Virtualswitchesallowyourvirtualmachinestoconnecttoeachotherandtoconnecttotheoutsideworld.

Whentwoormorevirtualmachinesareconnectedtothesamevirtualswitch,andthosevirtualmachines arealsoonthesameportgrouporVLAN,networktrafficbetweenthemisroutedlocally. Whenvirtualmachinesareconnectedtoavirtualswitchthatisconnectedtoanuplinkadapter,each virtualmachinecanaccesstheexternalnetworkthroughthatuplink.Theadaptercanbeanuplink connectedtoastandardswitchoradistributeduplinkportconnectedtoadistributedswitch.

VirtualswitchesallowyourESXihosttomigratevirtualmachineswithVMwarevMotionandtouseIPstorage throughVMkernelnetworkinterfaces.

UsingvMotion,youcanmigraterunningvirtualmachineswithnodowntime.YoucanenablevMotion withvicfg-vmknic --enable-vmotion.YoucannotenablevMotionwithESXCLI.

VMware, Inc.

111

vSphere Command-Line Interface Concepts and Examples

IPstoragereferstoanyformofstoragethatusesTCP/IPnetworkcommunicationasitsfoundationand includesiSCSIandNFSforESXi.Becausethesestoragetypesarenetworkbased,theycanusethesame VMkernelinterfaceandportgroup.

ThenetworkservicesthattheVMkernelprovides(iSCSI,NFS,andvMotion)useaTCP/IPstackinthe VMkernel.TheVMkernelTCP/IPstackisalsoseparatefromtheguestoperatingsystemsnetworkstack.Each ofthesestacksaccessesvariousnetworksbyattachingtooneormoreportgroupsononeormorevirtual switches.

Networking Using vSphere Standard Switches


vSpherestandardswitchesallowyoutoconnectvirtualmachinestotheoutsideworld. Figure 9-1. Networking with vSphere Standard Switches
VM VM VM Network C port groups VM VM

vSphere Standard Switch Host1 Host1

vSphere Standard Switch

Host2

virtual

Host2 physical

physical network adapters

physical network

Figure 91showstherelationshipbetweenthephysicalandvirtualnetworkelements.Thenumbersmatch thoseinthefigure.

AssociatedwitheachESXihostareoneormoreuplinkadapters(1).Uplinkadaptersrepresentthe physicalswitchestheESXihostusestoconnecttothenetwork.Youcanmanageuplinkadaptersusingthe esxcli network nicorvicfg-nicsvCLIcommand.SeeManagingUplinkAdaptersonpage 120. Eachuplinkadapterisconnectedtoastandardswitch(2).Youcanmanageastandardswitchand associateitwithuplinkadaptersbyusingtheesxcli network vswitchorvicfg-vswitchvCLI command.SeeSettingUpVirtualSwitchesandAssociatingaSwitchwithaNetworkInterfaceon page 115. Associatedwiththestandardswitchareportgroups(3).Portgroupisauniqueconceptinthevirtual environment.Youcanconfigureportgroupstoenforcepoliciesthatprovideenhancednetworking security,networksegmentation,betterperformance,highavailability,andtrafficmanagement.Youcan usetheesxcli network vswitch standard portgrouporvicfg-vswitchcommandtoassociatea standardswitchwithaportgroup,andtheesxcli network ip interfaceorvicfg-vmkniccommand toassociateaportgroupwithaVMkernelnetworkinterface. TheVMkernelTCP/IPnetworkingstacksupportsiSCSI,NFS,andvMotionandhasanassociated VMkernelnetworkinterface.YouconfigureVMkernelnetworkinterfaceswithesxcli network ip interfaceorvicfg-vmknic.SeeAddingandModifyingVMkernelNetworkInterfacesonpage 123. SeparateVMkernelnetworkinterfacesareoftenusedforseparatetasks,forexample,youmightdevote oneVMkernelNetworkinterfacecardtovMotiononly.VirtualmachinesruntheirownsystemsTCP/IP stacksandconnecttotheVMkernelattheEthernetlevelthroughvirtualswitches.

112

VMware, Inc.

Chapter 9 Managing vSphere Networking

Networking Using vSphere Distributed Switches


Whenyouwanttoconnectavirtualmachinetotheoutsideworld,youcanuseastandardswitchora distributedswitch.Withadistributedswitch,thevirtualmachinecanmaintainitsnetworksettingsevenifthe virtualmachineismigratedtoadifferenthost. Figure 9-2. Networking with vSphere Distributed Switches
VM VM VM Network C distributed port group A B C D E F G H I J VM VM

vSphere Distributed Switch Host1 Host1 uplink

uplink

Host2

virtual

Host2 physical

physical network adapters

physical network

Eachphysicalnetworkadapter(1)onthehostispairedwithadistributeduplinkport(2),which representstheuplinktothevirtualmachine.Withdistributedswitches,thevirtualmachinenolonger dependsonthehostsphysicaluplinkbutonthe(virtual)uplinkport.Youmanageauplinkports primarilyusingthevSphereWebClient,orvSphereAPIs. Thedistributedswitchitself(3)functionsasasinglevirtualswitchacrossallassociatedhosts.Becausethe switchisnotassociatedwithasinglehost,virtualmachinescanmaintainconsistentnetwork configurationastheymigratefromonehosttoanother. Likeastandardswitch,eachdistributedswitchisanetworkhubthatvirtualmachinescanuse.A distributedswitchcanroutetrafficinternallybetweenvirtualmachinesorlinktoanexternalnetworkby connectingtophysicalnetworkadapters.YoucreateadistributedswitchusingthethevSphereWeb ClientUI,butcanmanagesomeaspectsofadistributedswitchwithvicfg-vswitch.Youcanlist distributedvirtualswitcheswiththeesxcli network vswitchcommand.SeeSettingUpVirtual SwitchesandAssociatingaSwitchwithaNetworkInterfaceonpage 115.

Retrieving Basic Networking Information


ServiceconsolecommandsforretrievingnetworkinginformationarenotincludedintheESXiShell.Youcan insteaduseESXCLIcommandsdirectlyintheshellorusevCLIcommands. OnESXi5.0,ifconfiginformationshouldbetheinformationoftheVMkernelNICthatattachestothe ManagementNetworkportgroup.YoucanretrieveinformationbyusingESXCLIcommands.
esxcli esxcli esxcli esxcli <conn_options> <conn_options> <conn_options> <conn_options> network network network network ip ip ip ip interface interface interface interface list ipv4 get -n vmk<X> ipv6 get -n vmk<X> ipv6 address list

ForinformationcorrespondingtotheLinuxnetstatcommand,usethefollowingESXCLIcommand.
esxcli <conn_options> network ip connection list

VMware, Inc.

113

vSphere Command-Line Interface Concepts and Examples

Youcanalsopingindividualhostswiththeesxcli network diag pingcommand.Thecommandincludes optionsforusingICMPv4orICMPv6packetrequests,specifyinganinterfacetouse,specifyingtheinterval, andsoon.

Network Troubleshooting
YoucanusevCLInetworkcommandstoviewnetworkstatisticsandtroubleshootyournetworkingsetup.The nestedhierarchyofcommandsallowsyoutodrilldowntopotentialtroublespots. 1 Listallvirtualmachinenetworksonahost.
esxcli network vm list

ThecommandreturnsforeachvirtualmachinetheWorldID,name,numberofports,andnetworks,asin thefollowingexample.
World ID Name Num Ports Networks ---------------------------------------------------10374 ubuntu-server-11.04-1 2 VM Network, 10375 ubuntu-server-11.04-2 2 VM Network, 10376 ubuntu-server-11.04-3 2 VM Network, 10408 ubuntu-server-11.04-4 3 VM Network,

dvportgroup-19 dvportgroup-19 dvportgroup-19 VM Network 10Gbps, dvportgroup-19

ListtheportsforoneoftheVMsbyspecifyingitsWorldID.
esxcli network vm port list -w 10408

Thecommandreturnsportinformation,asinthefollowingexample.
Port: Port ID: XXXXXXXX vSwitch: vSwitch0 Portgroup: VM Network DVPort ID: MAC Address: 00:XX:XX:aa:XX:XX IP Address: 10.XXX.XXX.XXX Team Uplink: vmnic0 Uplink Port ID: 12345678 Active Filters:

Retrievetheswitchstatisticsforaport.
esxcli network port stats get -p 12345678

Thecommandreturnsdetailedstatistics,asinthefollowingexample.
Packet statistics for port 12345678: Packets received: 517631 Packets sent: 18937 Bytes received: 100471874 Bytes sent: 1527233 Broadcast packets received: 474160 Broadcast packets sent: 107 Multicast packets received: 8020 Multicast packets sent: 8 Unicast packets received: 35451 Unicast packets sent: 18822 Receive packets dropped: 45 Transmit packets dropped: 0

Retrievethefilterinformationfortheport.
esxcli network port filter stats get -p 12345678

Thecommandreturnsdetailedstatistics,asinthefollowingexample.
Filter statistics for dvfilter-test: Filter direction: Receive Packets in: 202080 Packets out: 202080 Packets dropped: 0

114

VMware, Inc.

Chapter 9 Managing vSphere Networking

Packets filtered: 0 Packets faulted: 0 Packets queued: 0 Packets injected: 0 Packet errors: 0

RetrievecompletestatisticsforaNIC.
esxcli network nic stats get -n vmnic0

GetaperVLANpackedbreakdownonaNIC.
esxcli network nic vlan stats get -n vmnic0

ThecommandreturnsthenumberofpacketssentandreceivedfortheVLANyouspecified.

Setting Up vSphere Networking with vSphere Standard Switches


Youcansetupyourvirtualnetworkbyperformingthesetasks. 7 Createormanipulatevirtualswitchesusingesxcli network vswitchorvicfg-vswitch.Bydefault, eachESXihosthasonevirtualswitch,vSwitch0.Youcancreateadditionalvirtualswitchesormanage existingswitches.SeeSettingUpVirtualSwitchesandAssociatingaSwitchwithaNetworkInterface onpage 115. (Optional)Makechangestotheuplinkadapterusingesxcli network vswitch standard uplinkor vicfg-nics.SeeManagingUplinkAdaptersonpage 120. (Optional)Useesxcli network vswitch standard portgrouporvicfg-vswitchtoaddportgroups tothevirtualswitch.SeeManagingPortGroupswithvicfgvswitchonpage 118. (Optional)Useesxcli network vswitch standard portgroup setorvicfg-vswitchtoestablish VLANsbyassociatingportgroupswithVLANIDs.SeeSettingthePortGroupVLANIDwith vicfgvswitchonpage 120. Useesxcli network ip interfaceorvicfg-vmknictoconfiguretheVMkernelnetworkinterfaces. SeeAddingandModifyingVMkernelNetworkInterfacesonpage 123.

8 9 10

11

Setting Up Virtual Switches and Associating a Switch with a Network Interface


AvirtualswitchmodelsaphysicalEthernetswitch.Youcanmanagevirtualswitchesandportgroupsbyusing thevSphereWebClient(seethevSphereNetworkingdocumentation)orbyusingvSphereCLIcommands. Youcancreateamaximumof127virtualswitchesonasingleESXihost.Bydefault,eachESXihosthasasingle virtualswitchcalledvSwitch0.Bydefault,avirtualswitchhas56logicalports.SeetheConfiguration MaximumsdocumentonthevSpheredocumentationmainpagefordetails.Portsconnecttothevirtual machinesandtheESXiphysicalnetworkadapters.

YoucanconnectonevirtualmachinenetworkadaptertoeachportbyusingthevSphereWebClientUI. Youcanconnecttheuplinkadaptertothevirtualswitchesbyusingvicfg-vswitchoresxcli network vswitch standard uplink.SeeLinkingandUnlinkingUplinkAdapterswithvicfgvswitchon page 122.

Whentwoormorevirtualmachinesareconnectedtothesamevirtualswitch,networktrafficbetweenthemis routedlocally.Ifanuplinkadapterisattachedtothevirtualswitch,eachvirtualmachinecanaccessthe externalnetworkthattheadapterisconnectedto. Thissectiondiscussesworkinginastandardswitchenvironment.SeeNetworkingUsingvSphere DistributedSwitchesonpage 113forinformationaboutdistributedswitchenvironments.

VMware, Inc.

115

vSphere Command-Line Interface Concepts and Examples

Whenworkingwithvirtualswitchesandportgroups,performthefollowingtasks: 1 Findoutwhichvirtualswitchesareavailableand(optionally)whattheassociatedMTUandCDP(Cisco DiscoveryProtocol)settingsare.SeeRetrievingInformationaboutVirtualSwitcheswithESXCLIon page 116andRetrievingInformationaboutVirtualSwitcheswithvicfgvswitchonpage 116. Addavirtualswitch.SeeAddingandDeletingVirtualSwitcheswithESXCLIonpage 117andAdding andDeletingVirtualSwitcheswithvicfgvswitchonpage 117. Foranewlyaddedswitch,performthesetasks: a b c d Addaportgroup.SeeManagingPortGroupswithESXCLIonpage 118andManagingPort Groupswithvicfgvswitchonpage 118. (Optional)SettheportgroupVLANID.SeeSettingthePortGroupVLANIDwithESXCLIon page 119andSettingthePortGroupVLANIDwithvicfgvswitchonpage 120. Addanuplinkadapter.SeeLinkingandUnlinkingUplinkAdapterswithESXCLIonpage 122and LinkingandUnlinkingUplinkAdapterswithvicfgvswitchonpage 122. (Optional)ChangetheMTUorCDPsettings.SeeSettingSwitchAttributeswithesxclinetwork vswitchstandardonpage 117andSettingSwitchAttributeswithvicfgvswitchonpage 118.

2 3

Retrieving Information About Virtual Switches


YoucanretrieveinformationaboutvirtualswitchesbyusingESXCLIorvicfg-vswitch.Specifyoneofthe optionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Retrieving Information about Virtual Switches with ESXCLI


Youcanretrieveinformationaboutvirtualswitchesbyusingesxcli network vswitchcommands.

Listallvirtualswitchesandassociatedportgroups.
esxcli <conn_options> network vswitch standard list

Thecommandprintsinformationaboutthevirtualswitch,whichmightincludeitsname,numberof ports,MTU,portgroups,andotherinformation.TheoutputincludesinformationaboutCDPsettingsfor thevirtualswitch.Thepreciseinformationdependsonthetargetsystem.Thedefaultportgroupsare Management NetworkandVM Network.

Listthenetworkpolicysettings(securitypolicy,trafficshapingpolicy,andfailoverpolicy)forthevirtual switch.Thefollowingcommandsaresupported.
esxcli <conn_options> network vswitch standard policy failover get esxcli <conn_options> network vswitch standard policy security get esxcli <conn_options> network vswitch standard policy shaping get

Retrieving Information about Virtual Switches with vicfg-vswitch


Youcanretrieveinformationaboutvirtualswitchesbyusingthevcifg-vswitchcommand.Specifyoneof theoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

CheckwhethervSwitch1exists.
vicfg-vswitch <conn_options> -c vSwitch1

Listallvirtualswitchesandassociatedportgroups.
vicfg-vswitch <conn_options> -l

Thecommandprintsinformationaboutthevirtualswitch,whichmightincludeitsname,numberof ports,MTU,portgroups,andotherinformation.ThedefaultportgroupsareManagement Networkand VM Network.

RetrievethecurrentCDP(CiscoDiscoveryProtocol)settingforthisvirtualswitch.

116

VMware, Inc.

Chapter 9 Managing vSphere Networking

IfCDPisenabledonavirtualswitch,ESXiadministratorscanfindoutwhichCiscoswitchportis connectedtowhichvirtualswitchuplink.CDPisalinklevelprotocolthatsupportsdiscoveryof CDPawarenetworkhardwareateitherendofadirectconnection.CDPisbitforwardedthrough switches.CDPisasimpleadvertisementprotocolwhichbeaconsinformationabouttheswitchorhostand someportinformation.


vicfg-vswitch <conn_options> --get-cdp vSwitch1

Adding and Deleting Virtual Switches


YoucanaddanddeletevirtualswitcheswithESXCLIandwithvicfg-vswitch.

Adding and Deleting Virtual Switches with ESXCLI


Youcanaddanddeletevirtualswitchesusingtheesxcli network vswitchstandard namespace.Specify oneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Addavirtualswitch.
esxcli <conn_options> network vswitch standard add --vswitch-name=vSwitch42

Youcanspecifythenumberofportgroupswhileaddingthevirtualswitch.Ifyoudonotspecifyavalue, thedefaultvalueisused.Thesystemwideportcountcannotbegreaterthan4096.
esxcli <conn_options> network vswitch standard add --vswitch-name=vSwitch42 --ports=8

Afteryouhaveaddedavirtualswitch,youcansetswitchattributes(SettingSwitchAttributeswithesxcli networkvswitchstandardonpage 117)andaddoneormoreuplinkadapters(LinkingandUnlinking UplinkAdapterswithESXCLIonpage 122).

Deleteavirtualswitch.
esxcli <conn_options> network vswitch standard remove --vswitch-name=vSwitch42

YoucannotdeleteavirtualswitchifanyportsontheswitcharestillinusebyVMkernelnetworksor virtualmachines.Runesxcli network vswitch standard list todeterminewhetheravirtualswitch isinuse.

Adding and Deleting Virtual Switches with vicfg-vswitch


Youcanaddanddeletevirtualswitchesusingthe--add|-aand--delete|-doptions.Specifyoneofthe optionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Addavirtualswitch.
vicfg-vswitch <conn_options> --add vSwitch2

Afteryouhaveaddedavirtualswitch,youcansetswitchattributes(SettingSwitchAttributeswith vicfgvswitchonpage 118)andaddoneormoreuplinkadapters(LinkingandUnlinkingUplink Adapterswithvicfgvswitchonpage 122).

Deleteavirtualswitch.
vicfg-vswitch <conn_options> --delete vSwitch1

YoucannotdeleteavirtualswitchifanyportsontheswitcharestillinusebyVMkernelnetworks,virtual machines,orvswifs.Runvicfg-vswitch --listtodeterminewhetheravirtualswitchisinuse.

Setting Switch Attributes with esxcli network vswitch standard


Youcansetthemaximumtransmissionunit(MTU)andCDPstatusforavirtualswitch.TheCDPstatusshows whichCiscoswitchportisconnectedtowhichuplink.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>.

SettheMTUforavSwitch.
esxcli <conn_options> network vswitch standard set --mtu=9000 --vswitch-name=vSwitch1

VMware, Inc.

117

vSphere Command-Line Interface Concepts and Examples

TheMTUisthesize,inbytes,ofthelargestprotocoldataunittheswitchcanprocess.Whenyousetthis option,itaffectsalluplinksassignedtothevirtualswitch.

SettheCDPvalueforavSwitch.Youcansetstatustodown,listen,advertise,orboth.
esxcli <conn_options> network vswitch standard set --cdp-status=listen --vswitch-name=vSwitch1

Setting Switch Attributes with vicfg-vswitch


Youcansetthemaximumtransmissionunit(MTU)andCDPstatusforavirtualswitch.TheCDPstatusshows whichCiscoswitchportisconnectedtowhichuplink.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>.

SettheMTUforavSwitch.
vicfg-vswitch <conn_options> -m 9000 vSwitch1

TheMTUisthesize(inbytes)ofthelargestprotocoldataunittheswitchcanprocess.Whenyousetthis option,itaffectsalluplinksassignedtothevirtualswitch.

SettheCDPvalueforavSwitch.Youcansetstatustodown,listen,advertise,orboth.
vicfg-vswitch <conn_options> --set-cdp listen

Checking, Adding, and Removing Port Groups


Youcancheck,add,andremoveportgroupswithESXCLIandwithvicfg-vswitch.

Managing Port Groups with ESXCLI


NetworkservicesconnecttovSwitchesthroughportgroups.Aportgroupallowsyoutogrouptrafficand specifyconfigurationoptionssuchasbandwidthlimitationsandVLANtaggingpoliciesforeachportinthe portgroup.Avirtualswitchmusthaveoneportgroupassignedtoit.Youcanassignadditionalportgroups. Youcanuseesxcli network vswitch standard portgroup tocheck,add,andremoveportgroups. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Listportgroupscurrentlyassociatedwithavirtualswitch.
esxcli <conn_options> network vswitch standard portgroup list

Liststheportgroupname,associatedvirtualswitch,activeclients,andVLANID.

Addaportgroup.
esxcli <conn_options> network vswitch standard portgroup add --portgroup-name=<name> --vswitch-name=vSwitch1

Deleteoneoftheexistingportgroups.
esxcli <conn_options> network vswitch standard portgroup remove --portgroup-name=<name> --vswitch-name=vSwitch1

Managing Port Groups with vicfg-vswitch


Networkservicesconnecttovirtualswitchesthroughportgroups.Aportgroupallowsyoutogrouptraffic andspecifyconfigurationoptionssuchasbandwidthlimitationsandVLANtaggingpoliciesforeachportin theportgroup.Avirtualswitchmusthaveoneportgroupassignedtoit.Youcanassignadditionalport groups.SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. Youcanusevicfg-vswitchtocheck,add,andremoveportgroups.

Checkwhetherportgroupsarecurrentlyassociatedwithavirtualswitch.
vicfg-vswitch <conn_options> --check-pg <port_group> vSwitch1

Thecommandreturns0ifthespecifiedportgroupisassociatedwiththevirtualswitch,andreturns1 otherwise.Usevicfg-vswitch --listtolistallportgroups.

118

VMware, Inc.

Chapter 9 Managing vSphere Networking

Addaportgroup.
vicfg-vswitch <conn_options> --add-pg <port_group_name> vSwitch1

Deleteoneoftheexistingportgroups.
vicfg-vswitch <conn_options> --del-pg <port_group_name> vSwitch1

Managing Uplinks and Port Groups


YoucanmanageuplinksandportgroupswithESXCLIandwithvicfg-vswitch.

Connecting and Disconnecting Uplink Adapters and Port Groups with ESXCLI
Ifyoursetupincludesoneormoreportgroups,youcanassociateeachportgroupwithoneormoreuplink adapters(andremovetheassociation).Thisfunctionalityallowsyoutofiltertrafficfromaportgrouptoa specificuplink,evenifthevirtualswitchisconnectedwithmultipleuplinks.Specifyoneoftheoptionslisted inConnectionOptionsonpage 17inplaceof<conn_options>.

Connectaportgroupwithanuplinkadapter.
esxcli <conn_options> network vswitch standard portgroup policy failover set --active-uplinks=vmnic1,vmnic6,vmnic7

Thiscommandfailssilentlyiftheuplinkadapterdoesnotexist.

Makesomeoftheadaptersstandbyinsteadofactive.
esxcli <conn_options> network vswitch standard portgroup policy failover set --standby-uplinks=vmnic1,vmnic6,vmnic7

Connecting and Disconnecting Uplinks and Port Groups with vicfg-vswitch


Ifyoursetupincludesoneormoreportgroups,youcanassociateeachportgroupwithoneormoreuplink adapters(andremovetheassociation).Thisfunctionalityallowsyoutofiltertrafficfromaportgrouptoa specificuplink,evenifthevirtualswitchisconnectedwithmultipleuplinks.Specifyoneoftheoptionslisted inConnectionOptionsonpage 17inplaceof<conn_options>.

Connectaportgroupwithanuplinkadapter.
vicfg-vswitch <conn_options> --add-pg-uplink <adapter_name> --pg <port_group> <vswitch_name>

Thiscommandfailssilentlyiftheuplinkadapterdoesnotexist.

Removeaportgroupfromanuplinkadapter.
vicfg-vswitch <conn_options> --del-pg-uplink <adapter_name> --pg <port_group> <vswitch_name>

Setting the Port Group VLAN ID


YoucansettheportgroupVLANIDwithESXCLIandwithvicfg-vswitch.

Setting the Port Group VLAN ID with ESXCLI


VLANsallowyoutofurthersegmentasinglephysicalLANsegmentsothatgroupsofportsareisolatedasif theywereonphysicallydifferentsegments.ThestandardisIEEE802.1Q. AVLANIDrestrictsportgrouptraffictoalogicalEthernetsegmentwithinthephysicalnetwork.

SettheVLANIDto4095toallowaportgrouptoreachportgroupslocatedonotherVLAN. SettheVLANIDto0todisabletheVLANforthisportgroup.

IfyouuseVLANIDs,youmustchangetheportgrouplabelsandVLANIDstogethersothatthelabels properlyrepresentconnectivity.VLANIDsareoptional. YoucanusethefollowingcommandsforVLANmanagement:

AllowportgroupstoreachportgroupslocatedonotherVLANs.

VMware, Inc.

119

vSphere Command-Line Interface Concepts and Examples

esxcli <conn_options> network vswitch standard portgroup set -p <pg_name> --vlan-id 4095

CallthecommandmultipletimestoallowallportstoreachportgroupslocatedonotherVLANs.

DisableVLANforportgroupg42
esxcli <conn_options> network vswitch standard portgroup set --vlan-id 0 -p <pg_name>

Setting the Port Group VLAN ID with vicfg-vswitch


VLANsallowyoutofurthersegmentasinglephysicalLANsegmentsothatgroupsofportsareisolatedasif theywereonphysicallydifferentsegments.ThestandardisIEEE802.1Q. AVLANIDrestrictsportgrouptraffictoalogicalEthernetsegmentwithinthephysicalnetwork.

SettheVLANIDto4095toallowaportgrouptoreachportgroupslocatedonotherVLAN. SettheVLANIDto0todisabletheVLANforthisportgroup.

IfyouuseVLANIDs,youmustchangetheportgrouplabelsandVLANIDstogethersothatthelabels properlyrepresentconnectivity.VLANIDsareoptional. YoucanusethefollowingcommandsforVLANmanagement:

AllowallportgroupstoreachportgroupslocatedonotherVLANs.
vicfg-vswitch <conn_options> --vlan 4095 --pg ALL vSwitch2

DisableVLANforportgroupg42.
vicfg-vswitch <conn_options> --vlan 0 --pg g42 vSwitch2

Runvicfg-vswitch -ltoretrieveinformationaboutVLANIDscurrentlyassociatedwiththevirtual switchesinthenetwork. Runesxcli network vswitch standard portgroup listtolistallportgroupsandassociatedVLANIDs.

Managing Uplink Adapters


Youcanmanageuplinkadapters,whichrepresentthephysicalNICsthatconnecttheESXihosttothenetwork byusingtheesxcli network nicsorthevicfg-nicscommand.Youcanalsouseesxcli network vswitchandesxcfg-vswitchtolinkandunlinktheuplink. Youcanusevicfg-nicstolistinformationandtospecifyspeedandduplexsettingfortheuplink. Youcanuseesxcli network nic tolistalluplinks,tolistinformation,tosetattributes,andtobringa specifieduplinkdownorup.

Managing Uplink Adapters with esxcli network nic


Thefollowingexampleworkflowlistsalluplinkadapters,listspropertiesforoneuplinkadapter,changesthe uplinksspeedandduplexsettings,andbringstheuplinkdownandbackup.Specifyoneoftheoptionslisted inConnectionOptionsonpage 17inplaceof<conn_options>. To manipulate uplink adapter setup 1 Listalluplinksandinformationabouteachdevice.
esxcli <conn_options> network nic list

Youcannarrowdowntheinformationdisplayedbyusingesxcli network nic get --nic-name=<nic>. 2 (Optional)Bringdownoneoftheuplinkadapters.


esxcli <conn_options> network nic down --nic-name=vmnic0

Changeuplinkadaptersettings.
esxcli <conn_options> network nic set <option>

120

VMware, Inc.

Chapter 9 Managing vSphere Networking

Specifyoneofthefollowingoptions.
-a|--auto -D|--duplex=<str> -P | --phy-address -l|--message-level=<long>

Setthespeedandduplexsettingstoautonegotiate. DuplextosetthisNICto.Acceptablevaluesarefullandhalf. SettheMACaddressofthedevice Setthedrivermessagelevel.Messagelevelsandwhattheyimplydifferper driver. NameoftheNICtoconfigured.Mustbeoneofthecardslistedinthenic list command(required). Selectsthedeviceport.Thefollowingdeviceportsareavailable.


-n|--nic-name=<str>

-p|--port=<str>

auiSelectauiasthedeviceport bncSelectbncasthedeviceport fibreSelectmiiasthedeviceport miiSelectmiiasthedeviceport tpSelecttpasthedeviceport

-S|--speed=<long> -t|--transceiver-type=<str>

SpeedtosetthisNICto.Acceptablevaluesare10,100,1000,and10000. Selecttransceivertype.Thefollowingtransceivertypesareavailable.

externalSetthetransceivertypetoexternal internalSetthetransceivertypetointernal

-w|--wake-on-lan=<str>

SetWake-on-LANoptions.Notalldevicessupportthisoption.Theoptionvalue isastringofcharactersspecifyingwhichoptionstoenable.

pWakeonphyactivity uWakeonunicastmessages mWakeonmulticastmessages bWakeonbroadcastmessages aWakeonARP gWakeonMagicPacket sEnableSecureOnpasswordforMagicPacket

(Optional)Bringtheuplinkadapterbackup.
esxcli <conn_options> network nic up --nic-name=vmnic0

Specifying Multiple Uplinks with ESXCLI


Atanytime,oneportgroupNICarrayandacorrespondingsetofactiveuplinksexist.Whenyouchangethe activeuplinks,youalsochangethestandbyuplinksandthenumberofactiveuplinks. Thefollowingexampleillustrateshowactiveandstandbyuplinksareset. 1 2 3 Theportgroupnicarrayis[vmnic1,vmnic0,vmnic3,vmnic5,vmnic6,vmnic7]andactive-uplinksis settothreeuplinks(vmnic1,vmnic0,vmnic3).Theotheruplinksarestandbyuplinks. Yousettheactiveuplinkstoanewset[vmnic3,vmnic5]. Thenewuplinksoverridetheoldset.TheNICarraychangesto[vmnic3,vmnic5,vmnic6,vmnic7]. vmnic0andvmnic1areremovedfromtheNICarrayandmax-activebecomes2.

Ifyouwanttokeepvmnic0andvmnic1inthearray,youcanmakethoseNICsstandbyuplinksinthe commandthatchangestheactiveuplinks.
esxcli network vswitch standard portgroup policy failover set -p testPortgroup --active-uplinks vmnic3,vmnic5 --standby-uplinks vmnic1,vmnic0,vmnic6,vmnic7

VMware, Inc.

121

vSphere Command-Line Interface Concepts and Examples

Managing Uplink Adapters with vicfg-nics


Thefollowingexampleworkflowlistsanuplinkadaptersproperties,changestheduplexandspeed,andsets theuplinktoautonegotiateitsspeedandduplexsettings.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To manipulate uplink adapter setup 1 Listsettings.
vicfg-nics <conn_options> -l

Liststheuplinksinthesystem,theircurrentandconfiguredspeed,andtheirduplexsetting. 2 Setthesettingsforvmnic0tofullandthespeedto100.
vicfg-nics <conn_options> -d full -s 100 vmnic0

Setvmnic2toautonegotiateitsspeedandduplexsettings.
vicfg-nics <conn_options> -a vmnic2

Linking and Unlinking Uplink Adapters with ESXCLI


Whenyoucreateavirtualswitchusingesxcli network vswitch standard add,alltrafficonthatvirtual switchisinitiallyconfinedtothatvirtualswitch.Allvirtualmachinesconnectedtothevirtualswitchcantalk toeachother,butthevirtualmachinescannotconnecttothenetworkortovirtualmachinesonotherhosts.A virtualmachinealsocannotconnecttovirtualmachinesconnectedtoadifferentvirtualswitchonthesame host. Havingavirtualswitchthatisnotconnectedtothenetworkmightmakesenseifyouwantagroupofvirtual machinestobeabletocommunicatewitheachother,butnotwithotherhostsorwithvirtualmachineson otherhosts.Inmostcases,yousetupthevirtualswitchtotransferdatatoexternalnetworksbyattachingone ormoreuplinkadapterstothevirtualswitch. Youcanusethefollowingcommandstolist,add,andremoveuplinkadapters.WhenyoulinkusingESXCLI, thephysicalNICisaddedasastandbyadapterbydefault.Youcanthenmodifytheteamingpolicytomake thephysicalNICactivebyrunningthecommandesxcli network vswitch standard policy failover set.

Listuplinkadapters.
esxcli <conn_options> network vswitch standard list

TheuplinkadaptersarereturnedintheUplinkitem.

Addanewuplinkadaptertoavirtualswitch.
esxcli <conn_options> network vswitch standard uplink add --uplink-name=vmnic15 vswitch-name=vSwitch0

Removeanuplinkadapterfromavirtualswitch.
esxcli <conn_options> network vswitch standard uplink remove --uplink-name=vmnic15 vswitch-name=vSwitch0

Linking and Unlinking Uplink Adapters with vicfg-vswitch


Whenyoucreateavirtualswitchusingvicfg-vswitch--add,alltrafficonthatvirtualswitchisinitially confinedtothatvirtualswitch.Allvirtualmachinesconnectedtothevirtualswitchcantalktoeachother,but thevirtualmachinescannotconnecttothenetworkortovirtualmachinesonotherhosts.Avirtualmachine alsocannotconnecttovirtualmachinesconnectedtoadifferentvirtualswitchonthesamehost. Havingavirtualswitchthatisnotconnectedtothenetworkmightmakesenseifyouwantagroupofvirtual machinestobeabletocommunicatewitheachother,butnotwithotherhostsorwithvirtualmachineson otherhosts.Inmostcases,yousetupthevirtualswitchtotransferdatatoexternalnetworksbyattachingone ormoreuplinkadapterstothevirtualswitch. Youcanusethefollowingcommandstoaddandremoveuplinkadapters:
122 VMware, Inc.

Chapter 9 Managing vSphere Networking

Addanewuplinkadaptertoavirtualswitch.
vicfg-vswitch <conn_options> --link vmnic15 vSwitch0

Removeanuplinkadapterfromavirtualswitch.
vicfg-vswitch <conn_options> --unlink vmnic15 vSwitch0

Adding and Modifying VMkernel Network Interfaces


VMkernelnetworkinterfacesareusedprimarilyformanagementtraffic,whichcanincludevMotion,IP Storage,andothermanagementtrafficontheESXisystem.YoucanalsobindanewlycreatedVMkernel networkinterfaceforusebysoftwareanddependenthardwareiSCSIbyusingtheesxcli iscsicommands. TheVMkernelnetworkinterfaceisseparatefromthevirtualmachinenetwork.Theguestoperatingsystem andapplicationprogramscommunicatewithaVMkernelnetworkinterfacethroughacommonlyavailable devicedriveroraVMwaredevicedriveroptimizedforthevirtualenvironment.Ineithercase,communication intheguestoperatingsystemoccursasitwouldwithaphysicaldevice.Virtualmachinescanalso communicatewithaVMkernelnetworkinterfaceifbothusethesamevirtualswitch. EachVMkernelnetworkinterfacehasitsownMACaddressandoneormoreIPaddresses,andrespondsto thestandardEthernetprotocolaswouldaphysicalNIC.TheVMkernelnetworkinterfaceiscreatedwithTCP SegmentationOffload(TSO)enabled. YoucanmanageVMkernelNICswithESXCLI(seeManagingVMkernelNetworkInterfaceswithESXCLI onpage 123)andwithvicfg-vmknic(seeManagingVMkernelNetworkInterfaceswithvicfgvmknicon page 124).

Managing VMkernel Network Interfaces with ESXCLI


YoucanconfiguretheVMkernelnetworkinterfaceforIPv4(seeToaddandconfigureanIPv4VMkernel NetworkInterfaceforIPv4onpage 123)orforIPv6(seeToaddandconfigureaVMkernelNetwork InterfaceforIPv6onpage 124)withESXCLI.Incontrasttovicfg-vmknic,ESXCLIdoesnotsupport enablingvMotion. YoucanaddandconfigureanIPv4VMkernelNICwithESXCLI.Specifyoneoftheoptionslistedin ConnectionOptionsonpage 17inplaceof<conn_options>. To add and configure an IPv4 VMkernel Network Interface for IPv4 1 AddanewVMkernelnetworkinterface.
esxcli <conn_options> network ip interface add --interface-name=vmk<x> --portgroup-name=<my_portgroup>

YoucanspecifytheMTUsettingafteryouhaveaddedthenetworkinterfacebyusingesxcli network ip interface set --mtu. 2 ConfiguretheinterfaceasanIPv4interface.YoumustspecifytheIPaddressusing--ip,thenetmask,and thename.Forthefollowingexamples,assumethatVMSFVMK363isaportgrouptowhichyouwantto addaVMkernelnetworkinterface.


esxcli <conn_options> network ip interface ipv4 set --ip=<ip_address> --netmask=255.255.255.0 --interface-name=vmk<X>

Youcansettheaddressasfollows.

<X.X.X.X>StaticIPv4address. DHCPUseIPv4DHCP.

TheVMkernelsupportsDHCPonlyforESXi4.0andlater. Whenthecommandfinishessuccessfully,thenewlyaddedVMkernelnetworkinterfaceisenabled. 3 ListinformationaboutallVMkernelnetworkinterfacesonthesystem.


esxcli <conn_options> network ip interface list

VMware, Inc.

123

vSphere Command-Line Interface Concepts and Examples

Thecommanddisplaysthenetworkinformation,portgroup,MTU,andcurrentstateforeachvirtual networkadapterinthesystem. YoucanaddandconfigureanIPv6VMkernelNICwithESXCLI. To add and configure a VMkernel Network Interface for IPv6 1 Runesxcli network ip interface addtoaddanewVMkernelnetworkinterface.
esxcli <conn_options> network ip interface add --interface-name=vmk<x> --portgroup-name=<my_portgroup>

YoucanspecifytheMTUsettingafteryouhaveaddedthenetworkinterfacebyusingesxcli network ip interface set --mtu. Whenthecommandfinishessuccessfully,thenewlyaddedVMkernelnetworkinterfaceisenabled. 2 Runesxcli network ip interface ipv6 address add toconfiguretheinterfaceasanIPv6interface. YoumustspecifytheIPaddressusing--ipandthename.Forthefollowingexamples,assumethat VMSFVMK363isaportgrouptowhichyouwanttoaddaVMkernelnetworkinterface.
esxcli <conn_options> network ip interface ipv6 address add --ip=<X:X:X::/X> --interface-name=vmk<X>

Youcansettheaddressasfollows.

<X:X:X::/X>:StaticIPv6address --enable-dhcpv6:EnablesDHCPv6onthisinterfaceandattemptstoacquireanIPv6addressfrom thenetwork. --enable-router-adv:UsetheIPv6addressadvertisedbytherouter.Theaddressisaddedwhen theroutersendsthenextrouteradvert.

TheVMkernelsupportsDHCPonlyforESXi4.0andlater. Whenthecommandcompletessuccessfully,thenewlyaddedVMkernelnetworkinterfaceisenabled. 3 ListinformationaboutallVMkernelnetworkinterfacesonthesystem.


esxcli <conn_options> network ip interface list

Thelistcontainsthenetworkinformation,portgroup,MTU,andcurrentstateforeachVMkernel NetworkInterfaceonthesystem. 4 YoucanlaterremovetheIPv6addressanddisableIPv6.


esxcli <conn_options> network ip interface ipv6 address remove --interface-name=<VMK_NIC> --ipv6=<ipv6_addr> esxcli <conn_options> network ip set --ipv6-enabled=false

Managing VMkernel Network Interfaces with vicfg-vmknic


YoucanconfiguretheVMkernelnetworkinterfaceforIPv4(seeToaddandconfigureanIPv4VMkernel NetworkInterfacewithvicfgvmkniconpage 124)orforIPv6(seeToaddandconfigureanIPv6VMkernel NetworkInterfacewithvicfgvmkniconpage 125).SpecifyoneoftheoptionslistedinConnectionOptions onpage 17inplaceof<conn_options>. To add and configure an IPv4 VMkernel Network Interface with vicfg-vmknic 1 Runvicfg-vmknic --addtoaddaVMkernelnetworkinterface. YoumustspecifytheIPaddressbyusing--ip,thenetmask,andthename.Forthefollowingexamples, assumethatVMSFVMK363isaportgrouptowhichyouwanttoaddaVMkernelnetworkinterface.
vicfg-vmknic <conn_options> --add --ip <ip_address> -n 255.255.255.0 VMSF-VMK-363

YoucanspecifytheMTUsettingwhenaddingaVMkernelnetworkinterface.Youcannotchangethat settingatalatertime. Whenthecommandcompletessuccessfully,thenewlyaddedVMkernelnetworkinterfaceisenabled.

124

VMware, Inc.

Chapter 9 Managing vSphere Networking

ChangetheIPaddressasneeded.
vicfg-vmknic <conn_options> --ip <address> VMSF-VMK-363

ForIPv4,chooseoneofthefollowingformats:

<X.X.X.X>StaticIPv4address. DHCPUseIPv4DHCP.

TheVMkernelsupportsDHCPonlyforESXi4.0andlater. 3 (Optional)EnablevMotion. Bydefault,vMotionisdisabled.


vicfg-vmknic <conn_options> --enable-vmotion VMSF-VMK-363

Youcanlateruse--disable-vmotiontodisablevMotionforthisVMkernelnetworkinterface. 4 ListinformationaboutallVMkernelnetworkinterfacesonthesystem.
vicfg-vmknic <conn_options> --list

Thecommanddisplaysthenetworkinformation,portgroup,MTU,andcurrentstateforeachvirtual networkadapterinthesystem. To add and configure an IPv6 VMkernel Network Interface with vicfg-vmknic 1 Runvicfg-vmknic --addtoaddaVMkernelnetworkinterface. YoumustspecifytheIPaddressbyusing--ip,thenetmask,andtheportgroupname.Forthefollowing examples,assumethatVMSFVMK363isaportgrouptowhichyouwanttoaddaVMkernelnetwork interface. YoucanspecifytheMTUsettingwhenyouaddaVMkernelnetworkinterface.Youcannotchangethat settingatalatertime. Whenthecommandcompletessuccessfully,thenewlyaddedVMkernelnetworkinterfaceisenabled. 2 EnableIPv6.
vicfg-vmknic <conn_options> --enable-ipv6 true VMSF-VMK-363

SupplyanIPv6address.
vicfg-vmknic <conn_options> --ip <ip_address> VMSF-VMK-363

ForIPv6,theIPaddresscanhaveoneofthefollowingformats:

<X:X:X::/X>StaticIPv6address DHCPV6UseDHCPIPv6address.TheVMkernelsupportsDHCPonlyforESX/ESXi4.0andlater. AUTOCONFUsetheIPv6addressadvertisedbytherouter.IfyoucreateaVMkernelnetworkinterface withAUTOCONF,anaddressisassignedimmediately.IfyouaddAUTOCONFtoanexisting vmknic,theaddressisaddedwhentheroutersendsthenextrouteradvert.

(Optional)EnablevMotion. Bydefault,vMotionisdisabled.
vicfg-vmknic <conn_options> --enable-vmotion VMSF-VMK-363

Youcanlateruse--disable-vmotiontodisablevMotionagain. 5 ListinformationaboutallVMkernelnetworkinterfacesonthesystem.
vicfg-vmknic <conn_options> --list

Thelistcontainsthenetworkinformation,portgroup,MTU,andcurrentstateforeachvirtualnetwork adapterinthesystem. 6 YoucanlaterremovetheIPv6addressanddisableIPv6.

VMware, Inc.

125

vSphere Command-Line Interface Concepts and Examples

vicfg-vmknic <conn_options> --unset-ip <X:X:X::/X> VMSF-VMK-363 vicfg-vmknic <conn_options> --enable-ipv6 false VMSF-VMK-363

Setting Up vSphere Networking with vSphere Distributed Switch


Adistributedswitchfunctionsasasinglevirtualswitchacrossallassociatedhosts.Adistributedswitchallows virtualmachinestomaintainaconsistentnetworkconfigurationastheymigrateacrossmultiplehosts.See NetworkingUsingvSphereDistributedSwitchesonpage 113. LikeavSpherestandardswitch,eachdistributedswitchisanetworkhubthatvirtualmachinescanuse.A distributedswitchcanforwardtrafficinternallybetweenvirtualmachinesorlinktoanexternalnetworkby connectingtouplinkadapters. Eachdistributedswitchcanhaveoneormoredistributedportgroupsassignedtoit.Distributedportgroups groupmultipleportsunderacommonconfigurationandprovideastableanchorpointforvirtualmachines thatareconnectingtolabelednetworks.Eachdistributedportgroupisidentifiedbyanetworklabel,whichis uniquetothecurrentdatacenter.AVLANID,whichrestrictsportgrouptraffictoalogicalEthernetsegment withinthephysicalnetwork,isoptional. YoucancreatedistributedswitchesbyusingthevSphereWebClient.Afteryouhavecreatedadistributed switch,youcanaddhostsbyusingthevSphereWebClient,createdistributedportgroups,andedit distributedswitchpropertiesandpolicieswiththevSphereWebClient.Youcanaddandremoveuplinkports byusingvicfg-vswitch. IMPORTANTInvSphere5.0,youcannotcreatedistributedvirtualswitcheswithESXCLI. SeethevSphereNetworkingdocumentationandthewhitepaperavailablethroughtheResourceslinkat http://www.vmware.com/go/networkingforinformationaboutdistributedswitchesandhowtoconfigure themusingthevSphereWebClient. Youcanaddandremovedistributedswitchuplinkportswithvicfg-vswitch. IMPORTANTYoucannotaddandremoveuplinkportswithESXCLI. Afterthedistributedswitchhasbeensetup,youcanusevicfg-vswitchtoaddorremoveuplinkports. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>.

Addanuplinkport.
vicfg-vswitch <conn_options> --add-dvp-uplink <adapter_name> --dvp <DVPort_id> <dvswitch_name>

Removeanuplinkport.
vicfg-vswitch <conn_options> --del-dvp-uplink <adapter> --dvp <DVPort_id> <dvswitch_name>

Managing Standard Networking Services in the vSphere Environment


YoucanusevCLIcommandstosetupDNS,NTP,SNMP,andthedefaultgatewayforyourvSphere environment.

Setting the DNS Configuration


YoucansettheDNSconfigurationwithESXCLIorwithvicfg-dns.

Setting the DNS Configuration with ESXCLI


Theesxcli network ip dnscommandlistsandspecifiestheDNSconfigurationofyourESXihost. IMPORTANTIfyoutrytochangethehostordomainnameortheDNSserveronhoststhatuseDHCP,anerror results.

126

VMware, Inc.

Chapter 9 Managing vSphere Networking

InnetworkenvironmentswhereaDHCPserverandaDNSserverareavailable,ESXihostsareautomatically assignedDNSnames. InnetworkenvironmentswhereautomaticDNSisnotavailableoryoudonotwanttouseautomaticDNS,you canconfigurestaticDNSinformation,includingahostname,primarynameserver,secondarynameserver, andDNSsuffixes. Theesxcli network ip dnsnamespaceincludestwonamespaces.


esxcli network ip dns searchincludescommandsforDNSsearchdomainconfiguration. esxcli network ip dns serverincludescommandsforDNSserverconfiguration.

ThefollowingexampleillustratessettingupaDNSserver.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To set up a DNS Server 1 PrintalistofDNSserversconfiguredonthesystemintheorderinwhichtheywillbeused.


esxcli <conn_options> network ip dns server list

IfDNSisnotsetupforthetargetserver,thecommandreturnsanemptystring. 2 Addaserverbyrunningesxcli network ip dns server addandspecifyingtheserverIPv4address orIPv6address.


esxcli <conn_options> network ip dns server add --server=<str>

Changethesettingswithesxcli network ip dns.

SpecifytheDNSserverusingthe--dnsoptionandtheDNShost.
esxcli <conn_options> network ip dns server add --server=<server>

RunthecommandmultipletimestospecifymultipleDNShosts.

ConfiguretheDNShostnamefortheserverspecifiedby--server(or--vihost).
esxcli <conn_options> system hostname set --host=<new_host_name>

ConfiguretheDNSdomainnamefortheserverspecifiedby--server(or--vihost).
esxcli <conn_options> system hostname --domain=mydomain.biz

ToturnonDHCP,enableDHCPandsettheVMkernelNIC.

TurnonDHCPforIPv4

esxcli <conn_options> network ip interface ipv4 set --type dhcp/none/static esxcli <conn_options> network ip interface ipv4 set --peer-dns=<str>

TurnonDHCPforIPv6

esxcli <conn_options> network ip interface ipv6 set --enable-dhcpv6=true/false esxcli <conn_options> network ip interface ipv6 set --peer-dns=<str>

To modify DNS setup for a preconfigured server 1 DisplayDNSpropertiesforthespecifiedserverasfollows:

Listthehostanddomainname.
esxcli <conn_options> system hostname get

ListavailableDNSservers
esxcli <conn_options> network ip dns server list

ListtheDHCPsettingsforindividualVMkernelNICs.
esxcli <conn_options> network ip interface ipv4 get esxcli <conn_options> network ip interface ipv6 get

VMware, Inc.

127

vSphere Command-Line Interface Concepts and Examples

IftheDNSpropertiesareset,andyouwanttochangetheDHCPsettings,youmustspecifythevirtual networkadaptertousewhenoverridingthesystemDNS.OverridetheexistingDHCPsettingasfollows:
esxcli <conn_options> network ip interface ipv4 set --type dhcp/none/static esxcli <conn_options> network ip interface ipv6 set --enable-dhcpv6=true/false

Setting the DNS Configuration with vicfg-dns


Thevicfg-dnscommandlistsandspecifiestheDNSconfigurationofyourESXihost.Callthecommand withoutcommandspecificoptionstolisttheexistingDNSconfiguration.Youcanalsouseesxcli network ip dnsforDNSmanagement. IMPORTANTIfyoutrytochangethehostordomainnameortheDNSserveronhoststhatuseDHCP,anerror results. InnetworkenvironmentswhereaDHCPserverandaDNSserverareavailable,ESXihostsareautomatically assignedDNSnames. InnetworkenvironmentswhereautomaticDNSisnotavailableornotdesirable,youcanconfigurestaticDNS information,includingahostname,primarynameserver,secondarynameserver,andDNSsuffixes. ThefollowingexampleillustratessettingupaDNSserver.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To set up DNS 1 Runvicfg-dnswithoutcommandspecificoptionstodisplayDNSpropertiesforthespecifiedserver.
vicfg-dns <conn_options>

IfDNSisnotsetupforthetargetserver,thecommandreturnsanerror. 2 Tochangethesettings,usevicfg-dnswith--dns,--domain,or--hostname.

SpecifytheDNSserverbyusingthe--dnsoptionandacommaseparatedlistofhosts,inorderof preference.
vicfg-dns <conn_options --dns <dns1,dns2>

ConfiguretheDNShostnamefortheserverspecifiedby--server(or--vihost).
vicfg-dns <conn_options> -n dns_host_name

ConfiguretheDNSdomainnamefortheserverspecifiedby--server(or--vihost).
vicfg-dns <conn_options> -d mydomain.biz

ToturnonDHCP,usethe--DHCPoption.
vicfg-dns <conn_options> --dhcp yes

To modify DNS setup for a preconfigured server 1 Runvicfg-dnswithoutcommandspecificoptionstodisplayDNSpropertiesforthespecifiedserver.


vicfg-dns <conn_options>

Theinformationincludesthehostname,domainname,DHCPsetting(trueorfalse),andDNSserverson theESXihost. 2 IftheDNSpropertiesareset,andyouwanttochangetheDHCPsettings,youmustspecifythevirtual networkadaptertousewhenoverridingthesystemDNS.v_nicmustbeoneoftheVMkernelnetwork adapters. OverridetheexistingDHCPsettingasfollows:


vicfg-dns <conn_options> --dhcp yes --v_nic <vnic>

128

VMware, Inc.

Chapter 9 Managing vSphere Networking

Adding and Starting an NTP Server


Someprotocols,suchasKerberos,musthaveaccurateinformationaboutthecurrenttime.Inthosecases,you canaddanNTP(NetworkTimeProtocol)servertoyourESXihost. IMPORTANTNoESXCLIcommandexistsforaddingandstartinganNTPserver. ThefollowingexampleillustratessettingupanNTPserver.SpecifyoneoftheoptionslistedinConnection Optionsonpage 17inplaceof<conn_options>. To manage an NTP Server 1 Runvicfg-ntp--add toaddanNTPservertothehostspecifiedin<conn_options>anduseahostname orIPaddresstospecifyanalreadyrunningNTPserver.
vicfg-ntp <conn_options> -a 192.XXX.XXX.XX

Runvicfg-ntp --starttostarttheservice.
vicfg-ntp <conn_options> --start

Runvicfg-ntp --listtolisttheservice.
vicfg-ntp <conn_options> --list

Runvicfg-ntp --stoptostoptheservice.
vicfg-ntp <conn_options> --stop

Runvicfg-ntp --deletetoremovethespecifiedNTPserverfromthehostspecifiedin<conn_options>.
vicfg-ntp <conn_options> --delete 192.XXX.XXX.XX

Managing the IP Gateway


IfyoumoveyourESXihosttoanewphysicallocation,youmighthavetochangethedefaultIPgateway.You canusethevicfg-routecommandtomanagethedefaultgatewayfortheVMkernelIPstack.vicfg-route supportsasubsetoftheLinuxroutecommandsoptions. IMPORTANTNoESXCLIcommandexiststomanagethedefaultgateway. Ifyourunvicfg-routewithnooptions,thecommanddisplaysthedefaultgateway.Use--familytoprint thedefaultIPv4orthedefaultIPv6gateway.Bydefault,thecommanddisplaysthedefaultIPv4gateway. SpecifyoneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. To add, view, and delete a route entry 1 AddarouteentrytotheVMkernelandmakeitthedefault.

ForIPv4networks,noadditionaloptionsarerequired.
vicfg-route <conn_options> --add <network_ip> <netmask_IP> <gateway_ip>

Forexample,toaddarouteto192.XXX.100.0through192.XXX.0.1:
vicfg-route <conn_options> -a 192.XXX.100.0/24 192.XXX.0.1

or
vicfg-route <conn_options> -a 192.XXX.100.0 255.255.255.0 192.XXX.0.1

ForIPv6networks,use--family v6
vicfg-route <conn_options> -f V6 --add <network_ip_and_mask> <gateway_ip>

Forexample:
vicfg-route <conn_options> -f V6 --add 2001:10:20:253::/64 2001:10:20:253::1

Listrouteentriestocheckthatyourroutewasaddedbyrunningthecommandwithoutoptions.

VMware, Inc.

129

vSphere Command-Line Interface Concepts and Examples

vicfg-route <conn_options>

Theoutputlistsallnetworksandcorrespondingnetmasksandgateways. 3 Setthedefaultgateway.

ForIPv4,usethissyntax:
vicfg-route <conn_options> 192.XXX.0.1 or vicfg-route <conn_options> -a default 192.XXX.0.1

ForIPv6,usethissyntax:
vicfg-route <conn_options> -f V6 -a default 2001:10:20:253::1

Runvicfg-route --deletetodeletetheroute.Specifyfirstthegateway,andthenthenetwork.
vicfg-route <conn_options> -d 192.XXX.100.0/24 192.XXX.0.1

Setting Up IPsec
YoucansetInternetProtocolSecuritywithesxcli network ip ipseccommandsorwiththevicfg-ipsec command.whichsecuresIPcommunicationscomingfromandarrivingatESXihosts.Administratorswho performIPsecsetupmusthaveasolidunderstandingofbothIPv6and IPsec. ESXihostssupportIPseconlyforIPv6traffic,butnotforIPv4traffic. IMPORTANTInESX/ESXi4.1,ESXi5.0,andESXi5.1,IPv6isbydefaultdisabled.YoucanturnonIPv6by runningoneofthefollowingvCLIcommands:
esxcli <conn_options> network ip interface ipv6 set --enable-dhcpv6 esxcli <conn_options> network ip interface ipv6 address add vicfg-vmknic <conn_options> --enable-ipv6

Youcannotrunvicfg-ipsecwithavCenterServersystemasthetarget(usingthe--vihostoption). Youcanrunesxcli network ip ipseccommandswithavCenterServersystemasatarget(usingthe --vihostoption). TheVMwareimplementationofIPsecadherestothefollowingIPv6RFCs:


4301SecurityArchitecturefortheInternetProtocol 4303IPEncapsulatingSecurityPayload(ESP) 4835CryptographicAlgorithmImplementationRequirementsforESP 2410TheNULLEncryptionAlgorithmandItsUseWithIPsec 2451TheESPCBCModeCipherAlgorithms 3602TheAESCBCCipherAlgorithmandItsUsewithIPsec 2404TheUseofHMACSHA196withinESPandAH 4868UsingHMACSHA256,HMACSHA384,andHMACSHA512

Using IPsec with ESXi


WhenyousetupIPseconanESXihost,youenableprotectionofincomingoroutgoingdata.Whathappens preciselydependsonhowyousetupthesystemsSecurityAssociations(SAs)andSecurityPolicies (SPs).

AnSAdetermineshowthesystemprotectstraffic.WhenyoucreateanSA,youspecifythesourceand destination,authentication,andencryptionparameters,andanidentifierfortheSAwiththefollowing options.


vicfg-ipsec sa-srcandsa-dst spi(securityparameterindex) esxcli network ip ipsec --sasourceand--sadestination --saspi

130

VMware, Inc.

Chapter 9 Managing vSphere Networking

vicfg-ipsec sa-mode(tunnelortransport) ealgoandekey ialgoandikey

esxcli network ip ipsec --samode -encryptionalgorithmand--encryptionkey --integrityalgorithmand--integritykey

AnSPidentifiesandselectstrafficthatmustbeprotected.AnSPconsistsoftwologicalsections,aselector, andanaction. Theselectorisspecifiedbythefollowingoptions.


vicfg-ipsec src-addrandsrc-port dst-addranddst-port ulproto direction(inorout) esxcli network ip ipsec --sasourceand--sourceport --destinationport --upperlayerprotocol --flowdirection

Theactionisspecifiedbythefollowingoptions
vicfg-ipsec sa-name sp-name action (none, discard, ipsec esxcli network ip ipsec --saname --spname --action

BecauseIPsecallowsyoutotargetpreciselywhichtrafficshouldbeencrypted,itiswellsuitedforsecuring yourvSphereenvironment.Forexample,youcansetuptheenvironmentsoallvMotiontrafficisencrypted.

Managing Security Associations


YoucanspecifyanSAandrequestthattheVMkernelusethatSA.ThefollowingoptionsforSAsetupare supported.
vicfg-ipsec Option sa-src <source_IP> sa-dst <destination_IP> spi esxcli Option sasource <source_IP> sadestination <destination_IP> saspi Description SourceIPfortheSA. DestinationIPfortheSA. SecurityParameterIndex(SPI)fortheSA.Mustbeahexadecimal numberwitha0xprefix. WhenIPsecisinuse,ESXiusestheESPprotocol(RFC43030), whichincludesauthenticationandencryptioninformationand theSPI.TheSPIidentifiestheSAtouseatthereceivinghost.Each SAyoucreatemusthaveauniquecombinationofsource, destination,protocol,andSPI. sa-mode [tunnel | transport] samode [tunnel | transport] Eithertunnelortransport. Intunnelmode,theoriginalpacketisencapsulatedinanother IPv6packet,wheresourceanddestinationaddressesaretheSA endpointaddresses. Encryptionalgorithmtobeused.Choose3des-cbcor aes128-cbc,ornullfornoencryption. Encryptionkeytobeusedbytheencryptionalgorithm.Aseries ofhexadecimaldigitswitha0xprefixoranASCIIstring.

ealgo [null | 3des-cbc | aes128-cbc] ekey <key>

encryptionalgorithm [null | 3des-cbc | aes128-cbc] encryptionkey <key>

VMware, Inc.

131

vSphere Command-Line Interface Concepts and Examples

vicfg-ipsec Option ialgo [hmac-sha1 | hmac-sha2-256 ] ikey

esxcli Option integrityalgorithm [hmac-sha1 | hmac-sha2-256 ] integritykey

Description Authenticationalgorithmtobeused.Choosehmac-sha1or hmac-sha2-256. Authenticationkeytobeused.Aseriesofhexadecimaldigitsor anASCIIstring.

YoucanperformthesemaintaskswithSAs:

CreateanSA.Youspecifythesource,thedestination,andtheauthenticationmode.Youalsospecifythe authenticationalgorithmandauthenticationkeytouse.Youmustspecifyanencryptionalgorithmand key,butyoucanspecifynullifyouwantnoencryption.Authenticationisrequiredandcannotbenull. Thefollowingexampleincludesextralinebreaksforreadability.Thelastoption(sa_2intheexample)is thenameoftheSA.


esxcli network ip ipsec sa add --sasource 2001:DB8:1::121 --sadestination 2001:DB8:1::122 --samode transport --saspi 0x1000 --encryptionalgorithm 3des-cbc --encryptionkey 0x6970763672656164796c6f676f336465736362636f757432 --integrityalgorithm hmac-sha1 --integritykey 0x6970763672656164796c6f67736861316f757432 --saname sa_2

ListanSAwithesxcli network ip ipsec sa list.ThiscommandreturnsSAscurrentlyavailable forusebyanSP.ThelistincludesSAsyoucreated. RemoveasingleSAwithesxcli network ip ipsec sa remove.IftheSAisinusewhenyourunthis command,thecommandcannotperformtheremoval. RemoveallSAswithesxcli network ip ipsec sa remove--removeall.ThisoptionremovesallSAs evenwhentheyareinuse. CAUTIONRunningesxcli network ip ipsec sa remove--removeallremovesallSAsonyour systemandmightleaveyoursysteminaninconsistentstate.

Managing Security Policies


AfteryouhavecreatedoneormoreSAs,youcanaddsecuritypolicies(SPs)toyourESXihosts.WhiletheSA specifiestheauthenticationandencryptionparameterstouse,theSPidentifiesandselectstraffic. ThefollowingoptionsforSPmanagementaresupported.
vicfg-ipsec Option sp-src <ip>/<p_len> sp-dst <ip>/<p_len> src-port <port> dst-port <port> esxcli Option spsource <ip>/<p_len> spdestination <ip>/<p_len> sourceport <port> destinationport <port> upperlayerprotocol [any | tcp | udp | icmp6] flowdirection [in | out] Description SourceIPaddressandprefixlength. DestinationIPaddressandprefixlength. Sourceport(065535).Specifyanyforanyports. Destinationport(065535).Specifyanyforanyports.Ifulprotois icmp6,thisnumberreferstotheicmp6type.Otherwise,this numberreferstotheport. Upperlayerprotocol.UsethisoptiontorestricttheSPtoonly certainprotocols,oruseanytoapplytheSPtoallprotocols. Directioninwhichyouwanttomonitorthetraffic.Tomonitor trafficinbothdirections,createtwopolicies.

ulproto [any | tcp | udp | icmp6] dir [in | out]

132

VMware, Inc.

Chapter 9 Managing vSphere Networking

vicfg-ipsec Option action [none | discard | ipsec]

esxcli Option action [none | discard | ipsec]

Description Actiontotakewhentrafficwiththespecifiedparametersis encountered. noneTakenoaction,thatis,allowtrafficunmodified. discardDonotallowdatainorout. ipsecUsetheauthenticationandencryptioninformation specifiedintheSAtodeterminewhetherthedatacomefroma trustedsource.

sp-mode [tunnel | transport] sa-name

spmode [tunnel | transport] saname

Mode,eithertunnelortransport. NameoftheSAtousebythisSP.

YoucanperformthesemaintaskswithSPs:

CreateanSPwithesxcli network ip ipsec add.Youidentifythedatatomonitorbyspecifyingthe selectorssourceanddestinationIPaddressandprefix,sourceportanddestinationport,upperlayer protocol,directionoftraffic,actiontotake,andSPmode.ThelasttwooptionarethenameoftheSAto useandthenameoftheSPthatisbeingcreated.Thefollowingexampleincludesextralinebreaksfor readability.


esxcli network ip ipsec add --spsource=2001:0DB8:0001:/48 --spdestination=2001:0DB8:0002:/48 --sourceport=23 --destinationport=25 --upperlayerprotocol=tcp --flowdirection=out --action=ipsec --spmode=transport --spname sp_2

ListanSPwithesxcli network ip ipsec list.ThiscommandreturnsSPscurrentlyavailable.All SPsarecreatedbytheadministrator. RemoveanSPwithesxcli network ip ipsecremove.IftheSPisinusewhenyourunthiscommand, thecommandcannotperformtheremoval.Youcanrunesxcli network ip ipsecremove --removeallinsteadtoremovetheSPevenwhenitisinuse. CAUTIONRunningesxcli network ip ipsecremove --removeallremovesallSPsonyoursystem andmightleaveyoursysteminaninconsistentstate.

Managing the ESXi Firewall


Tominimizetheriskofanattackthroughthemanagementinterface,ESXiincludesafirewallbetweenthe managementinterfaceandthenetwork.Toensuretheintegrityofthehost,onlyasmallnumberoffirewall portsareopenbydefault.ThevSphereSecuritydocumentationexplainshowtosetupfirewallsforyour environmentandwhichportsyoumighthavetotemporarilyenableforcertaintraffic. Youmanagefirewallsbysettingupfirewallrulesets.vSphereSecuritydocumentationexplainshowtoperform thesetaskswiththevSphereWebClient.Youcanalsouseesxcli network firewalltomanagefirewall rulesetsandtoretrieveinformationaboutthem.SpecifyoneoftheoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. To limit shell access 1 CheckfirewallstatusandsshServerrulesetstatus.
esxcli <conn_options> network firewall get Default Action: DROP Enabled: true Loaded: true esxcli <conn_options> network firewall ruleset list --ruleset-id sshServer
VMware, Inc. 133

vSphere Command-Line Interface Concepts and Examples

Name --------sshServer

Enabled ------true

EnablethesshServerrulesetifitisdisabled.
esxcli <conn_options> network firewall ruleset set --ruleset-id sshServer --enabled true

ObtainaccesstotheESXiShellandcheckthestatusoftheallowedAllflag.
esxcli <conn_options> network firewall ruleset allowedip list --ruleset-id sshServer Ruleset Allowed IP Addresses --------- -------------------sshServer All

SeeGettingStartedwithvSphereCommandLineInterfacesforinformationonaccessingtheESXiShell. 4 SetthestatusoftheallowedAllflagtofalse.
esxcli <conn_options> network firewall ruleset set --ruleset-id sshServer --allowed-all false

AddthelistofallowedIPaddresses.
esxcli <conn_options> network firewall ruleset allowedip add --ruleset-id sshServer --ip-address 192.XXX.1.0/24 esxcli <conn_options> network firewall ruleset allowedip add --ruleset-id sshServer --ip-address 192.XXX.10.10

ChecktheallowedIPaddresslist.
esxcli <conn_options> network firewall ruleset allowedip list --ruleset-id sshServer Ruleset Allowed IP Addresses --------- ----------------------------sshServer 192.XXX.10.10, 192.XXX.1.0/24

134

VMware, Inc.

10

Monitoring ESXi Hosts

10

StartingwiththevSphere4.0release,thevCenterServermakesperformancechartsforCPU,memory,diskI/O, networking,andstorageavailable.YoucanviewtheseperformancechartsbyusingthevSphereWebClient andreadabouttheminthevSphereMonitoringdocumentation.Youcanalsoperformsomemonitoringofyour ESXisystemusingvCLIcommands. Thischapterincludesthesetopics:


UsingresxtopforPerformanceMonitoringonpage 135 ManagingDiagnosticPartitionsonpage 135 ManagingCoreDumpsonpage 136 ConfiguringESXiSyslogServicesonpage 138 ManagingESXiSNMPAgentsonpage 139 RetrievingHardwareInformationonpage 141 ESX,ESXi,andVirtualMachineLogsonpage 142

Using resxtop for Performance Monitoring


TheresxtopvCLIcommandallowsyoutoexaminehowESXisystemsuseresources.Youcanusethe commandininteractivemode(default)orinbatchmode.TheResourceManagementdocumentationexplains howtouseresxtopandprovidesinformationaboutavailablecommandsanddisplaystatistics. IfyoucannotreachthehostwiththeresxtopvCLIcommand,youmightbeabletousetheesxtopcommand intheESXiShellinstead.SeeGettingStartedwithvSphereCommandLineInterfacesforinformationonaccessing theshell. IMPORTANTresxtopandesxtoparesupportedonlyonLinux.

Managing Diagnostic Partitions


Yourhostmusthaveadiagnosticpartition(dumppartition)tostorecoredumpsfordebuggingandforuseby VMwaretechnicalsupport. AdiagnosticpartitioncanbeonthelocaldiskwheretheESXisoftwareisinstalled.Thisisthedefault configurationforESXiInstallable.Youcanalsouseadiagnosticpartitiononaremotedisksharedbetween multiplehosts.Ifyouwanttouseanetworkdiagnosticpartition,youcaninstallESXiDumpCollectorand configurethenetworkedpartition.SeeManagingCoreDumpswithESXiDumpCollectoronpage 137. Thefollowingconsiderationsapply:

AdiagnosticpartitioncannotbelocatedonaniSCSILUNaccessedthroughthesoftwareiSCSIor dependenthardwareiSCSIadapter.FormoreinformationaboutdiagnosticpartitionswithiSCSI,see GeneralBootfromiSCSISANRecommendationsinthevSphereStoragedocumentation.


135

VMware, Inc.

vSphere Command-Line Interface Concepts and Examples

Astandalonehostmusthaveadiagnosticpartitionof110MB. IfmultiplehostsshareadiagnosticpartitiononaSANLUN,configurealargediagnosticpartitionthat thehostsshare. Ifahostthatusesashareddiagnosticpartitionfails,rebootthehostandextractlogfilesimmediatelyafter thefailure.Otherwise,thesecondhostthatfailsbeforeyoucollectthediagnosticdataofthefirsthost mightnotbeabletosavethecoredump.

Diagnostic Partition Creation


YoucanusethevSphereWebClienttocreatethediagnosticpartitiononalocaldiskoronaprivateorshared SANLUN.Youcannotusevicfg-dumpparttocreatethediagnosticpartition.TheSANLUNcanbesetup withFibreChannelorhardwareiSCSI.SANLUNsaccessedthroughasoftwareiSCSIinitiatorarenot supported. CAUTIONIftwohoststhatshareadiagnosticpartitionfailandsavecoredumpstothesameslot,thecore dumpsmightbelost. Ifahostthatusesashareddiagnosticpartitionfails,rebootthehostandextractlogfilesimmediatelyafterthe failure.

Diagnostic Partition Management


Youcanusethevicfg-dumppartortheesxcli system coredumpcommandtoquery,set,andscananESXi systemsdiagnosticpartitions.ThevSphereStoragedocumentationexplainshowtosetupdiagnosticpartitions withthevSphereWebClientandhowtomanagediagnosticpartitionsonaFibreChannelorhardwareiSCSI SAN. Diagnosticpartitionscaninclude,inorderofsuitability,paralleladapter,blockadapter,FC,orhardwareiSCSI partitions.ParalleladapterpartitionsaremostsuitableandhardwareiSCSIpartitionstheleastsuitable. IMPORTANTWhenyoulistdiagnosticpartitions,softwareiSCSIpartitionsareincluded.However,SANLUNs accessedthroughasoftwareiSCSIinitiatorarenotsupportedasdiagnosticpartitions.

Managing Core Dumps


Withesxcli system coredump,youcanmanagelocaldiagnosticpartitionsorsetupcoredumponaremote serverinconjunctionwithESXiDumpCollector.ForinformationaboutESXiDumpCollector,seethevSphere Networkingdocumentation.

Managing Local Core Dumps with ESXCLI


ThefollowingexamplescenariochangesthelocaldiagnosticpartitionwithESXCLI.Specifyoneofthe connectionoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. To manage a local diagnostic partition 1 ShowthediagnosticpartitiontheVMkernelusesanddisplayinformationaboutallpartitionsthatcanbe usedasdiagnosticpartitions.
esxcli <conn_options> system coredump partition list

Deactivatethecurrentdiagnosticpartition.
esxcli <conn_options> system coredump partition set --unconfigure

TheESXisystemisnowwithoutadiagnosticpartition,andyoumustimmediatelysetanewone. 3 Settheactivepartitiontonaa.<naa_ID>.
esxcli <conn_options> system coredump partition set --partition=naa.<naa_ID>

Listpartitionsagaintoverifythatadiagnosticpartitionisset.

136

VMware, Inc.

Chapter 10 Monitoring ESXi Hosts

esxcli <conn_options> system coredump partition list

Ifadiagnosticpartitionisset,thecommanddisplaysinformationaboutit.Otherwise,thecommand showsthatnopartitionisactivatedandconfigured.

Managing Core Dumps with ESXi Dump Collector


Bydefault,acoredumpissavedtothelocaldisk.YoucanuseESXiDumpCollectortokeepcoredumpsona networkserverforuseduringdebugging.ESXiDumpCollectorisespeciallyusefulforAutoDeploy,but supportedforanyESXi5.0host.ESXiDumpCollectorsupportsothercustomization,includingsendingcore dumpstothelocaldisk. ESXiDumpCollectorisincludedwiththevCenterServerautorun.exeapplication.YoucaninstallESXi DumpCollectoronthesamesystemasthevCenterServerserviceoronadifferentWindowsorLinux machine.SeevSphereNetworking. YoucanconfigureESXihoststouseESXiDumpCollectorbyusingtheHostProfilesinterfaceofthevSphere WebClient,orbyusingESXCLI.SpecifyoneoftheconnectionoptionslistedinConnectionOptionson page 17inplaceof<conn_options>. To manage core dumps with ESXi Dump Collector 1 SetupanESXisystemtouseESXiDumpCollectorbyrunningesxcli system coredump.
esxcli <conn_options> system coredump network set --interface-name vmk0 --server-ipv4=1-XX.XXX --port=6500

YoumustspecifyaVMkernelportwith--interface-name,andtheIPaddressandportoftheserverto sendthecoredumpsto.IfyouconfigureanESXisystemthatisrunninginsideavirtualmachine,you mustchooseaVMkernelportthatisinpromiscuousmode. 2 EnableESXiDumpCollector.


esxcli <conn_options> system coredump network set --enable=true

(Optional)CheckthatESXiDumpCollectorisconfiguredcorrectly.
esxcli <conn_options> system coredump network get

ThehostonwhichyouhavesetupESXiDumpCollectorsendscoredumpstothespecifiedserverbyusing thespecifiedVMkernelNICandoptionalport.

Managing Core Dumps with vicfg-dumppart


Thefollowingexamplescenariochangesthediagnosticpartition.Specifyoneoftheconnectionoptionslisted inConnectionOptionsonpage 17inplaceof<conn_options>. To manage a diagnostic partition 1 ShowthediagnosticpartitiontheVMkerneluses.
vicfg-dumppart <conn_options> -t

Displayinformationaboutallpartitionsthatcanbeusedasdiagnosticpartitions.Use-ltolistall diagnosticpartitions,-ftolistalldiagnosticpartitionsinorderofpriority.
vicfg-dumppart <conn_options> -f

Theoutputmightappearasfollows.
Partition name on vml.mpx.vmhba36:C0:T0:L0:7 -> mpx.vmhba36:C0:T0:L0:7

Deactivatethediagnosticpartition.
vicfg-dumppart <conn_options> -d

TheESXisystemisnowwithoutadiagnosticpartition,andyoumustimmediatelysetanewone. 4 Settheactivepartitiontonaa.<naa_ID>.
vicfg-dumppart <conn_options> -s naa.<naa_ID>

VMware, Inc.

137

vSphere Command-Line Interface Concepts and Examples

Runvicfg-dumppart -tagaintoverifythatadiagnosticpartitionisset.
vicfg-dumppart <conn_options> -t

Ifadiagnosticpartitionisset,thecommanddisplaysinformationaboutit.Otherwise,thecommand informsyouthatnopartitionisset.

Configuring ESXi Syslog Services


AllESXihostsrunaSyslogservice,whichlogsmessagesfromtheVMkernelandothersystemcomponentsto localfilesortoaremotehost.YoucanusethevSphereWebClient,orusetheesxcli system syslog commandtoconfigurethefollowingparametersofthesyslogservice.

Remotehostandport.RemotehosttowhichSyslogmessagesareforwardedandportonwhichthe remotehostreceivesSyslogmessages.Theremotehostmusthavealoglistenerserviceinstalledand correctlyconfiguredtoreceivetheforwardedsyslogmessages.Seethedocumentationforthesyslog serviceinstalledontheremotehostforinformationonconfiguration. Transportprotocol.LogscanbesentbyusingUDP(default),TCPorSSLtransports. Localloggingdirectory.Directorywherelocalcopiesofthelogsarestored.Thedirectorycanbelocated onmountedNFSorVMFSvolumes.Onlythe/scratchdirectoryonthelocalfilesystemispersistent acrossreboots. Uniquedirectorynameprefix.SettingthisoptiontotruecreatesasubdirectorywiththenameofESXi hostunderthespecifiedloggingdirectory.ThismethodisespeciallyusefulifthesameNFSdirectoryis usedbymultipleESXihosts. Logrotationpolicies.Setsmaximumlogsizeandthenumberofarchivestokeep.Policiescanbespecified bothglobally,andforindividualsubloggers.Forexample,youcansetalargersizelimitforthevmkernel log.

IMPORTANTTheesxcli system syslogcommandistheonlysupportedcommandforchangingESXi5.0 loggingconfiguration.Thevicfg-syslogcommandandeditingconfigurationfilesisnotsupportedforESXi 5.0andcanresultinerrors. Aftermakingconfigurationchanges,restartthesyslogservice(vmsyslogd)byrunningesxcli system syslog reload. Theesxcli system syslogcommandallowsyoutoconfiguretheloggingbehaviorofyourESXisystem. WithvSphere5.0,youcanmanagethetoplevelloggerandsubloggers.Thecommandhasthefollowing options.
Option mark reload config get config set Description Marksalllogswiththespecifiedstring. Reloadstheconfiguration,andupdatesanychangedconfigurationvalues. Retrievesthecurrentconfiguration. Setstheconfiguration.Useoneofthefollowingoptions.

--logdir=<path>Savelogstoagivenpath. --loghost=<host>Sendlogstoagivenhost.SeeesxclisystemsyslogExampleson page 139. --logdir-unique=<true|false>Specifywhetherthelogshouldgotoaunique subdirectoryofthedirectoryspecifiedinlogdir. --default-rotate=<int>Defaultnumberoflogrotationstokeep. --default-size=<int>Sizebeforerotatinglogs,inKB.

138

VMware, Inc.

Chapter 10 Monitoring ESXi Hosts

Option config logger list config logger set

Description Showcurrentlyconfiguredsubloggers. Setconfigurationoptionsforaspecificsublogger.Useoneofthefollowingoptions.


--id=<str>IDoftheloggertoconfigure(required). --reset=<str>Resetvaluestodefault. --rotate=<long>Numberofrotatedlogstokeepforaspecificlogger(requires--id). --size=<long>Sizeoflogsbeforerotationforaspecificlogger,inKB(requires--id).

esxcli system syslog Examples Thefollowingworkflowillustrateshowyoumightuseesxcli system syslogforlogconfiguration.Specify oneoftheoptionslistedinConnectionOptionsonpage 17inplaceof<conn_options>. 1 Showconfigurationoptions.
esxcli <conn_options> system syslog config get Default Rotation Size: 1024 Default Rotations: 8 Log Output: /scratch/log Logto Unique Subdirectory: false Remote Host: <none>

Setalllogstokeeptwentyrotationsbeforeoverwritingtheoldestlog.
esxcli <conn_options> system syslog config set --default-rotate=20

SettherotationpolicyforVMkernellogsto10rotations,rotatingat2MB.
esxcli <conn_options> system syslog config logger --id=vmkernel --size=2048 --rotate=10

Sendlogstoremotehostmyhost.mycompany.com.Thelogswillusethedefaulttransport(UDP)andport (514).
esxcli system syslog config set --loghost='myhost.mycompany.com'

Savethelocalcopyoflogsto/scratch/mylogsandsendanothercopytotheremotehost.
esxcli <conn_options> system syslog config set --loghost='tcp://myhost.mycompany.com:1514' --logdir='/scratch/mylogs'

Yousetthedirectoryontheremotehostbyconfiguringtheclientrunningonthathost.Youcanusethe vSphereWebClienttoredirectsystemlogstoaremotehostbychangingtheSystem.global.logHost advancedsetting. 6 Sendalogmessagetoalllogssimultaneously.


esxcli <conn_options> system syslog mark --message="this is a message!"

Reloadthesyslogdaemonandapplyconfigurationchanges.
esxcli <conn_options> system syslog reload

Managing ESXi SNMP Agents


SimpleNetworkManagementProtocol(SNMP)allowsmanagementprogramstomonitorandcontrol networkeddevices.YoucanmanagevSphere5.0SNMPagentswithvicfg-snmpcommandsdiscussedhere. IMPORTANTSignificantenhancementstoSNMP,includingsupportforSNMPv3,areincludedinESXi5.1.The newfunctionalityismanagedthroughESXCLIcommands.SeethevSphereMonitoringandPerformance documentationthatisavailableinthevSphere5.1DocumentationCenter. vCenterServerandESXisystemsincludedifferentSNMPagents.

VMware, Inc.

139

vSphere Command-Line Interface Concepts and Examples

vCenterServerSNMPagent.TheSNMPagentincludedwithvCenterServercansendtrapswhenthe vCenterServersystemisstartedorwhenanalarmistriggeredonvCenterServer.ThevCenterServer SNMPagentfunctionsonlyasatrapemitteranddoesnotsupportotherSNMPoperations(forexample, GET). YoucanmanagethevCenterServeragentwiththevSphereWebClientbutnotwiththevCLIcommand.

HostbasedembeddedSNMPagent.ESXi4.0andlaterincludesanSNMPagentembeddedinthehost daemon(hostd)thatcansendtrapsandreceivepollingrequestssuchasGETrequests. YoucanmanageSNMPonESXihostswiththevicfg-snmpvCLIcommand,butnotwiththevSphere ClientorwiththeESXCLIcommand.

NetSNMPbasedagent.VersionsofESXreleasedbeforeESX/ESXi4.0includeaNetSNMPbasedagent. YoucancontinuetousethisNetSNMPbasedagentinESX4.xwithMIBssuppliedbyyourhardware vendorandotherthirdpartymanagementapplications.However,tousetheVMwareMIBfiles,youmust usethehostbasedembeddedSNMPagent.

TousetheNETSNMPbasedagentandhostbasedembeddedSNMPagentatthesametime,makeoneofthe agentslistenonanondefaultport.Bydefault,bothagentsusethesameport. ThehostbasedembeddedSNMPagentisdisabledbydefault.Configuringandenablingtheagentrequires thatyouperformthefollowingtasks: 1 2 ConfigureSNMPCommunities.SeeConfiguringSNMPCommunitiesonpage 140. ConfiguretheSNMPAgent.Youhavethefollowingchoices:


ConfiguringtheSNMPAgenttoSendTrapsonpage 140 ConfiguringtheSNMPAgentforPollingonpage 141

Configuring SNMP Communities


BeforeyouenabletheESXiembeddedSNMPagent,youmustconfigureatleastonecommunityfortheagent. AnSNMPcommunitydefinesagroupofdevicesandmanagementsystems.Onlydevicesandmanagement systemsthataremembersofthesamecommunitycanexchangeSNMPmessages.Adeviceormanagement systemcanbeamemberofmultiplecommunities. ToconfigureSNMPcommunities,runvicfg-snmp -c,specifyingacommaseparatedlistofcommunities.For example:
vicfg-snmp <conn_options> -c public, internal

Eachtimeyouspecifyacommunitywiththiscommand,thesettingsthatyouspecifyoverwritetheprevious configuration.

Configuring the SNMP Agent to Send Traps


YoucanusetheSNMPagentembeddedinESXitosendvirtualmachineandenvironmentaltrapsto managementsystems.Toconfiguretheagenttosendtraps,youmustspecifyatarget(receiver)address,the community,andanoptionalport.Ifyoudonotspecifyaport,theSNMPagentsendstrapstoUDPport162 onthetargetmanagementsystembydefault. To configure a trap destination 1 Makesureacommunityissetup.
vicfg-snmp <conn_options> --show Current SNMP agent settings: Enabled: 1 UDP port: 161 Communities: public Notification targets:

140

VMware, Inc.

Chapter 10 Monitoring ESXi Hosts

Runvicfg-snmp --targetwiththetargetaddress,portnumber,andcommunity. vicfg-snmp <conn_options> -t target.example.com@163/public Eachtimeyouspecifyatargetwiththiscommand,thesettingsyouspecifyoverwriteallpreviously specifiedsettings.Tospecifymultipletargets,separatethemwithacomma. YoucanchangetheportthattheSNMPagentsendsdatatoonthetargetusingthe--targetsoption. ThatportisUDP162bydefault.

(Optional)EnabletheSNMPagentifitisnotyetrunning.
vicfg-snmp <conn_options> --enable

(Optional)Sendatesttraptoverifythattheagentisconfiguredcorrectly.
vicfg-snmp <conn_options> --test

TheagentsendsawarmStarttraptotheconfiguredtarget.

Configuring the SNMP Agent for Polling


IfyouconfiguretheESXiembeddedSNMPagentforpolling,itcanlistenforandrespondtorequestssuchas GETrequestsfromSNMPmanagementclientsystems. Bydefault,theembeddedSNMPagentlistensonUDPport161forpollingrequestsfrommanagement systems.Youcanusethevicfg-snmpcommandtoconfigureanalternativeport.Toavoidconflictswithother services,useaUDPportthatisnotdefinedin/etc/services. IMPORTANTBoththeembeddedSNMPagentandtheNetSNMPbasedagentavailableintheESX4.xservice consolelistenonUDPport161bydefault.IfyouareusinganESX4.xsystem,changetheportforoneagent toenablebothagentsforpolling. To configure the SNMP agent for polling 1 Runvicfg-snmp --targetwiththetargetaddress,portnumber,andcommunity. vicfg-snmp <conn_options> -c public -t target.example.com@163/public Eachtimeyouspecifyatargetwiththiscommand,thesettingsyouspecifyoverwriteallpreviously specifiedsettings.Tospecifymultipletargets,separatethemwithacomma. YoucanchangetheportthattheSNMPagentsendsdatatoonthetargetbyusingthe--targetsoption. ThatportisUDP162bydefault. 2 (Optional)Specifyaportforlisteningforpollingrequests.
vicfg-snmp <conn_options> -p <port>

(Optional)IftheSNMPagentisnotenabled,enableit.
vicfg-snmp <conn_options> --enable

Runvicfg-snmp --testtovalidatetheconfiguration.

Thefollowingexampleshowshowthecommandsareruninsequence.
vicfg-snmp <conn_options> c public t example.com@162/private --enable # next validate your config by doing these things: vicfg-snmp <conn_options> -test walk v1 c public esx-host

Retrieving Hardware Information


CommandsindifferentESXCLInamespacesmightdisplaysomehardwareinformation,buttheesxcli hardwarenamespaceisspecificallyintendedtogiveyouthatinformation.Thenamespaceincludes commandsforgettingandsettingCPUproperties,forlistingbootdevices,andforgettingandsettingthe hardwareclocktime.

VMware, Inc.

141

vSphere Command-Line Interface Concepts and Examples

YoucanalsousetheipminamespacetoretrieveIPMIsystemeventlogs(SEL)andsensordatarecords(SDR). Thecommandsupportsbothget(singlereturnvalue)andlist(multiplereturnvalues)commandsandreturns rawsensorinformation.


esxcli hardware ipmi sel get esxcli hardware ipmi sdr get

ESX, ESXi, and Virtual Machine Logs


Logscanhelpyoufindoutwhathappenedifcommandsdonothavethedesiredresults.OnESXi5.0systems, findalllogsinthe/var/logdirectory.Someoftheitemsinthatdirectoryaresymboliclinksfromthe /var/run/logdirectory. OnESXi4.1systems,youcanfindthefollowinglogs.
Component ESXServer3.xorESXservicelog vSphereclientagentlog Virtualmachinekernelcorefile Sysloglog Serviceconsoleavailabilityreport VMkernelmessages,alerts,and availabilityreport VMkernelwarning Virtualmachinelogfile Virtualmachineconfigurationfile Location /var/log/vmware/hostd.log /var/log/vmware/vpx/vpxa.log Afteryourebootyourmachine,files/root/vmkernel-log.<date>and /root/vmkernel-core.<date>arepresent. /var/log/messages /var/log/vmkernel /var/log/vmkernel /var/log/vmkwarning vmware.loginthesamedirectoryastheVMXfileforthevirtualmachine <virtual_machine_name>/<virtual_machine_name>.vmxlocatedona datastoreassociatedwiththemanagedhost.Usethevirtualmachinesummary pageinthevSphereWebClienttodeterminethedatastoreonwhichthisfileis located.

142

VMware, Inc.

Index

Numerics
3.5 LUN masks 95

A
Active Directory 25, 26 active path 47 ARP redirect 74 authentication algorithm (IPsec) 132 default inheritance 61 key (IPsec) 132 returning to default inheritance 61 AUTOCONF 125

local 136 managing 137 cp850 encoding 18 cp936 encoding 18 creating directories 35

D
datastores mounting 30 NFS 50 overview 41 default gateway 130 default inheritance 61, 78, 79 default port groups 116 dependent hardware iSCSI 57, 68, 73 device 41 device management 44, 86 device mappings 43, 44 device naming device UID 41 runtime name 41 VML name 41 Device UID 41 DHCP 127, 128 DHCPV6 125 diagnostic partitions creating 136 example 136, 137 managing 135 directory management 37 directory names with special characters 34 discovery sessions 58 discovery targets 59 disk file path 54 distributed switches 111, 112, 113, 115 DNS 126, 127, 128 downloading files 34 duplicate datastores 29 dynamic discovery 58

B
backing up configuration data 24

C
CDP 116, 117, 118 Challenge Handshake Authentication Protocol 60 changing IP gateway 129 CHAP 60 chapDiscouraged 60 chapPreferred 60 chapProhibited 60 chapRequired 60 Cisco Discovery Protocol 116 claim rules adding 93 converting 95 deleting 96 from 3.5 systems 95 from LUN mask 95 listing 96 loading 96 moving 97 rule IDs 95 running 97 commands with esxcfg prefix 12 configuration data backing up 24 restoring 24 configuration files, path 54 copying files 34 core dumps 136 ESXi Dump Collector 137

E
encoding cp936 18 Shift_JIS 18 encodings cp850 18

VMware, Inc.

143

vSphere Command-Line Interface Concepts and Examples

encryption algorithm (IPsec) 131 encryption key (IPsec) 131 ESX/ESXi logs 142 esxcfg prefix 12 esxcli network ip commands 123 esxcli network ip dns 127 esxcli network nic commands 120 esxcli network vswitch commands 116, 118, 122 esxcli storag nfs commands 51 esxcli storage core claiming commands 92 claimrule commands 93 claimrule convert commands 95 claimrule delete command 96 claimrule list command 96 claimrule load command 96 claimrule move command 97 claimrule run command 97 device list 42 esxcli storage core adapter rescan 55 esxcli storage core claiming reclaim command 92 unclaim command 92 esxcli storage core path 45, 47 esxcli storage nmp 85 device list command 86 device set command 86 fixed deviceconfig commands 88 path list command 86 psp commands 86, 87 psp roundrobin commands 88 roundrobin 50, 89 satp commands 89 esxcli system coredump 136 ESXi Dump Collector 135, 137 EUI name 45, 46, 59 examples backup with vMA 24 configure VMkernel NIC for IPv4 123 configure VMkernel NIC for IPv6 124 DNS setup 127 enable and set NetQueue modules 25 entering maintenance mode 22, 23 iSCSI storage setup 66, 68, 71, 73 managing users 101 route entry setup 129 svmotion 54 uplink adapter setup 120 external HBA properties 76

FC LUNs 41 Fibre Channel LUNs 41 file management introduction 27 vifs 28, 37 file path, configuration file 54 file systems NAS 51 VMFS 29 fixed path selection policy 88

G
gateway, IP 129 groups 99, 102

H
hard power operations 108 hardware iSCSI setup tasks 70, 74 HBA mappings 44 HBA properties 76 hosts managing 21 shutdown or reboot 21

I
ifconfig, ESXCLI equivalents 113 independent hardware iSCSI definition 57 setup tasks 70, 74 inheritance 79 IP gateway 129 IP storage 112 IPsec 130 IPv4 123, 124 IPv6 124, 125 IQN name 59 iSCSI authentication 61, 80, 81 default inheritance 78, 79 dependent hardware iSCSI 68, 73 discovery target names 59 independent hardware iSCSI 70, 74 LUNs 41 mutual authentication 80, 81 options 75 overview 57 parameters 77, 78 parameters, returning to default inheritance 78, 79 port binding 68, 73 ports for multipathing 81 remove sessions 83 securing ports 60

F
failover 44
144

VMware, Inc.

Index

security 59 sessions 82, 83 setup examples 66, 68, 71, 73

NMP 44, 85, 86 NTP server 129

O
offload iSCSI 57 orphaned virtual machine 104

K
Kerberos 129

L
license 53 listing available LUNs 42, 43 listing IP gateway 129 loading claim rules 96 lockdown mode 19 logical devices, listing 44 logs 142 LUN masks, convert to claim rule 95 LUNs listing available 42, 43 names 45, 46 overview 42

P
parameters default inheritance (iSCSI) 79 setting (iSCSI) 78 partitions, diagnostic 136 path change conditions for round robin 89 path claiming 92 path operations 86 path policies 47, 88, 89 path state, changing 47 paths active 47 changing state 47 disabling 47 identifier 41 listing 46 listing with ESXCLI 45 managing 44 preferred 49, 50, 88 performance monitoring 135 physical network interfaces 120 platform support 14 Pluggable Storage Architecture 44 port binding 68, 73, 82 port groups 112, 119, 120 adding 118 and uplink adapter 119 default 116 removing 118 ports, iSCSI multipathing 81 power operations 108 powerop_mode 108 preferred path 49, 50, 88 PSA 44 acronym 85 managing claim rules 93 PSP acronym 85 information 87 operations 86

M
MAC address, VMkernel NIC 123 MagicPacket 121 maintenance mode 22, 23 Managing 44, 57, 120 managing 136 managing local core dumps 136 managing NMP 85 managing paths 44 managing physical network interfaces 120 migrating virtual machines,svmotion 52 mount datastores 30 MTU 117, 118 multipathing 44, 45 mutual authentication 80, 81 mutual CHAP 67, 69, 72, 74, 80, 81

N
naa.xxx device name 45, 46 NAS datastores, datastores, NAS 50 NAS file systems 51 NetQueue VMkernel modules 25 network adapters duplex value 120 managing 120 speed 120 network interfaces 115, 120 networking vDS 126 vSS 115 NFS datastores 50 NFS, capabilities 51

R
raw devices 41 rebooting hosts 21 register virtual machines 105 removing snapshots 107
145

VMware, Inc.

vSphere Command-Line Interface Concepts and Examples

rescanning adapters 55 rescanning storage 41, 55 rescanning storage adapters 55 resignature VMFS copy 31 restoring configuration data 24 resxtop 12, 135 reverting snapshots 107 RFCs (vicfg-ipsec) 130 roles 99 round robin operations 50, 88 path change conditions 89 retrieve settings 89 route entry setup 129 rule IDs 95 rules 91 claim rules 93 SATP rules 91 runtime name 41

rescanning 41, 55 virtual machines 40 storage array target 42 storage device naming 41 supported platforms 14 svmotion 52 interactive Mode 53 license for storage vMotion 53 limitations 53 noninteractive mode 53 requirements 53 special characters 53 switch attributes 117, 118 syslog server specification 138

T
TCP Segmentation Offload 123 TCP/IP 70, 74, 112 transport mode 131 TSO 123 tunnel mode 131

S
SATP configuration parameters 91 deleting rules 91 retrieve settings 89 rules, adding 90 securing iSCSI ports 60 security associations (IPsec) 131 security policies (IPsec) 132 sessions, iSCSI 83 Shift_JIS encoding 18 Simple Network Management Protocol 139 snapshots 106, 107 SNMP communities 140 management 139 polling 141 traps 140 soft power operations 108 software iSCSI setup tasks 66, 68, 71, 73 spaces in directory names 34 special characters in directories 34 vicfg-iscsi 77, 79 standard networking services 126 starting NTP server 129 state of path, changing 47 static discovery 58 stopping virtual machines 109 storage creating directories with vifs 35 overview 39 path claiming 92
146

U
unregister virtual machines 105 uplink adapters 112, 120 and port groups 119 setup 122 useANO (round robin) 50 user input 109 users creating 101 in vSphere environment 99 modifying 101

V
VDS 111 vicfg-authconfig 25 vicfg-cfgbackup 23, 24 vicfg-dumppart 136, 137 vicfg-hostops 21, 22 vicfg-ipsec 131, 132 vicfg-iscsi command syntax 61 default inheritance for authentication 61 default inheritance for parameters 78, 79 iscsi parameter options 79 vicfg-module 24 vicfg-mpath 46 vicfg-nas 50, 51 vicfg-nics 122 vicfg-ntp 129 vicfg-rescan 55, 72, 73 vicfg-scsidevs
VMware, Inc.

Index

3.5 support 43 list options 43 vicfg-snmp 139 vicfg-syslog 138 vicfg-user 99, 100, 102 vicfg-vmhbadevs 42, 43 vicfg-vmknic 123 vicfg-volume 29 vicfg-vswitch 115, 118 vifs 28, 33 virtual devices 108 virtual machine configuration file path 54 virtual machines attributes 105 file management 27 listing 104, 105 logs 142 managing 105 migration with svmotion 52 network settings 113 orphaned 104 path 104 registering 104, 105 starting 107 stopping 109 storage VMotion 52 vmware-cmd 105 virtual switches 111, 115, 116 MTU 117, 118 retrieving information 116 vicfg-vswitch 115 VLAN ID 119, 120 VMFS duplicate datastores 29 resignature copy 30 resignaturing 31 VMFS3 to VMFS5 conversion 29 VMkernel modules 24 VMkernel network interfaces 123 VMkernel NIC 123 enable VMotion 125 IPv4 123, 124 IPv6 124, 125 VMkernel NICs 123 vmkfstools 28 VML LUN names 45, 46 VMotion 112, 125 VMW_PSP_FIXED 48 VMW_PSP_MRU 48 VMW_PSP_RR 48 vmware-cmd connection options 104

general options 104 server options 104 snapshots 106 virtual machine options 105 VMware Tools 108 vSphere distributed switches 113, 126 VSS 111

W
Windows Active Directory 26

VMware, Inc.

147

vSphere Command-Line Interface Concepts and Examples

148

VMware, Inc.