WilliamLam.com

How to control maximum number of VMware snapshots

by // 21 Comments

There are currently no methods of controlling the number of VMware snapshots using vCenter or ESX(i) permissions today, you either provide the snapshot privilege or you deny it all together. I recently discovered an undocumented .vmx entry that allows you to control the maximum number of VMware snapshots for a given virtual machine. By default, a virtual machine can have a snapshot tree depth of 31, in the worse case scenario supporting up to a maximum of 496 snapshots.

Here is what a VM looks like with 496 snapshots (unexpanded):

 

Note: If you are interested in what this looks like fully expanded, take a look at the screenshot at the very bottom of this post.

If you like to prevent the above or at least control the maximum number of snapshots for a given virtual machine, you can add the following into a VM's .vmx configuration file. Ideally, this is deployed using vSphere API as there is no need to directly edit the VMX's file and this can also be applied to a live running VM (another benefit of using the vSphere API).

Here is an example using PowerCLI:

$vm = Get-VM -Name TestVM
New-AdvancedSetting -Name snapshot.maxSnapshots -Value 1 -Entity $vm

For those that prefer using another vSphere SDK, you just need to use the ReconfigVM_Task() to add the VM Advanced Setting. Please take a look at this sample for here for how to add/update VM Advanced Settings.

snapshot.maxSnapshots = "n"

where n = max number of snapshots and n <= 496

Here is a screenshot of adding this .vmx parameter using the vSphere Client:

The virtual machine above already has one snapshot and per the configuration change, we should not be able to take any additional snapshots:

Next, we will try to take a second snapshot:

As you can see, an error is thrown that we have reached the maximum number of permitted snapshots. If you would like to disable snapshots all together, you can set the value to be 0 and this will prevent anyone from taking snapshots, including administrators.

Here is a an screenshot of the expanded view of a VM with 496 snapshots:

Note: These snapshots were created with a VM running in an vESXi host and script to exhaust the maximum snapshot depth of 31. Each snapshot level was also exhausted with the maximum number of snapshots. Starting from level-1: it was the maximum depth minus 1, level-2: it was maximum depth minus 2, and so fourth. This was just a test to see what the system could handle, you should not try this a home or on a production VM 😉 Use at your own risk

How to Ack & Reset vCenter Alarm implementing hidden API method

by // 11 Comments

There was a recent question in the VMTN developers forum around automating the acknowledgment and resetting of a triggered vCenter alarm using vSphere SDK for Perl. This is actually a trivial task using the vSphere Client, you would first identify the alarm and acknowledge the alarm by right clicking on the alarm and selecting "Acknowledge Alarm". To reset the alarm, you would right click on the alarm and select "Reset Alarm to Green".

To automate this task using the vSphere SDK for Perl which uses the vSphere API, you would perform the same two API operations. Doing a search, you will find a method called AcknowledgeAarm which should does exactly that, but if you try to search for method to reset an alarm, you will notice no such method exists. This was something I was aware of since vSphere 3.5 API, but never understood why it was kept hidden.

Here is a screenshot of the alarmManager in the vSphere MOB and you will notice no methods pertains to resetting an alarm:

You might ask, how is the vSphere Client performing this operation and what API method is it using? Sadly, this operation is one of the many hidden API methods that VMware choose to hide and not public expose for various reasons.

However, there are several ways of identifying some of these hidden vSphere API methods and properties. When you install the vSphere Client on your workstation, there is a catalog directory (e.g. C:\Program Files\VMware\Infrastructure\Virtual Infrastructure Client\4.1\Catalogs\Default)  that is created based on the version of vSphere and within the vim directory, there are these *.vmsg files that contain information regarding the VIM API (Virtual Infrastructure Management API) and searching within these files, you will find some hidden goodies.

Searching the task.vmsg file and within the alarm section, you will see a method name called setAlarmStatus:

alarm.AlarmManager.setAlarmStatus.label = "Set alarm status"
alarm.AlarmManager.setAlarmStatus.summary = "Sets the status of an alarm for an entity"

As you can see, there are other methods with respect to the alarmManager that is documented, but the method above is not documented in the vSphere API reference. We can take this information and further validate by using the vSphere MOB to see what parameters are required for this method.

By generating the proper URL, you can see the method is exposed and the required parameters to this function:

We can perform one additional confirmation to ensure that the method above is actually the method the vSphere Client is performing when resetting an alarm. The tool that we will use here is Onyx, yep, it is not only useful for PowerCLI but for all vSphere developers and administrators. I created a dummy alarm that would trigger if a VM is powered on or powered off and by running Onyx to capture the API calls when acknowledging and resetting an alarm.

Here is the output from Onyx:

As you can see, the two operations uses the AcknowledgeAlarm and the hidden SetAlarmStatus API method. We now can definitively say that the above hidden API method is being used and now we need to figure out how we can incorporate this method into the existing vSphere SDK for Perl.

In this example, I will be working with the vSphere SDK for Perl found on vMA 4.1, but the same set of changes will apply to vCLI 4.x being installed on a Windows or Linux system. There are two client Perl stubs or Perl Modules that contains prototype and definition of a vSphere API method:

/usr/lib/perl5/5.8.8/VMware/VIM25Stub.pm (prototype definition)
/usr/lib/perl5/5.8.8/VMware/VIM25Runtime.pm (method definition)

We will first edit the VIM25Runtime.pm module and if you are on vMA, you will need to use 'sudo' to edit the file. We will add the SetAlarmStatus entry try similar the AcknowledgeAlarm method:

Next we will edit the VIM25Stub.pm and again it will be very similar to an existing method, but now we must populate the parameters based on what we discovered from the vSphere MOB:

Now we are ready to implement this method in a vSphere SDK for Perl Script. I quickly threw together a script that helps manages your vCenter alarms using the CLI by listing all active and triggered alarms in either a red or yellow state.

Download Script: alarmManagement.pl

Here is an example of listing all triggered alarms that are either in a red or yellow state:

Here is an example of acking and resetting the above alarm and utilizing the new hidden API method that was just implemented:

There you have it, a method that was once hidden is no longer =)

If you are interested in locating other hidden API goodies, take a look at this post on How to browse the internal vSphere APIs

What's new in the vSphere 4.1 MOB

by // 16 Comments

The vSphere MOB (Managed Object Browser) is not a well known tool and unless you are a developer, you probably do not know of its existence. The simplest way to describe the vSphere MOB is that it is a debugging tool to graphical visualize all entities within the vSphere API through a web browser. It is often used to better understand the vSphere API/inventory and aide in developing your own vSphere application or script. For a detailed deep dive of the vSphere inventory, check out Steve Jin's post here.

The vSphere MOB can be reached by pointing your web browser to either an ESX(i) or vCenter host followed by the path "/mob". You will be prompted for credentials as you normally would prior to gaining access to the MOB.

The vSphere MOB may not always be the easiest to navigate. Understanding the vSphere inventory structure is definitely helpful, otherwise it can be very confusing to users. With the release of vSphere 4.1, there are two major changes in the MOB that can help make the navigation easier for developers.

Previous to vSphere 4.1, the MOB would display managed entities using their Managed Object IDs (MoRef ID) as a way to uniquely identify these objects. This made it very difficult for developers to identify the specific object you are viewing without having to dig further.

In vSphere 4.1, the MOB provides both the MoRef ID and the translated the names of the managed entities.

The vSphere MOB not only displays information about the managed entities but also provides a way to interact with the system. It does this by listing the available API methods for each managed entity at the bottom of the page and can be executed by providing the correct input parameters. The issue arises when trying to execute methods which requires complex input that require more than a simple string or integer value. The format of the input is XML-based and it can be challenging to generate the correct format, especially without any examples.

In the new version of the MOB, you are now presented with an XML template of the required parameters which can then be filled out to execute the method.

The following example will demonstrate the change of an ESXi advanced configuration value for configuring a syslog server:

Once you have filled in the required parameters, you will need to click on the "Invoke Method" to execute the specific method.

Here we verify the advanced configuration key "Syslog.Remote.Hostname" has been changed and is set to our new syslog server.

I think these two changes will make it easier for developers to navigate the vSphere MOB and assist with understanding the vSphere API and it's managed entities.