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 |
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation validate --guestusername root
./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.
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation kill --guestusername root --pid 13198
./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
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation ls --guestusername root --filepath_src /var/log
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mkdir --guestusername root --filepath_src /tmp/virtuallyghetto
./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
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation rm --guestusername root --filepath_src /root/virtuallyghetto
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mv --guestusername root --filepath_src /root/steve_jablonsky --filepath_dst /root/hans_zimmer
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation mvdir --guestusername root --filepath_src /tmp/foo --filepath_dst /tmp/bar
./guestOpsManagement.pl --server vcenter50-1 --username root --vm vMA5 --operation copyfromguest --guestusername root --filepath_src /var/log/messages
./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
Calling these methods in the MOB always returns "Not initialized: boolean interactiveSession"
Here is the auth param (ListProcessesInGuest):
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?
Just wanting to test it out before I put in the effort. NamePasswordAuthentication inherits from GuestAuthentication. Have you tried this from the MOB?
@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.
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
@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.
Hi William, thanks for the script!
I'm trying to iterate over all the *nix hosts to run a mkdir /tmp/vmware-root in each Guest OS - but at each iteration it is asking for the vcenter password (see community thread below) - is there a way to cache the vcenter password btw iterations or hard code it in the perl script as a workaround?
http://communities.vmware.com/message/2003225#2003225
thanks!
@vExpert2011 - You can easily do so by setting --password option and then use a simple "for" loop to iterate through all your VMs
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?
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
For the InitiateFileTransfer(...), the fileattributes are not populated. Is this not required ? If this field is needed, then what should be the time format ?
That's correct, it is not required as defined by the API reference http://pubs.vmware.com/vsphere-55/index.jsp?topic=%2Fcom.vmware.wssdk.apiref.doc%2Fvim.vm.guest.FileManager.FileAttributes.html There are defaults or you can follow the specification
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.
Try now. I've moved my scripts from SVN over to Github