virtuallyGhetto

vsphere sdk for perl

Retrieving Information from a Distributed vSwitch

by 30 Comments

There was a question on the VMTN community forums about retrieving the security policies: promiscuous, forged transmits and MAC Address change from a distributed vSwitch and distributed portgroup and I realized my getdvSwitchInfo.pl script that I wrote awhile back only included basic information about the dvSwitch.

I spent some time updating my vSphere SDK for Perl script to include additional information such as the high level summary, configuration of the dvSwitch, network resource pools, dvportgroups, hosts attached to dvSwitch and virtual machines attached to the dvSwitch. The script also includes information about many of the new features in vSphere 5.0 networking such as netflow, port mirror, LLDP, NIOC to just name a few. You can take a look at the What's New in vSphere 5 Networking whitepaper for more details.

The script allows for the following type of "list" operations: summary, config, networkpool, portgroup, host and vm. In addition, you can display all information by specifying the "all" operation and you can specify a specific dvSwitch by using the --dvswitch flag and providing the name of a dvSwitch.

Here is an example output for the list "summary" operation for all dvSwitches:

Here is an example output for the list "config" operation on a specific dvSwitch:

Here is an example output for the list "networkpool" operation on a specific dvSwitch:

Here is an example output for the list "portgroup" operation on a specific dvSwitch:

Here is an example output for the list "host" operation on a specific dvSwitch:

Here is an example output for the list "vm" operation on a specific dvSwitch:

Hopefully this script will be helpful if you need to quickly get information about your dvSwitches.

Identifying Idle vCenter Sessions

by 3 Comments

I recently received a question on how to identify idle vCenter sessions that may stem from a non-active vSphere Client or vSphere API connection. Properly managing sessions to your vCenter Server is as important as knowing who is logging in. If you exhaust the maximum number of connections, you can easily deny login access to other users and/or services that are needed to connect to vCenter Server which can lead to very bad things. In the worse case, you can even prevent administrators from logging into a new session to help terminate any stale/idle connections.

The vSphere API provides a sessionManagement manager to help you manage all sessions, including checking whether a session is still active and terminating a session. I wrote a quick vSphere SDK for Perl script called sessionManagement.pl which allows you to list all sessions for a given vCenter and terminating a a specific session. Every session has a unique sessionKey that the vCenter Server uses to track and it provides information such username, login time and last active which can be used to create an unattended script to automatically terminate sessions that have gone beyond a certain threshold.

Here is an example script output of performing the "list" operation:

Note: There maybe vCenter Plugins/Extensions that creates sessions such as CapacityIQ, those will be denoted by "vCenter Ext Session" field. These should not be terminated as it can negatively impact 3rd party applications.

Here is an example script output of terminating a specific session using the "disconnect" operation which you will need to specify sessionkey provided in the previous command:

For those of you that are interested in creating your own script to terminate idle sessions, you can use the DateTime Perl module to help with calculating the amount of idle time and comparing that to a pre-defined timeout value.

vSphere MoRef (Managed Object Reference) ID Finder Script

by 19 Comments

There was an interesting article this morning by my colleague Dave Hill about Looking up Managed Object Reference (MoRef) in vCenter Server, which references a VMware KB article showing you how to use vSphere MOB to find MoRef IDs.

A Managed Object Reference ID also known just as MoRef ID is a unique value that is generated by the vCenter Server and is guaranteed to be unique for a given entity in a single vCenter instance. Steve Jin has a great article going into detail about MoRef's, that you should check out here. MoRef ID's are not only used in vSphere, but they can also be referenced in other VMware products such as vCD (vCloud Director) or SRM to name a few or even by 3rd party/custom tools as a way to uniquely track objects within vCenter.

Using the vSphere MOB is one way of retrieving the MoRef ID, but of course this can be tedious if you are trying to locate MoRef's for multiple entities, in multiple vCenters. I decided to write a quick vSphere SDK for Perl script called moRefFinder.pl that allows a users to quickly query for a variety of Managed Objects (VM,Host,Cluster,Datacenter,Resource Pool,Network, Distributed vSwitch, Folder, vApp and Datastore) in a vCenter Server.

I also noted earlier, MoRef ID is only unique within a vCenter instance, so how do you track these objects across multiple vCenters? Well, VMware introduced a new property called instanceUUID (128 bit UUID) which is unique for a given vCenter Server and you can use this along with the MoRef ID to uniquely track objects across multiple vCenters and the script automatically outputs this value for any query.

Note: There have been some optimization in the latest vSphere SDK for Perl 5.0, it is recommended you use the latest version which is backwards compatible with vSphere 3.x and 4.x

The script requires two parameters:

  • type - The type of managed object
  • name - The name of the object as seen in vCenter Server

Here is an example querying for a Virtual Machine:

Here is an example querying for a Host:

Here is an example querying for a Cluster:

Here is an example querying for a Datacenter:

Here is an example querying for a Resource Pool:

Here is an example querying for a Network (Portgroup):

Here is an example querying for a Distributed vSwitch:

Here is an example querying for a Folder:

Here is an example querying for a vApp:

Here is an example querying for a Datastore:

How to Create a vCenter Alarm to Monitor for root Logins

by 6 Comments

Another interesting question on the VMTN forums this week, a user was looking for a way to trigger a vCenter alarm when a someone would login to an ESX(i) host using the root account. By default there are several dozen pre-defined vCenter alarms that you can adjust or modify to your needs, but it does not cover every single condition/event that can be triggered via an alarm. This is where the power of the vSphere API comes in. If you browse through the available event types, you will find one that corresponds to sessions called sessionEvent and within that category of events, you will see a UserLoginSessionEvent.

Now that we have identified the particular event we are interested in, we simply just create a new custom alarm that monitors for this event and ensure that "userName" property matches "root" as the user we are trying to alarm on. I wrote a vSphere SDK for Perl script called monitorUserLoginAlarm.pl that can be used to create an alarm on any particular user login.

The script requires only two parameters: alarmname (name of the vCenter alarm) and user (username to alarm on). Here is a sample output for monitoring root user logins on an ESX(i) host:

The alarm will be created at the vCenter Server level and you should see the new alarm after executing the script.

Note: The alarm action is currently to alert within vCenter, if you would like it to perform other operations such as sending an email or an SNMP trap, you can edit the alarm after it has been created by the script.

Next it is time to test out the new alarm, if you click on the "Alarms" tab under "Triggered Alarms" and login to one of the managed ESX(i) host using a vSphere Client with the root account, you should see the new alarm trigger immediately.

If we view the "Tasks/Events" tab for more details, we can confirm the login event and that it was from someone using the root account.

As you can see even though this particular event was not available as a default selection, using the vSphere API, you can still create a custom alarm to monitor for this particular event.

I do not know what the original intent of monitoring for monitoring root logins, but if there is a fear of the root  account being used, the easiest way to prevent this is to enable vCenter Lockdown Mode for your ESXi host.

How to Query VM Disk Format in vSphere 5

by 5 Comments

Prior to vSphere 5, it was not trivial to identify the particular disk format for a given virtual machine's disk. Using the vSphere Client, you would see a virtual machine's disk be displayed as either thin or thick. The problem with this is that the "thick" format can be either:

  • zeroedthick - A thick disk has all space allocated at creation time and the space is zeroed on demand as the space is used
  • eagerzeroedthick - An eager zeroed thick disk has all space allocated and wiped clean of any previous contents on the physical media at creation time. Such disks may take longer time during creation compared to other disk formats.

Users would not be able to distinguish the exact type using the vSphere Client or the vSphere 4 APIs. With the release of vSphere 4, VMware did introduce a new property in the vSphere 4 API called eagerlyScrub which was supposed to help identify whether a virtual disk was allocated as an eagerzeroedthick disk. Unfortunately there may have been a bug with the property as it never gets modified whether a disk is created as zeroedthick or eagerzeroedthick.

The only method that I was aware of to truly figuring out the disk format would be to manually parse the virtual machine's vmware.log file to identify the disk type which I wrote a script for in 2009.

During the vSphere 5 beta, I had noticed the vSphere Client UI now properly displays all three virtual machine disk format: zeroedthick (displayed as flat), thin and eagerzeroedthick (displayed as thick).

Seeing that VMware now displays the three different formats, I wanted to see if it was possible to extract this using the vSphere 5 APIs and not have to rely on the hack of reading the vmware.log files. It turns out that the eagerlyScrub property is now functioning properly when a VMDK is provisioned or has been inflated/converted to the eagerzeroedthick format. I wrote a simple vSphere SDK for Perl script called getVMDiskFormat.pl which allows you to extract the disk formats of all virtual machines connecting to either vCenter or directly to an ESX(i) host.

The script allows for two types of output: console (directly on the console) or csv (creates .csv file)

If you select csv output, by default it will be stored in a file called "vmDiskFormat.csv". You also have the option of specifying the filename by using the --filename flag and providing a name of your choosing.

You can then load the csv file into excel and easily sort through the various disk format types.

All this is already included in the latest version of the VMware vSphere Health Check Report 5.0 if you want a centralize report that includes virtual machine disk format.

How to Use Custom VM Icons in the vSphere 5 Client

by 3 Comments

Ever get tired of the same old virtual machine icons in the vSphere Client? Ever thought about changing it? Well with vSphere 5, you can! Here is a screenshot of some the custom icons I added for several virtual machines in my development lab.

One of the major enhancement in the vSphere 5 API is the introduction of the vCenter Solutions Manager, vSphere ESX Agent Manager, and vServices SDK. These various interfaces allows ISVs, partners and end users to easily extend the functionality of the vCenter Server and provide solutions that are tightly integrated via extensions/plugins that are aware of features such as vSphere HA, DRS and DPM.

Here what each of the interfaces provides:

vCenter Solutions Manager - is a view in the vSphere client where you can monitor and interact with the solutions that register with a vCenter Server instance. Solutions Manager shows three standard tabs for each running solution. The tabs list the virtual machines that a solution deploys and manages, show the health, name, company URL, version of the solution, and show any vServices that the solution provides.
vSphere ESX Agent Manager - automates the process of deploying and managing vSphere ESX agents. The services that ESX Agent Manager provides include out-of-the-box integration of agents with vSphere features such as DRS, AddHost, High Availability, DRM, and maintenance mode. All of these features can be difficult to integrate with manually. ESX Agent Manager also allows users to monitor the health of ESX agents, and blocks users from performing certain operations on ESX agents that might affect the virtual machines that use them. For example, ESX Agent Manager can prevent an ESX agent virtual machine from being powered off or moved from an ESX host that contains other virtual machines that use that agent.
vServices SDK - is a service that a solution provides to specific applications that run inside virtual machines and vApps. A solution can provide several types of vServices. Virtual machines or vApps can have dependencies on several types of vServices. A vService is similar to a virtual hardware device upon which virtual machines and vApps can depend. Instead of providing a piece of virtual hardware, vServices typically provide access to a service across a network. By providing a vService, a solution can expose application-aware services to virtual machines and vApps. For example, a vService can provide a backup service or a logging service to virtual machines and vApps.
For more details about these interfaces and how to implement them, take a look at the documentation here.

Even though these APIs are really meant for ISVs and partners to consume, if you would like to add a splash of color to your environment, you can use the following trick. At at high level we will be adding a new extension(s) which includes a mapping of a particular solution (e.g. logical name) to a particular icon that a virtual machine or vApp can be associated with. The icons must be 16x16 PNG format referenced by a URL. Once the custom extension has been created, you will then need to reconfigure the virtual machine(s) and associate the managedBy property to the solution's logical name key to update the virtual machine's icon.

You will need access to either the vCLI or vMA and the following two vSphere SDK for Perl scripts: registerCustomSolution.pl and updateVMManagedBy.pl You will also need access to vCenter Server 5 as this is not supported on an ESXi 5 host.

There is a very simple example in registerCustomSolution.pl which creates two extensions: one that includes custom icons and tabs that can link to any webpage (vGhetto) and one that only includes custom icons (Custom Application). You will need to edit the script so it fits your environment and there is a special variable in the script called "editedScript" which is set to 0 that prevents the script from running. This will ensure you do not accidentally create these extensions based on information in my development environment. Once you have updated the script, go ahead and change the value to a 1.

When you are ready, you will use the registerCustomSolution.pl script to create the extensions, here is an example:

To verify that the extensions were created properly with the information you provide, you can use pluginExtensionManager.pl to list all registered extensions. The command is the following: ./pluginExtensionManager.pl --operation list

You should see at the bottom of the output the extensions that were just registered and the associated configurations URL + icons. It is important to make note of the extension key (e.g. com.vmware.vGhetto) and the solution type string as that will be needed in the next section.

Now all we need to do is associate a particular virtual machine with the solution to update the virtual machine's default icon. You will use the updateVMManagedBy.pl script and using the extension key and type from the output from the previous screen.

To verify the icons have been updated, you will need to login to the vCenter Server and check out your virtual machines.You will also notice that on the right hand side of the virtual machine summary screen, there is a new "Managed By" section which includes a link to the vCenter Solution Manager.

Note: If you would like to reset or revert back to the original icons, you just need to use the  updateVMManagedBy.pl script and specify a empty string for the key. If you would like to unregister and remove the extension all together, you can use pluginExtensionManager.pl and perform remove operation.

Another way to view all the vCenter Solutions is on the home page and by clicking on the vCenter Solutions Manager icon.

From here you will see all registered vCenter extensions including some information about the vendor, version and health of the extension.

Here is a drill down into one of the extensions that contains several tabs to some URLs

As you can see, you can link to some useful URLs that can easily be accessible through the vSphere Client without having to go to your browser. Another neat feature of the tabs is to include any web management interfaces for a particular solution/vApp so that you can easily configure and manage the system from a single pane of glass.

In addition to this, you can also get a summary of the registered virtual machines with a given solution by clicking on the "Virtual Machines" tab and selecting "Managed By" box, the "Server" and "Agents" are reserved for ESX Agents.

There are also two caveats to be aware of if you decide to create custom icons for your virtual machines. The first is when you edit a virtual machine, you will get an annoying pop-up that states changes to the solution is not recommended. Under normal circumstance, where a solution/extension is provided by a 3rd party, you definitely do not want to manually tweak the virtual machine but in this scenario, it is fine.

The second thing I noticed is the custom icons do not properly show up in the nextgen vSphere Web Client, a default icon is used instead for virtual machines who have custom icons. I am not sure if this is a display bug with the vSphere Web Client or with the APIs.

So there you have it, if you are bored at looking at the same old icons and would like to differentiate some or all of your virtual machines, you now have the option to use custom icons.