vSphere Command-Line Interface 5.0
vCLI 5.0 Release Notes
Welcome to the vCLI 5.0 release notes. Any version numbers referenced in this document are placeholders and do not represent any commitment by VMware to have any specific features in the software included in any specific versions.
This document contains the following information:
The vCLI command set allows you to run common system administration commands against VMware ESXi systems from any machine with network access to those systems. You can run most vCLI commands against a vCenter Server system and target any ESXi system that the vCenter Server system manages.
vCLI commands run on top of the vSphere SDK for Perl. Both vCLI and the vSphere SDK for Perl are included in the same installation package.
The installer for vCLI on Linux has changed significantly in vCLI 5.0. See Getting Started with vSphere Command-Line Interfaces available in the vSphere Documentation Center.
The following vCLI
vicfg- commands have new options that were added since the last release, vSphere CLI 4.1.
vicfg-iscsinow allows you to specify
--mpchap_password. Use the user name and password with the
--authenticationoption when specifying mutual authentication.
vicfg-snmpnow includes the following options:
--hwsrcspecifies where to source hardware events originating from IPMI sensors or from CIM indications. Use either
indicationsas the value of this option.
--notrapallows you to specify a comma-separated list of trap object identifiers (oids) for traps not to be sent by the agent. Use
--notrap resetto clear the list.
vmkfstoolsnow includes the
--rescanvmfsoption to rescan the host for new Virtual Machine File System (VMFS) volumes to be added.
The following vSphere CLI
vicfg- commands and command options do not work against ESXi 5.0 hosts.
vihostupdatedoes not work against ESXi 5.0 hosts. Use
esxcli software vibto patch your hosts.
vicfg-syslog --setportcommands do not work against ESXi 5.0 hosts.
vmkfstoolsESXi Shell command has a number of new options. These new options are not supported by the
vmkfstoolscommand included in vCLI.
The ESXCLI command set has been completely revised and significantly expanded. ESXCLI is now based on an extensible framework and includes commands for managing most aspects of your system. See the vCLI Reference for a complete set of commands.
You can run ESXCLI commands against a vCenter Server system if you target ESXi 5.0 hosts by using the
Warning: You cannot run ESXCLI 4.x commands against ESXi 5.0 hosts.
vSphere CLI 5.0 documentation is available in the vSphere Documentation Center, a searchable HTML set of all vSphere 5.0 documentation, which also includes PDF documents for all guides.
Command-line help for each
vicfg- command and
esxcli command is available.
The technical note Command-Line Management of vSphere 5.0 for Service Console Users is for administrators who migrate from ESX to ESXi and includes reference information that maps deprecated esxcfg- commands to vCLI commands.
The vSphere CLI Linux installer has changed.
Note: Downloading modules from CPAN can take a long time.
See the Getting Started with vSphere Command-Line Interfaces document for detailed instructions, including the list of required modules.
The vCLI Windows installer works as before and installs the vSphere SDK for Perl, the vSphere CLI, and all prerequisite software including Active Perl 5.8.8. If you do not want to overwrite an existing Active Perl installation, exit the installer and install vCLI on a different system.
Important: Reboot your Windows system after installation. If you don't, ActivePerl might report that it cannot find some of the Perl modules.
For this release, vCLI is supported on the following Linux platforms:
For this release, vCLI is supported on the following Windows platforms:
The vSphere Management Assistant (vMA) is included in this release. You cannot upgrade vMA 4.1 to include vCLI 5.0 by running the vCLI installer inside vMA. Deploy the new vMA appliance.
vicfg-dumppart --list results in error.
When you run
vicfg-dumppart --list on an ESX/ESXi host that does not have a diagnostic partition configured, the following error results:
Use of uninitialized value in length at /usr/bin/vicfg-dumppart line 307
vicfg-snmp does not allow printable ASCII characters
In vCLI 4.1,
vicfg-snmp does not allow the ampersand character in trap destinations.
Starting SNMP service with vicfg-snmp sometimes fails.
Starting the SNMP service by running
vicfg-snmp sometimes fails with the following error:
# snmpwalk -m all -c public -v1 <IP address> enterprises.6876
Timeout: No Response from <ip-address>
On ESX systems, running snmpwalk fails after a call to vicfg-snmp -E.
When you enable SNMP by running
vicfg-snmp -E, the ESX firewall blocks port 161 from being open as an input port. As a result, calls to
snmpwalk do not work properly.
vSphere CLI not currently supported with Perl 5.10.
You cannot run vSphere CLI 4.1 on a Linux system that has Perl 5.10 installed.
vicfg-route --list option currently not functional.
If you create a default gateway by running the
vicfg-route vCLI command, running
vicfg-route --list does not display information about the gateway.
resxtop Storage Panel "l" interactive command replaced by "u".
When you use
resxtop in interactive mode and view the Storage Adapter panel, you can no longer type "l" to expand the view to the LUN level. Instead, an error results.
Running resxtop for extended periods might result in memory problems.
Memory usage by
resxtop might increase over time depending on what happens on the ESX/ESXi system being monitored. Because
resxtop also causes extra CPU consumption on ESX/ESXi, VMware recommends that you not leave
resxtop running for a long time, that is, for a few weeks.
Running vicfg-hostops to change state of multiple hosts fails when one host is already in that state.
You run a
vicfg-hostops operation on multiple hosts in a datacenter or cluster. If the operation fails on one of the hosts because the host is already in the state you want to set it to, the operation is not performed on other hosts in the datacenter or cluster.
Patch installation using
vihostupdate might fail on ESXi hosts for patch file sizes greater than 256MB.
If you run
vihostupdate to install patches on an ESXi host that does not have a scratch directory, and if the downloaded file size is above 256MB, patch installation fails.
When the ESXi server boots initially, the system tries to auto-configure a scratch directory. If no storage is available for the scratch directory, the scratch directory is not configured and points to a temporary directory.
Problems with resxtop and esxcli on Ubuntu 9.04 64 bit.
When you install vSphere CLI on Ubuntu 9.04 64 bit, and then attempt to run
resxtop or an
esxcli command, the following error results:
No such file or directory.
On Linux, cannot install into a non-default directory if it does not have a bin directory.
If you run the vSphere CLI installer and specify as the installation location a directory that does not contain a
bin directory, the installer ignores the specified directory and installs the package in the
/usr/bin directory instead.
New known issues for
esxcli commands are listed in the ESXi Release Notes. Old (4.x)
esxcli issues and all other vCLI issues are listed below.
The vSphere CLI 5.0 release has the following new known issues:
When running ESXCLI commands against vCenter Server 5.0, must target ESXi 5.0 hosts
With vSphere 5.0, you can run ESXCLI against vCenter Server 5.0 and specify the target host with the
--vihost parameter. If the target host is not an ESXi 5.0 system, the following error results.
Runtime error: Cannot complete the operation due to an incorrect request to the server.
Workaround: No workaround.
On Linux, installing vSphere SDK for Perl on systems where vSphere CLI is installed results in unusable installation.
If you install the vSphere SDK for Perl on a Linux system, and if vSphere CLI is already installed on that system, both products are not usable after the installer completes. This problem occurs regardless of the version of the two installers.
Workaround: Do not install the vSphere SDK for Perl bundle. The vSphere SDK for Perl software is included in the vSphere CLI bundle. Install the vSphere CLI bundle.
resxtop command may cause a Linux vCLI to stop functioning
When you use the
resxtop command against an ESX/ESXi or vCenter Server host on a Linux vCLI or vMA, a user name is required. If you do not provide one at the prompt, your command-line window stops responding.
Workaround: Terminate the
resxtop process with Ctrl-C or use the
kill command from another window.
vmkfstools reports the same volume twice.
If a VMFS (Virtual Machine File System) volume and its snapshot are both mounted,
vmkfstools reports the volume twice.
Workaround: No workaround needed.
Parameter values with spaces result in error for esxcli image command.
When you run
esxcli image with
--meta|-m and supply a parameter value that contains spaces, the second part of that parameter value is treated as a separate argument. An error results.
Workaround: Surround the parameter value with double quotes.
The following known issues documented for vSphere 4.0 and vSphere 4.1 have not yet been resolved:
Group ID length in vSphere Client shorter than group ID length in vCLI.
If you specify a group ID using the vSphere Client, only nine characters are allowed. In contrast, you can specify up to ten characters if you specify the group ID using the
Workaround: No workaround.
Cannot clone VMDK files from a non-VMFS directory using the vmkfstools vCLI.
When you attempt to run the
vmkfstools vCLI to clone a VMDK file that is not located in a VMFS directory, the command fails with a message
Invalid datastore path.
The operation does not fail if you use the
vmkfstools service console command.
Workaround: Move the VMDK file into the VMFS datastore and repeat the clone operation.
Users with read-only role cannot display some information on target servers.
You create a user running the
vicfg-user vCLI, and you assign the
read-only role to the user. When that user attempts to retrieve information from an ESX/ESXi host, the information is not always available. For example, when the user runs
vicfg-module <conn_options> --list, no modules are displayed even if those modules actually exist. When the user runs
vicfg-dumppart <conn_options> --list, no diagnostic partitions are displayed.
Workaround: No workaround for this issue. You can log in as a user with read and write permissions to display the information.
Connection failure message when running the esxcli vSphere CLI under SELinux.
When you run an
esxcli command on a Linux system that is using SELinux enhanced security, the command reports
Connect to 126.96.36.199 failed. The command records the following information in /var/log/messages
setroubleshoot: SELinux is preventing esxcli from loading /usr/lib/vmware-vcli/bin/esxcli/_ssl.so which requires text relocation.
Workaround: Make one of these changes on the system on which you run
chcon -t textrel_shlib_t /usr/lib/vmware-vcli/bin/esxcli/_ssl.so
Missing DLL error during first command execution after installation (Windows).
A vCLI installation on Windows completes successfully. However, when you later run vCLI commands, errors about missing DLLs might result. For example:
libxml2.dll wasn't found
Workaround: Reboot your Windows system.
Problems using vmkfstools to create VMFS3 volume when using VML name of LUN.
When you run
vmkfstools -C vmfs3 to create a VMFS3 volume, and you use the VML name for the LUN, the command might fail even if the VML name is a soft link to a device name (naa.xxx name). The command might fail, for example, if a VMFS3 volume already exists on the LUN.
Workaround: Use the device name (naa.xxx or eui.xx) to refer to the LUN.
Running vmkfstools -C does not prompt for confirmation.
When you run
vmkfstools -C to create a VMFS on a partition that already has a VMFS on it, the command erases the existing VMFS and creates the new VMFS without prompting for confirmation.
Workaround: No workaround. Check the command carefully before running it.
vmkfstools might print misleading error when running against free ESXi.
When you run the
vmkfstools vCLI against an ESXi host with a free license, some options, e.g.
vmkfstools createvirtualdisk, might return a message like the following:
Unable to create virtual disk with specified parameters
The error message should instead indicate that the operation cannot be performed because of licensing issues.
Workaround: No workaround. While the error is misleading, performing the operation against free ESXi is not supported.
resxtop not supported in replay mode.
resxtop command is supported only in interactive mode and batch mode. The
esxtop service console command is supported in interactive mode, batch mode, and replay mode.
Workaround: On ESX 4.x systems, use
esxtop instead. On ESXi 5.0 systems, use esxtop in the ESXi shell.
vicfg-route displays gateway that has been removed.
If you add a gateway using
vicfg-route, and then remove that gateway, a follow-up call to
vicfg-route still displays the gateway although it has actually been removed.
Diagnostic partition change is not persistent under certain conditions.
If you call
vicfg-dumppart to change the diagnostic partition, and if your ESX/ESXi system experiences a failure within an hour after this change is made and before the host is rebooted, the diagnostic partition reverts to the original setting.
When using svmotion in interactive mode, cannot specify non-ASCII characters as input.
When you use
svmotion in interactive mode, you cannot specify non-ASCII input, for example, a German datacenter name.
svmotion in non-interactive mode and use quotes around the datacenter name.
Error when using vicfg-iscsi to set up IP, subnet, and gateway separately.
You perform a factory reset on a QLogic hardware iSCSI card that results in an error. If you then use the
vicfg-iscsi vSphere CLI to set IP address, subnet mask, and gateway separately, an error status results in which the addresses for IP, subnet mask, default gateway, and DNS are set to NULL (0.0.0.0). This is also a problem if the address is 0.0.0.0 for other reasons.
Workaround: Use the following command to reset the IP address, subnet mask, and gateway at the same time:
vicfg-iscsi --network --ip <ip_addr> --subnetmask <subnet_mask> --gateway <default_gateway> <adapter_name>
Cannot modify hardware iSCSI adapter MTU using
When you call
vicfg-iscsi <conn_params> --pnp --mtu <number> <vmhba> to modify the MTU for a hardware iSCSI adapter, the MTU does not actually changed and an error indicates the property cannot be set.
vicfg-vmknic completes successfully but displays error.
When you set up an ESXi Installable system with a DHCP IP address, and then set an explicit IP address by running
vicfg-vmknic -i -n -p, the IP address is set successfully. However, a SOAP error is displayed. This problem has been found on ESXi Installable only.
Workaround: No workaround needed, the IP address is set successfully.
vicfg-volume does not maintain global datacenter information in a distributed environment.
In a distributed environment you mounted (persistent/no persistent) an unresolved volume from one ESX/ESXi system using
vicfg-volume -M. From another ESX/ESXi system, you run
vicfg-volume -r to resignature that unresolved volume. If the mounted volume is not active, running the volume resignature command unmounts the volume. The volume appears as a resignatures volume to all hosts in the environment.
In contrast, if you use vSphere Client to mount an unresolved volume from one host and issue resignature from another host, the vSphere Client generates a warning to let users know that volume has been mounted on another host and resignature does not succeed.
Workaround: Use the vSphere Client instead of the vSphere CLI to resignature volumes in a distributed environment.