VMware ESXi vim-cmd Command


To totally unlock this section you need to Log-in


Login

Command lines are very important for system administrors when it comes to automation. Although GUIs are more likely (not always) to be more intuitive and easier to get started with, sooner or later administrators will use command lines more for better productivity.

There are a few command line options in VMware ESXi, among which is the vim-cmd. If you are familiar with vSphere API, you already know VIM is the original name for vSphere management (Virtual Infrastructure Management). The vim-cmd is indeed associated with the vSphere API – it’s built on top of the hostd which implements the APIs. With this context in mind, you can guess out what you can do with the vim-cmd in general.

Where Is It Installed?

On ESXi, the vim-cmd is at /bin/vim-cmd, which is actually a symbolic link to a host executable as shown in the following.

~ # ls -l /bin/vim-cmd
lrwxrwxrwx 1 root root 11 Mar 23  2013 /bin/vim-cmd -> /sbin/hostd

What You Can Do With It?

The vim-cmd has a few sub-commands. To find out, you can simply type vim-cmd at a SSH shell as follows:

~ # vim-cmd
Commands available under /:
hbrsvc/ internalsvc/ solo/ vmsvc/ hostsvc/ proxysvc/ vimsvc/ help

As you can see, there are 7 sub-command categories with the help ignored (help is important but it does not represent a type of itself). With these 7 types, you can remove the svc (solo is exception) and get the types as: hbr, host, internal, proxy, solo, vim, and vm. I

think you can guess out what they are for at high level. Please note that the internal is not really related to internal APIs of the ESXi.

Without further due, let’s drive down each categories.

Virtual Machine Management Commands

Again, to find out what specific commands avaiable in each category, you just type the subcommand such as vmsvc here.

~ # vim-cmd vmsvc

Commands available under vmsvc/: acquiremksticket get.snapshotinfo acquireticket get.spaceNeededForConsolidation connect get.summary convert.toTemplate get.tasklist convert.toVm getallvms createdummyvm gethostconstraints destroy login device.connection logout device.connusbdev message device.disconnusbdev power.getstate device.diskadd power.hibernate device.diskaddexisting power.off device.diskremove power.on device.getdevices power.reboot device.toolsSyncSet power.reset device.vmiadd power.shutdown device.vmiremove power.suspend devices.createnic power.suspendResume disconnect queryftcompat get.capability reload get.config setscreenres get.config.cpuidmask snapshot.create get.configoption snapshot.dumpoption get.datastores snapshot.get get.disabledmethods snapshot.remove get.environment snapshot.removeall get.filelayout snapshot.revert get.filelayoutex snapshot.setoption get.guest tools.cancelinstall get.guestheartbeatStatus tools.install get.managedentitystatus tools.upgrade get.networks unregister get.runtime upgrade

As you can see, these subcommands are mostly mapped to the managed object type VirtualMachine in vSphere API. Some of these commands need additional arguments to carry out its duty.

When it’s associated with a virtual machine, it’s the virtual machine ID (VMID). What is it? You can find out with getallvms command – just watch out the first column. This ID is in fact the same as the value of ManagedObjectReference. You can therefore optionally find them out with the Managed Object Browser.

~ # vim-cmd vmsvc/getallvms
Vmid   Name                        File                       Guest OS      Version   Annotation
8     testVM   [datastore1]    testVM/testVM.vmx             ubuntu64Guest    vmx-09

Note that the ID is simple an integer. If you see something like “vm-9”, you are most likely get this from a vCenter MOB. You need to open URL to an ESXi for the vim-cmd command here.

The following example shows the network a virtual machine (whose vmID is 8) connects to:

~ # vim-cmd vmsvc/get.networks 8

Networks:
(vim.Network.Summary) { dynamicType = <unset>, network = 'vim.Network:HaNetwork-VM Network', name = "VM Network", accessible = true, ipPoolName = "", ipPoolId = <unset>, }

The following command list the taks related to the virtual machine. There is no task for the moment the command was issued, therefore an empty array was returned.

~ # vim-cmd vmsvc/get.tasklist 8
(ManagedObjectReference) []

The following command shows the capability of the virtual machine. Remember the property called capability defined with VirtualMachine managed object? They refer to the same thing and hold the same values.

~ # vim-cmd vmsvc/get.capability 8
(vim.vm.Capability) {
   dynamicType = <unset>,
   snapshotOperationsSupported = true,
   multipleSnapshotsSupported = true,
   snapshotConfigSupported = true,
   poweredOffSnapshotsSupported = true,
   memorySnapshotsSupported = true,
   revertToSnapshotSupported = true,
   quiescedSnapshotsSupported = true,
   disableSnapshotsSupported = false,
   lockSnapshotsSupported = false,
   consolePreferencesSupported = false,
   cpuFeatureMaskSupported = true,
   s1AcpiManagementSupported = true,
   settingScreenResolutionSupported = false,
   toolsAutoUpdateSupported = false,
   vmNpivWwnSupported = true,
   npivWwnOnNonRdmVmSupported = true,
   vmNpivWwnDisableSupported = true,
   vmNpivWwnUpdateSupported = true,
   swapPlacementSupported = true,
   swapPreservationSupported = true,
   toolsSyncTimeSupported = true,
   virtualMmuUsageSupported = true,
   diskSharesSupported = true,
   bootOptionsSupported = true,
   bootRetryOptionsSupported = true,
   settingVideoRamSizeSupported = true,
   settingDisplayTopologySupported = false,
   settingDisplayTopologyModesSupported = true,
   recordReplaySupported = true,
   changeTrackingSupported = true,
   multipleCoresPerSocketSupported = true,
   hostBasedReplicationSupported = true,
   guestAutoLockSupported = true,
   memoryReservationLockSupported = true,
   featureRequirementSupported = true,
   poweredOnMonitorTypeChangeSupported = true,
   vmfsNativeSnapshotSupported = true,
   seSparseDiskSupported = true,
   nestedHVSupported = true,
   vPMCSupported = true,
}

We’ve seen several commands that read information from the command. How about doing something? Here is a command that creates new dummy virtual machine.

~ # vim-cmd vmsvc/createdummyvm testVM [datastore1] /testVM/testVM.vmx

There are a few more sub-commands that I don’t intend to show samples – they are very similar and you can explore them by yourself.

VIM Service Commands

This category of commands are related to authentication, license, task management, etc. The following commands give you an idea what exactly they are and how to use some of them.

~ # vim-cmd vimsvc/
Commands available under vimsvc/:
auth/             
license           
property_dump     
task_info
connect           
login             
task_cancel       
task_list
disconnect        
logout            
task_description

~ # vim-cmd vimsvc/auth Commands available under vimsvc/auth/: entity_permission_add lockdown_mode_enter role_permissions entity_permission_remove lockdown_mode_exit role_remove entity_permissions permissions roles lockdown_is_enabled privileges lockdown_is_possible role_add
~ # vim-cmd vimsvc/auth/role_add vm_test Role created: 10

The property_dump is an interesting one and we think very helpful for debugging.

~ # vim-cmd vimsvc/property_dump
(vmodl.fault.InvalidRequest) {
   dynamicType = <unset>,
   faultCause = (vmodl.MethodFault) null,
   msg = "",
}

Proxy Service Commands

This category of commands are associated with networking as you can see from the following console output.

~ # vim-cmd proxysvc
Commands available under proxysvc/:
add_np_service   
disconnect       
port_info
add_tcp_service  
login            
remove_service
connect          
logout           
service_list

These commands are mostly straight-forward. Here is an example with port_info. The information displayed from this command is consistent with the hostd configuration you can find at /etc/vmware/rhttpproxy/endpoints.conf.

~ # vim-cmd proxysvc/port_info
Http Port: 80
Https Port: 443
~ # vim-cmd proxysvc/service_list
(vim.ProxyService.EndpointSpec) [
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/",
      accessMode = "httpsWithRedirect",
      port = 8309,
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/client/clients.xml",
      accessMode = "httpAndHttps",
      port = 8309,
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/ha-nfc",
      accessMode = "httpAndHttps",
      port = 12001,
   },
   (vim.ProxyService.NamedPipeServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/mob",
      accessMode = "httpsWithRedirect",
      pipeName = "/var/run/vmware/proxy-mob",
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/nfc",
      accessMode = "httpAndHttps",
      port = 12000,
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/sdk",
      accessMode = "httpsWithRedirect",
      port = 8307,
   },
   (vim.ProxyService.NamedPipeTunnelSpec) {
      dynamicType = <unset>,
      serverNamespace = "/sdkTunnel",
      accessMode = "httpOnly",
      pipeName = "/var/run/vmware/proxy-sdk-tunnel",
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/ui",
      accessMode = "httpsWithRedirect",
      port = 8308,
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/vpxa",
      accessMode = "httpsOnly",
      port = 8089,
   },
   (vim.ProxyService.LocalServiceSpec) {
      dynamicType = <unset>,
      serverNamespace = "/wsman",
      accessMode = "httpsWithRedirect",
      port = 8889,
   }
]

~ # more /etc/vmware/rhttpproxy/endpoints.conf / local 8309 redirect allow /sdk local 8307 redirect allow /client/clients.xml local 8309 allow allow /ui local 8308 redirect allow /vpxa local 8089 reject allow /mob namedpipe /var/run/vmware/proxy-mob redirect allow /wsman local 8889 redirect allow /sdkTunnel namedpipetunnel /var/run/vmware/proxy-sdk-tunnel allow reject /ha-nfc local 12001 allow allow /nfc local 12000 allow allow

Solo Commands

Unlike other command category, it does not come with svc as suffix. To find out what it does, just type in the following command:

~ # vim-cmd solo
Commands available under solo/:
connect          
environment      
logout           
querycfgoptdesc
disconnect       
login            
querycfgopt      
registervm

Most of the commands like environment, querycfgopt, querycfgoptdesc are for showing the environment that a ComputeResource presents for creating and configuring a virtual machine. The corresponding managed object is the EnvironmentBrowser in vSphere APIs.

~ # vim-cmd solo/querycfgoptdesc
(vim.vm.ConfigOptionDescriptor) [
   (vim.vm.ConfigOptionDescriptor) {
      dynamicType = <unset>,
      key = "vmx-03",
      description = "ESX 2.x virtual machine",
      createSupported = false,
      defaultConfigOption = false,
      runSupported = false,
      upgradeSupported = false,
   },
   (vim.vm.ConfigOptionDescriptor) {
      dynamicType = <unset>,
      key = "vmx-04",
      description = "ESX 3.x virtual machine",
      createSupported = true,
      defaultConfigOption = false,
      runSupported = true,
      upgradeSupported = true,
   },
   (vim.vm.ConfigOptionDescriptor) {
      dynamicType = <unset>,
      key = "vmx-07",
      description = "ESX/ESXi 4.x virtual machine",
      createSupported = true,
      defaultConfigOption = false,
      runSupported = true,
      upgradeSupported = true,
   },
   (vim.vm.ConfigOptionDescriptor) {
      dynamicType = <unset>,
      key = "vmx-08",
      description = "ESXi 5.0 virtual machine",
      createSupported = true,
      defaultConfigOption = false,
      runSupported = true,
      upgradeSupported = true,
   },
   (vim.vm.ConfigOptionDescriptor) {
      dynamicType = <unset>,
      key = "vmx-09",
      description = "ESXi 5.1 virtual machine",
      createSupported = true,
      defaultConfigOption = true,
      runSupported = true,
      upgradeSupported = true,
   }
]

The most important command there is the registervm command, which can be shown as follows:

~ # vim-cmd solo/registervm "{[datastore1] testvm/testvm.vmx}"
(vim.fault.InvalidDatastorePath) {
   dynamicType = <unset>,
   faultCause = (vmodl.MethodFault) null,
   datastore = ,
   name = "",
   datastorePath = "[]{[datastore1] testvm/testvm.vmx}",
   msg = "Invalid datastore path '[]{[datastore1] testvm/testvm.vmx}'.",
}

Ooops! The path to the datastore is not right. It turns out it has to be a path starts with /vmfs:

~ # vim-cmd solo/registervm
Insufficient arguments.
Usage: registervm vm path [name] [resourcepool]

registervm [cfg path] [name(optional)] [resourcepool(optional)]

Register the VM

~ # vim-cmd solo/registervm /vmfs/volumes/datastore1/testvm/testvm.vmx
69

You may be wondering how to do the opposite – unregister a virtual machine. It’s in the vmsvc category and can be done as follows:

~ # vim-cmd vmsvc/unregister 69
~ #

Host Service Commands

This category of commands represent the most complicated ones in the vim-cmd as it’s further divided into many sub-categories. See these with / in the following output:

~ # vim-cmd hostsvc
Commands available under hostsvc/:
advopt/                   
enable_ssh                
refresh_services
autostartmanager/         
firewall_disable_ruleset  
reset_service
datastore/                
firewall_enable_ruleset   
runtimeinfo
datastorebrowser/         
get_service_status        
set_hostid
firmware/                 
hostconfig                
standby_mode_enter
net/                      
hosthardware              
standby_mode_exit
rsrc/                     
hostsummary               
start_esx_shell
storage/                  
login                     
start_service
summary/                  
logout                    
start_ssh
vmotion/                  
maintenance_mode_enter    
stop_esx_shell
connect                   
maintenance_mode_exit     
stop_service
cpuinfo                   
pci_add                   
stop_ssh
disable_esx_shell         
pci_remove                
task_list
disable_ssh               
queryconnectioninfo       
updateSSLThumbprintsInfo
disconnect                
querydisabledmethods
enable_esx_shell          
refresh_firewall

Most of these command categories are self explantory, for example, datastore, autostartmanager, datastore, datastorebrowser, firmware, storage, summary, vmotion. Note that the summary is not really the same as you find from summary property of HostSystem managed object in vSphere API.

To find out what is there in summary, just type the command:

~ # vim-cmd hostsvc/summary
Commands available under hostsvc/summary/:
fsvolume  hba       scsilun

The three commands there are really for listing file system volumes, host based adapters, and SCSI LUNs.

Returning back to the direct commands under the hostsvc, there is one called advopt. This is a shorthand for advanced options. The corresponding managed object in vSphere API is OptionManager. If you’ve been familiar with OptionManager, it’s easy to figure out how to use the commands.

Another command subcategory that does not seem straight-forward is the rsrc, which is for grouping resource pool related sub-commands. We don’t know why rsrc is used, but we would have named it rp if we had designed it. Anyway, a name is a name. Once you know what it is, we can just focus on its functionalities.

Host Based Replication Commands

As you can guess, the hbr stands for host based replication. The following shows the sub-commands. As you can see, you can use them to manage the full cycle of virtual machine replicas, and monitor them accordingly.

~ # vim-cmd /hbrsvc
Commands available under /hbrsvc/:
vmreplica.abort                  
vmreplica.pause
vmreplica.create                 
vmreplica.queryReplicationState
vmreplica.disable                
vmreplica.reconfig
vmreplica.diskDisable            
vmreplica.resume
vmreplica.diskEnable             
vmreplica.startOfflineInstance
vmreplica.enable                 
vmreplica.stopOfflineInstance
vmreplica.getConfig              
vmreplica.sync
vmreplica.getState

~ # vim-cmd /hbrsvc/vmreplica.getState
Insufficient arguments.
Usage: vmreplica.getState vmid

Get the state of the specified replication group:

~ # vim-cmd /hbrsvc/vmreplica.getState 8
Retrieve VM running replication state:
(vim.fault.ReplicationVmFault) {
   dynamicType = <unset>,
   faultCause = (vmodl.MethodFault) null,
   reason = "notConfigured",
   state = <unset>,
   instanceId = <unset>,
   vm = 'vim.VirtualMachine:8',
   msg = "vSphere Replication operation error: Virtual machine is not configured for replication.",
}

Internal Service Commands

Again these commands are not related to the internal APIs, but rather services for performance management, log management, etc. To list out all the possible commands, just type as follows:

~ # vim-cmd internalsvc
Commands available under internalsvc/:
perfcount/          
host_mode_lock      
refresh             
set_log_level
vprobes/            
login               
refresh_consolenic  
shutdown
access_address      
loglist             
refresh_datastores  
throw_exception
cold_quit           
logout              
refresh_gateway     
use_fds
connect             
redirect_stderr     
refresh_network
disconnect          
redirect_stdout     
refresh_pnic

Under the perfcount and vprobes, there are more sub-commands as follows:

~ # vim-cmd internalsvc/perfcount/
Commands available under internalsvc/perfcount/:
enumerate      
query_execute  
query_list     
query_regex
query_destroy  
query_info     
query_names    
scoreboard

~ # vim-cmd internalsvc/vprobes Commands available under internalsvc/vprobes/: listGlobals listProbes load reset version

Summary

vim-cmd commands are pretty powerful set of commands that are built on top of vSphere APIs. Without deep knowledge of vSphere APIs, you can start to leverage the functionalities of vSphere APIs from ESXi Shell. Combined with scripting capability of Linux Shell, you can do a lot of automation work.