The Dreaded fault.RestrictedVersion.summary Error

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:

 

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.