VMware

VMware vSphere PowerCLI Release Notes

Released 1 December 2010

Build 332441 is version 4.1 Update 1 of VMware vSphere PowerCLI.

VMware vSphere PowerCLI 4.1 Update 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 following 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 Update 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 Update 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 2 i
  • VMware VirtualCenter 2.5 Update 6
  • VMware ESX 3.5 Update 5
  • VMware ESX 3.5 Update 5 i

What's New in This Release?

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

  • Using the ESX CLI and ESX Top features of VMware vSphere. (experimental)
  • Working with distributed switches and distributed switch port groups.
  • Supporting SCSI controllers.
  • Querying and modifying vCenter Server alarms.
  • Managing advanced vCenter Server settings and Cluster HA advanced options.
  • Waiting for VMware Tools of the specified virtual machines to load.
  • Querying information about disk and disk partitions of hosts.
  • Formatting host disk partitions.
  • Querying the primary HA cluster nodes.
  • Zeroing out virtual machine hard disks.

In addition, the following changes were made in PowerCLI 4.1 Update 1:

  • The DeleteFromDisk parameter of the Remove-VM, Remove-Folder, Remove-HardDisk, Remove-Template, and Remove-VApp cmdlets is now renamed to DeletePermanently.
  • The Set-VMGuestRoute cmdlet was removed for usability and stability reasons. Instead of modifying a route, you can create a new route and delete the old one.

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

Obtaining the Software

You can obtain vSphere PowerCLI 4.1 Update 1 at:

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

Known Issues

vSphere PowerCLI 4.1 Update 1 is known to have the following issues:

Apply-DrsRecommendation
    Apply-DrsRecommendation runs in asynchronous mode even when called without the RunAsync parameter.
Add-PassthroughDevice
    When adding multiple SCSI passthrough devices that require a second SCSI controller, first SCSI device on the second controller has wrong controller ID.
Connect-VIServer
    Every time when you try to connect to more than one server by using the Connect-VIServer cmdlet, PowerCLI prompts you to choose the server connection mode you want to use.
Copy-DatastoreItem
    Copy-DatastoreItem throws an error when uploading an item to the root folder of a Datastore Provider drive.
Format-VMHostDiskPartition
    On ESX 3.5 hosts, Format-VMHostDiskPartition throws an error and does not create a datastore, although the cmdlet successfully formats the specified VMHost disk partition with VMFS.
    Workaround: Use New-Datastore to create a datastore out of the formatted partition.
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-VIEvent
    Objects returned by Get-VIEvent contain ManagedObjectReference types that are not compatible with the Get-View cmdlet.
Get-VirtualPortGroup
    If you use the VirtualSwitch parameter of Get-VirtualPortGroup to specify a distributed virtual switch by its name, the cmdlet returns an error.
Get-VM
    During the process of creating a template from a virtual machine, Get-VM returns both the virtual machine and template objects.
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, the following cmdlets work only in 32-bit PowerCLI mode:
    • Invoke-VMScript
    • Copy-VMGuestFile
    • New-VMGuestRoute, Get-VMGuestRoute, and Remove-VMGuestRoute
    • New-VMGuestNetworkInterface and Set-VMGuestNetworkInterface
    • Set-HardDisk (only when resizing guest disk partitions).
New-AlarmActionTrigger
    On VirtualCenter 2.5, New-AlarmActionTrigger does not support the Repeat parameter but does not display an error message when you try to set this parameter.
New-HardDisk
    New-HardDisk cannot create an undoable disk on a powered-on virtual machine.
New-ScsiController

    When you create a new SCSI controller for a hard disk, the corresponding HardDisk object becomes invalid.
    Workaround: After you create the new SCSI controller , run the Get-HardDisk cmdlet to retrieve the hard disk again. For example:
    $controller = New-ScsiController -HardDisk $hardDisk -BusSharingMode "NoSharing" -Type "VirtualLsiLogic"
    $hardDisk = Get-HardDisk -VM $vm | ? {$_.Filename -eq $hardDisk.Filename}

New-Snapshot
    When run with the Quiesced switch parameter set to $true, New-Snapshot creates a snapshot with Quiesced property set to $false.
Remove-VMHostRoute
    Remove-VMHostRoute cannot remove a host route with destination 0.0.0.0 and prefix length 0.
Set-AlarmDefinition
  • On VirtualCenter 2.5, Set-AlarmDefinition does not support the ActionRepeatMinutes parameter but does not display an error message when you try to set this parameter.
  • The ActionRepeatMinutes parameter of Set-AlarmDefinition takes values in seconds instead of minutes, as the parameter name suggests. The ActionRepeatMinutes property of all AlarmDefinition objects returned by Set-AlarmDefinition and Get-AlarmDefinition is set in seconds as well.
Set-ScsiController
    On ESX 3.5, Set-ScsiController does not update the bus sharing mode when you provide both the Type and BusSharing parameters.
    Workaround: Update the type and the bus sharing mode in two consecutive calls of the Set-ScsiController cmdlet.
Set-ScsiLun
    Set-ScciLun does not work on ESX 4.0 and vCenter Server 4.0.
Set-VMGuestInterface
    Set-VMGuestNetworkInterface does not update correctly DNS values on Linux operating systems.
Set-VMHost
  • Set-VMHost throws an error when run on a disconnected host.
  • 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.
  • When Set-VMHost is run with both the VMSwapfilePolicy and VMSwapFileDatastore parameters, the VMSwapfileDatastoreId property of the returned object is not updated.
Set-VMHostNetwork
  • Set-VMHostNetwork cannot clear the values of the ConsoleV6Gateway and VMKernelV6Gateway properties of the input object.
  • Set-VMHostNetworkCannot set  VMKernel devices.
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.

Resolved Issues

The following issues have been resolved in vSphere PowerCLI 4.1Update 1:

Add-PassthroughDevice

    Add-PassthroughDevice cannot add more than fifteen SCSI passthrough devices to a virtual machine.
Get-VIEvent
    If a non‑existing user is specified, Get-VIEvent returns the events for all existing users.
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.
Invoke-VMScript
  • Running Invoke-VMScript against outdated VMware Tools makes the console non-responsive.
  • Invoke-VMScript might become non-responding.
  • Invoke-VMScript does not work if the guest operating system is installed on a drive other than C: or D:.
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.
Remove-Folder
    The WhatIf and Confirm parameters of Remove-Folder do not work as expected.
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 RedHat 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.
Datastore Provider
    Files cannot be copied in or out the Datastore Provider.
vSphere SDK for .NET
    The ScreenDimensions property of the VMGuestInfo object is not populated.
vSphere PowerCLI Compliance with WorkStation
    When vSphere PowerCLI is installed on a machine with Workstation already installed, the VIX API is not upgraded and the vSphere PowerCLI functionality that depends on VIX (for example, Invoke-VMScript) does not work.
    Workaround: Before installing vSphere PowerCLI, uninstall Workstation. After installing vSphere PowerCLI, install Workstation again.

Installing vSphere PowerCLI

VMware provides a single installer for vSphere PowerCLI.

To install vSphere PowerCLI
  1. Download vSphere PowerCLI 4.1 Update 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 18-Feb-2011 11:30 am [PDT]