VMware

vSphere Command-Line Interface 5.1
Release Notes

Released 10 Sep 2012

Build 780721 is the 5.1 release of the vSphere Command-Line Interface (vCLI).

vCLI 5.1 Release Notes

Welcome to the vCLI 5.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 vCLI

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.

What’s New in vSphere CLI 5.1

The following new commands have been added to the ESXCLI command set.

New esxcli system snmp namespace replaces vicfg-snmp commands. The following commands have been added.

  • esxcli system snmp get | hash | set | test

New commands for SAN device management operations on FC, FCoE, iSCSI and SAS devices..

  • esxcli storage san fc list | reset
  • esxcli storage san fc events clear | get
  • esxcli storage san fc stats get
  • esxcli storage san fcoe list | reset
  • esxcli storage san fcoe stats get
  • esxcli storage san iscsi list
  • esxcli storage san iscsi stats get
  • esxcli storage san sas list | reset
  • esxcli storage san sas stats get
  • esxcli storage san stats get

New esxcli network ip ipsec namespace provides namespaces and commands that correspond to the vicfg-ipsec command.

  • esxcli network ip ipsec set
  • esxcli network ip ipsec sa add | list | remove
  • esxcli network ip ipsec sp add | list | remove

New esxcli network ip route namespace provides namespaces and commands that correspond to the vicfg-route command and provides new functionality for managing routes.

  • esxcli network ip route ipv4 add | list | remove
  • esxcli network ip route ipv6 add | list | remove

New set of commands for retrieving networking statistics.

  • esxcli network nic stats get
  • esxcli network vlan stats get
  • esxcli network port filter stats get
  • esxcli network port stats get
  • esxcli network vm list
  • esxcli network vm port list

New set of commands for listing and resetting VXLAN distributed switches.

  • esxcli network vswitch dvs vmware vxlan list
  • esxcli network vswitch dvs vmware vxlan network list
  • esxcli network vswitch dvs vmware vxlan network mapping list | reset
  • esxcli network vswitch dvs vmware vxlan network port list
  • esxcli network vswitch dvs vmware vxlan network port stats list | reset
  • esxcli network vswitch dvs vmware vxlan network stats list | reset
  • esxcli network vswitch dvs vmware vxlan stats list | reset
  • esxcli network vswitch dvs vmware vxlan vmknic list
  • esxcli network vswitch dvs vmware vxlan vmknic multicastgroup list
  • esxcli network vswitch dvs vmware vxlan vmknic stats list | reset
  • esxcli network vswitch dvs vmware vxlan config stats get | set

Other new networking commands

  • esxcli network ip interface tag add | get | remove
  • esxcli network sriovnic list
  • esxcli network sriovnic vf list

New namespace for retrieving and changing the system-wide shared swap space.

  • esxcli sched swap system get | set

New commands for listing device information.

  • esxcli storage core device partition showguid
  • esxcli storage core device smart get

New commands for retrieving and setting maintenance mode and for performing shutdown operations that correspond to vicfg-hostops commands.

  • esxcli system maintenanceMode get
  • esxcli system maintenanceMode set
  • esxcli system shudown poweroff
  • esxcli system shudown reboot

New hardware ipmi namespace for checking for IPMI system event logs (SEL) and sensor data records (SDR)

  • esxcli hardware ipmi fru get | list
  • esxcli hardware impi sdr get | list
  • esxcli hardware impi sel get | list

Miscellaneous new commands.

  • esxcli hardware trustedboot
  • esxcli network diag ping
  • esxcli system coredump network check

 

Changed Commands

The following commands have changed in vCLI 5.1.

  • The resxtop command now requires an SSL connection.
  • The vicfg-user command no longer supports the group option.

Documentation

vSphere CLI 5.1 documentation is available in the vSphere Documentation Center, in searchable HTML and in PDF format.

Command-line help for each vicfg- command and ESXCLI command is available.

The technical note Command-Line Management of vSphere 5 for Service Console Users (PDF) is for administrators who migrate from ESX to ESXi and includes reference information that maps deprecated esxcfg- commands to vCLI commands.

Installing vCLI

The vCLI installer behaves differently for RHEL and for other Linux distributions.

Installing vCLI on RHEL

On RHEL, the vCLI installer prompts you whether you want to install required Perl modules from the installation package or from CPAN. You can install from the package if you do not have Internet access.

  1. Uninstall any existing versions of vCLI by running <install_dir>/vmware-uninstall-vSphere-CLI.pl. The default installation directory is /usr/bin.
  2. Delete any existing versions of: the vCLI installation
     rm -rf <install_dir>/vmware-vsphere-cli-distrib
  3. Download and untar vCLI 5.1.
  4. When prompted, choose Yes to install the missing Perl modules from the vCLI package.

The vCLI 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 Getting Started with vSphere Command-Line Interfaces.

Installing vSphere vCLI on Other Linux Distributions

For other supported Linux distributions, the vCLI installer works the way it did for vCLI 5.0. If you have Internet access, you can also direct the RHEL installer to follow this procedure.

  • Explicitly uninstalling previous versions of the software is no longer required.
  • You must have access to the Internet to successfully install vSphere SDK for Perl.
  • You must set your http:// and ftp:// proxies, as follows:
    export http_proxy=http://<proxy_server>:port
    export ftp_proxy=http://<proxy_server>:port
  • The installer installs missing Perl modules from CPAN, but does not overwrite existing versions of those modules.

Note: Downloading modules from CPAN can take a long time.

See Getting Started with vSphere Command-Line Interfaces available in the vSphere Documentation Center.

Installing vCLI on Windows

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 do not reboot, ActivePerl might report that it cannot find some of the Perl modules.

Supported Platforms

For this release, vCLI is supported on the following Linux platforms:

  • Red Hat Enterprise Linux (RHEL) 5.5 (32 bit and 64 bit)
  • SLES 10 SP1 (32 bit and 64 bit)
  • SLES 11 (32 bit and 64 bit)
  • SLES 11 SP1 (32 bit and 64 bit)
  • Ubuntu 10.04.1 (32 bit and 64 bit)

For this release, vCLI is supported on the following Windows platforms:

  • Windows 7 (32 bit and 64 bit)
  • Windows Vista Enterprise SP1 (32 bit and 64 bit)
  • Windows 2008 (64 bit)

The vSphere Management Assistant (vMA) is included in this release. You cannot upgrade vMA 4.1 to include vCLI 5.1 by running the vCLI installer inside vMA. Deploy the new vMA appliance.

 

Known Issues

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.1 release has the following new known issues:

  • resxtop cannot connect to ESXi 5.1 hosts.
    With vSphere 5.1, the ESXi host daemon only loads SSL certificates when they are valid. As a result of this change in behavior, resxtop might not be abe to connect to you ESXi server.

    Workaround: To resolve the issue, you have to make sure resxtop has a valid certificate.

    • If your current certificate is valid, that is, it is correctly loaded and has not yet expired, your ESXi host can use that certificate.
    • If the current certificate is expired or loaded incorrectly, you can generate and load a new certificate.

  • Installation fails on RHEL 5.5, 32 bit system with SELinux enabled and no Internet access.
    You attempt to install vCLI on a RHEL 5.5, 32-bit system with precompiled perl modules, that is, without accessing CPAN, in an environment where SELinuxis enabled. The installer fails with an error like the following:
    The following Perl modules were not found on the system. These must be installed for use by vSphere CLI: UUID 0.03 or newer.

    Workaround: Disable SELinux temporarily. The installation succeeds.

  • vicfg-user group management commands do not work.
    When you run vicfg-user with the group option, a SOAP fault results.

    Workaround: None. vSphere 5.1 no longer supports host-specific groups.

  • resxtop fails to run agains vSphere targets
    When you run resxtop against a vSphere 5.1 target, an error results.

    • If the SSL certificate is set in the vCLI client, the following error results:
      SSL Exception: Verification parameters
    • If the SSL certificate is not set, the following error results:
      Login failed, reason: HTTPS_CA_FILE or HTTPS_CA_DIR not set

    Workaround: If your environment supports this, run esxtop in the ESXi Shell. Otherwise, no workaround.

  • Error when running esxcli software commands with a VIB or depot name that includes parentheses.
    When you run an esxcli software command and supply a VIB or an offline depot ZIP file that has a name with parentheses ( ) in it, a VIB download error or metadata download error results.
    For example a MetadataDownloadError results if you run the following command.
    esxcli software sources profile list --bundle [datastore(new)]bundle.zip

    Workaround: Rename the datastore or directory name to a name that does not include parentheses.

  • On SLES 10, Server version unavailable error when running vicfg- commands.
    When you run a vicfg- vCLI command, an error like the following might result.
    Server version unavailable at 'https://<server>/sdk/vimService.wsdl' at /usr/lib/perl5/5.8.8/VMware/VICommon.pm line 545

    Workaround: Follow these steps to resolve the issue:

    1. Make sure the version of the LWP::UserAgent Perl module is above 6.0.4.
    2. Turn off host name verification by running the following command:
      export PERL_LWP_SSL_VERIFY_HOSTNAME=0

  • No output when running the resxtop vCLI command.
    When you install vCLI on a Linux system and attempt to run the resxtop command, no output results.

    Workaround: No workaround. You might be able to run the esxtop command in the ESXi Shell if you have access to the system. Enable the shell before you run the command.

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

  • When running ESXCLI commands against vCenter Server 5.0 or 5.1, must target ESXi 5.0 or 5.1 hosts
    With vSphere 5.0 and vSphere 5.1, you can run ESXCLI against vCenter Server 5.0 or vCenter Server 5.1 and specify the target host with the --vihost parameter. If the target host is not an ESXi 5.0 or ESXi 5.1 system, the following error results.
    Runtime error: Cannot complete the operation due to an incorrect request to the server.

    Workaround: No workaround.

  • 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 --vib|-v, --depot|-d, or --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 vicfg-user vCLI.

    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 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:
    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.
    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 4.x systems, use esxtop instead. On ESXi 5.0 and ESXi 5.1 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.

    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:

    • 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 <ip_addr> --subnetmask <subnet_mask> --gateway <default_gateway> <adapter_name>

  • 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 cannot be set.

    Workaround: None

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