powershellscripts.com

Tutorials  PowerShell Cmdlet Help for Invoke-VMScript



NAME
Invoke-VMScript

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

SYNTAX
Invoke-VMScript [-ScriptText] [-VM] [-HostCredential ] [-HostUser >] [-HostPassword ] [-GuestCredential ] [-GuestUser ] [-GuestPassword ring>] [-ToolsWaitSecs ] [-ScriptType ] [-RunAsync] [-Server ] [-WhatIf] [-Confirm]
[]


DESCRIPTION
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 pri
vilege. The virtual machines must be powered on and have VMware Tools installed. Network connectivity to the ESX sy
stem hosting the virtual machine on port 902 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 p
rovided. The guest account you use to authenticate with the guest operating system must have administrator's privil
eges. This cmdlet supports only Windows XP 32 SP3, Windows Server 2003 32bit SP2, Windows Server 2003 64bit SP2, Wi
ndows 7 64 bit, Windows Server 2008 R2 64bit and Redhat Enterprise 5 operating systems.


PARAMETERS
-ScriptText
Specify the text of the script you want to run. You can also pass to this parameter a string variable containin
g the path to the script.

Required? true
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false

-VM
Specify the virtual machines on whose guest operating systems you want to run the script.

Required? true
Position? 2
Default value
Accept pipeline input? true (ByValue)
Accept wildcard characters? true

-HostCredential
Specify 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 i
s earlier than 4.0, or the VIX version you have installed is earlier than 1.10.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-HostUser
Specify the user name you want to use for authenticating with the host. You need to specify host credentials on
ly if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX vers
ion you have installed is earlier than 1.10.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-HostPassword
Specify the password you want to use for authenticating with the host. You need to specify host credentials onl
y if the version of the vCenter Server or ESX you are authenticating with is earlier than 4.0, or the VIX versi
on you have installed is earlier than 1.10.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-GuestCredential
Specify a PSCredential object containing the credentials you want to use for authenticating with the virtual ma
chine guest OS.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-GuestUser
Specifies the user name you want to use for authenticating with the virtual machine guest OS.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-GuestPassword
Specify the password you want to use for authenticating with the virtual machine guest OS.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-ToolsWaitSecs
Specify how long in seconds the system waits for connecting to the VMware Tools. The default value is 20.

Required? false
Position? named
Default value 20
Accept pipeline input? false
Accept wildcard characters? false

-ScriptType
Specify the type of the script. The valid values are PowerShell, Bat, and Bash. If the virtual machine OS is Wi
ndows, the default value is PowerShell. If the virtual machine OS is Linux, the default value is Bash.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-RunAsync
Indicate that the command returns immediately without waiting for the task to complete. In this mode, the outpu
t of the cmdlet is a Task object. For more information about the -RunAsync parameter run " help About_RunAsync"
in the vSphere PowerCLI console.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Server
Specify the vSphere servers on which you want to run the cmdlet. If no value is given to this parameter, the co
mmand runs on the default servers. For more information about default servers, see the description of Connect-V
IServer.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? true

-WhatIf
Indicate that the cmdlet is run only to display the changes that would be made and actually no objects are modi
fied.

Required? false
Position? named
Default value
Accept pipeline input? false
Accept wildcard characters? false

-Confirm
If the value is $true, indicates that the cmdlet asks for confirmation before running. If the value is $false,
the cmdlet runs without asking for user confirmation.

Required? false
Position? named
Default value $true
Accept pipeline input? false
Accept wildcard characters? false


This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS



OUTPUTS
VMScriptResult


NOTES


Supported on ESX 3.5 Update 2 and newer.
To make PowerShell scripts work, you must restart the virtual machine after the PowerShell installation. For BI
N and BASH scripts, restart is not needed.
This cmdlet works only in 32-bit mode.

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

C:\PS>Invoke-VMScript -VM VM -ScriptText "dir" -HostUser root -HostPassword pass1 -GuestUser administrator -GuestPa
ssword pass2


Lists the directory entries on the guest OS.





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

C:\PS>$script = '&"$env:ProgramFiles\Common Files\Microsoft Shared\MSInfo\msinfo32.exe" /report "$env:Tmp\inforepor
t"'

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


Runs a PowerShell script. In PowerShell, to access environment variables, you must use the following syntax: $env:<
environment variable> (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 --------------

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

Invoke-VMScript -ScriptText $script -VM VM -HostCredential $hostCredential -GuestCredential $guestCredential -Scrip
tType Bat


Runs a BAT script. In BAT scripts, to access environment variables, you must use the following syntax: % t 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 there are spaces in the path.






RELATED LINKS
Online version: http://www.vmware.com/support/developer/PowerCLI/PowerCLI501/html/Invoke-VMScript.html