< Back
Invoke-VMScript
Post
NAME Invoke-VMScript
SYNOPSIS
This cmdlet runs a script in the guest OS of each of the specified virtual machines.
SYNTAX
Invoke-VMScript [-ScriptText] <String> [-VM] <VirtualMachine[]> [-GuestCredential <PSCredential>] [-GuestPassword
<SecureString>] [-GuestUser <String>] [-HostCredential <PSCredential>] [-HostPassword <SecureString>] [-HostUser
<String>] [-RunAsync] [-ScriptType <ScriptType>] [-Server <VIServer[]>] [-ToolsWaitSecs <Int32>] [-Confirm]
[-WhatIf] [<CommonParameters>]
DESCRIPTION
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. Network
connectivity to the ESX system 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 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, see the PowerCLI User's
Guide.
To run this cmdlet against vCenter Server/ESX/ESXi versions earlier than 5.0, you need to meet the following
requirements: *You must run the cmdlet on the 32-bit version of Windows PowerShell. *You must have access to the
ESX that hosts the virtual machine over TCP port 902. *For vCenter Server/ESX/ESXi versions earlier than 4.1, you
need VirtualMachine.Interact.ConsoleInteract privilege. For vCenter Server/ESX/ESXi 4.1 and later, you need
VirtualMachine.Interact.GuestControl privilege.
To run this cmdlet against vCenter Server/ESXi 5.0 and later, you need VirtualMachine.GuestOperations.Modify and
VirtualMachine.GuestOperations.Execute privileges.
PARAMETERS
-GuestCredential <PSCredential>
Specifies a PSCredential object containing the credentials you want to use for authenticating with the virtual
machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-GuestPassword <SecureString>
Specifies the password you want to use for authenticating with the virtual machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-GuestUser <String>
Specifies the user name you want to use for authenticating with the virtual machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostCredential <PSCredential>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostPassword <SecureString>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostUser <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-RunAsync [<SwitchParameter>]
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.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-ScriptText <String>
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.
Required? true
Position? 1
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ScriptType <ScriptType>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Server <VIServer[]>
Specifies the vCenter Server systems on which you want to run the cmdlet. If no 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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? true
-ToolsWaitSecs <Int32>
Specifies 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
-VM <VirtualMachine[]>
Specifies the virtual machines on whose guest operating systems you want to run the script.
Required? true
Position? 2
Default value None
Accept pipeline input? True (ByValue)
Accept wildcard characters? true
-Confirm [<SwitchParameter>]
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
-WhatIf [<SwitchParameter>]
Indicates that the cmdlet is run only to display the changes that would be made and actually no objects are
modified.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
One or more VMScriptResult objectsVMScriptResult
NOTES
To make PowerShell scripts work, you must restart the virtual machine after the PowerShell installation. For
BIN and BASH scripts, restart is not needed.
-------------------------- 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:<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 --------------------------
$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:
%<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 there are spaces in the path.
RELATED LINKS
Online Version: https://code.vmware.com/doc/preview?id= ... cript.html
SYNOPSIS
This cmdlet runs a script in the guest OS of each of the specified virtual machines.
SYNTAX
Invoke-VMScript [-ScriptText] <String> [-VM] <VirtualMachine[]> [-GuestCredential <PSCredential>] [-GuestPassword
<SecureString>] [-GuestUser <String>] [-HostCredential <PSCredential>] [-HostPassword <SecureString>] [-HostUser
<String>] [-RunAsync] [-ScriptType <ScriptType>] [-Server <VIServer[]>] [-ToolsWaitSecs <Int32>] [-Confirm]
[-WhatIf] [<CommonParameters>]
DESCRIPTION
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. Network
connectivity to the ESX system 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 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, see the PowerCLI User's
Guide.
To run this cmdlet against vCenter Server/ESX/ESXi versions earlier than 5.0, you need to meet the following
requirements: *You must run the cmdlet on the 32-bit version of Windows PowerShell. *You must have access to the
ESX that hosts the virtual machine over TCP port 902. *For vCenter Server/ESX/ESXi versions earlier than 4.1, you
need VirtualMachine.Interact.ConsoleInteract privilege. For vCenter Server/ESX/ESXi 4.1 and later, you need
VirtualMachine.Interact.GuestControl privilege.
To run this cmdlet against vCenter Server/ESXi 5.0 and later, you need VirtualMachine.GuestOperations.Modify and
VirtualMachine.GuestOperations.Execute privileges.
PARAMETERS
-GuestCredential <PSCredential>
Specifies a PSCredential object containing the credentials you want to use for authenticating with the virtual
machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-GuestPassword <SecureString>
Specifies the password you want to use for authenticating with the virtual machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-GuestUser <String>
Specifies the user name you want to use for authenticating with the virtual machine guest OS.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostCredential <PSCredential>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostPassword <SecureString>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-HostUser <String>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-RunAsync [<SwitchParameter>]
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.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
-ScriptText <String>
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.
Required? true
Position? 1
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-ScriptType <ScriptType>
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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? false
-Server <VIServer[]>
Specifies the vCenter Server systems on which you want to run the cmdlet. If no 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.
Required? false
Position? named
Default value None
Accept pipeline input? False
Accept wildcard characters? true
-ToolsWaitSecs <Int32>
Specifies 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
-VM <VirtualMachine[]>
Specifies the virtual machines on whose guest operating systems you want to run the script.
Required? true
Position? 2
Default value None
Accept pipeline input? True (ByValue)
Accept wildcard characters? true
-Confirm [<SwitchParameter>]
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
-WhatIf [<SwitchParameter>]
Indicates that the cmdlet is run only to display the changes that would be made and actually no objects are
modified.
Required? false
Position? named
Default value False
Accept pipeline input? False
Accept wildcard characters? false
<CommonParameters>
This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer, PipelineVariable, and OutVariable. For more information, see
about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216).
INPUTS
OUTPUTS
One or more VMScriptResult objectsVMScriptResult
NOTES
To make PowerShell scripts work, you must restart the virtual machine after the PowerShell installation. For
BIN and BASH scripts, restart is not needed.
-------------------------- 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:<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 --------------------------
$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:
%<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 there are spaces in the path.
RELATED LINKS
Online Version: https://code.vmware.com/doc/preview?id= ... cript.html