Optional Parameters

Optional parameters are sometimes present in a license, and can be present in any order. Optional parameters are allowed only once per license. Note that parameter names which begin with the underscore ('_') character can be either added or modified by the License Administrator without invalidating the license signature.

akey=activation-key

The RLM Activation Pro license generator can include the akey= keyword with the activation key used to fulfill the license, if specified by your Software Publisher. This parameter is unused by RLM.

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 (note: the list must be in quotes if more than one item is specified):

TerminalServer - disable use of Windows Terminal Server or Remote Desktop.

VM - Disable use on Virtual Machines.

Example:

disable=TerminalServer

disable=vm

disable="vm TerminalServer"

_failover_host=hostname

This field is used only on an “rlm_failover” or “rlm_failover_server” license and is set by the License Administrator to the failover server's hostname. This field has no meaning on any license other than an “rlm_failover” or “rlm_failover_server” license.

hold=n

hold specifies that a license is to be “held” checked-out by the license server after the application performs a checkin call or exits. The license will remain checked-out for the number of seconds n specified after application checkin or exit. 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.

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 after the application checks it in, 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. See also min_checkout=n.

host_based[=n]

host_based indicates that the specified number of licenses (or all licenses) must be reserved to hosts 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 refuse to serve the license. Also note that licenses reserved to a HOST_GROUP are not counted. Thus, all reservations must be to individual hosts.

hostid=hostid-string

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.

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 four specified hosts:

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

_id=nnn

Any License Administrator can add _id=nnn to a license. “nnn” is a positive integer, less than 2**31, 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).

Other than license pooling, 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.

issued=issue-date

The optional issued=issue-date attribute is used in conjunction with the replace keyword. See the description of replace for a description of how the issue-date affects license replacement.

max_roam=days

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.

max_roam is used to specify the maximum number of days which a license can be held by the server and used on a disconnected system.

If your Software Provider does not specify max_roam in an individual license, RLM limits the maximum number of days that a license can roam to 30 days. If max_roam is set to -1, roaming is disabled on that particular license.

Also note that if your ISV specifies max_roam on the rlm_roam license itself, this max_roam specification will apply to all of your products which do not have max_roam specifications.

max_roam_count=count

max_roam_count specifies the maximum number of licenses which can roam. If unspecified, all licenses are allowed to roam. If set to 0, no licenses are allowed to roam. If two licenses are pooled, their max_roam_count values are added. Finally, you can lower this value by using the ROAM_MAX_COUNT option, however ROAM_MAX_COUNT will never raise this value.

min_checkout=n

min_checkout specifies that a license is to be “held” checked-out by the license server after the application performs a checkin call or exits if the license did not remain checked out for the minimum interval specified by n. 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 after the application checks it in, 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. See also hold=n.

Example 1:

hold=30

Application checks license out for 5 minutes. Application checks license in at this point, the server keeps the license checked out for an additional 30 seconds.

Example 2:

min_checkout=30

Application checks license out for 5 minutes. Application checks license in at this point, the license will be checked in by the server with no extra hold time.

Example 3:

Application checks license out for 5 minutes. Application checks license in at this point, the server keeps the license checked out for an additional 100 seconds.

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 is disabled on this license.

min_timeout=n

You 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 checkin of the license and informs the application (if it is still running).

min_timeout specifies the lowest value, in seconds, you can set the TIMEOUT or TIMEOUTALL value for a license. If not specified in the license, the RLM default of 3600 seconds (1 hour) is used. Note that licenses NEVER time out on their own, you must set a TIMEOUT or TIMEOUTALL option in the options file to have them time out.

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. Note that if the string contains embedded white space, it must be enclosed within double quotes.

_password=password-text

The _password specification limits who can use this license to users who know the password.

You can assign a password to a license in order to restrict the ability to check out, or even see the license.

To do this, specify:

_password = password-string

in the license.

If specified, a license password restricts access to this license to requests which have specified the same password-string. The password-string is specified with the RLM_LICENSE_PASSWORD environment variable, or in the RLM web interface for viewing licenses.

Note that 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 node-locked, uncounted or single licenses in local license files.

Also note that if you do assign a password to a license, and the application fails to supply the correct password, the server will return a “License Server does not support this product” error (status -18) when a checkout is attempted.

License passwords can be specified on the ISV line, with the new “password=password-text” option. When specified this way, the password on the ISV line applies to all LICENSE or FEATURE lines for the ISV which follow the ISV line in the license file. If an individual LICENSE line specifies a password, the password from the LICENSE line is used in place of a password on the ISV line.

platforms=platform-list

The platforms specification limits the types of computers which can use this license.

RLM allows your ISV 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.

The platform-list consists of a list of RLM-defined platform names, which consist of a machine architecture and an operating system version/revision, as in the following table:

replace=[product-list]

The replace specification causes this license to replace other license(s).

In order to render ineffective one or more licenses which have already issued to you, the ISV uses the replace[=product-list] option in the new license. replace= causes RLM to ignore the “replaced” license(s).

replace operates as follows:

• licenses from the product-list will be replaced. 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.

  share=UHI[:nnn]

  share specifies how a license is shared between separate clients (processes).

  Licenses can be shared between separate running processes. To do so, your ISV will have put 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. Share is specified 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.

  For example, if share is specified as share=UH, then both the username and the hostname of a request must match an existing checked-out license in order to share that existing checked-out license. If share is specified as share=u, then only the usernames must match on two processes in order for them to share the license.

  The share= keyword accepts an optional maximum process count which can share the license: 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 that 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 two processes are sharing one license, and a third process consumes a second license (in the case where n==2), two licenses will continue to be in use until either (a) the third 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 checkin time.

  soft_lmit=n

  A license can have a soft_limit that is lower than it's count of available licenses. Once usage exceeds the soft_limit, checkout requests will return the RLM_EL_OVERSOFT status instead of a 0 status. The application's behavior in this case is entirely up to your ISV.

  Note that 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. Also note that licenses which do not specify a soft_limit use the license count as their soft_limit.

  start=start-date

  start= specifies a start-date. This license cannot be used before the specified date. The format is the same as the expiration date.

  timezone=timezone-spec

  timezone= allows your ISV to specify a set of valid timezones for the client machine that performs the license checkout. If timezone= is present in the license, there is a timezone restriction. The timezone-spec is a 24-bit HEX number, with one bit set for each timezone your ISV wishes to be valid. Bit 0 represents GMT and each bit to the “left” of bit 0 represents one timezone (one hour) west of GMT. Thus bit 5 would be EST, bit 8 would be PST, bit 23 would be one hour east of GMT, etc. Note that RLM uses the current local time, so the timezones will move by one hour when Daylight Savings Time is in effect (i.e., PST varies from 7 to 8 hours west of GMT).

  So, for example, to allow the license to be used in PST only, the timezone spec would be as follows, specifying timezones 7 and 8 west of GMT:

  timezone=180

  user_based[=n]

  user_based indicates that the specified number of licenses (or all licenses) must be reserved to users 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. Thus, all reservations must be to individual users.

The following fields are not used by RLM, but are present to identify licenses:

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.

customer=who

customer= is to identify the customer of the software. customer is not used by RLM.

issuer=who

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

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

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“

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

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

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