vSphere Command-Line Interface 4.0
Release Notes

Released 21-May-2009

Build 161974 is the release of the vSphere Command-Line Interface (vSphere CLI) 4.0.

vSphere CLI 4.0 Release Notes

Welcome to the vSphere CLI 4.0 release notes.

This document contains the following information:

About vSphere CLI

The vSphere CLI command set allows you to run common system administration commands against ESX/ESXi systems from any machine with network access to those systems. You can run most vSphere CLI commands against a vCenter Server system and target any ESX/ESXi system that the vCenter Server system manages. vSphere CLI commands are especially useful for ESXi hosts because ESXi does not include a service console.

vSphere CLI commands run on top of the vSphere SDK for Perl. The vSphere CLI and the vSphere SDK for Perl are included in the same installation package.

What’s New in vSphere CLI 4.0

The following vSphere CLI commands have been added since the last documented release, Remote CLI 3.5 Update 2:

  • esxcli – Supports management of the VMware Pluggable Storage Array (PSA) architecture. You can use esxcli to set the path policy and mask paths, and preview and manage third-party storage arrays. You can also use esxcli to manage iSCSI NIC bindings.
  • vicfg-iscsi – Allows you to manage both hardware and software iSCSI storage. The command includes functionality of the esxcfg-swiscsi and esxcfg-hwiscsi service console commands, as well as options for setting authentication and for IPv6 configuration.
  • vicfg-scsidevs – Displays information about available LUNs. The vicfg-vmhbadevs command available in ESX/ESXi 3.5 had similar but more limited functionality.
  • vicfg-mpath – Displays information about a storage array and supports changing the state of a path. This command does not allow you to set the path policy; use esxcli instead. Use vicfg-mpath35 to manage ESX/ESXi 3.5 systems.
  • vihostupdate – Applies software updates to ESX/ESXi images and installs and updates ESX/ESXi extensions such as VMkernel modules, drivers, and CIM providers. This command has more extensive functionality than the vihostupdate command available in Remote CLI 3.5 Update 2. Use vihostupdate35 to manage ESX/ESXi 3.5 systems.
  • vicfg-volume – Supports resignaturing a snapshot volume and mounting and unmounting the volume. You can make the mounted volume persistent across reboots and query a list of snapshot volumes and original volumes.

vSphere CLI 4.0 also includes the following new functionality:

  • You can now run resxtop through vCenter Server systems.
  • Networking commands support configuration of IPv6. The commands have not been tested running on an IPv6 network.
  • The vicfg-route command supports a number of new options for setting and managing the default route.
  • Several vSphere CLI commands have new options. See the vSphere Command-Line Interface Installation and Reference Guide or run the command with --help.

The vSphere CLI package installers for Linux and Windows install the vSphere CLI and the vSphere SDK for Perl. Instead of using an installable package, you can deploy the vSphere Management Assistant (vMA), which includes the vSphere SDK for Perl, the vSphere CLI, and a set of other software components.

Supported Platforms

You can install vSphere CLI on the following Windows platforms:

  • Windows XP SP2 32 bit
  • Windows XP SP2 64 bit
  • Windows Vista Enterprise SP1 32 bit
  • Windows Vista Enterprise SP1 64 bit

You can install vSphere CLI on the following Linux platforms:

  • Red Hat Enterprise Linux (RHEL) 5.2 (64 bit)
  • Red Hat Enterprise Linux (RHEL) 5.2 (32 bit)
  • SUSE Enterprise Server 10 SP1 32 bit
  • Ubuntu 8.04 32 bit

vSphere CLI is also included in the vSphere Management Assistant (vMA), a virtual machine which includes prepackaged software. Developers and administrators can use vMA to run agents and scripts to manage ESX and ESXi systems.

You can run most vSphere CLI commands against ESX/ESXi 4.0 and ESX/ESXi 3.5 Update 2 and later. When you run vSphere CLI 4.0 against ESX/ESXi 3.5 Update 2 and later, only the commands and command options supported by Remote CLI 3.5 Update 2 are supported. Call each command with --help for more information. In a few cases, command options supported by Remote CLI 3.5 Update 2 against ESX/ESXi systems are not supported by vSphere CLI 4.0. See VMware KB Article 1008940 for information on running vSphere CLI 4.0 commands against ESX/ESXi 3.5 Update 2 systems.

See VMware KB Article 1008194 for information on parity between vSphere CLI commands and ESX service console commands.

Installing vSphere CLI

You can install the vSphere CLI on one of the supported Windows or Linux platforms, or deploy vMA on your ESX/ESXi system. See the vSphere Command-Line Interface Installation and Reference Guide for detailed installation instructions.

Resolved Issues

The following issues that were reported in previous releases have been resolved.
  • VIMA 1.0 supports a maximum of 19 target servers. It is not possible to add more than 19 target servers to VIMA 1.0. This issue is resolved for vMA 4.0.

Known Issues

The vSphere CLI 4.0 release has the following known issues:

  • 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 (Virtual Machine File System) 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.

  • resxtop not supported in replay mode. The 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 systems, use esxtop instead. On ESXi systems, no workaround.

  • 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.
    Workaround: Type "u" to expand to the LUN level.

  • 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.

    Workaround: None.

  • 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

    Workaround: Configure a diagnostic partition for core dump files on your ESX/ESXi system. When you do,
    --list displays valid information.

  • Diagnostic partition change is not persistent under certain conditions. If you call esxcfg-dumppart or 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.
    • ESX: Run esxcfg-boot -b immediately after changing the partition to ensure this problem does not occur.
    • ESXi: Reboot the ESXi system immediately after changing the partition.

  • 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.
    Workaround: Run svmotion in non-interactive mode and use quotes around the datacenter name.

  • vihostupdate reports Host updated successfully when an obsolete bulletin is installed. An obsolete bulletin is a bulletin containing VIBs that are superseded by what is already installed. Because the bulletin is old, it does not need to be installed. When vihostupdate encounters an obsolete bulletin, it does not perform installation or update but skips the bulletin. The message is incorrect.
    Workaround: No workaround needed — just ignore the message. To verify what software is installed, run vihostupdate --query.

  • 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 ( This is also a problem if the address is 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 --subnetmask --gateway

  • Cannot modify hardware iSCSI adapter MTU using vicfg-iscsi. 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 is not settable.
    Workaround: None

  • vicfg-vmknic completes successfully but displays error. Set up an ESXi Installable system with a DHCP IP address, then set an explicit IP address by running vicfg-vmknic -i -n -p. The IP address is set successfully, but a SOAP error is displayed instead of a success message. This problem has been found on ESXi Installable only.
    Workaround: No workaround needed, the IP address is set successfully.

  • On Windows, Warnings During Startup if chcp Program Not Available. On Windows operating systems, if the chcp program is not present or is not in your PATH environment variable, vSphere CLI commands display the following warning message on startup:

    'chcp' is not recognized as an internal or external command, operable program or batch file.

    By default, the program is not included with Windows XP 64 bit, but included with all other supported versions of Windows.
    Workaround: No workaround needed. The commands are not affected. If you want to avoid the warning, make sure chcp is installed and in your PATH.

  • 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. For example, if you specify /home/user, the installer creates a /home/bin directory and installs the software there.
    Workaround: Create the bin directory before installation.

  • lcrypto installation error on some Linux platforms. When you install the package that includes the vSphere SDK for Perl and the vSphere CLI, you might see the following error on some Linux platforms:

    ld: cannot find -lcrypto
    Unable to link the Crypt::SSLeay Perl module. Secured connections will be unavailable until you install the Crypt::SSLeay module.

    The error indicates that OpenSSL is not available on that system.

    Workaround: Install OpenSSL, as described in the vSphere SDK for Perl Installation Guide.

  • Error running credstore_admin.pl on some SUSE 10 installations. When you run the /apps/general/credstore_admin.pl script on a SUSE 10 system the following error might result:

    *** glibc detected *** /usr/bin/perl: free(): invalid pointer: 0x083d0339 ***

    The probable reason for the error is that a version of perl-XML-LibXML that is older than the version included with the vSphere CLI / vSphere SDK for Perl package is already installed on the system. As a result, the installer did not add the required version of perl-XML-LibXML to the SUSE system.
    Workaround: First uninstall the perl-XML-LibXML package, and then reinstall the vSphere CLI / vSphere SDK for Perl package. The required version of perl-XML-LibXML can now be installed by that installer.

  • vicfg-volume does not maintain global datacenter information in a distributed environment. In a distributed environment a user has mounted (persistent/no persistent) an unresolved volume from one ESX/ESXi system using vicfg-volume -M. From another ESX/ESXi system, the user runs 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.


  • 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>

    The problem occurs under different conditions on ESX and ESXi systems.
    ESX: When you call the vicfg-snmp vSphere CLI command on ESX systems, the SNMP service starts successfully. However, if you later attempt to access the service by running snmpwalk, the call to snmpwalk times out and displays the error.
    ESXi: When you call the vicfg-snmp vSphere CLI command on ESXi systems, the SNMP service starts successfully and you can run snmpwalk to access the service. However, if you disable SNMP and then enable it, a call to snmpwalk fails.

    • ESX: Restart hostd from the service console by running: Service mgmt-vmware restart
    • ESXi: Restart the ESXi system.



Last updated 19-May-2009