VMware

VMware vSphere PowerCLI Release Notes

Released 24 August 2011

Build 435426 is VMware vSphere PowerCLI 5.0.

VMware vSphere PowerCLI 5.0 Release Notes

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

This document contains the following information:

About VMware vSphere PowerCLI

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

Requirements

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

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

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

Supported Platforms

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

  • Windows 7
  • Windows 2008 Server
  • Windows Vista
  • Windows XP Service Pack 2
  • Windows Server 2003 Service Pack 2

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)

vSphere PowerCLI 5.0 supports the following VMware environments:

  • VMware ESXi 5.0
  • vCenter Server 5.0
  • VMware ESX 4.1 / vCenter Server 4.1
  • VMware ESXi 4.1
  • VMware ESX 4.0 Update 2 / vCenter Server 4.0 Update 2
  • VMware ESX 4.0 Update 1 / vCenter Server 4.0 Update1
  • VMware ESX 4.0i Update 1
  • VMware VirtualCenter 2.5 Update 6
  • VMware ESX 3.5 Update 5
  • VMware ESXi 3.5 Update 5
  • VMware ESX 3.0.3 Update1

What's New in This Release?

New Features

This release of vSphere PowerCLI introduces the following new capabilities:
  • Cloning templates with New-Template.
  • Copying files and folders from and to the guest operating system through the Copy-VMGuestFile cmdlet.
  • Joining domains through the Get-VMHostAuthentication and Set-VMHostAuthentication cmdlets.
  • Joining ESX hosts (version 4.1 and later) into an active directory through the Get-VMHostAuthentication and Set-VMHostAuthentication cmdlets.
  • Retrieving vCenter Server users and groups through the Get-VIAccount cmdlet.
  • Support for vCenter Servers in linked mode through the Connect-VIServer cmdlet.
  • Retrieving object properties through the Get-VIProperty cmdlet.
  • Moving virtual appliances through the Move-VApp cmdlets.
  • Importing compressed and chunked files through the Import-VApp cmdlet.
  • Importing and exporting virtual appliances in OVA format.
  • Support for the SSPI passthrough feature of VIX.
  • Support for storage DRS: creating virtual machines and hard disks on datastore clusters and defining anti-affinity rules.(experimental)

Additional Snapins

vSphere PowerCLI 5.0 introduces three additional snapins of cmdlets that cover specific vSphere functionalities:

  • VMware.VimAutomation.License : The Licensing snapin contains the Get-LicenseDataManager cmdlet for managing VMware License components..
  • VMware.ImageBuilder : The Image Builder snapin contains cmdlets for managing depots, image profiles, and VIBs.
  • VMware.DeployAutomation : The Auto Deploy snapin contains cmdlets that provide an interface to VMware Auto Deploy for provisioning physical hosts with ESXi software.

Discontinued Support

Support for PowerShell 1.0 will be removed in the next PowerCLI release.

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

Obtaining the Software

You can obtain the vSphere PowerCLI 5.0 from here.

Known Issues

vSphere PowerCLI 5.0 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

  • The LocalPath parameter set of Install-VMHostPatch does not work.
  • 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 (added to ref)

    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 CommandsToSwitchPathBlocksToSwitchPath, 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), 'VMotionEnabled' property of the second nic may 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. In the described scenario the second nic will become a 'candidate' nic for vMotion. If you want 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.

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.

Documentation

    The examples in section "Use ESXCLI with PowerCLI" in the PowerCLI 5.0 User's Guide, are not applicable to ESX versions later than 4.0.

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 vSphere PowerCLI 5.0:

Get-View

  • If a ManagedObjectReference object that points to StorageResourceManager is specified for the Id parameter, Get-View returns no result.
  • Get-View fails to retrive Cluster views if HA is enabled.

Get-VMGuestNetworkInterface

    Get-VMGuestNetworkInterface throws an error if there is a disconnected network adapter.

Get-VMGuestRoute

    On Windows operating systems, the Persistence property of the objects returned by Get-VMGuestRoute is incorrect.

Invoke-VMScript

  • On 64-bit operating systems, Invoke-VMScript works only in 32-bit mode.
  • Invoke-VMScript does not work if the guest operating system is installed on a drive other than C: or D:.
  • Running Invoke-VMScript against outdated VMware Tools might make the console non-responsive.
  • Invoke-VMScript might become non-responding.

New-OSCustomizationSpec

  • New-OSCustomizationSpec clones only the first object if an array of objects is provided.
  • VMware vClient shows an error message Error reading password when opening specifications that are created by New-OSCustomizationSpec with empty passwords.

New-Snapshot

    When run with the Quiesced switch parameter set to $true, New-Snapshot creates a snapshot with Quiesced property set to $false.

Set-HardDisk

  • Set-HardDisk fails to resize the hard disk, if the helper virtual machine cannot access the datastore where the target hard disk is located.
  • Set-HardDisk fails to resize the hard disk, if the power state of the helper virtual machine is powered on.
    Workaround: Refresh the helper virtual machine object before running Set-HardDisk.

Set-PowerCLIConfiguration

    Set-PowerCLIConfiguration does not set a persistent proxy policy.

Set-VM

  • Set-VM cannot modify the DrsAutomationLevel property of the virtual machine if the current value of the property is Disabled.
  • Set-VM accepts only values that are powers of 2 for the Numcpu parameter.

Set-VMGuestNetworkInterface

  • On Linux Red Hat 5, Set-VMGuestNetworkInterface cannot set static DNS addresses.
  • Set-VMGuestNetworkInterface cannot set the WinsPolicy property to dhcp.

Set-VMGuestRoute

    On Linux operating systems, Set-VMGuestRoute cannot modify routes.
    Workaround: Remove all guest routes and then add them one by one.

Set-VMHostNetwork

    Set-VMHostNetwork cannot configure  VMKernel devices.

vSphere SDK for .NET

    The ScreenDimensions property of the VMGuestInfo object is not populated.

Installing vSphere PowerCLI

VMware provides a single installer for vSphere PowerCLI.

To install vSphere PowerCLI

  1. Download vSphere PowerCLI 5.0.
  2. Launch the vSphere PowerCLI installer by double-clicking the executable file. In the Welcome page, click Next.
  3. To install vSphere PowerCLI in a non-default location, click Change in the Destination Folder page and select a different directory.
  4. In the Ready to Install the Program page, choose whether to create a desktop shortcut.
  5. Click Install to proceed with the installation.
  6. Click Finish to complete the installation process.