VMware hinted earlier this year that the future of the VIX API would eventually be integrated into the core vSphere API, it looks like the wait is finally over. With the latest release of vSphere 5, the VIX API is no longer a separate API but consolidated into the core vSphere API which allows users to perform guest level operations directly to a virtual machine that is running VMware Tools.

There is now a new managed object called GuestOperationsManager which provides functionality for Authentication (authManager), File management (fileManager) and process management (processManager). The API is actually quite easy to use as you need to first acquire a guest auth credential within the guest and then you can perform any of the various guest operations using this credential cache.

I wanted to show the power of the VIX API by creating a vSphere SDK for Perl script called guestOpsManagement.pl that implements majority of the VIX/Guest Operations for users to manage from a centralized script. You will need to have a system that has the vCLI installed or use VMware vMA and to utilize the new VIX operations, your virtual machines must have the latest VMware Tools installed.

You can download guestOpsManagement.pl script here

The script supports 12 different VIX Operations which are described below:

Operation Description
validate Allows a user to validate guest credentials without performing any VIX Operation
ps Performs a process listing within the guestOS
startprog Starts a program within the guestOS
kill Kills a particular process within the guestOS
ls Perorms a listing of a particular directory within the guesOS
mkdir Creates a directory within the guestOS
rmdir Removes a directory within the guestOS
rm Removes a file within the guestOS
mv Move/Rename a file within the guestOS
mvdir Move a directory within the guestOS
copyfromguest Download a file from within the guestOS to local system
copytoguest Upload a file to the guestOS from a local system
Here is an example of performing the "validate" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation validate --guestusername root

Here is an example of performing the "ps" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation ps --guestusername root

In the next example, we will kill off the "tail" process as listed above.

Here is an example of performing the "kill" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation kill --guestusername root --pid 13198

Here is an example of performing the "startprog" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation startprog --guestusername root --working_dir /root --program_path /usr/bin/touch --program_args /root/virtuallyghetto

Note: There is known vSphere SDK for Perl bug for the return value of a "long" which will be resolved in GA release of vSphere SDK for Perl 5.0. You should not see the "error" message when running this operation

Here is an example of performing the "ls" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation ls --guestusername root --filepath_src /var/log

Here is an example of performing the "mkdir" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mkdir --guestusername root --filepath_src /tmp/virtuallyghetto

Here is an example of performing the "rmdir" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation rmdir --guestusername root --filepath_src /tmp/virtuallyghetto

Note: If you would like to perform a recursive directory delete, you will need to specify the --recursive, please use with caution

Here is an example of performing the "rm" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation rm --guestusername root --filepath_src /root/virtuallyghetto

Here is an example of performing the "mv" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mv --guestusername root --filepath_src /root/steve_jablonsky --filepath_dst /root/hans_zimmer

Here is an example of performing the "mvdir" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mvdir --guestusername root --filepath_src /tmp/foo --filepath_dst /tmp/bar

Here is an example of performing the "copyfromguest" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation copyfromguest --guestusername root --filepath_src /var/log/messages

Here is an example of performing the "copytoguest" operation:

./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation copytoguest --guestusername root --filepath_src /home/vi-admin/test.pl --filepath_dst /root/test.pl

There is also complete perl docs for this script which can be called using the following command:

perldoc guestOpsManagement.pl

20 thoughts on “Automating the New Integrated VIX/Guest Operations API in vSphere 5

  1. Calling these methods in the MOB always returns “Not initialized: boolean interactiveSession”

    Here is the auth param (ListProcessesInGuest):


    MyUsername MyPassword false

  2. Are you creating a new NamePasswordAuthentication? which is then passed to any of the VIX functions? Curious on why you’re going directly through the MOB versus one of the vSphere SDKs?

  3. Just wanting to test it out before I put in the effort. NamePasswordAuthentication inherits from GuestAuthentication. Have you tried this from the MOB?

  4. @Bob,

    I’ve already created a Perl script that implements majority of the VIX operations, I would say the hard work is pretty much done 🙂 It works very well, but no I’ve not used the MOB test VIX operations. I only use the MOB if I have to, else I use the SDKs which is what they’re there for.

  5. This is a really useful script for me, now that VMware have dropped guest customisation for Ubuntu and Debian – I can use this to write a script to perform my customisations again (and do a lot more besides). However, I’m having trouble getting it to work on my vSphere 5 setup. It dies with this error:

    Can’t locate object method “guestOperationsManager” via package “ServiceContent” at /usr/local/vmware/bin/guestOpsManagement.pl line 370.

    When I use a web browser to look at ServiceContent, I can see GuestOperationsManager, so it is there, but for some reason the script can’t see it.

    Any ideas?

    Tim

  6. @Tim, Are you sure you’re using the latest vSphere SDK for Perl 5.0? It sounds like that might be the problem and not so much for the actual host itself.

  7. @vExpert2011 – You can easily do so by setting –password option and then use a simple “for” loop to iterate through all your VMs

  8. Interesting topic and tried to implement some of it myself.
    I did find however, that the script only works ons a vma installation related to the function of uploaden data to a guest vm. This function simply fails with a http 500 error.

    A second issue I noticed is that vmware tools does not allocate an tty (or pty) on linux, meaning that you cannot use the sudo command.

    Any suggestions on how to tackle these problems?

  9. This is working great.
    How does it handle duplicate VM names? Is there any way to specify where the TestVMName1 resides (Cluster, Host) inside the vCenter tree?

    This script can be great to configure /etc/network/interfaces and hostname on new guests.

    I’ve been searching for something that would allow to launch a “deploy from template” from command line, and if possible, specify guest customization options (if this is not possible, it can be easily done using guestOpsManagement anyway.) Do you know of any or accept such script suggestion?

    Thanks for this great content!

    • @Javier,

      vCenter does not allow for duplicated VM names, so you should not have to worry about that. Regarding your customization question, today you can do basic network customization (UNIX/Linux) via the Customization process in vCenter. If you need further customization such as application or other OS configurations, I would recommend using the Guest Operations Management OR via traditional SSH

    • Thanks for the quick response 🙂
      vCenter allows duplicate VM names. Just to be sure, i just created 3 VMs named “1”, in different hosts, same & different datacenter.

      The problem is, having such repeated VM names, how can i specify the source (datacenter, host) to take it from?

      Regarding the customization. I already have a debian customization spec that works like a charm when deploying templates from the vsphere client (click click), however, we wanted to automate this from command. (although i am already using your great datastoredeploy + guestmgmt scripts to do it)

    • @Javier,

      Ah sorry, you’re right, uniqueness is defined at the Datacenter boundary (though good rule of thumb to generate unique names or at least check if you’re deploying it programmatically).

      If you want to filter a VM by Datacenter, you can use the following when searching for a VM:

      my $vm_view = Vim::find_entity_views(view_type => ‘VirtualMachine’, begin_entity => $datacenter_view);

      where $datacenter_view is Datacenter you want to search in. Recommend taking a look at the vSphere SDK for Perl docs for more details

  10. For the InitiateFileTransfer(…), the fileattributes are not populated. Is this not required ? If this field is needed, then what should be the time format ?

  11. Hi William,

    I am trying to download the guestOpsManagement.pl script but it is not available at the link you provided.
    Do you have an alternate location to download the script.

Thanks for the comment!