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

Syntax

[-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
  • wildcards
  • pipeline
  • 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: (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: %% (for example, %programfiles%).

    Related Commands

    Feedback

    Was this page helpful?