VMware

VMware vSphere PowerCLI Release Notes

Released 19-Nov-2009

Build 208462 is version 4.0 Update 1 of VMware vSphere PowerCLI.

VMware vSphere PowerCLI 4.0 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 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.0 Update 1 works on the 32-bit and 64-bit versions of the following operating systems:

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

vSphere PowerCLI 4.0 Update 1 supports the following VMware environments:

  • VMware ESX Server 3.5
  • VMware ESXi Server 3.0
  • VMware VirtualCenter 2.5
  • VMware ESX 3.0 and VirtualCenter 2.0
  • VMware ESX 4.0 and vCenter 4.0
  • VMware ESXi 4.0
  • VMware ESX 4.0 Update 1 and vCenter 4.0 Update 1

 

What's New in This Release?

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

  • Managing the failover and load-balancing policies of VirtualSwitch and VirtualPortGroup objects with Get-NicTeamingPolicy and Set-NicTeamingPolicy.
  • Copying files in and out of guest operating systems with Copy-VMGuestFile.
  • Restarting virtual machines with Restart-VM.
  • Managing the power state of hosts using Start-VMHost, Restart-VMHost, Suspend-VMHost, and Stop-VMHost.
  • Managing guest networks with Get-VMGuestNetworkInterface, Set-VMGuestNetworkInterface, Get-VMGuestRoute, New-VMGuestRoute, Remove-VMGuestRoute, and Set-VMGuestRoute.
  • Retrieving and removing USB devices with Get-UsbDevice and Remove-UsbDevice.
  • Managing NIC customization settings with Get-OSCustomizationNicMapping, New-OSCustomizationNicMapping, and Set-OSCustomizationNicMapping.
  • Handling virtual machine questions with Get-VMQuestion and Set-VMQuestion.
  • Working with host storages and iSCSI HBA devices with Get-VMHostHba, Set-VMHostHba, Get-iScsiHbaTarget, New-iScsiHbaTarget, Remove-iScsiHbaTarget, Set-iScsiHbaTarget, and Set-VMHostStorage.
  • Moving templates with Move-Template and Move-Inventory.
  • Managing the access control system with Get-VIPrivilege, Get-VIRole, New-VIRole, Remove-VIRole, Set-VIRole, Get-VIPermission, New-VIPermission, Remove-VIPermission, and Set-VIPermission.
  • Managing DRS recommendations with Get-DrsRecommendation and Apply-DrsRecommendation.
  • Upgrading hosts with Install-VMHostPatch.
  • Managing virtual appliances with Get-VApp, Export-VApp, Import-VApp, New-VApp, Remove-VApp, Set-VApp, Start-VApp, and Stop-VApp.
  • Managing PCI and SCSI passthrough devices with Add-PassthroughDevice, Get-PassthroughDevice, and Remove-PassthroughDevice.
  • Running BAT (Windows) and BASH (Linux) scripts with Invoke-VMScript.
  • Granting and revoking shell access with New-VMHostAccount and Set-VMHostAccount.
  • Uploading firmware packages with Set-VMHostFirmware.
  • Creating virtual machines with thin provisioned disks with New-VM.
  • Cloning powered-on virtual machines with New-VM.
  • Resizing virtual disks and guest partitions with Set-HardDisk.
  • Extending, cloning, inflating, and reallocating virtual hard disks with Copy-HardDisk, New-HardDisk, and Set-HardDisk.
  • Managing the host time zones with Get-VMHostAvailableTimeZone and Set-VMHost.
  • Working with default Datastore Provider and Inventory Provider drives.
  • Working with files and directories in datastores by using the Datastore Provider.

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

Obtaining the Software

You can obtain vSphere PowerCLI 4.0 Update 1 at:

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

Known Issues

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

Add-PassthroughDevice

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

Apply-DrsRecommendation

    Apply-DrsRecommendation runs in asynchronous mode even when called without the RunAsync 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

Copy-DatastoreItem

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

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-CDDrive

    Get-CDDrive cannot obtain a CD drive from a snapshot, when you are connected to ESX Server 3.5 Update 4 and ESX Server 3i.

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-ScsiLunPath

    When running Get-ScsiLunPath, the SCSI device cannot be specified by name.

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

  • When Get-VIEvent is run for entities other than virtual machines, an incorrect result is returned.
  • 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-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-VIObjectByVIView cannot convert network MORs (Managed Object References) into VirtualPortGroup objects.

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 fails on Windows virtual machines if the name of the guest NIC is not Area Connection.

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.

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 makes the console non-responsive.
  • Invoke-VMScript requires a reboot of the virtual machines after installing vSphere PowerCLI, otherwise the cmdlet returns no result.

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-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-Snapshot

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

New-VM

  • New-VM cannot create virtual machines whose names contain special symbols ( ~!@#$%^&*()-_=+[]\\{}|;':\`",./<>?-) on VirtualCenter 2.0 and ESX 3.0.
  • 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.

Remove-Template

    When invoked with the DeleteFromDisk switch parameter set to $true, Remove-Template is not run synchronously.

Remove-VMHostNtpServer

    Remove-VmHostNtpServer does not accept a pipeline input for the NtpServer parameter.

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

    Set-ScciLun does not work on ESX 4.0 and vCenter Server 4.0.

Set-VMGuestNetworkInterface

  • When Set-VMGuestNetworkInterface is run with the WinsPolicy parameter set to dhcp, the RouteInterfaceId property of the returned object is empty.
  • Set-VMGuestNetworkInterface cannot modify the IP and Gateway properties of the input object.

Set-VMGuestRoute

    Set-VMGuestRoute cannot modify the IP and Gateway properties of the input object.

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

Inventory Provider

  • If you run the dir command while the Inventory Provider is running, the output might be difficult to read.
  • 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.

Datastore Provider

  • Files cannot be copied in or out the Datastore Provider.
  • Tab completion in the Datastore Provider is slow.

vSphere SDK for .NET

    The ScreenDimensions property of the VMGuestInfo object is not populated.

Backward Compatibility

    In vSphere PowerCLI 4.0 Update 1, the ChangeSid and DeleteAccounts property types of the OSCustomizationSpec object are changed. This results in backward binary incompatibility between vSphere PowerCLI 4.0 and VI Toolkit (for Windows) 1.0.

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.

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

  • When upgrading vSphere PowerCLI, the old version might not uninstall and thus vSphere PowerCLI might not upgrade properly.
  • The vSphere PowerCLI installer might become non-responsive for more than thirty minutes depending on the machine configuration environment.

 

Resolved Issues

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

Get-Datastore

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

Get-Log

    The output of Get-LogType cmdlet cannot be pipelined to the Get-Log cmdlet.

Get-VIEvent

    When Get-VIEvent is run on a machine whose time zone setting differs from the time zone setting of the ESX host, providing server time to the Start and Finish parameters might give incorrect or no result.

Get-VMHost

    Passing a resource pool through a pipeline to the Get-VMHost cmdlet does not work properly unless the Location parameter is specified explicitly.

Get-VMHostAdvancedConfiguration

    Get-VMHostAdvancedConfiguration returns null when run against vCenter Server and ESX.

Invoke-VMScript

    Invoke-VMScript might stop responding when run against a virtual machine running on ESX 3.0.

Move-Inventory

    Move-Inventory does not work with virtual machine templates.

New-HardDisk

    New-HardDisk cannot create a new virtual hard disk on a virtual machine that has no hard disks.

New-VMHostNetworkAdapter

    New-VMHostNetworkAdapter does not accept object names as arguments for the VirtualSwitch parameter.
    Workaround: Instead of object names, pass VirtualSwitch objects.

Remove-CDDrive

    If a user tries to remove a nonexistent CD drive or a CD drive that belongs to a powered-on or suspended virtual machine, a terminating error is thrown and the following message is displayed: Object reference not set to an instance of an object.

Remove-FloppyDrive

    If a user tries to remove a nonexisting floppy drive or a floppy drive that belongs to a powered-on or suspended virtual machine, a terminating error is thrown and the following message is displayed: Object reference not set to an instance of an object.

Remove-NetworkAdapter

    If a user tries to remove a nonexisting network adapter or a network adapter that belongs to a powered-on or suspended virtual machine, a terminating error is thrown and the following message is displayed: Object reference not set to an instance of an object.

Update-Tools

    Update-Tools might stop responding if the mouse, VGA, and network drivers are not signed. A standard Windows dialog appears, and manual interaction is needed.

Returned Objects Properties

    All VM, VMHost, Cluster, Datacenter, Folder, and ResourcePool objects returned by Move-*, Set-*, and New-* cmdlets have an empty CustomFields property even if there is a global annotation on the server.

User Authentication

    vSphere PowerCLI, vSphere Client, and vCenter Server do not support the user@domain.name format for user names.
    Workaround: Use the domain\user format instead.

Installing vSphere PowerCLI

VMware provides a single installer for vSphere PowerCLI.

To install vSphere PowerCLI

  1. Download vSphere PowerCLI 4.0 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 20-May-2010 11:30 am [PDT]