VMware vSphere PowerCLI 5.5 Release 1 Release Notes

Released 19 September 2013

Build 1295336 is VMware vSphere PowerCLI 5.5 Release 1

VMware vSphere PowerCLI 5.5 Release 1 Release Notes

VMware vSphere PowerCLI provides a Windows Powershell interface to the VMware 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 400 cmdlets for managing and automating vSphere and vCloud.

VMware vSphere PowerCLI Components and Versioning

VMware vSphere PowerCLI 5.5 Release 1 consists of two components:
  • vSphere PowerCLI 5.5 Release 1 is the core component of the PowerCLI package. It contains five snap-ins with cmdlets for managing vSphere 5.5 features:
    • VMware.VimAutomation.Core: VMware vSphere PowerCLI 5.5 Release 1 provides cmdlets for automated administration of the vSphere environment.
    • VMware.VimAutomation.Vds: VMware VDS PowerCLI 5.5 Release 1 provides cmdlets for managing virtual distributed switches and port groups.
    • VMware.VimAutomation.License: VMware License PowerCLI 5.5 Release 1 provides the Get-LicenseDataManager cmdlet for managing VMware License components.
    • VMware.ImageBuilder: VMware ImageBuilder PowerCLI 5.5 Release 1 provides cmdlets for managing depots, image profiles, and VIBs.
    • VMware.DeployAutomation: VMware Auto Deploy PowerCLI 5.5 Release 1 provides cmdlets that provide an interface to VMware Auto Deploy for provisioning physical hosts with ESXi software.
  • vCloud Director PowerCLI 5.5 Release 1 is an optional component that you can install during the PowerCLI installation. It provides the VMware vCloud Director PowerCLI 5.5 Release 1 snap-in (VMware.VimAutomation.Cloud) with cmdlets for automating vCloud Director 1.5.1 and 5.1 features. VMware vCloud Director PowerCLI 5.5 Release 1 also provides support for automating vCloud Director 5.1 features against vCloud Director 5.5.

Requirements

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

  • Windows PowerShell 2.0
  • A supported version of .NET Framework
    • .NET Framework 2.0 with Service Pack 2
    • .NET Framework 3.0 or .NET Framework 3.0 with Service Pack 1, or Service Pack 2
    • .NET Framework 3.5 or .NET Framework 3.5 with Service Pack 1

Supported Platforms

For a list of VMware vSphere PowerCLI 5.5 Release 1 supported operating systems, see the VMware vSphere PowerCLI 5.5 Release 1 User's Guide.

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)

When running against vCenter Server or ESX/ESXi versions earlier than 5.0, the following PowerCLI features are supported only on the 32-bit version of Windows PowerShell.

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

VMware vSphere PowerCLI 5.5 Release 1 supports the following VMware environments:

  • vCenter Server 5.5
  • VMware ESXi 5.5
  • vCenter Server 5.1 Update 1
  • VMware ESXi 5.1 Update 1
  • vCenter Server 5.0 Update 2
  • VMware ESXi 5.0 Update 2
  • vCenter Server 4.1 Update 3
  • VMware ESX 4.1 Update 3
  • VMware ESXi 4.1 Update 3
  • vCenter Server 4.0 Update 4
  • VMware ESX 4.0 Update 4
  • VMware ESXi 4.0 Update 4

vCloud Director PowerCLI 5.1 is compatible with VMware vCloud Director 1.5.1, VMware vCloud Director 5.1, and VMware vCloud Director 5.5.

Note: You can automate only vCloud Director 5.1 features against vCloud Director 5.5.


VMware vSphere PowerCLI 5.5 Release 1 is compatible with the following PowerShell versions:

  • Windows PowerShell 2.0
  • Windows PowerShell 3.0

What's New in This Release

New Features

This release of vSphere PowerCLI introduces a number of new capabilities and expands on the existing cmdlets allowing further management of the VMware vSphere and VMware vCloud Director products.

vSphere PowerCLI 5.5 Release 1 introduces the following new features and improvements:

  • vSphere PowerCLI is now supported on Windows 8 and Windows Server 2012.
  • Cmdlets and properties have been added to allow you to manage vSphere tags for vCenter Server 5.1 or later.
    • The Get-VM, Get-VMHost, Get-Datastore, Get-VirtualPortGroup, and Get-VDPortGroup cmdlets now have a tag parameter to let you identify entities with a specific tag.
    • You can now retrieve all tags with the Get-Tag cmdlet.
    • You can now retrieve all assigned tags with the Get-TagAssignment cmdlet.
    • You can now assign tags to existing vSphere entities which support tags by using the New-TagAssignment cmdlet.
    • You can now remove all connections to tags on an existing vSphere entity which supports tags by using the Remove-TagAssignment cmdlet.
  • The vSphere PowerCLI snap-in for vSphere Distributed Switches has been updated to include a number of improvements and new features in the following areas:
    • You can now perform easy vSwitch and vSphere Distributed Switch migration by using the Add-VDSwitchPhysicalNetworkAdatper and Add-VirtualSwitchPhysicalNetworkAdapter cmdlets to allow attaching and migrating physical and virtual NICs to virtual standard and distributed switches.
    • You can now manage vSphere Distributed Switch private VLANs by using the Get-VDSwitchPrivateVlan, New-VDSwitchPrivateVlan, and Remove-VDSwitchPrivateVlan cmdlets.
    • You can now manage vSphere Distributed Switch policy configuration by using the following cmdlets.
      • Get-VDUplinkTeamingPolicy and Set-VDUplinkTeamingPolicy
      • Get-VDBlockedPolicy and Set-VDBlockedPolicy
      • Get-VDPortGroupOverridePolicy and Set-VDPortGroupOverridePolicy
      • Get-VDSecurityPolicy and Set-VDSecurityPolicy
      • Get-VDTrafficShapingPolicy and Set-VDTrafficShapingPolicy
      • Get-VDUplinkLacpPolicy and Set-VDUplinkLacpPolicy
    • You can now manage vSphere Distributed Switch VLAN configuration by using the Set-VDVLanConfiguration cmdlet.
    • You can now manage vSphere Distributed Switch port configuration by using the Get-VDPort and Set-VDPort cmdlets.
  • vSphere PowerCLI 5.5 Release 1 also introduces the new Open-VMConsoleWindow cmdlet for opening the console of a vSphere or vCloud Director virtual machine.
  • The Set-VMHost cmdlet has been enhanced with a LicenseKey parameter which allows you to easily add a license.

For more information on changes made in vSphere PowerCLI 5.5 Release 1, including improvements, security enhancements, and deprecated features, see the vSphere PowerCLI Change Log. For more information on specific product features, see the VMware vSphere PowerCLI 5.5 Release 1 User's Guide. For more information on specific cmdlets, see the VMware vSphere PowerCLI 5.5 Release 1 Cmdlet Reference.

Known Issues

VMware vSphere PowerCLI 5.5 Release 1 is known to have the following issues:

  • Add-VDSwitchPhysicalNetworkAdapter
    If you connect to a vCenter Server 4.0 or 4.1 system and try to migrate physical NICs from the host management network of a vSphere standard switch to a vSphere distributed switch, the migration fails and the host is disconnected.
  • Add-VirtualSwitchPhysicalNetworkAdapter
    If you connect to a vCenter Server 4.0 or 4.1 system and try to migrate physical NICs from the host management network of a vSphere distributed switch to a vSphere standard switch, the migration fails and the host is disconnected.
  • Apply-DrsRecommendation
    Apply-DrsRecommendation runs in asynchronous mode even when called without the RunAsync parameter.
  • Connect-VIServer
    • Connect-VIServer cannot use the Kerberos network authentication protocol to connect to vCenter Server systems that are installed under a custom user account on a Windows system. Connect-VIServer uses NTLM instead.
      Workaround: Install and run vCenter Server under the default system account. Alternatively, you can:
      1. Add another IP to the Windows system where vCenter Server is running.
      2. Register a new A DNS record for the IP.
      3. Run the setspn tool to register an SPN for the new DNS record and associate it with the vCenter Server account under which vCenter Server was installed.
        For example: To register an SPN for the vc-alias.domain.com DNS and the VCAccount account, run:
        setspn -A -HOST/vc-alias.domain.com Domain\VCAccount
      4. Use the new DNS name to connect to the vCenter Server system.
        For example: Run Connect-VIServer vc-alias.domain.com
    • When you use the User and Password parameters to authenticate with a vCenter Server 5.1 or later system, you might not be recognized as a domain user.
      Workaround: Pass the domain name and the user name to the User parameter.
      For example: Run Connect-VIServer my.server.com -Username MyDomain\MyUserName -Password MyPassword
  • 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-HardDisk
    The value of the Persistence property of the object returned by Get-HardDisk is different depending on the way the hard disk is retrieved by the cmdlet.
  • Get-ResourcePool
    The RelatedObject parameter does not accept ProviderVdc objects through the pipeline.
  • 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 cannot obtain USB devices from snapshots.
  • Get-VDPortgroup
    When you are connected to a vCloud Director 5.1 or later environment, you cannot use the RelatedObject parameter to retrieve a distributed port group from an organization network backed by the port group.
  • 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 is not populated.
    • You cannot retrieve the vSphere PowerCLI view of the underlying port group from the vCloud Director PowerCLI view of a network pool backed by the port group.
  • 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-VirtualSwitch
    When you are connected to a vCloud Director 5.1 or later environment, you cannot use the RelatedObject parameter to retrieve a distributed switch from a network pool backed by the distributed switch.
  • Get-VirtualPortgroup
    When you are connected to a vCloud Director 5.1 or later environment, you cannot use the RelatedObject parameter to retrieve a distributed port group from an organization network backed by the port group.
  • Get-VM
    During the process of creating a template from a virtual machine, Get-VM returns both the virtual machine and template objects.
  • Get-VMHostProfileRequiredInput
    On vCenter Server 5.0, Get-VMHostProfileRequiredInput returns a result even if you pass a hashtable with inapplicable elements.
  • Install-VMHostPatch
    • On ESX 4.0, the LocalPath parameter does not accept paths to .vib files as arguments.
    • Install-VMHostPatch cannot install patches on diskless ESXi servers.
    • 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-CIVAppNetwork
    You can create a vApp network by specifying inconsistent network settings. While the settings of the newly created vApp network are inconsistent, you can only modify them to restore their consistency. To configure the vApp network, run Set-CIVAppNetwork.
  • New-HardDisk
    New-HardDisk does not prompt for confirmation when you try to create a VMDK anti-affinity rule that overwrites an existing one.
  • New-OrgNetwork
    You cannot create new organization networks in vCloud Director 5.1 or later environments.
  • New-OrgVdc
    To ensure backward compatibility, PowerCLI provides limited support for the StorageAllocationGB parameter on vCloud Director 5.1 environments. When you develop new scripts for vCloud Director 5.1 environments, do not use this parameter.
  • Set-OrgVdc
    The StorageAllocationGB parameter is supported only on vCloud Director 1.5.x environments.
  • Set-ScsiController
    Set-ScsiController cannot set both the Type and BusSharingMode parameters at the same time when running against vCenter Server or ESX/ESXi versions 5.1 or earlier.
    Workaround: First run the cmdlet to set the type and then run it again to configure the bus sharing mode.
  • Set-VMGuestNetworkInterface
    On Windows operating systems, Set-VMGuestNetworkInterface becomes non-responsive if the provided IP address conflicts with an existing IP address on the network.
  • Set-VMHost
    • When an ESX/ESXi host is registered with multiple vCenter Server systems, you cannot change the state of the disconnected host to connected.
      Workaround:
      1. Run Remove-VMHost to remove the disconnected host from the vCenter Server system that it is registered with.
      2. Run Add-VMHost to attach the host to the vCenter Server system again.
      3. (Optional) Run Set-VMHost to restore the initial configuration of the host.
      The operation authenticates you with the host and automatically changes its state to connected.
    • When you update the value of the VMSwapfileDatastore parameter and immediately retrieve the host information, the value of VMSwapfileDatastore might appear unchanged. If you retrieve the host information after a brief period of time, the change of the property value should be reflected.
  • Set-VMHostAccount
    If you pass a collection of valid and invalid objects to the AssignUsers or AssignGroups parameter, Set-VMHostAccount throws an error when it encounters the first invalid object and stops processing the remaining objects.
  • 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 by using Set-VMHostNetworkAdapter, the VMotionEnabled property of the second NIC might still report that vMotion is not enabled. This is because only one NIC can be 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-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.
    • Against ESXi 5.1 hosts, you cannot use the Set-VMHostSNMP cmdlet to modify any trap target-related settings. Attempting to modify any of these settings with the Set-VMHostSNMP cmdlet might cause the ESXi SNMP agent to stop working properly.
  • Get-CIDatastore
    When you specify the ProviderVdc parameter, Get-CIDatastore might return incorrect results if multiple provider virtual datacenters share a datastore.
  • Get-CIVM
    When you are logged in 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.
  • 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
    • 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.
    • All VIX cmdlets support use of SSPI for Windows guest machines if the underlying vCenter Server is version 5.0. 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.5 Release 1:

  • Get-VDSwitch
    Get-VDSwitch cannot filter Cisco virtual distributed switches.
  • Set-VMGuestNetworkInterface
    Set-VMGuestNetworkInterface cannot configure the DNS address correctly on Linux operating systems.

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.5 Release 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. Accept the license agreement terms and click Next.
  5. On the Custom Setup page, select the PowerCLI components you want to install.
  6. (Optional) To change the default location to install VMware vSphere PowerCLI, click Change and select a different Destination Folder.
  7. Click Next.
  8. On the Ready to Install the Program page, click Install to proceed with the installation.
  9. Click Finish to complete the installation process.

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