.. _token-based-licenses: ##################### 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=" ... "** * 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**): .. code-block:: text LICENSE reprise test 1.0 permanent token token="" 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: .. code-block:: text LICENSE reprise test 1.0 permanent token token=" " 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: .. code-block:: text token="[ .... ]" 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: .. code-block:: text LICENSE reprise test 1.0 permanent token sig=xxxx token="" LICENSE reprise t2 2.0 permanent token sig=xxxx token="" 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. -------- .. _token-based-restrictions: ************************************ 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: .. code-block:: text LICENSE reprise t1 1.0 permanent token token="" sig=... or: .. code-block:: text LICENSE reprise t1 1.0 permanent token token="" sig=... LICENSE reprise t2 1.0 permanent token token="" sig=... The server will generate a warning about this condition similar to the following: .. code-block:: text 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.