Managed Object - LicenseManager

Property of: HostConfigManager, ServiceContent
See also: HostSystem, KeyValue, LicenseAssignmentManager, LicenseAvailabilityInfo, LicenseDiagnostics, LicenseFeatureInfo, LicenseManagerEvaluationInfo, LicenseManagerLicenseInfo, LicenseSource, LicenseUsageInfo

Managed Object Description

This managed object type controls entitlements for a given VMware platform. VMware platforms include VirtualCenter, ESX Server, VMware Server, Workstation and Player. Entitlements define what software capabilities this host may use.

Entitlements are identified by a short string 'key'. Keys can represent either a particular edition (Full, Starter) or a particular feature/function (featureKey) (backup, nas). An edition implies zero one or more functions which are express, denied or optional. For example a 'Full' edition includes 'iscsi' function but a Starter edition might disallow it.

Which edition a given VMware platform uses can be defined at any time. Generally this is done right after first install and boot as installation software may not set it. For editions that are similar in nature, any future changes to edition type will only impact future requests for functionality. Current functionality is left unaffected. The same is true for optional functions enabled/disabled after some period of time. For dissimilar editions, such transitions may require entering maintenance mode first else an exception of InvalidState will be thrown.

To specify the edition type and any optional functions, use updateLicense for ESX Server and addLicense follow by LicenseAssingmentManager.updateAssignedLicense for VirtualCenter.

When an edition is specified for a given host, the cost of that edition (how many licenses are needed) is determined. The cost is computed using the license's CostUnit value multiplied by the number of units activated. For example, when a VMware platform is set to an edition which uses a 'cpuPackage' on a two socket server, two licenses would be needed to successfully install that edition.

Here is a diagram of the unit costs supported by this API and their relationships.

             
   +------------------------------+   +--------+      +-------+
   | +-----------+ +-----------+  |   | Server |      |  Host |
   | |           | |           |  |   +--------+      +-------+
   | |  cpuCore  | |   cpuCore |  |                   +-------+
   | +-----------+ +-----------+  |   +--------+      |  Host |
   |                  cpuPackage  |   |  VM    |      +-------+
   +------------------------------+   +--------+

Properties

Name	Type	Description
diagnostics*	LicenseDiagnostics	Deprecated. As of vSphere API 4.0, this property is not used by the system. Return current diagnostic information. *Since* VI API 2.5
evaluation P	LicenseManagerEvaluationInfo	*Since* vSphere API 4.0
featureInfo*	LicenseFeatureInfo[]	Deprecated. As of VI API 2.5, use QuerySupportedFeatures instead. The list of features that can be licensed.
licenseAssignmentManager* P	ManagedObjectReference to a LicenseAssignmentManager	License Assignment Manager *Since* vSphere API 4.0
licensedEdition	xsd:string	Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead. The product's license edition. The edition defines which product license the server requires. This, in turn, determines the core set of functionalities provided by the product and the additional features that can be licensed. If no edition is set the property is set to the empty string (""). To set the edition use SetLicenseEdition. *Since* VI API 2.5
licenses P	LicenseManagerLicenseInfo[]	Get information about all the licenses avaiable. *Since* vSphere API 4.0
source	LicenseSource	Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses to get evaluation information. Set or return a data object type of LocalLicense or LicenseServer.
sourceAvailable	xsd:boolean	Deprecated. As of vSphere API 4.0, this property is not used. Current state of the license source. License sources that are LocalSource are always available.

*May not be presentPRequired privilege - see tooltip for details

Methods

Methods defined in this Managed Object
AddLicense, CheckLicenseFeature, ConfigureLicenseSource, DecodeLicense, DisableFeature, EnableFeature, QueryLicenseSourceAvailability, QueryLicenseUsage, QuerySupportedFeatures, RemoveLicense, RemoveLicenseLabel, SetLicenseEdition, UpdateLicense, UpdateLicenseLabel

AddLicense

Adds a license to the inventory of available licenses.

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A license. E.g. a serial license.
labels*	KeyValue[]	array of key-value labels. Ignored by ESX Server.

*Need not be set

Return Value

Type	Description
LicenseManagerLicenseInfo	Returns information about the license specified in licenseKey.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddLicense" type="vim25:AddLicenseRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="AddLicenseResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseManagerLicenseInfo"/>
               </sequence>
            </complexType>
         </element>

CheckLicenseFeature

Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead.

Returns whether or not a given feature is enabled.

Required Privileges: System.Read

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the LicenseManager used to make the method call.

host*

ManagedObjectReference
to a HostSystem

Host to act on if LicenseManager is not on a host.

featureKey

xsd:string

Name of the feature to enable.

*Need not be set

Return Value

Type	Description
xsd:boolean	Returns true if the feature is enabled and false if it is not.

Faults

Type	Description
InvalidArgument	Thrown if a feature name is not found.
InvalidState	Thrown if the feature cannot be supported on the platform, potentially because the hardware configuration does not support it.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckLicenseFeature" type="vim25:CheckLicenseFeatureRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="CheckLicenseFeatureResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>

ConfigureLicenseSource

Deprecated. As of vSphere API 4.0, use UpdateLicense instead.

Allows for reconfiguration of the License Manager license source.

This changes the licensing source to be either served or local. Before changing the license source location, the API checks the number of licenses available at the new potential source to ensure there are at least as many licenses there as have been issued by the current source. If there are an equal or greater number of licenses at the new source, all licenses on the current source are released and then reacquired from the new source. If there are not enough licenses available on the new source to reissue all licenses, the operation fails.

This is used to configure the license source on an individual host.

PLATFORM Specific Notes: VirtualCenter - only supports a served source. the host parameter is mandatory. ESX Server - the host parameter is optional.

Required Privileges: Global.Licenses

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the LicenseManager used to make the method call.

host*

ManagedObjectReference
to a HostSystem

Host for which the license manager should be reconfigured.

licenseSource

LicenseSource

ServedSource or LocalSource.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
CannotAccessLocalSource	Thrown if the local source cannot be accessed.
InvalidLicense	Thrown if the new license source is LocalLicenseSource and the license file is not valid.
LicenseServerUnavailable	Thrown if the license server is unreachable.
NotEnoughLicenses	Thrown if the new license source does not have enough licenses.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ConfigureLicenseSource" type="vim25:ConfigureLicenseSourceRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="ConfigureLicenseSourceResponse">
            <complexType/>
         </element>

DecodeLicense

Decodes licensing information on the license specified.

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A license. E.g. a serial license.

Return Value

Type	Description
LicenseManagerLicenseInfo	Returns information about the license specified in licenseKey.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DecodeLicense" type="vim25:DecodeLicenseRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DecodeLicenseResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseManagerLicenseInfo"/>
               </sequence>
            </complexType>
         </element>

DisableFeature

Deprecated. As of vSphere API 4.0, use RemoveAssignedLicense instead.

Release licenses for an optional feature.

Required Privileges: Global.Licenses

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the LicenseManager used to make the method call.

host*

ManagedObjectReference
to a HostSystem

Host to act on if LicenseManager is not on a host.

featureKey

xsd:string

key of the feature to disable.

*Need not be set

Return Value

Type	Description
xsd:boolean	Returns true if the feature was disabled and false if not.

Faults

Type	Description
InvalidArgument	Thrown if a feature name is not found or it is not optional.
InvalidState	Thrown if the feature is in use.
LicenseServerUnavailable	Thrown if the license server is unavailable.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DisableFeature" type="vim25:DisableFeatureRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="DisableFeatureResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>

EnableFeature

Deprecated. As of vSphere API 4.0, use UpdateAssignedLicense instead.

Enable a feature that has an optional state.

Required Privileges: Global.Licenses

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the LicenseManager used to make the method call.

host*

ManagedObjectReference
to a HostSystem

Host to act on if LicenseManager is not on a host.

featureKey

xsd:string

Name of the feature to enable.

*Need not be set

Return Value

Type	Description
xsd:boolean	Returns true if enabling the feature was successful, false otherwise.

Faults

Type	Description
InvalidArgument	Thrown if a feature name is not found or it is not optional.
InvalidState	Thrown if the feature cannot be supported on the platform, potentially because the hardware configuration does not support it.
LicenseServerUnavailable	Thrown if the license server is unavailable.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableFeature" type="vim25:EnableFeatureRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="EnableFeatureResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="xsd:boolean"/>
               </sequence>
            </complexType>
         </element>

QueryLicenseSourceAvailability

Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead.

Queries the current license source for total and available licenses available for each feature known to this system.

Required Privileges: Global.Licenses

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
host*	ManagedObjectReference to a HostSystem	Use the license source of the specified host.

*Need not be set

Return Value

Type	Description
LicenseAvailabilityInfo[]

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLicenseSourceAvailability" type="vim25:QueryLicenseSourceAvailabilityRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLicenseSourceAvailabilityResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseAvailabilityInfo" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

QueryLicenseUsage

Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead.

Returns the license usage. The license usage is a list of supported features and the number of licenses that have been reserved.

PLATFORM Specific Notes: VirtualCenter - Empty string returns the usage of non-host specific features. Must specify managed host to query. ESX Server - Host argument ignored.

Required Privileges: System.Read

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
host*	ManagedObjectReference to a HostSystem	Host to query for usage. If missing, query the server the LicenseManager is on.

*Need not be set

Return Value

Type	Description
LicenseUsageInfo

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLicenseUsage" type="vim25:QueryLicenseUsageRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QueryLicenseUsageResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseUsageInfo"/>
               </sequence>
            </complexType>
         </element>

QuerySupportedFeatures

Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead.

Queries the current license source for a list of available licenses that can be licensed from this system.

Required Privileges: Global.Licenses
Since: VI API 2.5

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
host*	ManagedObjectReference to a HostSystem	Use the license source of the specified host.

*Need not be set

Return Value

Type	Description
LicenseFeatureInfo[]

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QuerySupportedFeatures" type="vim25:QuerySupportedFeaturesRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="QuerySupportedFeaturesResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseFeatureInfo" minOccurs="0" maxOccurs="unbounded"/>
               </sequence>
            </complexType>
         </element>

RemoveLicense

Remove license from the available set.

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A licenses. E.g. a serial license.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveLicense" type="vim25:RemoveLicenseRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveLicenseResponse">
            <complexType/>
         </element>

RemoveLicenseLabel

Removed a license's label.

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A license.
labelKey	xsd:string	A label key.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveLicenseLabel" type="vim25:RemoveLicenseLabelRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="RemoveLicenseLabelResponse">
            <complexType/>
         </element>

SetLicenseEdition

Deprecated. As of vSphere API 4.0, use QueryAssignedLicenses instead.

Defines the product's license edition. The edition defines which product license the server requires. This, in turn, determines the core set of functionality provided by the product and the additional features that can be licensed.

To determine what featureKey the current platform will accept, use querySourceAvailablity() at runtime, or consult the documentation for the current platform.

Required Privileges: Global.Licenses

Parameters

Name

Type

Description

_this

ManagedObjectReference

A reference to the LicenseManager used to make the method call.

host*

ManagedObjectReference
to a HostSystem

Host to act on if LicenseManager is not on a host.

featureKey*

xsd:string

Name of edition feature to select. If featureKey is not set or set to empty string, the product becomes unlicensed.

*Need not be set

Return Value

Type	Description
None

Faults

Type	Description
InvalidArgument	Thrown if a feature key is not an edition feature key.
InvalidState	Thrown if the feature cannot be supported on the platform, potentially because the hardware configuration does not support it.
LicenseServerUnavailable	Thrown if the license server is unavailable.
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetLicenseEdition" type="vim25:SetLicenseEditionRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="SetLicenseEditionResponse">
            <complexType/>
         </element>

UpdateLicense

Updates the available licenses to the one provided in licenseKey. This is the same as removing all the licenses using RemoveLicense and adding licenseKey using AddLicense If the optional parameter labels is specify this is the same as calling updateLicense without the optioal parameter and calling updateLabel for each pair in the labels array.

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A license. E.g. a serial license.
labels*	KeyValue[]	array of key-value labels.

*Need not be set

Return Value

Type	Description
LicenseManagerLicenseInfo	Returns information about the license specified in licenseKey.

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLicense" type="vim25:UpdateLicenseRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLicenseResponse">
            <complexType>
               <sequence>
                  <element name="returnval" type="vim25:LicenseManagerLicenseInfo"/>
               </sequence>
            </complexType>
         </element>

UpdateLicenseLabel

Update a license's label. It creates a label entry if the labelKey doesn't already exist

Required Privileges: Global.Licenses
Since: vSphere API 4.0

Parameters

Name	Type	Description
_this	ManagedObjectReference	A reference to the LicenseManager used to make the method call.
licenseKey	xsd:string	A license.
labelKey	xsd:string	A label key.
labelValue	xsd:string	Value for the label.

Return Value

Type	Description
None

Faults

Type	Description
RuntimeFault	Thrown if any type of runtime fault is thrown that is not covered by the other faults; for example, a communication error.

Show WSDL type definition

         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLicenseLabel" type="vim25:UpdateLicenseLabelRequestType"/>
         <element xmlns="http://www.w3.org/2001/XMLSchema" xmlns:vim25="urn:vim25" name="UpdateLicenseLabelResponse">
            <complexType/>
         </element>