Token-Based Licenses

Token-Based licenses are licenses that are defined in terms of another license. For example, an application could request a license for product write. If this were a normal license, the product write would appear in the license file (if the request succeeds) with a license count (or uncounted). On the other hand, if this were a token-based license, the product write would appear in the license file without a count, but with a specification of one or more other products which are used to satisfy the request. When the license server encounters a request for a token-based license, it uses the other products specified in the license to satisfy the request, rather than the originally requested product. These other licenses are called the primary licenses.

There are two main uses for token-based licenses. The first use of token-based licenses allows a license administrator to mix-and-match different products as their needs change. If several products are all defined in terms of a single pool of primary licenses, the license administrator can control license usage as needs demand. This can be a benefit to both ISVs and their customers, since as new products are introduced, if they are licensed based on the same primary license, all customers instantly have access to the new products without having to go through a purchase-order cycle.

Another use of token-based licenses is to allow alternate licenses to satisfy a request for a product. To use the familiar example, if product write checks out a write license, the addition of a token-based license for write mapping it to office would allow an office license to be used in the case where no write licenses are available. Even though the office license is a more expensive license, the customer is allowed to continue working by consuming the more expensive office license. Several token-based licenses can be used in this way, and the order of the licenses in the license file will determine the order that alternate checkouts are attempted.

A token-based license differs from a normal license in a few significant ways:

  • The count field contains one of the 3 token keywords (token, token_bound, or token_unlocked) rather than an integer, uncounted, or single.

  • The license has a token spec: token=”<prod ver count> … <prodN verN countN>”

  • The only optional parameter on a token-based license which is used by RLM is the start date. All other optional parameters are ignored.

  • License Administration option processing is different for token-based licenses. See below.

  • There are a few restrictions on token-based licenses, especially for queuing. See below.

Warning

The keyword token_locked was deprecated in v12.4 and replaced with token_bound. Licenses with token_locked keywords will continue to operate, but they will not be locked to the server’s hostid).

Types of token-based Licenses

When a product is specified as a token-based license, requests for that product are turned into requests for the primary license(s) specified in the token= part of the license. For example, consider this license for product test (primary license dollars):

LICENSE reprise test 1.0 permanent token token="<dollars 2.0 5>" sig=xxxx

LICENSE reprise dollars 2.0 permanent 10 sig=xxxx

This license is called a simple token-based license. Any token-based license that maps a checkout of one product into a (single) primary license is a simple token-based license.

A token-based license can map one request into multiple checkouts, however. In this case, it is called a compound token-based license. Using our product test as an example again:

LICENSE reprise test 1.0 permanent token token="<dollars 2.0 5> <cents 3.4 53>" sig=xxxx
LICENSE reprise dollars 2.0 permanent 100 sig=xxxx
LICENSE reprise cents 3.4 permanent 1000 sig=xxxx

Now, a request for 1 license of test v1.0 would result in the license server checking out 5 v2.0 licenses of the product dollars, and 53 v3.4 licenses of the product cents. If both of these primary licenses are available, the checkout request for test succeeds, otherwise it fails. Note that when a compound tokenbased license is checked out, the rlm_license_xxx functions return information about the first license in the list only. In this example, rlm_license_xxx functions would return information about the dollars license.

Issues with roaming

When a license is roamed, only the name of the license that was requested in the checkout can be used on the roamed system. What this means, in practice, is that as long as you use the same name to attempt the checkout, the checkout will succeed. However, sometimes token-based licenses are used to migrate a product license name.

For example, if v2.0 of your product checks out an “old_name” license, and v3.0 checks out a “new_name” license, and you have a token license definition to map the “new_name” checkout to “old_name”, then a roamed license created by checking out “new_name” will not work for the product that checks out “old_name”, even though the “new_name” checkout may have been satisfied by an “old_name” license. In other words, while this mapping works on the server side, it does not work for a roamed license.

The License Count Keywords

In a token-based license, the count keyword is one of:

  • token

  • token_bound

  • token_unlocked

token and token_unlocked imply that the token-based license itself does not include the license server hostid in its license signature. This makes the license usable in any license file.

Note

token and token_unlocked are 100% equivalent.

token_bound means that the token-based license includes the license server hostid in its signature, and is valid only in this license file.

The token= keyword

In a token-based license, the token= keyword specifies the primary licenses which are checked out in response to a request for the token-based license itself. Specify one or more licenses to be checked out. These licenses can also be token-based licenses themselves (in which case the primary license(s) will be the ultimate expansion of all token-based licenses). The format is:

token="<product1 ver1 count1>[ <product2 ver2 count2> .... <productN verN countN>]"

The request for the one of the original licenses turns into checkouts of:

  • count1 of product1, ver1

  • count2 of product2, ver2

  • …

  • countN or productN, verN

Nesting token-based licenses

The definition of a token-based license can include other licenses which are token-based licenses themselves. For example:

LICENSE reprise test 1.0 permanent token sig=xxxx token="<t2 2.0 5>"
LICENSE reprise t2 2.0 permanent token sig=xxxx token="<dollars 2.0 5>"

In this example, a request for one test v1.0 license results in 25 dollar v2.0 licenses checked out.

Note

The license server uses nesting of greater than 20 levels to detect token “loops”, so any licenses nested this deeply will be rejected. Also note that nesting has no effect on whether a token-based license is simple or compound - this is determined solely by whether a single request maps into a single checkout or not.

Restrictions on token-based licenses

There are a few restrictions on token-based licenses:

  • All token-based licenses are processed by the license server, so there can be no uncounted, node-locked token-based or primary licenses that operate without a license server. (However, a license server can serve a node-locked, uncounted primary license.)

  • All individual checkouts for a compound token-based license are satisfied by a single license server. This means that if a license turns into checkouts of primary licenses a, b, and c, where only a and b are available on one server and only c is available on a second server, the request will fail.

  • The mapping from a token-based license to its primary license(s) maps to a single primary license. This means that a single token-based license generates requests of a single primary license pool (for each of it’s primary licenses). So, for example, if your token-based license turned into a request for primary license prim, the first pool of prim licenses would be used, and other pools of prim licenses could not be used to satisfy this token request.

  • Queuing is not allowed for compound token-based licenses. This would lead to license server insanity.

Note

Token licenses, once fully resolved, should NOT contain multiple instances of the same primary license name. If this is the case, the server can inadvertently overdraft that license while processing the token-based checkout.

The following licenses are examples of licenses which contain multiple instances of the same primary license:

LICENSE reprise t1 1.0 permanent token token="<x 1.0 1><x 2.0 1>" sig=...

or:

LICENSE reprise t1 1.0 permanent token token="<t2 1.0 1><x 2.0 1>" sig=...
LICENSE reprise t2 1.0 permanent token token="<x 2.0 1>" sig=...

The server will generate a warning about this condition similar to the following:

01/01 10:09 (reprise) *WARNING: token definition for t1 has multiple
01/01 10:09 (reprise) instances of primary license x

For the 2 examples above, if there is only a single license for “x”, a checkout of “t1” will cause the server to checkout 2 copies of “x” and return an RLM_EL_OVERSOFT error to the application.

rlmremove and token-based licenses

The token-based license itself cannot be removed. If any of the primary licenses are removed, the server will remove all primary licenses, and the application will notice a loss of license on the next check with the server resulting from an rlm_get_attr_health() call or from the heartbeats generated by rlm_auto_hb(). In this sense, the token-based license works just like a regular, non token-based license.

Report Log

When a token-based license is checked out, the name of the license requested (and its version) is logged in the checkout record for each resulting primary license checkout. If the check-out results from the dequeuing of a previously queued request, the requested product name/version will not appear (they appear in the queue record, but not the checkout record).

License Administration Options

The only options that apply to the token-based license itself are the include and exclude keywords:

  • INCLUDE

  • INCLUDEALL

  • INCLUDEALL_ROAM

  • EXCLUDE

  • EXCLUDEALL

  • EXCLUDEALL_ROAM

All other license administration options have no effect on the token-based license.

All options affect the primary licenses, however.