New Licensing APIs Since VMware vSphere 4

There has been a total change in vSphere licensing model since version 4. Before that, you need a special/dedicated licensing server which may be more flexible/powerful but also cause many troubles in production environment which made licensing related issues one of the top categories in tech support.

vSphere 4 has dramatically simplified the whole licensing model, and removed the licensing server. To find out how the new licensing model works, check out the VMware vSphere 4 Licensing Guide. It covers both the vSphere side and the portal with which you can easily manage your license keys: splitting/combining, etc. This article does not cover the portal part but related APIs only.

Lost VMs or Containers? Too Many Consoles? Too Slow GUI? Time to learn how to "Google" and manage your VMware and clouds in a fast and secure HTML5 App.

Management APIs reflect product features. If you check the latest API reference, you will find out that quite a few properties and methods of the LicenseManager managed object are deprecated and added (If you use managed object browser to view the deprecated properties, they may be null or literally “unset”). A new managed object LicenseAssignmentManager is added for assigning licenses to entities like vCenter or ESX/ESXi.

Although I covered the changes of vSphere 4 in appendix of my book published by Prentice Hall, they are pretty high level. In this post, I will give a detailed introduction on the changes related to licensing APIs, and how you should use the new licensing APIs effectively.


The change in LicenseManager is dramatic in that whatever there before are deprecated and all the current ones are newly added. You can think of the LicenseManager as a brand new managed object except that it inherits the old name. I will not include the deprecated in the following discussion. If you are interested in them, please check them out in either API ref or my book.

The new responsibilities include managing new licensing keys which are 25 character strings that encapsulate information on the entitlement. Remember, it does not actually assign licenses, which is left to the new LicenseAssignmentManager (will be discussed soon.)

The 3 new properties are as follows:

Property Name Type
evaluation LicenseManagerEvaluationInfo
licenseAssignmentManager ManagedObjectReference to a LicenseAssignmentManager
licenses LicenseManagerLicenseInfo[]

The 6 new methods are shown in the following code snippet from VI Java API:

public class LicenseManager extends ManagedObject
  public LicenseManagerLicenseInfo addLicense(String licenseKey, KeyValue[] labels) throws RuntimeFault, RemoteException;
  public LicenseManagerLicenseInfo decodeLicense(String licenseKey) throws RuntimeFault, RemoteException;
  public void removeLicense(String licenseKey) throws RuntimeFault, RemoteException;
  public void removeLicenseLabel(String licenseKey, String labelKey) throws RuntimeFault, RemoteException;
  public void updateLicense(String licenseKey, KeyValue[] labels) throws RuntimeFault, RemoteException;
  public void updateLicenseLabel( String licenseKey, String labelKey, String labelValue) throws RuntimeFault, RemoteException;

Most of the methods are self explaining. The key to understand the new LicenseManager is the LicenseManagerLicenseInfo, which includes the following properties:

Name Type Description
costUnit xsd:string The cost unit for this license, i.e. “server”,” “cpuPackage:12core”
editionKey xsd:string Edition key, i.e. “vc”, “esxEnterprisePlus”
labels* KeyValue[] Key-value lables for this license
licenseKey xsd:string Key for the license. 25 character serial number.
name xsd:string Display name for the license, “vSphere 4 Enterprise Plus”, “vCenter Server 4 Standard”.
properties* KeyAnyValue[] Additional properties associated with this license
total xsd:int Total number of units contain in the license
used* xsd:int Number of units used from this license

Seemingly easy and simple, the properties represent a learning curve here. As you can guess from its type, any item in the array can be any value (any type), meaning you put any data there. In practice, you can find string, KeyValue, long, date, and even LicenseManagerLicenseInfo (I don’t have explanation why another copy of LicenseManagerLicenseInfo is embedded in itself) as values.

In the “properties”, you can find feature definitions, as shown in the following MOB screenshot:


This newly added managed object is responsible to assign/remove/query licenses to particular entities like vCenter or ESX/ESXi. The following code snippet shows what it does exactly.

public class LicenseAssignmentManager extends ManagedObject
 public LicenseAssignmentManagerLicenseAssignment[] queryAssignedLicenses(String entityId) throws RuntimeFault, RemoteException;
 public void removeAssignedLicense(String entityId) throws RuntimeFault, RemoteException;
 public LicenseManagerLicenseInfo updateAssignedLicense( String entity, String licenseKey, String entityDisplayName) throws RuntimeFault, RemoteException;

One important thing here is to understand the value/format for the entityId. For ESX/ESXi server, it is the value of its MOR, for example, “host-21”; for vCenter server, it’s the value of the instanceUuid added into AboutInfo data object since 4.0, for example, “BA9CE658-75F7-4A99-ACE6-99EB1376B94A”.

You may be wondering how you can get all the assignments, meaning which license keys assigned to which entities. If it’s just a VC, it’s easy because you just get its instanceID and call the queryAssignedLicenses() method. For ESX/ESXi servers, they could be hundreds. Do you have to first grab all of their MOR values and call one by one for hundreds of times?

Luckily, you don’t have to. The parameter to the queryAssignedLicenses() is optional, and you can bypass that (In VI Java API, you use null in place of entityId; in MOB, you leave it as empty string). As a result, you will get all the mappings in the returned LicenseAssignmentManagerLicenseAssignment[] array. The following table summarizes the properties in the data object.

Name Type Description
assignedLicense LicenseManagerLicenseInfo License assigned to the entity
entityDisplayName* xsd:string Display name of the entity
entityId xsd:string Id for the entity
properties* KeyAnyValue[] Additional properties associated with this assignment, i.e. “inUseFeatures” — Features in the license key that are being used by the entity;  “ProductName” – Name of the entity. Should match the product name of the assigned license; “ProductVersion” – Version of the entity. Should match the product version of the assigned license; “Evaluation” – EvaluationInfo object representing the evaluation left for the entity; “entityCost” – number of units taken ; “CostUnit” – the unit like “cpuPackage”
scope* xsd:string Scope of the entityId. If ESX/ESXi, it’s the instanceId of the vCenter that manages it; if vCenter, it’s null or unset.

Again, you see properties defined as KeyAnyValue[], which can hold any types of values. The most important thing is the “inUseFeatures” key/value pairs.

With the queryAssignedLicenses(), you can retrieve all the assignments in a single call. In a fairly big environment where a license key is assigned to many ESXi servers, you have a big array returned, most of which are duplicated (see the assignedLicense property). This is of course not an ideal case but a compromise given that the method is intended for single entity at a time.

What’s Next?

You’ve learned the new license model and related APIs since vSphere 4. Just like learning any APIs, it’s always good to show some samples. That is what I will do. Please stay tuned for next post with samples based on VI Java API. If you haven’t tried VI Java API yet, it’s time to do so. Be ready for licensing samples in a future post.

This entry was posted in vSphere API and tagged , , , . Bookmark the permalink. Post a comment or leave a trackback: Trackback URL.


  1. Posted August 10, 2012 at 8:55 am | Permalink

    Hi there,
    do you know maybe why in powercli
    Is not returning anything. I agree with you that it works via mob, when not giving any value for entityID it prints out everything. In powercli it just does not returning anything.


  2. Posted November 7, 2012 at 5:41 pm | Permalink

    Enjoyed, belatedly, this post. I was the part of the team that redesigned and implemented VIM Licensing in VI4. Just one point to add which is vCenter is the authoritative truth for a given ESX systems license and not the ESX host (ssh to esx, vim-cmd vimsvc/license –show or from mob or vim api LicenseManager object). Any attempt to change a license on an ESX Host will be overridden by VC once it discovers any direct change.

  3. Posted July 21, 2014 at 4:21 pm | Permalink

    I was predicting that VMware would sell some of their new ftaeures separately. I heard rumors they would charge $250 per VM for FT and sell host profiles as a separate configuration management product. That’s what MSFT would have done if they had the first-mover advantage on new ftaeures like that. So I don’t think it’s unreasonable what VMware has done with their new licensing. Plus I’m expecting to get a lot more VMs per server with the new version 4, so net-net it’ll be less expensive than 3.5.

One Trackback

Post a Comment

Your email is never published nor shared. Required fields are marked *


You may use these HTML tags and attributes <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>


    My company has created products like vSearch ("Super vCenter"), vijavaNG APIs, EAM APIs, ICE tool. We also help clients with virtualization and cloud computing on customized development, training. Should you, or someone you know, need these products and services, please feel free to contact me: steve __AT__

    Me: Steve Jin, VMware vExpert who authored the VMware VI and vSphere SDK by Prentice Hall, and created the de factor open source vSphere Java API while working at VMware engineering. Companies like Cisco, EMC, NetApp, HP, Dell, VMware, are among the users of the API and other tools I developed for their products, internal IT orchestration, and test automation.