Will Invoke-VMScript work ?

The Invoke-VMScript cmdlet can be a very useful cmdlet, but sometimes it will fail against one or more of your VMs. And it is not always immediately clear why the Invoke-VMScript cmdlet will not work against that specific VM.
The cmdlet help contains a number of prerequisites, but how do you verify if all the prerequisites are fulfilled?
I decided to create a function that would verify the prerequisites, and that would, if requested, which of the prerequisites was missing.

The prerequisites

Official

The official prerequisites are all documented in the help for the Invoke-VMScript cmdlet. The following table is a summary.

PowerCLI 4.1 4.1U1 5
only 32-bit engine x x x
VMware Tools installed x x x
read access to VM folder x x x
Virtual Machine.Interaction.Console privilege x x x
VM powered on x x x
port 902 to ESX(i) hosting the VM x x x
VIX 1.6.2 x x
VIX 1.10 x
Windows XP, Windows 7, Windows 2003 Server, Windows 2008 Server,Redhat Enterprise 5 x x x

Unofficial

From my own experience and from several posts in the PowerCLI Community, I have 2 additional prerequisites.

  • The cmdlet seems to work most of the time when the guest OS is Windows 2008 R2. Note that there have been reports about errors with this OS. In the current PowerCLI build Windows 2008 R2 is not in the list of supported guest OS.
  • When you use the hostname in the Connect-VIServer cmdlet, the Invoke-VMScript doesn’t seem to work. When you do the Connect-VIServer with the FQDN or the IP address, the cmdlet works. The error message looks like this

The list of my 2 non-official prerequisites

PowerCLI 4.1 4.1U1 5
Windows 2008 R2 Server x
Connected with FQDN or IP x x x

The Script

Annotations

Line 32-35: Retrieve some properties the script will use later.

Line 38-40: My poor man’s Object By Name (OBN) implementation.

Line 42: Set all prerequisites to $false

Line 73-89: To test if the caller has read access to the VM folder, the script will copy the VMX file to local storage.

Line 82: This is the major bottleneck in the function. The Copy-DatastoreItem cmdlet is quite slow compared to the other PowerCLI cmdlets.

Line 110: All Windows Server 2003 variations have a guestId that starts with “winNet”. See the VirtualMachineGuestOsIdentifier enumeration.

Line 131-133: Chekc if the guest OS is Windows 2009 R2. If you don’t want this test, just comment out these lines.

Line 136: By testing if there any dots in the name, we can verify if it is a Fully Qualified Domain Name or an IP address.

Sample use

A very straightforward example

This will return a simple object, where the OK property will say if the prerequisites are met or not.

If we want to know which of the prerequisites failed, we can do

From the output we can immediately see why the Invoke-VMScript cmdlet would fail.

Looks like we are not running this in a 32-bit engine.

To also see my non-official prerequisites, we can do

This produces the following

All the official prerequisites are fulfilled, but it looks as if our Connect-VIServer might have been done with a short hostname.

Let me know if you know of any other prerequisites, and I will add them to the function.

Enjoy the function.

18 Comments

    Ashok Sharma

    Hi LucD,

    I want to verify the following things on a windows VMware machine after build. Please can you help me here.
    1. Verification of System Properties:
    1.1 OS Version : Yes
    1.2 Server Name : Yes
    1.3 Server Domain : Yes
    1.4 Server OU : Yes
    1.5 IP Details : Yes

    2. Verify the Region and Language dialog box from the Server Management console.

    2.1 Location : Yes
    2.2 Format for Date and Time : Yes
    2.3 Keyboard : Yes
    2.4 Language : Yes
    3. Verify the VLAN details
    3.1 VLAN ID : Yes

    4. Verify the antivirus agent is installed with the latest definitions are updated.

    5. Verify that the partitions C:\ and D:\ are available

    5.1 C Drive: : Yes
    5.2 D Drive: : Yes

    Alexander Witt

    Hi Luc,

    Do you know if the remote connection to the VM uses network stack, or if the hypervisor is able to talk to the VM through VMware tools exclusively?

    I am asking because my VM is not on the network — in fact the reason I am trying Invoke-VMScriptis because I want to remotely iniate an IP-address reset.

    I am able to locate the Vm with Get-VM, have saved a credential object with Get-Credential into a variable $cred but trying something like Get-VM | Invoke-VMScript 'ls' -GuestCredential $cred gives me:

    > A general system error occured: vix error codes = (1, 0).
    I am trying your script to see to debug a connection to a VM. Attempting to then use Invoke-VMScript I get

      LucD

      Hi Alexander,
      The ESXi host “talks” to the VMware Tools through the VMX process on the ESXi server.
      In section Benefits of the New API Set in Transporting VIX Guest Operations to the vSphere API, there is a great schematic that shows the process.
      Guest Operations

      In fact the script needs to be updated. For example port 902 is not required anymore.

    Sergg

    Thank you so much!

    dj

    Hi LucD,

    When I run it, it does not do anything…I must be missing something.

    I copied your script to E:\tmp

    PowerCLI E:\tmp>
    PowerCLI E:\tmp>
    PowerCLI E:\tmp> $vm = get-vm -name vmname2
    PowerCLI E:\tmp> .\Test-InvokeVMScript -vm $vm
    PowerCLI E:\tmp>

    ken

    Hi LucD. In looking at your test script, I don’t see anything pertaining to 32bit guestOS in it, so am I correct in assuming that Invoke-VMscript doesn’t support 32bit guestOS? such as w2003 or vista 32bit?

    If 2003 32bit is NOT supported it would explain why I can’t get my script to produce against these VMs in my test lab..

      admin

      Hi Ken, as a matter of fact the 32-bit versions of the supported guest OSs are included in the test, see lines 110-112

    Dan Meier

    I found that I did need WinRM installed to perform just a simple “dir” script.
    My server passed with -Official:$false. My server is Win2003 Enterprise SP2. I installed .Net 2.0 SP1 and KB968930 and then the script worked. I’m using PowerCLI 5.0 build 768137 and I’m only using Guest credentials and not Host credentials.

      LucD

      Hi Dan, interesting.
      Although I can’t see why WinRM would make a difference.

      Did you run the ‘dir’ with ScriptType Bat or PowerShell ? The default is PowerShell.

    E. Jacob Hayes

    Luc,

    Did you forget this in your details section?

    Add-Member -Name VIXVersion -Value $condVix -MemberType NoteProperty -PassThru

      LucD

      Hi Jacob, no I just didn’t think of including it 🙂
      Good suggestion, I’ll plan an update.

    chittra

    i had used invoke-vmscript to execute perl scripts within a guestos. copied the perl script into VM using copy-vmguestfile and then would invoke it.
    What i find is, every time the script completes execution, it prints below on the powercli window,
    ScriptOutput
    —————————————————————————————————
    —————————————————————————————————

    how do i avoid this? or how do i hide this?

      LucD

      Hi Chittra,
      Did you try piping the output of the Invoke-VMScript cmdlet to Out-Null ?

      Invoke-VMScript .... | Out-Null

    JJ_Cain

    @LucD- First time post, long time fan. Thanks for this script – great time saver. I am doing a mass migration of Windows guests (~50 a week) to upgrade to pvscsi and vmxnet3. I have a large number of 2k8R2 VMs coming up and during my testing, 1 line from my .ps1 is not passed. I use Invoke-VMscript several times throughout the .ps1 but this 1 liner to remove the e1000 is not playing nice. It does not like the “@” even when in the “double quotes”. Any ideas to get this passed? single quotes? Here-string?
    #$remove1 = C:\Devcon64 -r remove “@PCI\VEN_8086&DEV_100F&SUBSYS_075015AD&REV_01\4&B70F118&0&0888”
    #Invoke-VMScript -vm $vm -ScriptType bat -ScriptText $remove1 -GuestCredential $vmcredentials

    Ed Grigson

    I’ve just discovered that the PowerCLI cmdlets for guest OS integration (including Invoke-VMScript) aren’t backwards compatible. Presumably the VIX change is the reason for this? I just put up a quick blogpost – http://www.vexperienced.co.uk/2012/01/06/powercli-v5-gotcha-if-you-use-guest-os-cmdlets/.

    I can see the script checks that the VIX version is correct, but does it check the version of the host running the VM? Otherwise it’ll give the all clear to a PC with PowerCLI 5 installed but if the VM runs on an ESX4 host the scripts will still fail.

      LucD

      @Ed, you are right. I’ll update the script to reflect what is stated in KB2010065

    Benj Starratt

    Thanks again for another great script. You helped me out with a script a year ago when I was doing a mass migration of Windows guests with an upgrade to pvscsi and vmxnet. As a different part of that project I did use invoke-vmscript against about 500 Windows VM with about 80% Windows 2003 SP2. I didn’t have any problem getting the invoke-vmscript to work on the 2003 VMs. I did ensure that PowerShell 2.0 and all the WinRM management components were installed prior to that project so that may be why it worked so well. The only weird issue I remember is that I would have to connect with host credentials instead of vCenter credentials.

      LucD

      @Benj, thanks.
      Afaik WINRM is not needed for the Invoke-VMScript cmdlet, it uses the VMware Tools to execute commands inside the guest OS. When you do PowerShell Remoting, which is another possibility to execute commands inside a guest OS, you do need WINRM.
      In PowerCLI 4.0 you did have to pass the hosts credentials, when your Connect-VIServer was executed against a vCenter. That requirement was dropped in recent PowerCLI builds.

Leave a Reply

Your email address will not be published. Required fields are marked *

*
*

Buy the Book