Invoke-VMScript

Synopsis

Runs a PowerShell script in the guest OS of each of the specified virtual machines.

Syntax

Invoke-VMScript [-ScriptText] <String> [-VM] <VirtualMachine[]> [-HostCredential <PSCredential>] [-HostUser <String>] [-HostPassword <SecureString>] [-GuestCredential <PSCredential>] [-GuestUser <String>] [-GuestPassword <SecureString>] [-ToolsWaitSecs <Int32>] [-ScriptType <ScriptType>] [-Server <VIServer[]>] [-WhatIf] [-Confirm] [<CommonParameters>]

Related Commands

Detailed Description

Runs a PowerShell script in the guest OS of each of the specified virtual machines. To run Invoke-VMScript, the user must have read access to the folder containing the virtual machine and a Virtual Machine.Interaction.Console Interaction privilege. The virtual machines must be powered on and have PowerShell and VMware Tools installed. Network connectivity to the ESX system hosting the virtual machine on port 902 must be present. 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.

Parameters

NameDescriptionRequired?Pipeline InputDefault Value
ScriptTextSpecify the text of the script you want to run. You can also pass to this parameter a string variable containing the path to the script.truefalse
VMSpecify the virtual machines on whose guest operating systems you want to run the script.truetrue (ByValue)
HostCredentialSpecify a PSCredential object containing the credentials you want to use for authenticating with the host.falsefalse
HostUserSpecify the user name you want to use for authenticating with the host.falsefalse
HostPasswordSpecify the password you want to use for authenticating with the host.falsefalse
GuestCredentialSpecify a PSCredential object containing the credentials you want to use for authenticating with the virtual machine guest OS.falsefalse
GuestUserSpecifies the user name you want to use for authenticating with the virtual machine guest OS.falsefalse
GuestPasswordSpecify the password you want to use for authenticating with the virtual machine guest OS.falsefalse
ToolsWaitSecsSpecify how long in seconds the system waits for connecting to the VMware Tools. The default value is 20.falsefalse20
ScriptTypeSpecify the type of the script. The valid values are PowerShell, Bat, and Bash. If the virtual machine OS is Windows, the default value is PowerShell. If the virtual machine OS is Linux, the default value is Bash.falsefalse
ServerSpecify the vSphere servers on which you want to run the cmdlet. If no value is given to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.falsefalse
WhatIfIndicate that the cmdlet is run only to display the changes that would be made and actually no objects are modified.falsefalse
ConfirmIndicate that the cmdlet asks for confirmation before running.falsefalse

Input Type

Return Type

System.Object

Notes

Supported on ESX 3.5 and newer.
    To make PowerShell scripts work, you need to restart the virtual machine af
    ter the PowerShell installation. For BIN and BASH scripts, restart is not n
    eeded.

Examples

--------------  Example 1 --------------

C:\PS>$vm = Get-VM myVM

Invoke-VMScript -VM $vm -ScriptText "dir" -HostUser root -HostPassword mypass -G
uestUser administrator -GuestPassword mypass


Lists the directory entries on the guest OS.




--------------  Example 2 --------------

C:\PS>$script = '&"$env:ProgramFiles\Common Files\Microsoft Shared\MSInfo\msinfo
32.exe" /report "$env:Tmp\inforeport"'

Invoke-VMScript -ScriptText $script -VM MyVM -HostCredential $hostCredential -Gu
estCredential $guestCredential


Runs a PowerShell script. In PowerShell, to access environment variables, you mu
st use the following syntax: $env:<environment variable> (for example, $env:Prog
ramFiles). Also, to run the program, you must specify an ampersand (&) in front 
of the program path. 
The outer quotes ($script = '...') are required because this is how you define a
 string variable in PowerShell. The inner double quotes are required because the
re are spaces in the path.




--------------  Example 3 --------------

C:\PS>$script = '"%programfiles%\Common Files\Microsoft Shared\MSInfo\msinfo32.e
xe" /report "%tmp%\inforeport"'

Invoke-VMScript -ScriptText $script -VM MyVM -HostCredential $hostCredential -Gu
estCredential $guestCredential -ScriptType Bat


Runs a BAT script. In BAT scripts, to access environment variables, you must use
 the following syntax: %<environment variable>% (for example, %programfiles%).

The outer quotes ($script = '...') are required because this is how you define a
 string variable in PowerShell. The inner double quotes are required because the
re are spaces in the path.

Copyright © 1998 - 2009 VMware, Inc. All rights reserved.