virtuallyGhetto

vix

Using PowerCLI to invoke Guest Operations API to a Nested ESXi VM

by Leave a Comment

In my opinion, the Guest Operations API in vSphere is still one of the most powerful Virtual Machine capabilities that is available to vSphere Administrators and anyone else who integrates with the vSphere Platform. The Guest Operations API allows users to perform guest operations (running commands, transferring files, etc) directly within the guestOS as if you were logged in. Valid guest credentials are still required and once authenticated, the operations are then proxied through VMware Tools. Networking is not even required which makes this a handy feature for troubleshooting and can even extend into application level provisioning through a single API.

Obviously, I am a huge fan of this capability and have used it myself on more than one occasion. However, one limitation that I discovered awhile back when using the Guest Operations API with Nested ESXi VMs is that it threw some very strange memory related errors. It was only recently did I find out that there was a known issue with the VMware Tools for Nested ESXi, both the installable VIB and the pre-installed version in ESXi 6.0 on how the guest operations are executed. The good news is that for now, there is a simple workaround that can be applied when using the Guest Operations API.

You will need to add the following option, which runs the command under a specific resource group in the ESXi Shell:

'++group=host/vim/tmp'

Here is an example if I were to run the 'echo' command:

/bin/echo '++group=host/vim/tmp' "hello world"

A more interesting example would be to issue ESXCLI commands using the Guest Operations API, perhaps configuring the welcome message?

/bin/python '++group=host/vim/tmp' '/bin/esxcli.py system welcomemsg set -m "vGhetto Was Here"'

Notice, we need to pass in the resource group command to the "python" binary versus ESXCLI binary. The reason for this is that /bin/esxcli is really just a symlink to /bin/esxcli.py which is just a Python wrapper. The actual command being launched is the python interpreter and the arguments to the command is /bin/esxcli.py and the ESXCLI arguments itself.

For those who prefer to consume the Guest Operations API without having to directly use the vSphere API, you can use PowerCLI and use the Invoke-VMScript cmdlet. The problem with that is due to the way the cmdlet has been abstracted, the necessary underlying API details can not be accessed due to certain assumed defaults which can not be overridden or extended. This is a general problem that I have seen in more than one occasion where the abstraction is to make the consumption of the API simpler but in certain cases, it can also inhibit the use of the underlying API feature.

In this case, we will actually need to call into the vSphere API and using PowerCLI as an example, I have created a script called runGuestOpsInNestedESXiVM.ps1 which implements the specific Guest Operations APIs to issue commands to a Nested ESXi VM.

Here is an example of running the script and configuring the welcome message using ESXCLI:

guest_operations_api_nested_esxi

Whitepaper: Migrating From VIX API to the vSphere Guest Operations API

by 6 Comments

The VMware VIX API in my opinion is still one of the most powerful and undervalued API's that is available to customers and partners for Virtual Machine guest operating system Automation. The VIX API allows you to perform guest operations such as starting/stopping an application, file/directory manipulation, uploading/downloading files all within the guest operating system without requiring any network connectivity to the Virtual Machine. This is all made possible through the use of VMware Tools that is running inside of the Virtual Machine and operations are only performed after a user of the guestOS is properly authenticated.

Guest Operations using vSphere API

The use cases for such an API are endless:

  • Network reconfiguration (Re-IP for DR or miss-configuration)
  • Operating System configurations
  • Application configurations or deployments (example of this)
  • Backup/Restore for individual files
  • Downloading log files for troubleshooting
  • The list goes on ....

The VIX API was first introduced as a separate client API supporting VMware's hosted products such as VMware Fusion, Workstation and Player and later supported VMware vSphere. The API was quite popular for the hosted products and with the release of vSphere 5.0, the VIX API was finally integrated into the vSphere API to provide a single API that could manage all aspects of vSphere as well as these new guest operations APIs for your Virtual Machines. With this integration, these new APIs are now known as the vSphere Guest Operations API.

If you are familiar with the VIX API and would like to move or migrate to using the new Guest Operations API within vSphere, there is a really useful whitepaper that I recently came across called Transporting VIX Guest Operations to the vSphere API that provides a nice mapping of the API methods between the VIX and new vSphere Guest Operations API. The whitepaper also includes various code samples using Java, PowerCLI cmdlets and vSphere SDK for Perl to demonstrate the new Guest Operations APIs.

I think every vSphere administrator or developer should be familiar with the capabilities of the VIX and Guest Operations API and how it can help them further automate and manage your guestOSes and the applications that run inside of them.

Additional Resources:

Automating VCSA Network Configurations For Greenfield Deployments

by 6 Comments

If you deploy the VCSA (vCenter Server Appliance) or other virtual appliances directly onto an ESXi host,
you will notice the network configuration wizard for the virtual appliance is not available as you would expect when deploying to a vCenter Server.

The reason for this is that ESXi does not support some of the advanced OVF/OVA properties such as the Networking section and you will need to deploy the OVF/OVA to a vCenter Server to be able to configure these advanced options. This poses a problem if you need to deploy the VCSA in a greenfield environment where you will not have an existing vCenter Server running and you will be deploying directly to the ESXi host. Unless you have a DHCP enabled network, you will most likely need to manually go into the vSphere C# Client to change the network configuration as it was unable to obtain an IP Address.

Though this is a one time configuration, it is still not ideal and would require the use of a Windows system to access the vSphere C# Client. You can actually get around this by leveraging the GuestOperations API (previously known as VIX API) which allows you to perform operations within the guestOS that is running VMware Tools. The other nice thing about the GuestOperations API is that it does not require any network connectivity from the virtual machine.

Note: The GuestOperations API can be accessed in variety of ways and in this article I am demonstrating just two methods and does not require a Windows system. You can also access the GuestOperations API using PowerCLI if you are more comfortable with Windows and do not wish to use the vSphere C# Client to manually configure the network settings for the VCSA. I would also like to stress that though this article is about the VCSA, you can easily apply this to any VMware based virtual appliance or virtual appliance running VMware Tools.

The most important thing to identity before using the GuestOperations API is the specific command or program you wish to invoke and the argument it accepts. To configure the network configuration for the VCSA or any other VMware based virtual appliance, you would use /opt/vmware/share/vami/vami_set_network If you just run this command by itself, there are variety of options from IPv4 to IPv6, static or dhcp configuration. In our example, we will be configuring a Static IPv4 address for our VCSA and the command we would run is the following:

/opt/vmware/share/vami/vami_set_network "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1"

Method 1 - Using RVC (Ruby vSphere Console)

 

RVC is a nice open-source tool for interactively managing and configuring your vSphere infrastructure. RVC can be installed on any platform, in this example, I am running RVC on my Apple OS X laptop.

Step 1 - We first need to deploy the VCSA OVA and we can do so by using the ovftool via the command-line which can also be installed on Mac OS X system.

Step 2 - We then login to our ESXi host using RVC.

Step 3 - Next we will need to "change directory" to the location of our VM, in this example my VCSA is called VCSA-5.1. We can then run the "info ." command to view the summary of our VM. We can see that our VM is powered on from our initial deployment and we are ready to apply our network configurations in the next step.

Step 4 - To be able to run the above command, we will need to first authenticate into the guestOS. To do so, we will run the "vm_guest.authenticate ." and we will be prompted for the VCSA password. By default, the command assumes the username is root but that can also be specified on the command-line. If you are successful, you should not see any errors and then we can run the "vm_guest.start_program" command. Run the following to set a IPv4 static IP Address:

vm_guest.start_program . --program-path /opt/vmware/share/vami/vami_set_network --arguments "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1"

Note: All commands in RVC can be tabbed out with auto-completion.

If the command was successful, you can quit RVC and you should be able to ping the IP Address that you have just configured.

Method 2 - Using vSphere SDK for Perl Script

 

Awhile back I wrote a script called guestOperations.pl which is a vSphere SDK for Perl script that implements the new GuestOperations API. This is a generic script which can be used to remotely connect to either a vCenter Server or ESXi host and perform operations within a guestOS as long as VMware Tools is installed and running. In this example, I also have the vSphere SDK for Perl installed on my Mac OS X laptop, but you can also install this SDK on any platform as well.

Step 1 - We will first use the "validate" operation to ensure our credentials to the guestOS is correct, but more importantly ensure that VMware Tools is up and running.

If the operation was successful, we should see our guest credentials validated. If not, you may need to wait a minute or two while VMware Tools is still loading up.

Step 2 - To invoke the command to configure the network configuration, we will use the "startprog" operation and run the following:

./guestOpsManagement.pl --server mini --username root --guestusername root --vm VCSA-5.1 --operation startprog --program_path /opt/vmware/share/vami/vami_set_network --program_args "eth0 STATICV4 192.168.1.150 255.255.255.0 192.168.1.1" --working_dir /

If the command was successful, then you should now be able to ping the IP Address that you have just configured.

As you can see, with the use of the GuestOperations API, you can do more than just setup the network configuration for a VM, you can run pretty much any command within the guestOS as you normally would if you were to RDP or SSH in. This is a very powerful interface that you can leverage to help you automate your virtual machine deployment and configurations!

Automating the New Integrated VIX/Guest Operations API in vSphere 5

by 25 Comments

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

Automate Update Manager Operations using vSphere SDK for Perl + VIX + PowerCLI + PowerCLI VUM

by Leave a Comment

I recently saw an interesting question on the VMTN developers forum asking about vSphere SDK for Perl and VUM API integrations. As it stands today, VMware has not publicly exposed or documented the VMware Update Manager APIs, though they have released a few PowerCLI VUM cmdlets for PowerCLI users. This is one feature, in my opinion, that PowerCLI has over the other vSphere SDKs. This is quite unfortunate, since automating VUM operations is something I have looked forward to and the process can be slow from clicking around in the GUI. I think VMware sometimes forget that the world does not run on Windows and that VMware != Windows.

I was hoping with the release of vSphere 4.1, the VUM APIs would finally be exposed as a standard web service like the vSphere API provided with proper SDKs for the various languages. My reply to the VMTN user was exactly this: this type of integration does not exist today. If you would like to automate VUM operations, you must use the PowerCLI VUM cmdlets. The follow-up comment was how one might integrate between vSphere SDK for Perl and PowerCLI VUM cmdlets. Initially, I did not recommend this but it could potentially work with some type of WMI call or hooks from some Perl modules. The solution might get a little messy and it would probably be faster to just set up the PowerCLI VUM cmdlets on a Windows host.

As I thought about the question later that evening, I realized that there is potentially another method if you wanted to use the vSphere SDK for Perl but utilize the PowerCLI VUM cmdlets. The following solution will demonstrate the use of vMA, vSphere SDK for Perl, VIX Perl API, PowerCLI and PowerCLI VUM cmdlets. VMware VIX is used for guest management for VMs running on a VMware hypervisor, whether it be Workstation, Fusion or ESX(i). There is a Perl SDK for the VIX API which I use to generate a PowerCLI script that is transferred directly into a Windows VM running both PowerCLI and PowerCLI VUM. This dynamic PowerCLI script will contain the host information and VUM baseline provided from the vSphere SDK for Perl script. The script will remediate the host and then it will be deleted by VIX. This configuration is not ideal, but if you wanted to automate some of the available VUM operations but continue to use your vSphere SDK for Perl scripts, then you can.

The dynamic PowerCLI script that is generated is the following:

Connect-VIServer -Server [vc-server] -Protocol https -User [vc-user] -Password [vc-password]
$vmhost = Get-VMHost [vi-host]
$baseline = Get-Baseline [host-baseline]
$baseline | Attach-Baseline -Entity $vmhost -Confirm:$false
$vmhost | Scan-Inventory
$baseline | Remediate-Inventory -Entity $vmhost -Confirm:$false

Note: This is just one example, you can easily customize the script to generate other VUM operations or more complex PowerCLI script. Once the operation is completed on the ESX(i) host, the script is deleted via VIX.

Before we get started, you will need to have a Windows VM that has both PowerCLI and PowerCLI VUM installed which resides in the same infrastructure as your VUM Server. You will also need to have VMware vMA available and installed with VMware VIX which will be documented down below.

1. Download VMware VIX 1.10

2. Transfer VMware-VIX-1.10.1-266898.x86_64.bundle installer to vMA

3. Install VIX:

VMware-VIX-1.10.1-266898.x86_64.bundle

================================================================

[[email protected] ~]$ sudo sh VMware-VIX-1.10.1-266898.x86_64.bundle
Password:
Extracting VMware Installer...done.
You must accept the VMware VIX API End User License Agreement to
continue. Press Enter to proceed.
.....
The product is ready to be installed. Press Enter to begin
installation or Ctrl-C to cancel.
Installing VMware VIX API 1.10.1
Configuring...
[######################################################################] 100%
Installation was successful.

To complete the next section, you will need GCC to be installed which is not part of the default vMA installation. If you are using vMA 4.1, it is running CentOS and you can setup CentOS YUM repository. This will require that your vMA host can proxy out to internet or to specific site. I will document the changes that need to be made to talk to CentOS repository for package installs.

4. Create repository file:

[[email protected] ~]$ sudo vi /etc/yum.repos.d/centos-base.repo

Add the following to the repo file:

5. Install GCC using yum:

[[email protected] ~]$ sudo yum -y --nogpgcheck install gcc.x86_64

6. CD to vmware-vix directory and extract VIX Perl

[[email protected] ~]$ cd /usr/lib/vmware-vix/

[[email protected] vmware-vix]$ sudo tar -zxvf vix-perl.tar.gz
vix-perl/
vix-perl/vix.h
vix-perl/includeCheck.h
vix-perl/vm_basic_types.h
vix-perl/VixBinding.xs
vix-perl/VixBinding.pm
vix-perl/ModuleList
vix-perl/lib/
vix-perl/lib/API/
vix-perl/lib/API/API.pm
vix-perl/lib/API/Host.pm
vix-perl/lib/API/Job.pm
vix-perl/lib/API/VM.pm
vix-perl/lib/API/Snapshot.pm
vix-perl/lib/API/PropertyList.pm
vix-perl/lib/API/Constants.pm
vix-perl/lib/Simple.pm
vix-perl/Makefile.PL
vix-perl/typemap
vix-perl/ppport.h
vix-perl/README
vix-perl/samples/
vix-perl/samples/findhosttest.pl
vix-perl/samples/powertest.pl
vix-perl/samples/vmrun.pl
vix-perl/libvixAllProducts.so

7. Install VIX Perl

[[email protected] vmware-vix]$ cd vix-perl

[[email protected] vix-perl]$ sudo perl Makefile.PL
Writing Makefile for VMware::VixBinding

[[email protected] vix-perl]$ sudo make

[[email protected] vix-perl]$ sudo make install

If you did not want to go through all these manual steps after installing VIX, I actually wrote a quick shell script that will automate the configuration of the CentOS repository, GCC installation and extraction and installation of VIX Perl.

Download installVIXPerl.sh

Executing installVIXPerl.sh:

[[email protected] ~]$ chmod +x installVIXPerl.sh

[[email protected] ~]$ sudo ./installVIXPerl.sh

9. Download patch-host.pl script and transfer it to vMA

10. You will need to edit 4 variables defined within the script:

$psvm_username = Is the username to your Windows system running PowerCLI
$psvm_password = Is the password to your Windows system running PowerCLI
$powercli_bin = Is the full path to your powershell binary, if it is a default installation, you can leave this unchanged
$powercli_options = Is the path to vSphere PowerCLI psc file, you can also leave this as the default

Note: If you do decide to change either $powercli_bin or $powercli_options, make sure you add an extra "forward slash" which needs to be escaped in the Perl script.

The script requires you to connect to your vCenter server and provide the following parameters:

--vihost = Name of ESX(i) host to be patched

--baseline = Name of the VUM basline to attach

--psvm = Name of the Windows VM running both PowerCLI and PowerCLI VUM

Here is an example patching an ESXi host that is running on 4.0u2 and using the script to apply vSphere 4.1 baseline:

[[email protected]]$ ./patch-host.pl --config --server reflex.primp-industries.com --username primp --vihost esxi4-3.primp-industries.com --psvm powerclivm --baseline vSphere4.1-Upgrade

Entering maintenance mode for esxi4-3.primp-industries.com
Successfully entered maintenance mode for esxi4-3.primp-industries.com
Guest login successfully!
Copy patch-host-esxi4-3.primp-industries.com-22174.ps1 to guest successfully!
PowerCLI/VUM script executed successfully!
Script removed successfully!
Successfully patched esxi4-3.primp-industries.com using VUM baseline: vSphere4.1-Upgrade

One thing I did notice, after the script is transferred to the Windows VM, it takes about 15-20 seconds before the script executes. I am not exactly sure why this occurs, as this does not happen when running the PowerCLI script logged into the VM. This may be due to the way VIX is executing the script within the guest.

The following resources were used in creating this script: