WilliamLam.com

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

by // 27 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

New SRM 5 APIs

by // 2 Comments

There was a question about in one of my previous articles HBR (Host Based Replication) CLI for SRM 5 on whether there were any new/updates to the SRM 5 APIs. There are no official VMware SRM SDK's today as far as I know that can be consumed by toolkits such as PowerCLI, vSphere SDK for Perl, VI Java, etc. There is however an SRM Web Services API that can be used and has existed since the early days of SRM 1.0 as noted here in the documentation. Users that would like to use this API would need to create their own language bindings (stubs) based on WSDL (Web Services Description Language) provided by VMware.

Here are the list of available operations in the SRM 1.0 API:

  • SrmLogin
  • SrmLogout
  • GetApiVersion
  • ListRecoveryPlans
  • RecoveryPlanSettings
  • RecoveryPlanStart
  • RecoveryPlanPause
  • RecoveryPlanResume
  • RecoveryPlanCancel
  • RecoveryPlanAnswerPrompt
  • GetFinalStatus

In the SRM 5 API, there are 33 new operations not including the existing ones from 1.0:

  • ListProtectionGroups
  • ListInventoryMappings
  • GetInfo
  • GetPeer
  • ListProtectedVms
  • ListProtectedDatastores
  • ListAssociatedVms
  • GetProtectionState
  • ProtectionGroupListRecoveryPlans
  • ProtectionGroupQueryVmProtection
  • ProtectVms
  • UnprotectVms
  • AssociateVms
  • UnassociateVms
  • GetTasks
  • IsComplete
  • GetProtectionStatus
  • ListPlans
  • GetHistory
  • RecoveryPlanGetInfo
  • RecoveryPlanGetPeer
  • Start
  • Cancel
  • ListPrompts
  • AnswerPrompt
  • GetResultCount
  • GetRecoveryResult
  • GetResultLength
  • RetrieveStatus
  • RetrieveContent
  • SrmLoginLocale
  • SrmLoginSites
  • SrmLogoutLocale

During the SRM 5 beta, I did not see an updated API documents but I suspect the details and the implementation of these new operations will be available when SRM 5 is GA (generally available).

In the meantime, if you are on the SRM 5 beta and would like to get more details, you can retrieve the WSDL in several ways.

The first option is view the WSDL from your web browser by pointing it to your SRM server using the following URL: http://[srm-hostname]:8096/srm.wsdl

 
Note: Make a note of the URL protocol, it actually does not support HTTPS, but just normal HTTP when retrieving the WSDL

The second option is to browse the filesystem of the SRM server and the WSDL file can be found under the following path: C:\Program Files (x86)\VMware\VMware vCenter Site Recovery Manager\www

Free Linux & Windows Syslog Alternatives to depercated vi-logger in vMA 5

by // 12 Comments

Those of you who currently use vi-logger in vMA 4.x as a free syslog server for your ESX(i) hosts may notice this functionality has been removed in the latest vMA 5 release. VMware decided to remove the syslog functionality in vMA in favor of combining it with the vCenter Server. If you decide to run vCenter 5 on Windows, you have the option of installing an additional syslog collector on the same or separate Windows system and registering it as a vCenter plugin. If you are using the new VCVA (vCenter Server Virtual Appliance), there is also a syslog collector that is installed by default.

Using vMA's vi-logger was an easy and free solution, but you still have some alternatives without having to use vCenter or install/build a new syslog server. The following will document a free syslog solution for both a Linux or Windows platform.

Linux Syslog server alternative using vMA 5.0
You can actually leverage the existing syslog server on the latest vMA 5 release and with a few customization, get it setup to start collecting logs from your ESX(i) hosts as before with vi-logger.

Step 1 - It is recommend that you configure an additional disk on vMA for your syslogs as the size of vMA is quite tiny for additional use. I will assume that you know how to add and configure an additional disk, if not you can do a simple search on Google. In this example, I have a second disk that is 10GB and it is mounted up under /var/log/remote which is where the ESX(i) logs will be stored in.

Step 2 - You will need to edit the syslog configuration under /etc/syslog-ng/syslog-ng.conf and you will need to add three entries. The first addition is to configure the source for log messages from the network and enabling both udp/tcp on port 514, you may add the following under the default "src" entry.

source network {
udp6( port(514) );
tcp6( port(514) );
};

The next two entries will define the destination and how it'll log. You will add the following at the end of the syslog-ng.conf configuration file.

destination log_remote {
file("/var/log/remote/$HOST_FROM/$YEAR-$MONTH/messages-$YEAR-$MONTH-$DAY"
create_dirs(yes) frac-digits(3)
template("$ISODATE $PROGRAM $MSGONLY\n")
template_escape(no)
);
};
log {
source(network);
destination(log_remote);
};

The "log_remote" destination will send all logs from your ESX(i) hosts into /var/log/remote and will have the following format: $HOST_FROM/$YEAR-$MONTH/messages-$YEAR-$MONTH-$DAY

Step 3 -  Now you will need to restart the syslog server for the changes to take effect. You will need to run the following command: sudo /etc/init.d/syslog restart

If everything went successful, you should now be able to configure your ESX(i) hosts to point to your vMA 5 system and you should see logs appearing under /var/log/remote

Note: You will need to use sudo to view the directory under /var/log/remote and to view the logs

Windows Syslog server alternative using vCenter Syslog Collector
The vCenter Syslog Collector can be installed and used without the use of vCenter, you can easily turn any existing or new Windows system into a syslog server for your ESX(i) hosts for free.

Step 1 -  It is recommend that you configure a seperate disk on the Windows system that you are going to be using for your syslog server. I will assume that you know how to add and configure an additional disk, if not you can do a simple search on Google. In this example, I have a second disk that is 10GB and listed as Syslog (E: drive)

Step 2 - You will need access to the vCenter Server 5.0 installation ISO or executable to install the Syslog Collector utility. Start the installer and select and install VMware Syslog Collector

Step 3 - You have the option of using the local C:\ drive, but I would recommend setting up a separate drive if you can. If you decide to change the default log location, you need to ensure that you specify the following directory structure VMware\VMware Syslog Collector\Data else you will run into issues with the installation. In this example, I have moved my logs into E:\ drive and the path looks like the following: E:\VMware\VMware Syslog Collector\Data. You also have the ability to change the size of the log files before rotation and the number of logs before rotating.

Step 4 - If you are installing the Syslog Collector on the same host as vCenter Server, you should select the integrated installation else you should select a standalone installation.

Step 5 - The next screen will be the default ports to enable for both TCP/UDP and SSL which can be configured or left as the default as recommend.

Step 6 - The screen is how the Syslog Collector will be identified on the network and it should just be the IP Address of the host.

If everything went successful, you should now be able to configure your ESX(i) hosts to point to your Windows Syslog Collector system and you should see logs appearing under E:\VMware\VMware Syslog Collector\Data

As you can see even with vi-logger being removed in the latest version of vMA 5, you can easily still configure a free syslog server with your ESX(i) hosts on either a Linux or Windows platform.