WilliamLam.com

vSphere MoRef (Managed Object Reference) ID Finder Script

by // 20 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:

The Dreaded fault.RestrictedVersion.summary Error

by // 9 Comments

The question about the fault.RestrictedVersion.summary error message comes up pretty often on the VMTN community forums, specifically for new users of VMware vSphere. This particular error message is usually generated when trying to use one of the VMware SDK toolkits such as the vCLI, PowerCLI, VI Java, etc. or directly interfacing with the vSphere API for automation. The reason for this error message is due to the use of the free vSphere Hypervisor license (formally known as free ESXi).

Here is an example of the error trying to use vCLI to put an ESXi host into maintenance mode:

 
Here is an example of the error trying to use PowerCLI to power on a virtual machine:

Though the message is not easy to decipher for new users, it is a VMware license restriction placed on the vSphere Hypervisor license edition. Users only have the ability to perform read-only operations against the vSphere API which includes all the vSphere toolkits/management tools such as the vCLI, vMA, PowerCLI, VI Java, etc. Any operations that requires the change of state such as powering on a virtual machine or putting an ESXi host into maintenance mode is considered a write operation and is NOT allowed using the vSphere Hypervisor license type. When using the vSphere Client to manage an ESXi host, users have complete read and write access to these types of operations, they just can not be automated using the vSphere APIs or the various SDKs.

I personally think the error message should be updated to be a bit more clear and state that this particular license type (free ESXi) does not allow for any changes using the APIs. There is a small VMware KB article regarding the configuration of Jumbo Frames using the vCLI, but as you can see this error is not just applicable to vCLI but across the vSphere API/toolkits.

Now there are three types of licenses I consider an ESXi host can be configured and we'll walk through each of them. In the following example, I will be using the vSphere SDK for Perl script licenseManagement.pl to demonstrate the various license types which is allowed since it is only querying the license information which is a read operation to the APIs. 

1. Evaluation License - When you first install vSphere Hypervisor (free ESXi) and before applying your free license key, the host is automatically configured to be in this mode. In the evaluation state (60 days), you are basically licensed with ALL features just as if you have paid for the highest license type which is Enterprise Plus. You have full read and write access to the vSphere API and all the various vSphere toolkits for 60 days as part of the eval, once the 60 days are up, you will be configured just like the free version of ESXi. 

Here is an example of querying the license information for an evaluation ESXi host:

If we take a look at the License section using the vSphere Client, we'll see all the features included with this particular license type:

2. Free License - This is the free license that is provided from VMware once you have registered and downloaded vSphere Hypervisor (free ESXi)

Here is an example of querying the license information on a free ESXi host:

Notice the editionKey which is the first column and the name of the license in the second column which is "vSphere 4 Hypervisor" which represents the use of the free edition/license of ESXi. Both of these string text can also be used in conjunction to determine programmatically that you are running the free edition of ESXi.

If we take a look at the vSphere Client we also notice the list of features is quite small compared to the evaluation version:

3. All other licenses - This is all other vSphere edition license available which includes Essentials, Essentials Plus, Standard, Advanced, Enterprise and Enterprise Plus. For more details about the various license editions, please take a look a the vSphere Edition Comparison chart.

There is not a specific license feature that allows for the read and write access to the vSphere API and toolkits but by using any of the paid editions, you automatically have complete full read and write access to the vSphere APIs and the various vSphere toolkits.

Here is an example of querying the licensing information on a host with Enterprise Plus license type:

Here is an example of the features available via the vSphere Client:

So now you can easily check the vSphere edition you are running to determine whether or not you have the ability to use some of the awesome vSphere toolkits and management tools to automate your vSphere infrastructure which I highly recommend you do.

vSphere Tagging Feature Not So Invisible

by // 9 Comments

This evening I was reading a new blog post Tagging: An Invisible Feature in vSphere by Steve Jin in which he describes a hidden vSphere feature for tagging particular managed entities in your vSphere environment. The main consumer of this hidden feature is primarily VMware and it provides a level of meta data tagging to denote the importance of an entity. These tags are used in workflows in various vSphere products such as vCenter Server, vCenter Update Manager and View to just name a few.

Here is a screenshot of a VM entity using the vSphere MOB and as you can see from the tags, VMware can identify that this particular VM is running both vCenter Server and vCenter Update Manager.

If you have a VM that is a View Replica/Linked Clone, you may see these tags associated with the VM:

SYSTEM/COM.VMWARE.SIM.SVIMANAGEDOBJECT
SYSTEM/COM.VMWARE.VIM.SVIMANAGEDOBJECT

This feature can be really useful to allow users to tag particular objects in their environment of importance and easily correlate/integrate with a provisioning system and/or CMDB without having to resort to a separate database to store the meta data. You might say that custom fields exists today that can provide the same level of functionality, but they are actually pretty limited in scope. It only allows you to create custom attributes at a global vCenter level, host and virtual machine but not all managed objects such as Datastore, Networks, Resource Pool, etc.

So what if you wanted to create your own custom tags? Since these are hidden methods from VMware and they are not exposed through the public vSphere API, how might we access it? I spent a few minutes of digging and I was able to identify the two methods that pertained to tag management in the vSphere API:

addTag - Adds a tag to a managed entity
removeTag - Removes a tag to a managed entity

You can access both of these methods using the vSphere MOB as none of the official vSphere SDKs have these methods implemented. These methods are only supported when connecting to vCenter Server and are not exposed at an ESX(i) level.

In this example, I will create a custom tag at the Datacenter level called "WWW.VIRTUALLYGHETTO.COM"

Here is the path to a Datacenter object using the vSphere MOB:

If we scroll down on the page, you will notice a property called "tag" and as you can see in the screenshot below, no tags have been defined:

I will now craft the URL to the "addTag" method using the Datacenter as a point of reference:

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=addTag

As you can see the method accepts an array of tags which can be defined within the section. All tags MUST begin with "SYSTEM/" and then a unique string following, in our example I used "SYSTEM/WWW.VIRTUALLYGHETTO.COM". Once you have created your tag, you will then click on the "Invoke Method" to add the tag. Since this method does not return anything, the return result is void.

Now if we go back to the Datacenter page and refresh the page, you should see the new tag that was just created:

To delete a tag, you will generate the same URL but replace "add" with "remove":

https://reflex.primp-industries.com/mob/?moid=datacenter-1246&method=removeTag

You will again fill in the tags to be removed and then click on "Invoke Method":

As you can see, you now have the power to create your own tags on various managed entities in your vSphere environment. If you want to automate this through a script or command line, you can create simple HTTP POST operations to the vSphere MOB or create the appropriate interface methods to the SDK bindings to support these hidden methods. I'll leave the latter as an exercise for the readers.