VMware

VMware Infrastructure Toolkit (for Windows)
Release Notes

Released 27-January-2009

Build 142961 is version 1.5 of the VMware Infrastructure Toolkit (for Windows).

VMware Infrastructure Toolkit (for Windows) 1.5 Release Notes

The VMware Infrastructure Toolkit (for Windows) provides an easy-to-use Windows Powershell interface to the VMware Infrastructure API (VI API). The VI Toolkit (for Windows) includes numerous cmdlets, sample scripts, and a function library.

This document contains the following information:

About the VMware Infrastructure Toolkit (for Windows)

VI Toolkit (for Windows) is a command-line and scripting tool built on Windows PowerShell, and provides more than 150 cmdlets for managing and automating your VMware Infrastructure.

Requirements

To use the VI Toolkit (for Windows) console, you need to have installed the following software:

  • .NET 2.0 Service Pack 1
  • Windows PowerShell 1.0

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

Supported Platforms

VI Toolkit (for Windows) 1.5 works on the 32-bit and 64-bit versions of the following operating systems:

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

VI Toolkit (for Windows) 1.5 supports the following VMware environments:

  • VMware ESX 3.5
  • VMware ESX 3i
  • VMware VirtualCenter 2.5
  • VMware ESX 3.0/VirtualCenter 2.0

What's New in This Release?

This release of VI Toolkit (for Windows) 1.5 includes the following new cmdlets:

Cmdlet Name Description
Add-VMHostNtpServer

Adds the specified Ntp servers to the Ntp server list of the specified hosts. If a server is already in the list, a non-terminating error is generated and a duplicate is not created.

Get-DrsRule

Retrieves the list of Drs rules for the specified clusters. Each rule defines the virtual machines that can run on the same host (affinity rule) or must run on different hosts (anti-affinity).

Get-ScsiLun

Retrieves Scsi devices from the specified virtual machine host(s). Examples of Scsi logical unit objects include disks which may contain file system volumes or parts of volumes for the host or might serve as raw disks to a virtual machine. Other examples include Scsi passthrough devices that can be used by virtual machines.

Get-ScsiLunPath

Retrieves the list of Vmhba paths to a specified Scsi device.

Get-StatInterval Retrieves the available statistics intervals and filters them using the provided parameters.
Get-StatType

Retrieves the available statistics types for a given inventory object. The inventory object must be a virtual machine, virtual machine host, cluster, or resource pool. Performance statistics types might be filtered by their names, start and finish times, and collection intervals.

Get-VICredentialStoreItem

Retrieves credential store items that correspond to the filter criteria defined by the Host and User parameters. Both the Host and User parameters support wildcards. If none of the Host and User parameters are specified, all available credential store items are returned. If they are specified and do not contain wildcards, and no item is found, non-terminating errors are reported for the Host and User parameters. If a file is not specified, items are retrieved from the default credential store file, which resides in %APPDATA%\VMware\credstore\vicredentials.xml.

Get-VMHostAdvancedConfiguration

Retrieves the advanced configuration of the specified virtual machine host. For each of the specified hosts, returns a hash table mapping setting names to setting values.

Get-VMHostDiagnosticPartition

Retrieves a list of diagnostic partitions for the specified virtual machine hosts. The server provides the list in order of preference. In general, local diagnostic partitions are better than shared diagnostic partitions because of the impossibility of multiple servers sharing the same partition. The most preferred diagnostic partition will be first in the array.

Get-VMHostFirewallDefaultPolicy

Gets the firewall default policy for the specified virtual machine hosts. Shows if the outgoing and/or incoming connections are allowed.

Get-VMHostFirewallException

Retrieves the firewall exceptions of the hosts. The exceptions might be filtered using the VMHost, Name, Port, and Enabled parameters.

Get-VMHostNtpServer

Retrieves the Ntp servers of the specified virtual machine hosts.

Get-VMHostSysLogServer

Displays the remote syslog servers of the specified hosts.

Get-VMResourceConfiguration

Retrieves information about resource allocation between the virtual machines.

Invoke-VMScript

Executes the specified PowerShell script in the guest OS of each of the specified virtual machines. The virtual machines must be powered on and have PowerShell and VM Tools installed. In order to authenticate with the host or the guest OS, one of the HostUser/HostPassword (GuestUser/GuestPassword) pair and HostCredential (GuestCredential) parameters must be provided.

New-DrsRule

Creates a new Drs rule. Each rule defines the virtual machines that can run on the same host (affinity rule) or must run on different hosts (anti-affinity).

New-StatInterval

Creates a statistics interval with the specified parameters.

New-VICredentialStoreItem

Creates a new entry in the credential store. If there is an existing entry for the specified host and user, it is overwritten. If the credential store file does not exist, it is created (along with its directory if needed). If file is not specified, the item is created in the default credential store file, which resides in %APPDATA%\VMware\credstore\vicredentials.xml. Note that the credential store is not designed to be a secure password repository. Although the passwords added to the credential store are obfuscated, they can be recovered by anyone who can access the credential store file. By default, only the user who has created the credential store file has rights to read it.

Remove-DrsRule

Removes the specified Drs rules.

Remove-StatInterval

Removes the statistics interval specified by the provided sampling period or name.

Remove-VICredentialStoreItem

Removes credential store items that match the specified Host and User filters. Both Host and User parameters accept wildcards. At least one of Host/User parameters must be specified or a terminating error is reported. To remove all passwords, call “Remove-VICredentialStoreItem *”, which is a wildcard matching all hosts.

Remove-VMHostNtpServer Removes the specified Ntp servers from the Ntp server list of the specified hosts.
Set-DrsRule

Modifies an existing Drs rule. Each rule defines the virtual machines that can run on the same host (affinity rule) or must run on different hosts (anti-affinity).

Set-ScsiLun

Configures a Scsi device.

Set-ScsiLunPath

Configures a Vmhba path to a Scsi device.

Set-StatInterval

Updates the statistics interval specified by the provided parameters.

Set-VMHostAdvancedConfiguration

Updates the advanced configuration settings of one or more virtual machine hosts.

Set-VMHostDiagnosticPartition

Activates or deactivates the diagnostic partitions of virtual machine hosts.

Set-VMHostFirewallDefaultPolicy

Sets the default policy for the specified virtual machine host firewall. Specifies if outgoing or incoming connections are allowed. At least one of the AllowIncoming and AllowOutgoing parameters must be set.

Set-VMHostFirewallException

Enables or disables virtual machine host firewall exceptions.

Set-VMHostSysLogServer

Configures the remote syslog server of the specified hosts.

Set-VMResourceConfiguration

Configures resource allocation between the virtual machines. To retain the current value of a setting, omit the corresponding parameter. To disable a setting (only applicable to the nullable limit settings), pass $null.

 

The following parameters have been added to existing cmdlets:

Cmdlet Name Parameter Name Description
Add-VMHost Force

If set, the cmdlet is executed even if the authenticity of the host SSL certificate can not be verified. Otherwise, the cmdlet execution is cancelled and an error message is displayed.

Get-Stat

IntervalSecs

Specifies the granularity in seconds for which the statistics should be collected. The closest available granularity is used.

New-Cluster

HARestartPriority

Sets the virtual machines HA restart priority. VMware HA is a feature that detects failed virtual machines and automatically restarts them on alternate ESX hosts. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

HAIsolationResponse

Indicates whether or not the virtual machine should be powered off if a host determines that it is isolated from the rest of the compute resource. The available values are "PowerOff" and "DoNothing". Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

VMSwapfilePolicy

Specifies the swapfile placement policy. It might be one of the following:

- InHostDataStore - Store the swapfile in the datastore specified by the VMSwapfileDatastoreID property of the virtual machine host, if that property is set and indicates a datastore with sufficient free space. Otherwise store the swapfile in the same directory as the virtual machine. This setting may degrade the VMotion performance.

- WithVM - Store the swapfile in the same directory as the virtual machine.

Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

DrsAutomationLevel

Specifies a Drs (Distributed Resource Scheduler) automation level. Must be one of the following - FullyAutomated, Manual, PartiallyAutomated.

New-OSCustomizationSpec

LicenseMode

Specifies the license mode of the Windows guest operating system. The valid values are Perseat, Perserver, and Notspecified. If Perserver is set, use the LicenseMaxConnection parameter to define the maximum number of connections.

LicenseMaxConnections

Specifies the maximum connections for server license mode. Use this parameter only if the LicenseMode parameter is set to Perserver.

New-VM

HARestartPriority

Sets the virtual machines HA restart priority. The valid values are Disabled, Low, Medium, and High. VMware HA is a feature that detects failed virtual machines and automatically restarts them on alternate ESX hosts. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

HAIsolationResponse

Indicates whether or not the virtual machine should be powered off if a host determines that it is isolated from the rest of the compute resource. The available values are AsSpecifiedByCluster, PowerOff, and DoNothing. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

DrsAutomationLevel

Specifies a Drs (Distributed Resource Scheduler) automation level. Can be one of the following FullyAutomated, Manual, PartiallyAutomated. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

New-VMHostAccount

GrantShellAccess

Specifies whether the new account is allowed to access the ESX shell.

Set-Cluster

HARestartPriority

Sets the virtual machines HA restart priority. VMware HA is a feature that detects failed virtual machines and automatically restarts them on alternate ESX hosts. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

HAIsolationResponse

Indicates whether or not the virtual machine should be powered off if a host determines that it is isolated from the rest of the compute resource. The available values are PowerOff and DoNothing. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

VMSwapfilePolicy

Specifies the swapfile placement policy. It might be one of the following:

- InHostDataStore - Store the swapfile in the datastore specified by the VMSwapfileDatastoreID property of the virtual machine host, if that property is set and indicates a datastore with sufficient free space. Otherwise store the swapfile in the same directory as the virtual machine. This setting may degrade the VMotion performance.

- WithVM - Store the swapfile in the same directory as the virtual machine. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

DrsAutomationLevel

Specifies a Drs (Distributed Resource Scheduler) automation level. Can be one of the following FullyAutomated, Manual, PartiallyAutomated.

Set-OSCustomizationSpec

LicenseMode

Specifies the license mode of the Windows guest operating system. The valid values are Perseat, Perserver, and Notspecified. If Perserver is set, use the LicenseMaxConnection parameter to define the maximum number of connections.

LicenseMaxConnections

Specifies the maximum connections for server license mode. Use this parameter only if the LicenseMode parameter is set to Perserver.

Set-VM

HARestartPriority

Sets the virtual machines HA restart priority. The valid values are Disabled, Low, Medium, and High. VMware HA is a feature that detects failed virtual machines and automatically restarts them on alternate ESX hosts. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

HAIsolationResponse

Indicates whether or not the virtual machine should be powered off if a host determines that it is isolated from the rest of the compute resource. The available values are AsSpecifiedByCluster, PowerOff, and DoNothing. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

DrsAutomationLevel

Specifies a Drs (Distributed Resource Scheduler) automation level. Can be one of the following FullyAutomated, Manual, PartiallyAutomated. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases. Specifying this parameter is only supported when the virtual machine is inside a cluster, otherwise an error is generated.

Set-VMHost

VMSwapfilePolicy

Specifies the swapfile placement policy. It might be one of the following:

- InHostDataStore - Store the swapfile in the datastore specified by the VMSwapfileDatastoreID property of the virtual machine host, if that property is set and indicates a datastore with sufficient free space. Otherwise store the swapfile in the same directory as the virtual machine. This setting may degrade VMotion performance.

- WithVM - Store the swapfile in the same directory as the virtual machine. Passing values to this parameter through a pipeline is deprecated and will be disabled after one of the following releases.

VMSwapfileDatastore

Specifies a datastore visible to this host that may be used to store virtual machine swapfiles, for virtual machines executing on this host. Using a host specific swap location may degrade the VMotion performance.

Set-VMHostAccount

GrantShellAccess

Specifies whether the account is allowed to access the ESX shell.

Set-VMHostNetworkAdapter

Dhcp

Specifies the virtual machine host network adapter Dhcp.

Obtaining the Software

You can obtain the VI Toolkit (for Windows) 1.5 at:

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

Known Issues

The VI Toolkit (for Windows) 1.5 has the following known issues:

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

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

Get-ScsiLunPath

    When running Get-ScsiLunPath, the Scsi device can not be specified by name.

Get-VIEvent

  • When Get-VIEvent is run for entities other than virtual machines, an incorrect result is returned.
  • When Get-VIEvent is run against an ESX host and a non‑existing user is specified, a hundred entity records are returned.
  • When Get-VIEvent is run against an ESX host whose time zone setting differs from the time zone setting of the local machine, no result is returned.
    Workaround: Run Get-VIEvent directly on the ESX host.

Get-View

    Get-View might behave inconsistently depending on how the managed object is specified.

Get-VM

    During the process of creating a template from a virtual machine, Get-VM returns both the virtual machine and template objects.

Get-VMHostFirmware

    Get-VMHostFirmware can not be executed by users with read-only rights on the ESX or the VirtualCenter host.

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.

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 hard drive different than C: or D:.
  • Invoke-VMScript might hang when executed against a virtual machine running on ESX 3.0.

Move-Inventory

    Move-Inventory does not work with virtual machine templates.

New-HardDisk

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

New-VM

    New-VM can not create virtual machines whose names contain special chars on VirtualCenter 2.0/ ESX3.0.

New-VMHostNetworkAdapter

  • New-VMHostNetworkAdapter cannot set the value of the MAC address on VirtualCenter 2.5 and ESX 3.5.
  • New-VMHostNetworkAdapter does not accept object names as arguments for the VirtualSwitch parameter.
    Workaround: Pass to the VirtualSwitch parameter VirtualSwitch objects instead of their names.

New-OSCustomizationSpec

    The operating system customization specifications with passwords created by New-OSCustomizationSpec, if edited with VIClient, throw errors when applied.

New-Snapshot

    When invoked with the Quiesced switch parameter on, New-Snapshot creates a snapshot with Quiesced parameter value $false.

Remove-Template

    When invoked with the DeleteFromDisk switch parameter on, Remove-Template is not executed synchronously.

Remove-VMHostNtpServer

    The pipeline Get-VMHost | Get-VMHostNtpServer | Remove-VMHostNtpServer does not work.

Set-HardDisk

    Set-HardDisk can not set the hard disk persistence to IndependentNonPersistent.

Set-ScsiLunPath

    Set-ScsiLunPath does not work properly when the Active parameter is set to $false.

Set-VMHost

    Set-VMHost throws an error when applied on a disconnected virtual machine host.

Set-VMHostDiagnosticPartition

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

Set-VMHostNetworkAdapter

    On VMware ESX 3.x/ VirtualCenter 2.x, the Set-VMHostNetworkAdapter cmdlet might take longer time to update the values of the FullDuplex and BitRatePerSec network adapter properties due to the hardware configuration being performed, and the object returned by Set-VMHostNetworkAdapter might still contain the current configuration instead of the updated one.

Set-VMHostSNMP

  • Set-VMHostSNMP fails to enable VMHostSNMP and to set the ReadOnlyCommunityString when called for the first time.
    Workaround: Run the command again.
  • The default value of the Set-VMHostSNMP TargetPort parameter is a random number instead of the port number.
  • Set-VMHostSNMP does not take in account the value of the TargetPort parameter.

Update-Tools

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

Inventory Provider

    The output of the dir command, run while the Inventory Provider is running, might be difficult to read.

Datastore Provider

    Files can not be copied in or out the Datastore Provider.

VI .NET Toolkit

    The ScreenDimensions property of the VMGuestInfo object is not populated.

Working on 64-bit Platforms

    Operations with ESX or VirtualCenter take long to complete when working on 64-bit platforms.
    Workaround: This is a .NET 2.0 issue and it is fixed in Service Pack 1. Install Service Pack 1 for .NET 2.0.

Backward Incompatibility

  • In VI Toolkit (for Windows) 1.5, the ChangeSid and DeleteAccounts properties types of the OSCustomizationSpec object are changed and this results in backward binary incompatibility between VI Toolkit (for Windows) 1.5 and VI Toolkit (for Windows) 1.0.
  • VI Toolkit (for Windows) 1.5 is not compatible with VMware Update Manager - PowerShell Library 1.0.

Resolved Issues

The following issues have been resolved in VI Toolkit (for Windows) 1.5:

Get-CDDrive

    Get-CDDrive works on snapshots.

Get-FloppyDrive

    Get-FloppyDrive works on snapshots.

Get-VICredentialStoreItem

    Get-VICredentialStoreItem successfully retrieves an item when the string passed to the User parameter contains hyphens in the middle of the string.

Get-VMHostSNMP

    Get-VMHostSNMP returns a correct result when called with two virtual machine hosts passed through a pipeline.

New-HardDisk

  • The New-HardDisk cmdlet can create NonPersistent and Undoable disks.
  • Split hard disks can be created only from Flat disk type. When a Raw disk is created with New-HardDisk and the Split parameter is set, an error is generated.
  • NonPersistent RawPhysical disks can not be created. When New-HardDisk is run with the RawPhysical and NonPersistent parameters, an error is generated.
  • ThinProvisioned disks can be created only from Flat disk type. When a raw disk is created using New-HardDisk and the ThinProvisioned parameter is set, an error is generated.

New-VM

    New-VM works properly when cloning multiple virtual machines asynchronously.

Set-ResourcePool

    No error is thrown when Set-ResourcePool is executed by a user with read-only rights.

Set-VMHost

    When Set-VMHost is executed asynchronously, the properties of the returned object are correct.

Set-VMHostSNMP

    VmHostSNMP objects have TrapTargets correctly set to an empty array.

VI .NET Toolkit

    The UpdateViewData method updates VitualMachineSnapshot objects.

Debugging

    The user is able to see debug messages in the VI Toolkit logs even when working without administrator privileges.

Installing the VI Toolkit (for Windows)

VMware provides a single installer for the VI Toolkit (for Windows).

To install the VI Toolkit (for Windows)

  1. Download and install PowerShell 1.0 from the Microsoft PowerShell 1.0 download page .
  2. Download VI Toolkit (for Windows) 1.5 from http://www.vmware.com/go/powershell.
  3. Launch the VI Toolkit (for Windows) installer by double-clicking the executable file.
  4. Follow the instructions in the wizard.
  5. To install the toolkit in a location other than the default, click Change in the Destination Folder page and select a different directory.
  6. In the Ready to Install the Program page, choose whether to create a desktop shortcut.
  7. Click Install to proceed with the installation.
  8. Click Finish to complete the installation process.

To find a more detailed description of the VI Toolkit (for Windows) installation process and prerequisites, see the Installation Guide for VI Toolkit (for Windows) .

Last updated 19-Feb-2009 10:30 am