VMware

VMware vSphere PowerCLI Release Notes

Released 09 January 2012

Build 581491 is VMware vSphere PowerCLI 5.0.1.

VMware vSphere PowerCLI 5.0.1 Release Notes

VMware vSphere PowerCLI provides an easy-to-use Windows Powershell interface to the vSphere and vCloud APIs. VMware vSphere PowerCLI includes numerous cmdlets, sample scripts, and a function library.

This document contains the following information:

About VMware vSphere PowerCLI

VMware vSphere PowerCLI is a command-line and scripting tool built on Windows PowerShell, and provides more than 200 cmdlets for managing and automating vSphere and vCloud.

VMware vSphere PowerCLI Components And Versioning

VMware vSphere PowerCLI 5.0.1 consists of two components:
  • vSphere PowerCLI 5.0 is the core component of the PowerCLI package. It contains four snapins with cmdlets for managing vSphere 5.0 features:
    • VMware.VimAutomation.Core: VMware vSphere PowerCLI 5.0 provides cmdlets for automated administration of the vSphere environment.
    • VMware.VimAutomation.License: VMware License PowerCLI 5.0 provides the Get-LicenseDataManager cmdlet for managing VMware License components.
    • VMware.ImageBuilder: VMware ImageBuilder PowerCLI 5.0 provides cmdlets for managing depots, image profiles, and VIBs.
    • VMware.DeployAutomation: VMware Auto Deploy PowerCLI 5.0 provides cmdlets that provide an interface to VMware Auto Deploy for provisioning physical hosts with ESXi software.
  • vCloud Director PowerCLI 1.5 is an optional component that you can install during the PowerCLI installation. It provides the VMware vCloud Director PowerCLI 1.5 snapin (VMware.VimAutomation.Cloud) with cmdlets for automating the vCloud Director 1.5 features.

Requirements

To use VMware vSphere PowerCLI, you need to have installed the following software:

  • .NET 2.0, 3.0, or 3.5 with Service Pack 1
  • Windows PowerShell 2.0

If .NET is installed without Service Pack 1, some operations might take long to complete.

Supported Platforms

VMware vSphere PowerCLI 5.0.1 works on the 32-bit and 64-bit versions of the following operating systems:

  • Windows 7 Service Pack 1
  • Windows Server 2008 R2 Service Pack 1
  • Windows XP Service Pack 2 and Service Pack 3 (on 32 bit)
  • Windows Server 2003 R2

The following PowerCLI features are supported only on the 32-bit version of Windows PowerShell.

  • New-OSCustomizationSpec and Set-OSCustomizationSpec
  • New-VM and Set-VM (only when used for applying customization specifications)
  • Invoke-VMScript
  • Copy-VMGuestFile
  • New-VMGuestRoute, Get-VMGuestRoute, and Remove-VMGuestRoute
  • New-VMGuestNetworkInterface and Set-VMGuestNetworkInterface
  • Set-HardDisk ( only when used for resizing guest disk partitions)

VMware vSphere PowerCLI 5.0.1 supports the following VMware environments:

  • VMware ESXi 5.0
  • vCenter Server 5.0
  • VMware ESX 4.1 Update 2 / vCenter Server 4.1 Update 2
  • VMware ESXi 4.1 Update 2
  • VMware ESX 4.0 Update 4 / vCenter Server 4.0 Update 4
  • VMware ESX 4.0i Update 4
  • VMware VirtualCenter 2.5 Update 6
  • VMware ESX 3.5 Update 5
  • VMware ESXi 3.5 Update 5
vCloud Director PowerCLI 1.5 is compatible with VMware vCloud Director 1.5.

What's New in This Release?

New Features

This release of VMware vSphere PowerCLI introduces the VMware vCloud Director PowerCLI 1.5 snapin (VMware.VimAutomation.Cloud) with cmdlets for automating the vCloud Director 1.5 features.

This release introduces the Get-CIView cmdlet for retrieving cloud view objects. Note: This is an experimental feature. For an explanation of how experimental support is different from full support, see VMware Experimental Feature Support.

Deprecated Features

Working with multiple servers will be enabled by default in a future release. You can explicitly set your own preference by using the DefaultServerMode parameter of Set-PowerCLIConfiguration.

For more information on changes made in PowerCLI 5.0.1, see the VMware vSphere PowerCLI Change Log.

Obtaining the Software

You can obtain VMware vSphere PowerCLI 5.0.1 from here.

Known Issues

VMware vSphere PowerCLI 5.0.1 is known to have the following issues:

Apply-DrsRecommendation

    Apply-DrsRecommendation runs in asynchronous mode even when called without the RunAsync parameter.

Copy-DatastoreItem

    Copy-DatastoreItem throws an error when uploading an item to the root folder of a Datastore Provider drive.

Copy-HardDisk

    On vCenter Server 5.0, Copy-HardDisk cannot change the storage format of the destination hard disk.

Get-Datastore

    (Get-Datastore).FreeSpaceMB might not return the actual datastore free space after a virtual machine is powered on. A refresh should be made first.

Format-VMHostDiskPartition

    On ESX 3.5, Format-VMHostDiskPartition throws an error and does not create a datastore, although the specified VMHost disk partition is formatted with VMFS and you can run New-Datastore to create a datastore from the formatted partition.

Get-HardDisk

    The value of the Persistence property of the object returned by Get-HardDisk is different depending on the way the hard disk is obtained by the cmdlet.

Get-NetworkAdapter

  • Get-NetworkAdapter does not throw an error message if you try to retrieve a nonexisting adapter.
  • Get-NetworkAdapter returns only one object, when you try to retrieve existing network adapters by name from two virtual machines or snapshots.

Get-ScsiLun

    When you use Get-ScsiLun to retrieve Powerpath devices, the value of their MultipathPolicy property is shown as Unknown.

Get-Template

    The Location parameter of Get-Template does not accept Cluster objects.

Get-UsbDevice

  • Get-UsbDevice does not work on ESX Server 3.5 Update 4 and ESX Server 3.5i platforms.
  • Get-UsbDevice cannot obtain USB devices from snapshots.

Get-View

    If you run Get-View with the SearchRoot and ViewType parameters and specify a property path for the Property parameter, the linked view of the cmdlet output will not be populated.

Get-VIEvent

  • If a nonexisting user is specified, Get-VIEvent returns the events for all existing users.
  • Objects returned by Get-VIEvent contain ManagedObjectReference types that are not compatible with the Get-View cmdlet.

Get-VM

  • During the process of creating a template from a virtual machine, Get-VM returns both the virtual machine and template objects.
  • If you try to retrieve virtual machines by their IDs and the list of the provided IDs contains the IDs of removed virtual machines, Get-VM returns no value.

Get-VMHostProfileRequiredInput

    On vCenter Server 5.0, Get-VMHostProfileRequiredInput returns a result even if you pass a hashtable with inapplicable elements.

Install-VMHostPatch

  • Install-VMHostPatch cannot install patches on diskless ESXi servers.
  • Install-VMHostPatch cannot install patches on ESX 3.5.
  • Install-VMHostPatch cannot apply VIB patches.
    Workaround: Use metadata.zip patches.

Invoke-VMScript

    When using Invoke-VMScript to invoke multi-line BAT and BASH scripts, the command might not run all the script lines.

New-HardDisk

    New-HardDisk does not ask for confirmation when you try to create a VMDK anti-affinity rule that overwrites an existing one.

New-OSCustomizationSpec

    Cloning a server-side customization specification with New-OSCustomizationSpec changes the values of the PlainText properties from true to false.

New-VIPermission

    If you use New-VIPermission to create a permission for a distributed switch, the Entity property of the returned object is null.

New-VMHostNetworkAdapter

    New-VMHostNetworkAdapter cannot configure the MAC address on VirtualCenter Server 2.5 and ESX 3.5 hosts.

Set-Annotation

    Set-Annotation cannot set an annotation for a custom attribute if another custom attribute with the same name exists.

Set-HardDisk

    Increasing the size of a system partition on Windows 7 and Windows 2008 by using the GuestDiskResize parameter of Set-HardDisk is not supported.

Set-ResourcePool

    Set-ResourcePool disconnects the vCenter Server if the name you pass to the Name parameter already exists for another resource pool on the server.

Set-ScsiController

    Set-ScsiController cannot set both the Type and BusSharing parameters at the same time.
    Workaround: First run the cmdlet to set the type and then run it again to configure the bus sharing mode.

Set-ScsiLun

    The CommandsToSwitchPath,  BlocksToSwitchPath, NoCommandsSwitch, and NoBlocksSwitch parameters of Set-ScciLun do not work on ESX 4.0 and later.

Set-VM

    On vCenter Server 5.0, when you use Set-VM to upgrade the VM hardware version, the output of the cmdlet displays the old value although the version has been updated successfully.

Set-VMGuestNetworkInterface

    On Windows operating systems, Set-VMGuestNetworkInterface becomes non-responding if the provided IP address conflicts with an existing IP address on the network.

Set-VMHost

    Set-VMHost might not populate the VMSwapfileDatastoreId property of the returned VMHost object when VMSwapFilePolicy or VMSwapFileDatastore properties are modified.
    Workaround: Use Get-VMHost to retrieve the object returned by Set-VMHost.

Set-VMHostNetwork

    Set-VMHostNetwork cannot clear the values of the ConsoleV6Gateway and VMKernelV6Gateway properties of the input object.

Set-VMHostNetworkAdapter

    If you have vMotion enabled on one VMKernel NIC and you enable it on a second NIC on the same switch using Set-VMHostNetworkAdapter, the VMotionEnabled property of the second NIC might still report that vMotion is not enabled. This is due to the fact that there can only be one NIC selected for vMotion, but more than one can be candidate NICs for vMotion. To change the currently active vMotion NIC, first disable the current one and then enable the one you want.

Set-VMGuestNetworkInterface

    Changing the value of the IPPolicy parameter to Static with Set-VMGuestNetworkInterface changes the value of the WinsPolicy parameter to Static as well.

Set-VMHostNetworkInterface

    Set-VMGuestNetworkInterface cannot configure correctly the DNS address on Linux operating systems.

Set-VMHostSNMP

  • The default value of the Set-VMHostSNMP TargetPort parameter is a random number instead of the port number.
  • Set-VMHostSNMP skips the value of the TargetPort parameter.
  • Set-VMHostSNMP fails to enable VMHostSNMP and to set the ReadOnlyCommunityString when called for the first time.
    Workaround: Run the command again.

Get-CIVM

    While logged on as SysAdmin the Get-CIVM cmdlet returns system vShield Edge virtual machines used to establish perimeter security in the NAT routed network.

Get-CIVApp

    Get-CIVApp returns all virtual appliance objects in the inventory including expired ones.

Get-CIVAppTemplate

    Get-CIVAppTemplate returns all virtual appliance templates in the inventory including expired ones.

PowerCLI in-guest commands

While connected to a vCenter Server 5.x that manages ESX 4.x hosts, the following PowerCLI in-guest commands will not work against virtual machines on those ESX hosts:
  • Invoke-VMScript
  • Get/Set-VMGuestNetworkInterface
  • Get/New/Remove-VMGuestRoute
  • Copy-VMGuestFile
Workaround: Do one of the following.
  • Migrate the virtual machines to an ESXi 5.0 host and upgrade their VMware Tools.
  • Upgrade the ESXi 4.x hosts to ESXi 5.0 and upgrade the VMware Tools on all virtual machines.
  • Use an older version of PowerCLI (e.g. 4.1.1) for invoking commands.
Inventory Provider
    When run within the Inventory Provider, Get-Datacenter returns the datacenters from the default servers instead from the VIServer folder of the Inventory Provider drive.

Other

  • On vCenter Server 5.0/ ESXi 5.0 platforms, all guest-related cmdlets have slow and unstable behavior due to the slow performance of VMware Tools.
  • The VirtualMachine parameter of the PowerCLI cmdlets is defined with the deprecated Description property of the VirtualMachine type, instead of the new one named Notes. In result, The PowerShell auto-complete function works with the deprecated property name.
  • The types labels in the UpdateViewData property are case-sensitive.
  • When running in 64-bit mode, PowerCLI cannot detect the registry key HKEY_LOCAL_MACHINE\SOFTWARE\VMware, Inc.\VMware vSphere PowerCLI\, which is used for determining the PowerCLI installation folder. Instead, you can use the following key: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\VMware, Inc.\VMware vSphere PowerCLI.
  • The Model and Vendor properties of the ScsiLun objects are always filled up with white-spaces to 16 (for Model) and 8 (for Vendor) characters.
  • All VIX cmdlets support using SSPI for Windows guest machines if the underlying vCenter Server is 5.0 version. This might not be valid for users who are local, and not domain users. VIX cmdlets are Invoke-VMScript, Copy-VMGuestFile, *-VMGuestNetworkInterface, *-VMGUestRoute, and Set-HardDisk when used for guest disk resizing.

Resolved Issues

The following issues have been resolved in VMware vSphere PowerCLI 5.0.1:

Install-VMHostPatch

    The LocalPath parameter set of Install-VMHostPatch does not work.

Installing VMware vSphere PowerCLI

VMware provides a single installer for VMware vSphere PowerCLI.

To install VMware vSphere PowerCLI components

  1. Download VMware vSphere PowerCLI 5.0.1.
  2. Navigate to the local folder that contains the PowerCLI installer file you downloaded and double-click the executable file.
  3. On the Welcome page, click Next.
  4. On the VMware Patents page click Next.
  5. Accept the license agreement terms and click Next.
  6. On the Custom Setup page, select the PowerCLI components you want to install. If you want to change the default location to install VMware vSphere PowerCLI click Change and select a different Destination Folder. After you are done click Next.
  7. On the Ready to Install the Program page, click Install to proceed with the installation.
  8. Click Finish to complete the installation process.

For more information about installing PowerCLI 5.0.1, see the VMware vSphere PowerCLI 5.0.1 User's Guide.