VMware

VMware vSphere PowerCLI Release Notes

Released 13 Jul 2010

Build 264274 is version 4.1 of VMware vSphere PowerCLI.

VMware vSphere PowerCLI 4.1 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 Service Pack 1
  • Windows PowerShell 1.0 or Windows PowerShell 2.0 Release To Manufacture (RTM).

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

Supported Platforms

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

vSphere PowerCLI 4.1 supports the following VMware environments:

  • VMware ESX 4.1 / vCenter Server 4.1
  • VMware ESX 4.1 i
  • 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.0 Update 1 i
  • VMware VirtualCenter 2.5 Update 6
  • VMware ESX 3.5 Update 5
  • VMware ESX 3.5 Update 5 i
  • VMware ESX 3.0.3 Update1

What's New in This Release?

This release of vSphere PowerCLI 4.1 introduces the following new capabilities:

  • Retrieving counters for real time statistics with Get-StatType.
  • Creating floppy image files with New-FloppyDrive.
  • Customizing objects returned by PowerCLI cmdlets with New-VIProperty and Remove-VIProperty.
  • Exposing the View object that corresponds to an object returned by a PowerCLI cmdlet through the object's ExtensionData property.
  • Retrieving, adding, and removing routes from the host route table through the Get-VMHostRoute, New-VMHostRoute, Set-VMHostRoute, and Remove-VMHostRoute cmdlets.
  • Specifying the virtual machine version through New-VM and Set-VM.
  • Generating error reports with the Get-ErrorReport cmdlet.
  • Retrieving host patches with the Get-VMHostPatch cmdlet.
  • Adding and removing virtual machines and network adapters from virtual distributed switches (vDS) with New-VM, New-NetworkAdapter, Set-NetworkAdapter, Set-VMHostNetworkAdapter, and Remove-VMHostNetworkAdapter.

For more information on changes made in vSphere PowerCLI 4.1, including improvements and security enhancements, see the vSphere PowerCLI Change Log.

Obtaining the Software

You can obtain vSphere PowerCLI 4.1 at:

http://www.vmware.com/go/powercli

Known Issues

vSphere PowerCLI 4.1 is known to have the following issues:

Add-PassthroughDevice

    Add-PassthroughDevice cannot add more than fifteen SCSI passthrough devices to a virtual machine.

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

    Copy-HardDisk does not work against ESX 3.5.

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.

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-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 a ManagedObjectReference object that points to StorageResourceManager is specified for the Id parameter, Get-View returns no result.

Get-VIEvent

  • If a non‑existing 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.

Get-VMGuest

  • When Get-VMGuest is run against a virtual machine that is just starting, the properties of the returned VMGuest object are not filled at one time.
  • Get-VMGuest incorrectly reports Windows Server 2008 guests operating systems as Windows Vista.

Get-VMGuestNetworkInterface

  • Get-VMGuestNetworkInterface does not work when the network is disconnected.
  • 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.

Install-VMHostPatch

  • On ESX 4.0, you cannot pass a path to a .vib file as an argument to the LocalPath parameter of 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

  • 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.
  • After installing Powershell 1.0, you must first reboot the virtual machine before running Invoke-VMScript with a PowerShell script.
  • Invoke-VMScript might become non-responding.
  • Invoke-VMScript does not work on Windows 2008 Server with PowerShell 2.0 installed.

New-HardDisk

  • When New-HardDisk is run, the Split parameter cannot be applied to the hard disk.
  • New-HardDisk cannot create an undoable disk on a powered-on virtual machine.

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.

Remove-Datastore

    When run against ESX 3.0 U1, Remove-Datastore might throw an error and fail to remove the specified datastores.

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-HardDisk cannot inflate a hard disk that has already been inflated.

Set-OSCustomizationSpec

    When customizing a Windows Server 2003 machine with Set-OSCustomizationSpec, the value of the LicenceMode property of the customization specification object must be either PerSeat or PerServer. For Windows XP and Linux machines, the LicenceMode property can be set to NotSpecified.

Set-PowerCLIConfiguration

    Set-PowerCLIConfiguration does not set a persistent proxy policy.

Set-ScsiLun

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

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 Windows operating systems, Set-VMGuestNetworkInterface becomes non-responding if the provided IP address conflicts with an existing IP address on the network.
  • 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-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-VMHostHba

    When Set-VmHostHba is run against vCenter Server, changing the iScsiName property of an iSCSI adapter modifies its AuthenticationCapabilities property.
    Workaround: Run Set-VmHostHba directly against ESX.

Set-VMHostNetwork

  • Set-VMHostNetwork cannot clear the values of the ConsoleV6Gateway and VMKernelV6Gateway properties of the input object.
  • Set-VMHostNetworkCannot set  VMKernel devices.

Set-VMHostDiagnosticPartition

    Enabling a diagnostic partition with the Set-VMHostDiagnosticPartition cmdlet does not work on VirtualCenter 2.0/ ESX 3.0 platforms.

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.

vSphere SDK for .NET

    The ScreenDimensions property of the VMGuestInfo object is not populated.

vSphere PowerCLI Installation

    When upgrading vSphere PowerCLI, the old version might not uninstall and thus vSphere PowerCLI might not upgrade properly.

Resolved Issues

The following issues have been resolved in vSphere PowerCLI 4.1:

Add-PassthroughDevice

    Add-PassthroughDevice modifies the property values of the object passed to the PassthroughDevice parameter.

Connect-VIServer

    If a default server is accidentally disconnected for some reason (for example, a session has expired), it is not automatically removed from the default servers variable $global:defaultVIServers.
    Workaround: To remove all disconnected servers from the default servers list, run:

    $global:defaultVIServers | where { -not $_.IsConnected } | Disconnect-VIServer -confirm:$false

Disconnect-VIServer

    If a default server has been accidentally disconnected, Disconnect-VIServer cannot find it by name.
    Workaround: Instead of specifying the server name, provide the corresponding VIServer object.

Get-View

    Get-View returns no result if a Cluster object is specified for the SearchRoot parameter.

Get-VIObjectByView

    When Get-VIObjectByVIView returns a VMHostNetwork object, some of the object properties might not be properly updated.

Get-VMGuestNetworkInterface

    Get-VMGuestNetworkInterface fails on Windows virtual machines if the name of the guest NIC is not Area Connection.

New-NetworkAdapter

    New-NetworkAdapter does not populate the MAC address property of the returned object when run against ESX Server 4.0 and ESXi Server 4.0.

New-OSCustomizationSpec

    The operating system customization specifications with passwords created by New-OSCustomizationSpec, if edited with vSphere Client, result in errors when applied.

New-VM

    New-VM can clone virtual machines using customization specification objects only of type Persistent.
    Workaround: Use Set-VM to apply customization specification objects of type NonPersistent.

New-VMHostNetworkAdapter

    New-VMHostNetworkAdapter cannot set the value of the MAC address when run against VirtualCenter 2.5 and ESX 3.5.

Set-NicTeamingPolicy

    The InheritNotifySwitches and InheritFailback parameters of Set-NicTeamingPolicy do not work.

Set-OSCustomizationSpec

    Set-OSCustomizationSpec cannot change the Domain property of a OS customization specification object.
    Workaround: Create a new OS customization specification.

Set-VMGuestNetworkInterface

    When Set-VMGuestNetworkInterface is run with the WinsPolicy parameter set to dhcp, the RouteInterfaceId property of the returned object is empty.

Datastore Provider

    Tab completion in the Datastore Provider is slow.

Running Cmdlets Asynchronously

    When a cmdlet is run with the RunAsynch switch parameter, some of the properties of the output Task object might not be populated.

VIX Compatibility

    Invoke-VMScript, Copy-VMGuestFile, and all VMGuestNetworkInterface and VMGuestRoute cmdlets require VIX version 1.6.2 to run.

vSphere PowerCLI Installation

    The vSphere PowerCLI installer might become non-responsive for more than thirty minutes depending on the machine configuration environment.

Installing vSphere PowerCLI

VMware provides a single installer for vSphere PowerCLI.

To install vSphere PowerCLI

  1. Download vSphere PowerCLI 4.1 from the VMware vSphere PowerCLI home page.
  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 nondefault 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.

For a more detailed description of the vSphere PowerCLI installation process and prerequisites, see the Installation Guide for vSphere PowerCLI .

Last updated 19-July-2010 11:30 am [PDT]