6.2.2.5 LICENSE Line

Fixed (positional) parameters

The first 6 parameters are required on every license and are present in the order shown above.

isv

The name of the ISV granting the rights.

product

The name of the product for which license rights are being granted.

version

The highest-numbered product version supported by this license, in the form “N.M”. For example, 1.0, 2.37, or 2006.12. Each RLM license has a version number, of the form “major.minor.” The version in the rlm_checkout() call must be less than or equal to the version in the license for the checkout to succeed. (Note: This comparison is done in the “normal” way, ie, 1.2 is greater than 1.10).

The version can be used in a number of ways:

• You could make all your software ask for version 1.0 with all your licenses issued for version 1.0, and the version would never be an issue, unless and until you wanted to obsolete all the old licenses on a new release.
• You could put your product’s version number in the rlm_checkout() call, then licenses for an older version of your product will not work with a newer version of the product.
• You can use a date-based version. To do this, you might put the year and month of release into the rlm_checkout() call in your application, then when you issue licenses, issue them either for this year and month when your customer’s maintenance period ends. This allows your customer to use products released on or before the date in the license. Bear in mind that you would need to use the leading 0 in the month, since 2006.2 is greater than 2006.11, which might not be what you intend.

exp-date

The date the license expires, in the form dd-mmm-yyyy, for example, 1-jul-2007. All licenses have an expiration date. If you prefer for your licenses to not expire, you can use the special expiration date of permanent, which never expires (any date with a year of 0 is also non-expiring, e.g. 1-jan-0). The license expires at midnight on the date specified, in other words, it is valid for the entire day of the expiration date.

You can also specify an expiration time, using the Expiration time keyword.

The license expiration date can be either dd-mmm-yyyy (e.g., 01-jan-2023), or it can be formatted entirely numerically as yyyy-mm-dd (e.g., 2023-01-01).

RLM uses a proprietary algorithm to check for clock windback. This algorithm does not access any other computers and has been used in RLM since version 1.0. It is fast but sometimes returns false positives.

count

The number of licenses granted. The count field defines the license type. See the license-models for a discussion of license types and modifiers. The license type is one of:

• A positive integer indicates a counted license.
• 0 or “uncounted” indicates an uncounted license.
• “single” means a node-locked, single-use license. single is a special case of a counted license, but it is different from “1.” A license with a count of 1 is a regular counted license and requires a license server. A license with the keyword “single” is a single-use, nodelocked license. This license does not require a license server, and in fact license servers will not process this license. single licenses are a convenient way to issue single-use licenses without the license administrator having to configure a license server.
• token, token_bound, and token_unlocked are used to specify a Token-Based License; this license must also have the token=… optional parameter (see License Admin Manual, Release 16.1.0, Section 2.1). The only optional parameter on a token-based license which is used by RLM is the start date. All other optional parameters are ignored.
• Meter indicates a metered license. See metered-licenses for a complete description of metered licenses.

license-key

This is a digital signature of all the license data, along with the hostid on the HOST line, if present. If a license has a non-zero count, it always requires a HOST line. An uncounted license does not require a HOST line, and even if there is a HOST line, the hostid of the license server is not used in computation of its license-key. The license-key will have “sig=” prepended after the license has been signed by the rlmsign utility.

Licenses can also have the following optional license modifier attributes:

Locking: Node-locked, Username-locked, or Floating licenses.

RLM can lock a license in a variety of ways:

node-locked (counted or uncounted)

A node-locked license can only be used on a single node, as specified by the hostid of the license. For a description of the available hostids in RLM, see rlm-host-ids.

The hostid in a license can be a hostid list, which means that the license is usable on any of the specified hostids.

A node-locked license can be either counted, uncounted, or “single.” If it is uncounted or single, then the software need only verify that it is executing on the correct computer, and no license server is required. If it is counted, however, a license server is required to maintain a count of licenses currently in use.

To create a node-locked license, add the keyword hostid=.. at the end of the license line.

username-locked (counted or uncounted)

A license can be locked to a user. This is a special case of a node-locked license, and is accomplished using the hostid user=….

floating

A license can be floating. This license will work anywhere on the network that can communicate with the license server. To specify a floating license, do not put a hostid= keyword on the license.

hostid=hostid-string (used for license locking)

The optional hostid at the end of the line specifies that the licenses can only be used on the specified host. Uncounted licenses always require a hostid. Counted licenses generally do not have a hostid, but it could be present, in which case we would call this license a “node-locked, counted” license. (For a description of the various hostids that RLM supports, see rlm-host-ids.

The hostid on a LICENSE line can be a hostid list. The hostid list is a space-separated list of valid hostids, enclosed in double-quotes. The license can be used on any of the hostids in the list.

The list can contain at most 25 hostids, and can be no longer than 200 characters.

For example, this hostid list would allow the license to be used in any of the 4 specified environments:

hostid="ip=172.16.7.200 12345678 rlmid1=83561095 user=joe"

Other optional license parameters

Activation Key used to create this license

akey=activation-key

When requested in RLM Activation Pro, the license generator will include the akey= keyword with the activation key used to fulfill the license. The maximum length of the activation key is 40 characters, including the “akey=” part.

Caching Licenses on the Client Node

client_cache=seconds

When specified, the license will be held by the license server for “seconds” seconds, in exactly the same way as a “minimum_checkout” attribute would. However, on the client side, license data will be cached which can be used by subsequent checkout requests. The maximum cache time is one hour (3600 seconds). Note that the client-side caching will be ineffective if not enabled with rlm_isv_cfg_enable_client_cache() in rlm_isv_config.c, however the server will still hold the license checked-out in this case.

You can think of this as a very short-term, automatic, roam.

You should note that only licenses which have a sharing attribute will be usable as cached licenses. In other words, if the license has a “share=u” attribute, and the same user attempts a checkout, the cached license can be used. If the “share=” attribute is missing, no checkouts of the cached license will be possible. Also note that the host attribute is matched automatically, by definition, since the license is being used on the same computer.

Your customer can modify the value of client_cache between 0 and 2x the value you specify with the license administration CLIENT_CACHE option. See License Admin Manual, Release 16.1.0, Section 1.9.3, for more details.

Disable Computing Environments

disable=”computing-environment-list”

disable= specifies that clients running in the appropriate computing environment cannot use this license.

computing-environment-list is a list of different computing environment descriptions; if the application is running in any of these environments, the license will not be usable.

computing-environment-list is a space-separated list of the following environments. Put the list in quotes if more than one item is specified.

Disabling TerminalServer is most useful for node-locked, uncounted licenses, if you do not want to allow multiple network users running remote sessions to make use of a single license.

Note that you can’t disable both TerminalServer and TerminalServerAllowRD – they are mutually exclusive.

Disabling Virtual Machines is useful for node-locked, uncounted licenses in order to prevent these licenses from being used on multiple virtual machines with the same hostid.

Example:

disable=TerminalServer

Expiration time

exptime=hh:mm

Beginning in RLM v14.1, a license can be set to expire at a particular time on the expiration day. If the license includes an “exptime” keyword, the license will expire at this time on the expiration date rather than at midnight. If the exptime keyword isn’t present, the license expires at midnight, as it has always done in previous versions of RLM. The expiration time, like the expiration date, is in local time either for the client (for nodelocked licenses) or on the server (for floating licenses).

Hold time and Minimum Checkout

hold=N and min_checkout=n

By specifying hold=N in the license, the license will be held for N seconds after the application exits or checks the license back in via rlm_checkin(). hold is typically used in the case of licenses that have a very short duty-cycle, in order to provide a “fairer” measure of concurrent usage.

min_checkout specifies that a license is to be “held” checked-out by the license server after the application performs a check-in call or exits, only if the license did not remain checked out for the minimum interval specified by n. n must be a positive integer, greater than 0. The license will remain checked-out such that the total checkout time is n seconds. min_checkout is typically used in the case of licenses that have a very short duty-cycle, in order to provide a “fairer” measure of concurrent usage.

hold and min_checkout both perform this function in slightly different ways. hold always keeps the license checked out for the specified amount of time, whereas min_checkout keeps the license checked out for an additional time only if the license was checked back in by the application before the specified minimum time.

License ID

_id=nnn

Any License Administrator can add _id=nnn to a license. “nnn” is a positive integer, less than 231, which is used to identify the license. If no _id= keyword is present, the id of the license is 0. The id of a license can affect license pooling as follows: A license that doesn’t specify an id (or specifies 0), will pool with any other license that it would normally pool with. However, a non-zero id will only pool with the same ID# (assuming all the other attributes make it eligible to pool).

In addition, beginning in RLM v12.0 licenses are sorted (within a license file) in the order of the _id keyword. Licenses without _id keywords will remain unsorted (in their original order) at the end of all the licenses with _id keywords, which are sorted in increasing numerical order. This sort is done prior to REPLACE processing.

Other than license pooling and sorting, the id can be used to select which licenses to apply an option (such as RESERVE). The id is not used in the computation of the license signature, and as such can be added or changed by the License Administrator.

License Issue Date

issued=dd-mmm-yyyy

If issued=dd-mmm-yyyy is specified in the license, this license issue date will be used in the computation of license replacement. If no issue date is present, the license start date is used. If neither is present, then this license will be replaced by any license specifying a replace= keyword with this license’s product name.

Maximum Roam Count

max_roam_count=num

A Roaming license is a license that is checked out from the license server and used on a disconnected system. During this time, the license server holds the license checked-out just as if the system were still connected to the license server. Roaming licenses are only allowed if you issue your customer an rlm_roam license that is valid on the disconnected system.

If you do not specify max_roam_count in an individual license, RLM allows the total number of licenses to be roamed. Setting max_roam_count to a number less than the total number of licenses will cause the server to only allow that number of licenses to roam. To disable roaming on a particular license, set max_roam_count=0 for that license.

Maximum Roam Days

max_roam=days

If you do not specify max_roam in an individual license, RLM limits the maximum number of days that a license can roam to 30 days. To disable roaming on a particular license, set max_roam=-1 for that license.

Specifying max_roam on the rlm_roam license itself will potentially lower the max_roam of all products. The effective max_roam is the minimum of the value specified in the license itself (or the default value) and the value in the rlm_roam license. So, for example, if you set max_roam=20 on the rlm_roam license, then all licenses without a max_roam will be limited to 20 days. If you set max_roam=40 on the rlm_roam license, then only individual licenses with max_roam set to greater than 40 days will be affected.

Metered licenses

Metered licenses are described in detail in metered-licenses. Metered licenses use the following 4 keywords:

• meter_counter=counter#
• meter_dec=decrement_amount
• meter_period=period_in_minutes
• meter_period_dec=periodic_decrement_amount

Named User licenses

named_user[=num] or named_user=”num min_hours”

Named User Licenses allow the ISV to require that a list of users be created who can use the license(s). The number of users in the list can be less than, equal to, or greater than the number of licenses available. Once a user is added to the list, they can be deleted, but once deleted, they must remain off the list for a minimum number of hours (24 hours by default).

To create a named user license, add the named_user keyword to the LICENSE:

With a named_user license, the license server can construct the list of users automatically as license checkouts occur, or the list can be entered via the RLM web interface by the license administrator. If entered manually, either individual users or GROUP names (as defined in the ISV server options file) can be used.

named_user licenses utilize the INCLUDE functionality of the license server, and do not need the entire list of num users specified before the licenses can be used. In fact, no users need to be specified since the license server will add users who do not appear on the list if the current list size is less than the number of allowed named users.

Once a user is added to the list, they can be removed at any time. However, once removed, a user cannot be placed back on the list until they have been off the list for min_hours hours (default: 24 hours).

License Options

options = options_list

The options specification is used to encode options for the product license. The options field is a string (up to 64 characters in length) which is completely defined by the ISV. The options are used to calculate the license signature, but otherwise are unused by RLM. You can retrieve the options from a license with either the rlm_product_options() or the rlm_license_options() call.

You can specify a required substring in the options field with the rlm_set_attr_req_opt() call. See rlm-set-attr-req-opt for more information.

License Password

_password = password-string

A license password restricts access to this license to requests which have specified the same password-string. The password-string is specified either with the rlm_set_attr_password() call, or (for the command-line utilities) with the RLM_LICENSE_PASSWORD environment variable, or in the RLM web interface. The password string must be <= 32 characters.

If a request (checkout or status) is made for a license which contains a password, and the request does not specify a matching password, the license server will return RLM_EL_NO_SERV_SUPP (for a checkout request) or no data (for a status request). This prevents a user from knowing that a license exists and attempting to guess the password.

The license password can be specified on the ISV line with the password=password-text optional field. If specified on the ISV line, the password applies to all LICENSE or FEATURE lines which follow the ISV line in the license file. If any individual LICENSE/FEATURE line specifies a password, the password from the LICENSE/FEATURE line is used.

Platform Restrictions

platforms=platform_list

RLM allows you to specify one or more platforms on which the application must be running. If a platforms=platform-list specification is contained in the license, the computer on which the application is running must be one of the specified platforms.

To specify one or more platforms, create a list of platform names. The platform-list consists of a list of RLM-defined platform names, which consist of a machine architecture and an operating system version/revision. Specify platforms= as a space-separated list of platform names with the trailing OS revision removed, as shown in the following table.

Replacement Licenses

replace[=product_list]

In order to render ineffective one or more licenses which you have already issued, use the replace[=product-list] option in the new license. replace= causes RLM to ignore the “replaced” license(s). If product_list is the single character ‘*’, all licenses will be replaced.

replace operates as follows:

• Licenses from the product_list will be replaced (all licenses if product_list is ‘*’). If product-list is not specified, then the product name of the license containing the replace keyword will be the only product to be replaced.
• If the license with the replace keyword specifies an issued=date, then this is the “replacement date.”
• If the license with the replace keyword does not have an issued date, then the “replacement date” is the start date of the license.
• If the license contains neither an issued date nor a start date,no licenses will be replaced.
• Any license in the list of products with an issued date prior to the replacement date will be replaced.
• Any license in the list of products which does not have an issued date, but which has a start date prior to the replacement date will be replaced.
• Finally,any license in the list of products with neither an issued nor a start date will be replaced.
• EXAMPLE:To replace products “a” and “b”, use: replace=”ab” in the license.

Effective Start Date

start=dd-mmm-yyyy

If start=dd-mmm-yyyy is specified in the license, the license cannot be used before the specified date.

License Soft Limits

soft_limit=n

A license can have a soft_limit that is lower than its count of available licenses. Once usage exceeds the soft_limit, checkout requests will return the RLM_EL_OVERSOFT status instead of a 0 status

Soft limits are processed by the license server, so they have no effect on unserved nodelocked licenses.

Sharing of licenses between different processes

share=UHI[:nnn]

Licenses can be shared between separate running processes by using a share= specification in the license. A license can be shared between processes with the same username, hostname, or ISV-defined data; or any combination of these. Specify share as share=UHI where the keywords ‘U’, ‘H’, and ‘I’ indicate that the Username, the Hostname, or the ISV-defined fields must match.

If more than one is specified, all specified must match in order to share the license.

The share= keyword accepts an optional maximum process count which can share the license. To specify a maximum process count for a license that is shared by user, use share=U:nnn, where nnn is the number of processes which can share this license. The nnn+1st request will consume an additional license.

If the :nnn specification is omitted, any number of processes can share the license.

User, Host-based or Personal licenses.

user_based[=n] host_based[=n] personal (RLM Cloud only)

User-based licenses allow the ISV to require that the specified number of licenses (or all licenses) must be reserved to users (with RESERVE lines) in the options file. Note that the special user ‘*’ does not count as being reserved. If fewer than the required number of licenses are reserved, the license server will log an error and discard the license. Also note that licenses reserved to a GROUP are not counted, otherwise the license administrator could simply bypass the intent of this license by creating a GROUP consisting of all their users. Thus, all reservations must be to individual users.

Similarly, host-based licenses allow the ISV to require that the specified number of licenses (or all licenses) must be reserved to hosts (with RESERVE lines) in the options file. Note that the special host ‘*’ does not count as being reserved. If fewer than the required number of licenses are reserved, the license server will log an error and discard the license. Also note that licenses reserved to a HOST_GROUP are not counted, otherwise the license administrator could simply bypass the intent of this license by creating a HOST_GROUP consisting of all their hosts. Thus, all reservations must be to individual hosts.

Personal licenses (which are only available on RLM Cloud servers) allow the ISV to require that the authorized users be preassigned with the RLM Cloud portal GUI.

To create either user-based, host-based, or personal licenses, add the appropriate keyword to the LICENSE:

If the optional “=nnn” is specified, only “nnn” of the total number of licenses need to be reserved, otherwise all licenses must be reserved.

For personal licenses, no count is specified, the personal user count is the license count.

Timezone Restrictions

timezone=timezone-spec

RLM allows you to specify one or more timezones in which the applications must be running. If a timezones=timezone-spec specification is contained in the license, the computer on which the application is running must be set to one of the specified timezones.

To specify one or more timezones, create a bitmask of the desired timezones, expressed as hours west of GMT:

Bit 0 - GMT Bit 1 - 1 hour west of GMT Bit 2 - 2 hours west of GMT … Bit 23 - 23 hours west of GMT (or 1 hour east of GMT).

This bitmask should be represented as a hex number. So, for example, to allow your application to run in the GMT timezone only:

timezone=1

To allow your application to run in timezone 8 (PST):

timezone=100

To allow your application to run in timezones 5-8 (continental USA):

timezone=1E0

Minimum rlmremove interval

min_remove=n

min_remove specifies the lowest value, in seconds, a License Administrator can set the MINREMOVE value for a license.

If not specified in the license, the RLM default of 120 seconds (2 minutes) is used.

If min_remove is set to -1, then rlmremove (and the Remove button in the RLM web interface) is disabled on this license.

Minimum Timeout specification

min_timeout=n

A license administrator can specify a TIMEOUT value for any idle license. If the license remains idle (i.e.. does not communicate with the license server) for this amount of time, the license server performs an automatic check-in of the license and informs the application (if it is still running).

min_timeout=n specifies the lowest value a license administrator can set for the timeout value for a license. If not specified in the license, the RLM default minimum of 3600 seconds (1 hour) is used.

Additional Fields

The following fields are not used by RLM, but are present to identify licenses, or can be used in your application to present to the user:

contract=contract-info

contract= is meant to hold the customer’s purchase order or software agreement number. This can be used to display to the user to validate a support contract, etc. It is not used by RLM. Maximum of 64 characters.

customer=who

customer is to identify the customer of the software. This can be an added incentive to keep honest users honest, as it is unlikely that Mega South-East Airlines would want to use a license that was issued to Main St. Bank., for example. customer is not used by RLM. Maximum of 64 characters.

issuer=who

issuer= is used to identify the organization which issued the license. It is not used by RLM.

Maximum of 64 characters.

_line_item=”descriptive_text”

The _line_item field is used to map a particular product to the item purchased. This field will be logged into the report log at the start when all products supported are logged, so that a report writer can generate reports based on purchased products, as opposed to product names used for licensing purposes. If the descriptive text contains spaces, it should be enclosed in double-quote (”) characters. The contents of the _line_item field can be modified (or the field can be added) without invalidating the license signature. Maximum of 64 characters.

type=type-spec

type= is used to identify the type of license. type-spec is a string containing one or more of the values:

• “beta”
• “demo”
• “eval”
• “subscription”

For example, type=”beta eval” or type=”eval.” The contents of the license type field are retrieved by the rlm_license_type() call (see rlm-license-xxxx). type is not used by RLM.