The License File

The license file contains information which configures the license servers and describes all the licenses granted from the ISV to your customer. There are 4 basic license types:

  • counted

  • uncounted

  • token

  • metered

Everything else in the license file is a modification of one of these 4 basic license types. For example, if a counted license has a hostid associated with it, it becomes a nodelocked, counted license. If the counted license has no hostid, it is a floating license. The various attributes modify the basic license types. For example, if a counted license has a share= attribute, then multiple application instances can use a single license. If the license file has counted or metered licenses, it requires a license server, so a HOST and ISV line must be present. If the license file has only uncounted licenses, the HOST and ISV lines are not required.

License Files have 6 types of lines:

Line

Description

HOST

Specify the license server host (SERVER is an alias for HOST – see HOST Line)

ISV

Specify the ISV’s license server information (DAEMON is an alias for ISV – see ISV Line)

LICENSE

Describe license grants from the ISV to your customer (FEATURE is an alias for LICENSE – see LICENSE Line)

UPGRADE

Upgrade the version number of some or all LICENSEs, (see UPGRADE Line)

CUSTOMER

RLM Cloud only - See: CUSTOMER line

Comment

(see next section)

Applications, License Servers, and License Administration Tools locate the license file using The License Environment.

Note

RLM does not support byte order markers (BOMs) in license files. If a BOM is present in a license file, RLM will not recognize the content.

Comments in license files

Lines beginning with ‘#’ are treated as comments and not interpreted by RLM. Comments may be added to a license file without invalidating the signatures of licenses, but should not be added between the lines of a multiple-line license. Here is an example:

#
# Licenses served by host gt2
#
HOST gt2 0000a74f88ce 5053
ISV reprise
#
# Original license for v3.0 (10 seats)
#
LICENSE reprise joe 3.0 permanent 10 _ck=f81efcf79a
sig="60PG451KTXVQ0WYBX785XAKTDKUCHB7T683Y2MG22M088S8UAFR0VKPMFGPKH
4XW4H5QQ8JSFFJG"
#
# v4.0 license (5 additional seats)
#
LICENSE reprise joe 4.0 permanent 5 _ck=3b1efcd48c
sig="60P045145JSKEJSR48V3GXCX29S8TM5TKE91TS022HW0XAEEWH82DRTCJB830AW
EV62MUE2N7C"

Note

Prior to RLM v9.3, the comment character was not strictly required on comment lines. With improved error checking in 9.3 however, the comment character is required.

Special License Names

Any product name beginning with “rlm_” is reserved to Reprise Software.

The product name rlm_roam is treated specially by RLM. rlm_roam indicates that roaming has been enabled by an ISV. If an ISV issues an rlm_roam license, then roaming is enabled on any computer which is able to check out the rlm_roam license while in a disconnected state.

Order of lines in the license file

In general, the order of lines in the license file does not matter, with the following exceptions:

  • For an ISV/DAEMON line which specifies a password, all LICENSE/FEATURE lines following the ISV/DAEMON line which do not specify a password will use the password of the ISV/DAEMON line which precedes it. If the ISV/DAEMON line follows the LICENSE/FEATURE line, the password will not apply to that LICENSE/FEATURE.

  • LICENSE/FEATURE lines are processed in the order they appear in the license file. This means that you can bias the selection of licenses by the order they appear in the license file. For example, if you have licenses for product ABC versions 1.0 and 2.0, and your software requests version 1.0, the license you receive will depend on the order: if the 2.0 license appears first in the license file, and it is available, your application will receive a v2.0 license. If the v1.0 license appears first and it is available, you will receive a v1.0 license.

HOST Line

HOST hostname hostid [tcp/ip port #]

The HOST line specifies which computer the license server is to run on. There is only one HOST line per license file. Note that if a license file contains only nodelocked-uncounted licenses, a HOST line is not required.

The hostname is the standard TCP/IP hostname for the system. This name is not an input to the license key signature algorithm, and thus can be changed at any time.

The hostid is RLM’s idea of the computer’s identification. The hostid is an input to the license key signature algorithm, so it cannot be changed. All licenses in the license file have this hostid as input to their license signatures, so it is important to avoid moving LICENSE lines from one license file to another, as this invalidates them.

The tcp/ip port number is the port which RLM attempts to use for communications. This number can be changed to any available port.

For a description of the various hostids that RLM supports, see RLM Host IDs.

Example:

HOST melody 80b918aa 2700

In this example, the license servers run on host “melody” at TCP/IP port # 2700.

Note

The keyword “SERVER” can be used instead of “HOST”.

ISV Line

Format:

ISV isvname [isv-binary-pathname [options-file-filename [port-number]]] [binary=isv-binarypathname]
[options=options-file-filename] [port=port-number] [password=password-text]

The ISV line specifies an ISV’s license server. There is one ISV line in the license file for every isvname which has licenses in that file. Note that if a license file contains only nodelocked-uncounted licenses for a particular ISV, an ISV line is not required for that ISV.

Parameter

Required

Description

isvname

Yes

The name assigned to the ISV - does not change.

isv-binary-pathname

Yes*

Location of the ISVs license server binary. Can be any accessible location. Not an input to license key signature algorithm so can be changed any time. * Can be omitted if ISV server is in same location as the RLM binary.

options=options-file-filename

No

Specifies whether an options file will be used (see: The ISV Options File). Specify options file location here, or name the ISV options file isvname.opt and place in same directory as license file.

port=port-number

No

Specifies port ISV server will use. If omitted, port is allocated dynamically.

password=password-text

No

Specifies license password applied to all LICENSE or FEATURE lines which follow the ISV line in the license file. If individual LICENSE/FEATURE line has a password, password from LICENSE/FEATURE line is used.

Any of the optional parameters can be specified by themselves. Also note that any number of the positional parameters can be specified, and optional parameters can be added after the positional parameters.

Note

If you specify the same parameter both as a positional parameter and as a keyword=value parameter, the value of the keyword=value parameter will be used.

Examples:

License server for ISV reprise is located at /home/reprise/reprise, options file is located at /home/reprise/reprise.opt:

ISV reprise options=/home/reprise/reprise.opt binary=/home/reprise/reprise

License server for ISV reprise located at /home/reprise/reprise and ISV server port # specified:

ISV reprise /home/reprise/reprise port=8765

License server for ISV reprise located at /home/reprise/reprise and ISV server binary name /a/b/reprise used instead of /home/reprise/reprise:

ISV reprise /home/reprise/reprise binary=/a/b/reprise

Note

The keyword “VENDOR” can be used instead of “ISV”.

LICENSE Line

Format:

LICENSE isv product version exp-date count [sig=]license-key [optional parameters]

The LICENSE line defines the usage rights to a product. All fields in the license line are case-insensitive (with the exception of short, i.e., less than 62-character, license keys), and none may be modified by the license administrator, with the exception of the parameters whose names begin with the underscore (“_”) character.

Note

The license file parser will reject unknown keywords.

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 Token-Based Licenses). 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.

Note

If the license-key is preceded by sig=, it can be present after any or all of the optional parameters.

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.

Note

While uncounted nodelocked licenses can be served by a license server, single licenses cannot.)

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=….

Note

Any white space in a username is converted to the underscore (‘_’) character. Also note that usernames are case-insensitive.

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 CLIENT_CACHE in the License Administration manual 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.

Environment

Description

TerminalServer

Disable use on Windows Terminal Server and Remote Desktop.

TerminalServerAllowRD

Disable use on Windows Terminal Server but allow use via Remote Desktop.

VM

Disable use on Virtual Machines.

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.

Note

Both hold and min_checkout time specifications are ignored for any license which is roaming. Also note that hold time is processed by the license server, so it has no effect on unserved nodelocked licenses.

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.

Note

The ISV-supplied max_roam_count attribute is equivalent to the license administrator MAX_ROAM_COUNT option, except that max_roam_count in the license is always enforced, rather than being optional.

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:

named_user

Require the same # of users as there are licenses.

named_user=n

Require n users to be named.

named_user=”n min_hours”

Require n users, and specify the minimum number of hours.

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).

Note

  • Different named_user licenses will never be combined into one license pool, even if all other license parameters match.

  • named_user utilizes the INCLUDE list in the server, so any INCLUDE specification for this license will be ignored.

  • named_user is processed by the license server, so it has no effect on unserved nodelocked licenses.

  • usernames are case-insensitive, so user “Joe” is the same as user “joe”.

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.

Note

If the string contains embedded white space, it must be enclosed within double quotes.

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.

Note

The license password does not factor into the license signature, and hence can be changed at any time after the license is signed. Also note that license passwords only work with served licenses, not nodelocked, uncounted or single licenses in local license files.

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.

Note

If you specify more than one platform, enclose the entire string in double quotes (e.g., platforms=”sun_s x86_w sun64_s”).

Also note that while you can include the trailing revision number, it will not be used by RLM in any comparisons, so including it may lead to confusion.

Platform

RLM Platform name

string to use in platforms=

HP//UX on PA-Risc, 32-bit

hp_h1

hp_h

HP//UX Itanium, 64-bit

ia64_h1

ia64_h

IBM AIX, 32-bit

ibm_a1

ibm_a

IBM AIX, 64-bit

ibm64_a1

ibm64_a

IBM Power Linux, 64-bit

p64_l1

p64_l

Linux Intel, 64-bit

x64_l1

x64_l

Linux ARM, 64-bit

arm64_l1

arm64_l

Linux, 32-bit

x86_l2

x86_l

Linux, 64-bit

x64_l1

x64_l

Linux Itanium, 64-bit

ia64_l2

ia64_l

Linux PPC, 64-bit

ppc64_l1

ppc64_l

Mac Arm, 64-bit

arm64_m2

arm64_m

Mac Intel, 32-bit

x86_m1

x86_m

Mac Intel, 64-bit

x64_m2

x64_m

Mac PPC, 64-bit

ppc_m1

ppc_m

NetBSD, 32-bit

x86_n1

x86_n

Solaris Sparc , 32-bit

sun_s1

sun_s

Solaris Sparc, 64-bit

sun64_s1

sun64_s

Solaris, 64-bit

x64_s1

x64_s

Windows Intel, 32-bit

x86_w3, x86_w4

x86_w

Windows Intel, 64-bit

x64_w3, x64_w4

x64_w

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.

Note

If you specify replace, you must also specify either start= or issued=.

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=”a b” in the license.

Warning

If two replace licenses have the same issued/start date, they will both be active after the replace determination has been made.

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.

Note

When the license server pools separate licenses into a single license pool, the soft_limit of each license is added to obtain the pool’s soft_limit. Licenses which do not specify a soft_limit use the license count as their soft_limit.

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.

Note

Usernames and hostnames in RLM are case-insensitive.

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.

Note

Once a shared license is in use, it will continue to be in use until all the processes sharing the license check it back in. In other words, if 2 processes are sharing one license, and a 3rd process consumes a 2nd license (in the case where n==2), 2 licenses will continue to be in use until either (a) the 3rd process checks in its license, or (b) BOTH the first and second processes check in their licenses. In other words, there is no dynamic re-combination of shared licenses done at license check-in time.

Note

Share is processed by the license server, so it has no effect on unserved nodelocked licenses.

Examples

share=UH

Both username and hostname of a request must match.

share=U

Only the usernames must match on two processes to share license.

share=U:2

With matching usernames, one license is consumed for every two shares.

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:

user_based[=nnn]

For user-based licenses.

host_based[=nnn]

For host-based licenses.

personal

For personal licenses.

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.

Note

user_based and host_based are processed by the license server, so they have no effect on unserved nodelocked licenses.

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.

Note

min_remove is processed by the license server, so it has no effect on unserved nodelocked licenses.

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.

Note

Timeout is processed by the license server, so it has no effect on unserved nodelocked licenses.

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.)

The maximum length and types of license fields are as follows:

Field

Type

max data length (excluding keyword=) or value range

isv

string

10 characters

product

string

40 characters

version

string, in the form nnn.mmm

10 characters

exp-date

string of the form dd-mmm-yyyy

11 characters

count

positive integer

231 - 1

hold

positive integer - seconds

231 - 1

host_based

int

231 - 1

hostid (single)

string

75 characters

hostid (list)

space-separated, quoted string

200 characters, max of 25 hostids

hostname

string

64 characters

issued

string of the form dd-mmm-yyyy

11 characters

_line_item

string – license administrator defined

64 characters

max_roam

non-negative integer - days

231 - 1

max_roam_count

non-negative integer - count

231 - 1

min_checkout

positive integer - seconds

231 - 1

min_remove

integer - seconds (-1 for no remove available)

231

min_timeout

positive integer - seconds

231 - 1

options

string

64 characters

password

string

32 characters

personal

int

231 - 1

platform

string

80 characters

share

enumerated

3 (“uhi”) + :integer

soft_limit

int

231 - 1

start

string of the form dd-mmm-yyyy

11 characters

timezone

int

bitmap with bits 0-23 set

user_based

int

231 - 1

contract

string – unused by RLM

64 characters

customer

string – unused by RLM

64 characters

issuer

string – unused by RLM

64 characters

type

string - consisting of “demo” “eval” “beta” and/or “subscription”

14 characters

Valid LICENSE Option Configurations

Only certain combinations of license types and options are valid. The following table indicates which options are valid for various license types. An X in a cell indicates that the attribute on the left is valid with the main license type in the column; empty cells indicate unsupported option configurations. All license administrator editable options (beginning with “_”) can be added to any license type.

License Type →

Floating

Nodelocked

Single

Uncounted

Token

Metered

Attributes ↓

HOST/ISV line

required

required

ignored

X

X

required

UPGRADE-able

X

X

X

X

contract

X

X

X

X

X

X

customer

X

X

X

X

X

X

disable

X

X

X

X

X

X

hold

X

X

when served

host_based

X

hostid

required

required

required

X

X

issued

X

X

X

X

X

X

issuer

X

X

X

X

X

X

max_roam

X

max_roam_count

X

min_checkout

X

X

min_timeout

X

X

X

X

named_user

X

X

options

X

X

X

X

X

X

platforms

X

X

X

X

X

X

replace

X

X

X

X

X

X

start

X

X

X

X

X

X

soft_limit

X

X

share

X

X

timezone

X

X

X

X

X

X

type

X

X

X

X

X

X

user_based

X

X

Examples

LICENSE reprise write 1.0 permanent uncounted 987435978345973457349875397345
hostid=IP=172.16.7.3

LICENSE reprise calc 1.0 1-aug-2008 5 987435978345973457349875398749587345987345

In the first example, the write product is licensed to a host with an IP address of 172.16.7.3. This is a non-expiring, node-locked, uncounted license. The second example is for 5 licenses of product calc which expire on the first of August 2008. The first license would not require a HOST line, whereas the second one would.

Note

The keyword “FEATURE” can be used in place of “LICENSE”.

Note

Licenses are always additive, in other words, the counts on 2 license lines of the same product/isv/version/hostid would be added together by the license server and the total number of licenses would be available.

UPGRADE Line

Format:

UPGRADE isv product from-version to-version exp-date count [sig=]upgrade-key [optional
parameters]

The UPGRADE line defines an upgrade from an older version (from-version or higher) to a newer version (to-version) of an existing product. All fields in the upgrade line are case-insensitive (with the exception of short, i.e., less than 62-character, license keys), and none may be modified by the license administrator with the exception of the parameters whose names begin with an “_” character.

We refer to the license specified by the UPGRADE line as the upgrade license, and the license it operates on as the base license.

An UPGRADE license will convert count licenses of product of version from-version or higher into to-version.

Note

An UPGRADE license will never operate on a base license that is >= to-version.

In order for the upgrade to be performed, certain parameters of the upgrade license must match the parameters of a base license in order for that license to be eligible to be upgraded.

Certain licenses can never be upgraded. In particular, token-based licenses (the token definitions themselves) will never be upgraded. Also, named-user and metered licenses are not eligible for upgrades.

In order for a license to be upgraded, the following parameters must match on the base license and the upgrade license:

  • License Disable specification

  • License Options

  • License Sharing specification (share and max_share)

  • License Timezone specification

  • License Platform list

  • Both licenses must have the same counting type: counted, uncounted, or single

  • License node-locked hostid

  • Both licenses must be user-based or host-based (or neither)

Note

This list is the same as the criteria for a license server combining multiple licenses into a license pool.

If the license is eligible for an upgrade, count licenses of the base license will be transformed into to-version licenses. An upgrade can be performed on multiple base licenses, until the count on the upgrade license is exhausted.

Note

License “replace” processing is done (both in client and server) before upgrade processing. This means that an upgrade license should not specify replacement of the base license which it is going to upgrade, because the base license will no longer exist when the upgrade is done.

There are 3 upgrade cases:

  • Fewer base licenses than upgrade licenses - in this case, the extra upgrade licenses are “wasted”, and the license server issues a warning. All base licenses are upgraded.

  • Same number of base licenses and upgrade licenses - all base licenses are upgraded.

  • Fewer upgrade licenses than base licenses - in this case, count licenses are upgraded, and the remaining base licenses remain at their old version.

The 3rd case above is the most useful - if you are upgrading all instances of an existing license, a replace option on a new license will do this just as well. The only advantage to the upgrade license in the first two cases is that the base license is required, i.e., the upgrade license, by itself, grants no rights.

When a license is upgraded by the license server, the new licenses will have their parameters modified as follows. All other license parameters will be the same as the base license:

Field

Result for Served counted (or uncounted) licenses

Result for Unserved single or uncounted licenses

exp-date

earlier date is used

earlier date is used

hold

maximum of the 2 values

  • undefined -

max_roam

minimum of the 2 values

  • undefined -

min_checkout

maximum of the 2 values

  • undefined -

min_remove

maximum of the 2 values

  • undefined -

min_timeout

maximum of the 2 values

  • undefined -

soft_limit (upgrading all)

Larger of 2 deltas from license count is used.

  • undefined -

soft_limit (partial upgrade)

Upgrade soft limit is preserved for the new version, base license soft limit delta is preserved (minimum value 0) for the old version.

  • undefined -

user_based, host_based (upgrading all)

If licenses have a specification, the value closest to the license count is used .

  • undefined -

user_based, host_based (partial upgrade)

If licenses have a specification, upgrade spec is preserved for the new version; base license spec delta (countuser_based) is preserved (minimum value 1) for the old version.

  • undefined -

contract

If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty, use value from base license for the new version.

If base license is empty, use upgrade license.

customer

If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty, use value from base license for the new version.

If base license is empty, use upgrade license.

issuer

If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty, use value from base license for the new version.

If base license is empty, use upgrade license.

type

If base license is empty, use upgrade license. On partial upgrade, if upgrade license is empty, use value from base license for the new version.

If base license is empty, use upgrade license.

Fixed (positional) parameters

The first 7 parameters are required on every upgrade line 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 upgraded.

from-version

The lowest-numbered product version which is eligible for an upgrade, in the form “N.M”.

For example, 1.0, 2.37, or 2006.12

to-version

The highest-numbered product version supported by the license once it is upgraded, in the form “N.M”.

For example, 1.0, 2.37, or 2006.12

exp-date

The date the upgrade expires, in the form dd-mmm-yyyy, for example, 1-jul-2007. A non-expiring upgrade can be specified with either a year of “0” (i.e., “1-jan-0”), or simply the word “permanent”.

count

The number of licenses to be upgraded. 0 or uncounted means an uncounted, node-locked license is to be upgraded. uncounted and 0 are 100% equivalent.

single means a node-locked, single-use license is to be upgraded. single is different from 1. See LICENSE Line above for more information.

token, token_locked, token_bound and token_unlocked are not allowed in an UPGRADE license. All other optional parameters are ignored.

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).

upgrade-key

A digital signature of all the upgrade data, along with the hostid on the HOST line, if present. If an upgrade license has a non-zero count, it always requires a HOST line. An upgrade to 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 upgrade-key. The upgrade-key will have “sig=” prepended after the license has been signed by the rlmsign utility.

Note

If the upgrade-key is preceded by sig=, it can be present after any or all of the optional parameters.

Optional Parameters

Optional parameters are sometimes present in a license and can be present in any order. Optional parameters are allowed only once in an UPGRADE line. The syntax and meaning of optional parameters for the UPGRADE line are identical to the same parameters for the LICENSE line. Note that token and named_user are not allowed on an UPGRADE line. See LICENSE Line for information on the optional parameters.

Example:

LICENSE reprise write 1.0 permanent 5 sig=.....
UPGRADE reprise write 1.0 2.0 1-aug-2015 5 sig=.....

In this example, the 5 licenses of the write product have been upgraded from v1.0 to v2.0.

Note

This license file would require a HOST line, since the licenses are counted.

CUSTOMER line

CUSTOMER customer-name isv=isvname server=server-name port=port# password=yourpw

The CUSTOMER line, used for the client side of RLM Cloud-served licenses only, is used to identify the correct license server for a particular customer.

customer-name

Your customer’s assigned Customer name.

isvname

Your ISV name.

server-name

The fully qualified hostname of the RLM Cloud license server machine.

port#

Either 5053 for normal RLM communications, or for HTTPS transport, 443).

yourpw

Your assigned password for this server.

Note

HTTPS support must be enabled by your ISV to be effective. Please consult with your ISV to see if HTTPS support is available.

Example:

CUSTOMER yourco isv=reprise server=ls423.rlmcloud.com port=5053 password=xyz

isvname

Your ISV name.

The License Environment

All software that uses RLM attempts to read a license file or communicate with a license server. The specification of the license file or the license server is done with the license environment.

If the software is ISV-specific (e.g., an application program), the first place that is checked is any license file or port@host specified in the environment variable ISV_LICENSE (if it is defined), where ISV is name of the ISV (e.g., REPRISE_LICENSE).

If ISV_LICENSE is not defined (in the case of ISV software), or for generic software (RLM utilities, the RLM server) the path specified by the environment variable RLM_LICENSE is checked, if RLM_LICENSE is defined.

If neither environment variable is defined, the program’s default location for the license is checked next. In the case of the RLM utilities and the RLM server, this is any file ending in .lic in the current directory. Note that the RLM utilities will substitute the path specification from a -c option in place of the current directory.

Finally, any .lic file in the directory containing the binary will be checked.

The format of the environment variable (RLM_LICENSE or ISV_LICENSE) is:

license_spec1

or

Unix
license_spec1:license_spec2:license_spec3: .... :license_specN
Windows
license_spec1;license_spec2;license_spec3; .... ;license_specN

where:

license_spec is a license specification of the form:

  • port@host - or -

  • license_file_pathname - or -

  • directory pathname (containing license files, all of which are added to the list) - or -

  • <actual text of license>

Note

The separator character is ‘:’ for Unix systems and ‘;’ for Windows systems.

Note

The license file cannot be placed in a path where any component of the pathname contains the ‘@’ character.

Example

On Unix/Mac:

% setenv RLM_LICENSE 1700@myhost:/home/reprise/reprise.lic

On Windows:

C:\ set RLM_LICENSE=1700@myhost:/home/reprise/reprise.lic

In this example, the server at port 1700 on host “myhost” is checked first, then if the request is not satisfied, the license file at /home/reprise/reprise.lic is used. Note that this search order may be modified if the environment variable RLM_PATH_RANDOMIZE is set.

Example 2

% setenv RLM_LICENSE 1700@myhost:<LICENSE isv prod1 1.0 1-jan-09 uncounted hostid=any
key="1234...">

This example specifies the license for “prod1” directly in the environment variable, in addition to using the server at port 1700 at host “myhost”.

On Windows, you can also set the environment variable via the control panel using these steps:

  1. Go to Control Panel->System (or Control Panel->System and Security)

  2. Click on “Advanced System Settings”

  3. Click on “Environment Variables”

  4. Enter RLM_LICENSE as the environment variable name and the license file directory as the value

Note

Beginning in RLM v14.2, white space is trimmed from the start and end of the license environment variable value.

Note

Beginning in RLM v15.1, uppercase ISV_LICENSE can be used as well as isv_LICENSE on case-sensitive file systems. In the case that both are defined, the uppercase ISV_LICENSE will be used.