Invoke-VMScript

This cmdlet runs a 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 VMware Tools installed and running. Network connectivity to the ESX system hosting the virtual machine must be present. To authenticate with the host or the guest OS, one of the HostUser/HostPassword (GuestUser/GuestPassword) pair and HostCredential (GuestCredential) parameters must be provided. The guest account you use to authenticate with the guest operating system must have administrator's privileges. For a list of supported operating systems, check the release notes of the specific VMware Tools version. To run this cmdlet against vCenter Server/ESXi 5.0 and later, you need VirtualMachine.GuestOperations.Modify and VirtualMachine.GuestOperations.Execute privileges.

Syntax

Invoke-VMScript

[ -VM ] < VirtualMachine[] >

-ScriptText < String >

[-GuestCredential < PSCredential > ]

[-GuestPassword < SecureString > ]

[-GuestUser < String > ]

[-HostCredential < PSCredential > ]

[-HostPassword < SecureString > ]

[-HostUser < String > ]

[-RunAsync ]

[-ScriptType < ScriptType > ]

[-Server < VIServer[] > ]

[-ToolsWaitSecs < Int32 > ]

[CommonParameters]

Parameters

Required	Parameter Name	Type	Position	Features	Description
required	VM	VirtualMachine[]	1	pipeline wildcards	Specifies the virtual machines on whose guest operating systems you want to run the script.
required	ScriptText	String	named		Provides 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.
optional	GuestCredential	PSCredential	named		Specifies a PSCredential object containing the credentials you want to use for authenticating with the virtual machine guest OS.
optional	GuestPassword	SecureString	named		Specifies the password you want to use for authenticating with the virtual machine guest OS.
optional	GuestUser	String	named		Specifies the user name you want to use for authenticating with the virtual machine guest OS.
optional	HostCredential	PSCredential	named		Specifies a PSCredential object containing the credentials you want to use for authenticating with the host. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.
optional	HostPassword	SecureString	named		Specifies the password you want to use for authenticating with the host. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.
optional	HostUser	String	named		Specifies the user name you want to use for authenticating with the host. You need to specify host credentials only if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX version you have installed is earlier than 1.10.
optional	RunAsync	SwitchParameter	named		Indicates that the command returns immediately without waiting for the task to complete. In this mode, the output of the cmdlet is a Task object. For more information about the RunAsync parameter run "help About_RunAsync" in the VMware PowerCLI console.
optional	ScriptType	ScriptType	named		Specifies 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.
optional	Server	VIServer[]	named	wildcards	Specifies the vCenter Server systems on which you want to run the cmdlet. If no value is provided or $null value is passed to this parameter, the command runs on the default servers. For more information about default servers, see the description of Connect-VIServer.
optional	ToolsWaitSecs	Int32	named		Specifies how long in seconds the system waits for connecting to the VMware Tools. The default value is 20.

Output

VMware.VimAutomation.ViCore.Types.V1.VM.Guest.VMScriptResult

Examples

Example 1

Invoke-VMScript -VM VM -ScriptText "dir" -GuestUser administrator -GuestPassword pass2

Lists the directory entries on the guest OS.

Example 2

$script = '&"$env:ProgramFiles\Common Files\Microsoft Shared\MSInfo\msinfo32.exe" /report "$env:Tmp\inforeport"'

Invoke-VMScript -ScriptText $script -VM VM -GuestCredential $guestCredential

Runs a PowerShell script. In PowerShell, to access environment variables, you must use the following syntax: $env:&#60environment variable&#62 (for example, $env:ProgramFiles). 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 there are spaces in the path.

Example 3

$script = '"%programfiles%\Common Files\Microsoft Shared\MSInfo\msinfo32.exe" /report "%tmp%\inforeport"'

Invoke-VMScript -ScriptText $script -VM VM -GuestCredential $guestCredential -ScriptType Bat

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

Related Commands

VM

Get-VM

This cmdlet retrieves the virtual machines on a vCenter Server system.

Move-VM

This cmdlet moves virtual machines to another location.

New-VM

This cmdlet creates a new virtual machine.

Remove-VM

This cmdlet removes the specified virtual machines from the vCenter Server system.

Restart-VM

This cmdlet restarts the specified virtual machines.

Set-VM

This cmdlet modifies the configuration of the virtual machine.

Start-VM

This cmdlet powers on virtual machines.

Stop-VM

This cmdlet powers off virtual machines.

Suspend-VM

This cmdlet suspends virtual machines.

Unlock-VM

This cmdlet unlocks the specified virtual machine.

VMConsoleWindow

Open-VMConsoleWindow

This cmdlet opens a window to the virtual machine's console.

VMGuest

Get-VMGuest

This cmdlet retrieves the guest operating systems of the specified virtual machines.

Restart-VMGuest

This cmdlet restarts the virtual machine guest operating systems.

Stop-VMGuest

This cmdlet shuts down the specified virtual machine guest OS.

Suspend-VMGuest

This cmdlet suspends the specified guest operating systems.

VMGuestDisk

Get-VMGuestDisk

This cmdlet retrieves storage volumes as seen by the virtual machines' guest operating systems.

VMGuestFile

Copy-VMGuestFile

This cmdlet copies files and folders from and to the guest OS of the specified virtual machines using VMware Tools.

VMQuestion

Get-VMQuestion

This cmdlet retrieves the pending questions for the specified virtual machines.

Set-VMQuestion

This cmdlet answers the specified virtual machine question.

VMResourceConfiguration

Get-VMResourceConfiguration

This cmdlet retrieves information about the resource allocation between the selected virtual machines.

Set-VMResourceConfiguration

This cmdlet configures resource allocation between the virtual machines.

VMScript

Invoke-VMScript

This cmdlet runs a script in the guest OS of each of the specified virtual machines.

VMStartPolicy

Get-VMStartPolicy

This cmdlet retrieves the start policy of the virtual machines on a vCenter Server system.

Set-VMStartPolicy

This cmdlet modifies the virtual machine start policy.