VMware

vSphere Command-Line Interface 4.1
Release Notes

Released 13-July-2010

Build 254719 is the 4.1 release of the vSphere Command-Line Interface (vSphere CLI).

vSphere CLI 4.1 Release Notes

Welcome to the vSphere CLI 4.1 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:

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

The following vSphere CLI commands have been added since the last documented release, vSphere CLI 4.0:

  • vicfg-hostops – Allows you to examine, stop, and reboot hosts and to instruct hosts to enter and exit maintenance mode.
  • vicfg-authconfig – Allows you to add an ESX/ESXi host to an Active Directory domain, remove the host, and list Active Directory domain information.
  • vicfg-ipsec – Supports IPsec setup.

vSphere CLI 4.1 also includes the following new functionality:

  • The following options have been added to esxcli:
    • esxcli swiscsi session – Manage iSCSI sessions.
    • esxcli swiscsi nic – Manage iSCSI network interfaces.
    • esxcli swiscsi vmknic – List VMkernel network interfaces available for binding to particular iSCSI adapter.
    • esxcli swiscsi vmnic – List available uplink adapters for use with a specified iSCSI adapter.
    • esxcli vaai device – Display information about devices claimed by the VMware VAAI (vStorage APIs for Array Integration) Filter Plugin.
    • esxcli corestorage – List devices or plugins. Used in conjunction with hardware acceleration.
    • esxcli network – List active connections or list active ARP table entries.
    • esxcli vms – List and forcibly stop virtual machines that do not respond to normal stop operations.
  • Some of the parity issues between vSphere CLI and the ESX service console have been resolved.
  • You can now run vCLI commands using SSPI (--passthroughauth) against both vCenter Server and ESX/ESXi systems.
  • Lockdown mode allows vSphere administrators to block direct access to ESXi systems. With lockdown mode enabled, all operations must go through a vCenter Server system. The following commands cannot run against vCenter Server systems and can therefore not be used in lockdown mode:
    • vicfg-snmp
    • vifs
    • vicfg-user
    • vicfg-cfgbackup
    • vihostupdate
    • vmkfstools
    • esxcli
    • vicfg-ipsec
    If you want to run these commands against an ESXi system, turn off lockdown mode using the vSphere Client.

vSphere CLI 4.1 includes the following changed functionality:

  • vmware-cmd -T has been changed to vmware-cmd --vihost | -h to be compatible with other vSphere CLI commands.
  • vmware-cmd -h has been changed to vmware-cmd --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.

vSphere CLI 4.1 documentation includes the vSphere Command-Line Interface Installation and Scripting Guide and the vSphere Command-Line Interface Reference (HTML). For the Reference, download and unzip the ZIP file and click on index.html.

Deprecated Functionality

The get option of credstore_admin.pl is deprecated. Do not use this option; it is scheduled for removal in an upcoming release.

TSO is enabled on ESX/ESXi systems by default. In previous releases of vSphere, the vicfg-vmknic -t command allowed you to disable TSO. The option is not supported against ESX/ESXi 4.1 and later.

Supported Platforms

You can install vSphere CLI on the following Windows platforms:

  • Windows XP SP3 32 bit
  • Windows 2003 32 bit
  • Windows Vista Enterprise SP1 32 bit
  • Windows 2008 64 bit

You can install vSphere CLI on the following Linux platforms:

  • Red Hat Enterprise Linux (RHEL) 5.2 (32 bit and 64 bit)
  • SLES 10 (32 bit and 64 bit)
  • SLES 11 (32 bit and 64 bit)
  • Ubuntu 9.04 (32 bit and 64 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. vMA 4.1 includes vSphere CLI 4.1 running on a CentOS system.

You can run most vSphere CLI commands against ESX/ESXi 4.x and ESX/ESXi 3.5 Update 2 and later. When you run vSphere CLI 4.x 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 and later. See VMware KB Article 1008940 for information on running vSphere CLI 4.x 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

The vSphere CLI Linux installer has changed.

To install vSphere CLI:

  1. Uninstall any existing versions of vSphere CLI by running <install_dir>/bin/vmware-uninstall-vSphere-CLI.pl. The default installation directory is /usr/bin.
  2. Delete any existing versions of vSphere-CLI.tar.gz:
    rm -rf <install_dir>/vmware-vsphere-cli-distrib
  3. Download and untar vSphere CLI 4.1.

The vSphere CLI Linux installer stops installation if required modules cannot be found on your Linux system. The installer installs other missing Perl modules, but does not overwrite existing versions of those modules. See the vSphere Command-Line Interface Installation and Scripting Guide

The vSphere CLI Windows installer works as before and installs the vSphere SDK for Perl, the vSphere CLI, and all prerequisite software including Active Perl. If you do not want to overwrite an existing Active Perl installation, use a different system for installing vSphere CLI.

Important: Reboot your Windows system after installation. If you don't, ActivePerl might report that it cannot find some of the Perl modules.

Resolved Issues

The following issues that were reported in previous releases have been resolved.

  • vicfg-dumppart --list results in error. When you run vicfg-dumppart --list against 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

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

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

Known Issues

The vSphere CLI 4.1 release has the following new known issues:

  • Documentation about vNetwork Distributed Switch misleading The vSphere CLI Installation and Scriptig Guide erroneously stated that you can manage vNetwork Distributed Switches (vDS) and dvPort Groups using the vicfg-vswitch command. You can only add uplink adapters to already existing vDS using vicfg-vswitch. Use the vSphere Client or the vSphere Web Services SDK for other vDS management tasks.

    Workaround: No workaround needed. The documentation has been updated.

  • Running vicfg-snmp -r or vicfg-snmp -D against ESX systems fails. On an ESX system, when you try to reset the current SNMP settings by running the command vicfg-snmp –r or to disable the SNMP agent by running the command vicfg-snmp –D, the command fails. The failure happens because the command tries to run the esxcfg-firewall command, which becomes locked and hangs. With esxcfg-firewall hung, the vicfg-snmp -r or vicfg-snmp –D command results in a time-out and signals an error.
    The problem does not occur on ESXi systems.

    Workaround: Rebooting the ESX system removes the lock file and applies the previously executed vicfg-snmp command that caused the lock. However, if you try to run vicfg-snmp -r or vicfg-snmp -D again, an error results again.

  • 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 vicfg-user vCLI.

    Workaround: No workaround.

  • 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. The reason is that in contrast to other 64 bit Linux distributions, Ubuntu 9.04 does not have 32-bit compatibility libraries installed by default.

    Workaround: Follow the steps in the vSphere Command-Line Interface Installation and Scripting Guide, which instruct you to install a number of non-default prerequisite software, as follows:

    1. sudo apt-get update
    2. sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl ia32-libs

  • Cannot clone VMDK files from a non-VMFS directory using 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.

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

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

    Workaround: Run the following command in the ESX service console to manually open port 161 as an input port:
    /usr/sbin/esxcfg-firewall -o 161,udp,in,hostdSnmp
    After the port has been opened, calls to snmpwalk work correctly.

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

    The total number of iterations on ESX/ESXi 4.1 (-n) is set to a default value of 10,000. After resxtop has generated 10,000 displays, it shuts itself down. That means that if a default delay of five seconds between two displays is used, resxtop might shut itself down after around 14 hours.

    Workaround: Although you can use the -n option to change the total number of iterations, it is better to run resxtop only when you need the data. If you have to collect resxtop statistics over a long time, shut down and restart resxtop periodically instead of running one resxtop instance for weeks or months.

  • 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. For example, if you run vicfg-hostops to put multiple hosts in a cluster into maintenance mode, the operation stops when it encounters a host that is already in maintenance mode. The operation does not process the other hosts in the cluster.

    Workaround: In your script, perform a check whether the host is already in the state you want to set it to. Have your script call the vicfg-hostops operation only if the host is not yet in that state.

  • 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 --list, no modules are displayed even if those modules actually exist. When the user runs vicfg-dumppart --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.

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

    Workaround: Configure a scratch directory on a VMFS volume using the vSphere Client, then run vihostupdate again.

  • On Ubuntu 9.04, SSL_connect messages result from running vmware_cmd. When you run vmware-cmd on an Ubuntu 9.04 system, SSL_connect: messages are displayed. The messages do not affect command execution.

    Workaround:Run the following command to make sure all required modules are up to date:
    sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl

  • On Ubuntu 9.04, message "no packages found matching libxml-libxml-perl". On Ubuntu 9.04, the following message might display when your run the installer:
    No packages found matching libxml-libxml-perl In which directory do you want to install the executable files? [/usr/bin] The message indicates that the libxml module is not up to date.

    Workaround: Run the following command to make sure all required modules are up to date:
    sudo apt-get install libssl-dev perl-doc liburi-perl libxml-libxml-perl libcrypt-ssleay-perl
    See the vSphere CLI Installation and Scripting Guide for more information on required and recommended Perl modules.

  • Connection failure message when running the esxcli vSphere CLI under Linux. When you run an esxcli command on a Linux system that is using SELinux enhanced security, the command reports Connect to 1.2.3.4 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 esxcli commands:

    • Run the following command to resolve the text relocation issue:

      chcon -t textrel_shlib_t /usr/lib/vmware-vcli/bin/esxcli/_ssl.so

    • Disable SELinux or change the SELinux policy to permissive. Note that this is a significant change to the security of the client system. Do not make this change unless you have in-depth knowledge of SELinux and your local network security policies.

  • 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:
    lib2xml.dll wasn't found

    Workaround: Reboot your Windows system.

The following known issues documented for vSphere 4.0 have not yet been resolved:

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

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

    Workaround:

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

  • 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 --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 using the appropriate installation process for your Linux platform.

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