RLM License Administration

RLM v15.2

December, 2023

Table of Contents

Section 1 – License Management Introduction

Introduction ......................................................................................... 5

What's New in RLM v15.2 ................................................................. 7

Section 2 – License Administration Basics

Installing an RLM-licensed Product …............................................. 9

The License Server ............................................................................. 11

The License File ................................................................................... 20

HOST line...................................................................................... 21

ISV line.......................................................................................... 21

LICENSE line............................................................................... 23

UPGRADE line............................................................................. 34

CUSTOMER line.......................................................................... 37

The License Environment............................................................ 37

License Administration Tools ............................................................ 40

Client Authentication.......................................................................... 48

The RLM Web Server......................................................................... 49

The RLM Options File ....................................................................... 63

The ISV Options File .......................................................................... 69

Section 3 – Advanced Topics

Token-Based Licenses ........................................................................ 84

How to Queue for Licenses ................................................................ 87

How to use Roaming Licenses ........................................................... 88

Failover License Servers .................................................................... 92

Transferring Licenses to Another Server ........................................ 95

Section 4 – Reference Material

RLM Environment Variables ........................................................... 99

RLM Performance Testing ............................................................... 103

Reportlog File Format ....................................................................... 106

RLM hostids ...................................................................................... 118

Optional hostid Installation Instructions ........................................ 120

IPv6 Considerations .......................................................................... 121

RLM Status Values ........................................................................... 122

RLM Version History ....................................................................... 129

Revision History ................................................................................ 137

RLM License Administration Manual Page 2 of 139

Reprise License Manager

Detached Demo, Open Usage, Reprise License Manager, RLM Activation Pro, RLM, RLM-Embedded and Transparent

License Policy are all trademarks of Reprise Software, Inc.

RLM contains software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org)

RLM contains software (the GoAhead WebServer) developed by GoAhead Software, Inc.

RLM contains software (Mongoose Web Server), developed by Cesanta Software Ltd.

RLM License Administration Manual Page 3 of 139

Section 1 – License Management

Introduction

RLM License Administration Manual Page 4 of 139

Introduction

About this Manual

This manual describes setup and maintenance of the RLM licensing system, and as such it is

intended for license administrators and users at organizations which have purchased software

which uses the Reprise License Manager. This manual explains how to install and configure the

licensing system included with your software.

Introduction To RLM

You are most likely reading this manual because one or more of your software vendors (ISVs)

have included RLM in their product(s) to enforce their license agreements. This manual describes

the components of RLM that you need to understand in order to accomplish day-to-day license

administration tasks.

RLM allows your organization to know that you are using purchased software within the license

limits set by your ISV. In addition, RLM collects usage information (at your option) for later

reporting and analysis. This usage information is provided in a fully documented report log

format, described in Appendix A of this manual.

When one of your ISVs delivers software to you that incorporates RLM, in addition to the normal

application files, you will receive some additional RLM components:

• the RLM (generic) license server provided by Reprise Software, called "rlm" on Unix

systems, or "rlm.exe" on Windows. This is the same for every ISV who uses RLM.

• the RLM utilities ("rlmutil" on Unix, "rlmutil.exe" on Windows) provided by Reprise

Software. This is the same for every ISV who uses RLM.

• A custom license server, built from components from Reprise Software by your ISV. This

server will have a different name for each ISV.

• a license file to describe your rights to the product. This license file is unique to your site.

In addition to these components which your ISV supplies, you can create an ISV options file to

control various aspects of operation of each licensed product. This options file is described later in

this manual. In addition, an RLM options file allows you to restrict access to various

administration commands.

RLM is a client-server system, with license requests transmitted over TCP/IP from the software

application to a license server that controls license usage rights.

What sets RLM apart?

RLM was designed from the start to emphasize openness, transparency, and simplicity.

RLM is open because we publish the format of our report log file, so that you can always examine

and generate usage reports on licensing activity from the RLM servers.

RLM License Administration Manual Page 5 of 139

RLM is transparent in the sense that we do not allow "back doors" which lead to unique

behaviors from one ISV to another. In addition, we have removed policy from the application

code, and placed it into the license key itself, so that everyone will be able to understand the

license terms without having to understand a particular implementation by an ISV.

RLM is simple because we include functionality like truly automatic selection of license servers

from a set of multiple, independent servers. In older license management systems, the ISV ends up

writing much code to manage multiple license servers. This is handled by RLM itself.

Software License Management Basics

RLM is similar in structure to most popular license managers. RLM consists of 3 major

components:

1. A client library

2. A license server (RLM has 2 license servers - a generic server called rlm and an ISV-

specific server.)

3. A text file which describes the licenses granted (the license file).

Your ISVs application is linked with the client library which provides access to the license

management functions.

The license server is used for floating licenses and logging of usage data. You, as a License

Administrator, have the ability to control certain aspects of the license server's operations by

specifying options in a file called the ISV Options File.

The RLM client library (linked into your ISVs application) and the license server are both

controlled by license authorizations stored in a text file called the license file.

Most license managers provide APIs with calls to control many of the aspects of licensing

behavior, as well as options within the license servers to control licensing behavior. The design

philosophy of RLM is to preserve the simplicity of the system for both ISVs and License

Administrators by avoiding all unnecessary options in the client library and the license servers and

moving all these options to the license file, where they are visible and understandable by

everyone. In general, license policy should be kept out of the application and the license server,

and placed into the license itself. This makes for a more understandable licensing system for both

ISVs and License Administrators. The API is simpler, and the license server performs in a more

standard way from ISV to ISV. This prevents license management confusion by customers. We

learned this the hard way when we supported hundreds of customers in the past and applied these

lessons to the design of RLM.

Table of Contents

RLM License Administration Manual Page 6 of 139

What's New in RLM v15.2

This section lists the new features in RLM v15.2, along with pointers to the relevant sections in

the manual.

• Warning no longer presented to user when C:\ProgramData\Reprise\isvname\ doesn't

exist.

• License path no longer includes temporary directory if the temporary directory does

not exist.

• rlm_stat() no longer returns an error if the C:\ProgramData\Reprise\isvname folder is

missing.

• Temporary licenses are now correctly created with version number equal to "parent"

license.

• Using unicode in company names no longer causes issues with portal users on RLM

Cloud.

• Server usage on the RLM Cloud customer portal now loads additional pages correctly.

• log.php no longer fails to download report logs.

• ISVs are now able to disable certificate revocation in RLM Cloud.

Table of Contents

RLM License Administration Manual Page 7 of 139

Section 2 – License Administration Basics

This section of the manual contains the information you need to install and

manage your purchased applications which use the RLM license manager.

RLM License Administration Manual Page 8 of 139

Installing an RLM-licensed Product

When you receive a product licensed with RLM, your Software Provider (or Independent

Software Vendor, referred to in this manual as your “ISV”) will provide an installation procedure

that installs the license management components (in the case of floating licenses, this is typically

separate from the installation procedure for the application, since the license server processes

usually run on a different machine from the application). Your ISV will generally make the

licensing installation as transparent as possible.

In some cases, your ISV will not provide you with an installation procedure for the license server

(the license server is required for floating licenses only – it is not required for nodelocked

licenses). This might happen, for example, if you want to run the server on a platform which your

ISV does not support. The remainder of this section describes a manual RLM server installation, in

the event you need to install it yourself or troubleshoot your installation.

First, you need the three required licensing components for the license server:

• The generic license server, rlm on Unix, rlm.exe on Windows.

• The ISV's license server, either a settings file named isv.set, or a binary named isv on

Unix, isv.exe on Windows.

• The license file which describes your rights to the product.

Optionally, you might want the RLM utilities - rlmutil on Unix, rlmutil.exe on Windows. These

utilities are often installed as their separate command names, see License Administration Tools on

page 40.

For the easiest installation, place all three components in the same directory (put the utilities, if

you want to install them, in that directory as well.) In this way, license servers, utilities, and

application programs will all be able to locate the license without any additional environment

settings for users. All that remains to get floating licensing working is to start the license servers.

(Note: if you did not locate the license file (or a link to it) in the binary directory, you need to

provide a pointer to the license file (or license server) to the application, using the RLM_LICENSE

environment variable.)

To start the license server (again, only required for floating, or counted licenses):

1. place the license file into the binary directory (or startup directory) and name it

something.lic If you do not do this, then set the RLM_LICENSE environment variable to the path

of the license file.

2. execute the rlm command:

% rlm > output_file

To enable your users to find the license file or license server, either:

1. Put the license file (named something.lic) in the binary directory with the application

program (RECOMMENDED), OR

2. setenv RLM_LICENSE license_file_path, OR

3. setenv RLM_LICENSE port@host, where port is the port # in the license file, and host is

the hostname in the license file.

Note: if you are using RLM v10.0 or later (both clients and servers), and you are running on a

local-area network, the client will broadcast to locate the license server, and no other configuration

is required beyond setting up the license server.

RLM License Administration Manual Page 9 of 139

Here are the details of how floating licensing works

To use floating licenses, an RLM client connects to an RLM server to check out a floating license.

(The RLM client is usually part of the licensed application.)

RLM Server

• The RLM server is started by a start script on the server machine, or started manually.

• The RLM server scans for valid license files, for one or more ISVs. For each ISV, rlm

will start the ISV server – either an ISV server binary, or another copy of rlm that takes on the

personality of the ISV server via the ISV server settings file.

• The RLM server opens and listens on one or more ports to receive license requests from

the RLM clients.

• The RLM server port numbers are specified on the HOST line of the license files. The

default (if none is given) is 5053.

• The ISV server's port number is specified on the ISV line of the license file. If there is

more than one license file, there can be more than one port defined for the ISV server. If no port

number is set, a random free port number is used.

• Once a day - at midnight local time - the RLM server will trigger a re-read of all ISV

license files. All ISV servers will then reread the license file and continue processing requests.

RLM Client

• The application contains an embedded "RLM client". Eventually some part of the

application will request a license "check out". To process this request, the RLM client connects to

the RLM server.

• The RLM server gets the requests from the RLM client, looks up the ISV (in its internal

list of ISV servers), and forwards the RLM client to the correct ISV server port number.

• The RLM client then connects to the ISV server and sends a "check out" request for the

requested license.

• NB: The RLM client needs to 'know' only the RLM server host name and port number.

The application's installation procedure must document how to set these values.

Troubleshooting in large networks

• In order to check out a license, the RLM client (embedded in the application) needs to be

able to connect to the RLM server and to the ISV server. Large companies with internal firewalls

must make sure both ports are accessible for the RLM client to successfully check out a license.

Table of Contents

RLM License Administration Manual Page 10 of 139

The License Server

The license server consists of at least two processes

• The generic server, called rlm

• At least one ISV server, named isv

The rlm server is provided by Reprise Software and is completely generic. The ISV server is

configured to contain license key validation that is ISV-specific.

The rlm server handles requests from clients and directs them to the appropriate ISV server. In

addition, the rlm server watches for failures in ISV servers and restarts them when appropriate.

The rlm server also provides status to the various utilities, when appropriate.

The rlm server initiates a reread of the license files (for itself and any ISV servers) at midnight

every night.

The rlm server is delivered with an embedded Web Server to perform normal administration tasks.

For more information on the web server interface, see The RLM Web Server on page 49.

Note that Reprise recommends users not run the RLM server as a privileged user (root on

Unix or administrator on Windows).

rlm startup options

The rlm command is:

% rlm [-c license_file] [-dat] [-dlog [+]logfile] [-info]

[-l] [-noudp] [-nows | -ws port] [-x [rlmdown|rlmremove]]

[-install_service] [-service_name sname]

[-v] [-user username -password password]

[-isv_startup_delay seconds]

[-verify]

[-sslcert certfile -sslpriv privkey]

The -c license_file option specifies which license file to use. This option overrides the setting of

the RLM_LICENSE environment variable. Note that the -c option first appeared in RLM v2.0.

Beginning in RLM v6.0, the license_file parameter can be a directory containing license files, all

of which will be processed.

The -dat option specifies that license files should have the extension ".dat", rather than ".lic". If

-dat is specified, the rlm server will search for all files ending in ".dat" instead of ".lic" as

documented elsewhere. This option first appeared in RLM v3.0.

The -dlog logfile specifies the pathname for the server debug log. If logfile is preceded by the '+'

character, the logfile will be appended, otherwise it is overwritten. This option first appeared in

RLM v2.0. (Note: starting in RLM v4.0, all ISV servers will write their output to the same logfile

specified in the -dlog option.)

The -info option causes RLM to print information about all copies of rlm that are running on this

computer, including copies which have run in the prior 24 hours, then exit.

The -install_service and -service_name sname options are used to run the rlm server as a service

under windows. Optionally a username and password of a user account under which you wish to

RLM License Administration Manual Page 11 of 139

run the service may be specified, via the -user and -password arguments. See the description of

running the rlm server as a service below.

Notes on using the -user and -password options:

1. Windows expects the username argument to be <domain>\<user>. To use the local system

domain, specify ".\<username>", e.g., ".\joe". Without the ".\" you will get a service creation

failure.

2. In order to run a service, the account specified by the -user argument must have the "Log on

as a Service" property set. For details on how to set that property on an account:

https://learn.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/log-

on-as-a-service

The -isv_startup_delay seconds option specifies that when running as a Windows service, rlm

should delay seconds seconds before starting up the ISV servers. If not specified, there is no delay.

This is useful if a license file specifies a hostid of type rlmid1 or rlmid2 (hardware keys), the

server is started at system boot time, and the key driver is not yet started at the time the ISV server

needs to read it. This option was introduced in RLM v8.0BL6.

The -l switch causes rlm to only process command-line utilities from the local host (v12.1+)

The -nows and -ws port options control the operation of the embedded Web Server. The -nows

option instructs the rlm server to not start the embedded web server. The -ws port option instructs

the rlm server to use port as the port number for the web server.

The -noudp option tells RLM to not bind the UDP port (5053) used for replying to broadcast

messages from clients in RLM v10.0 and later.

The -v option causes RLM to print its version and exit. This option was introduced in RLM

v9.3BL2.

The -verify option will cause RLM to start all ISV servers to verify their licenses, then all servers

will exit.

The -x [rlmdown | rlmremove] option controls whether the rlmdown and/or rlmremove

commands will be processed by the server. Specifying only -x will disable both commands.

Specifying either command name after the -x will disable just that command.

The -sslcert certfile and -sslpriv privkey options together instruct the rlm web server to use

HTTPS using the SSL certificate certfile and SSL private key privkey. These options first

appeared in RLM v15.1

These options can appear in any order on the command line.

If you want to generate a report log file, specify this on an ISV-by-ISV basis in the individual

ISV's options file. See the description of the REPORTLOG line in The ISV Options File on page

69 for more information.

Note that if the rlm server cannot bind the web server port (5054 by default), it will exit. Note that

the web server default port was 9000 prior to RLM v6.0.

Also note that, prior to RLM v3.0, if there was not at least one license file with the current

hostname (as returned by gethostname()), or "localhost", the servers would not run. This condition

generates a warning in RLM v3.0 and later.

Starting in RLM v10.0, if the ISV server pathname is incorrect in a license file which RLM is

RLM License Administration Manual Page 12 of 139

processing, RLM will attempt to start that ISV server using the path information in other license

files, if present.

Starting in RLM v15.1, removed processing of -iai and -z flags. RLM will silently ignore these

flags without giving an error message.

The Server Debug Log

Both RLM and the ISV servers write debug logs, useful for diagnosing licensing inconsistencies

or failures. By default, this output goes to stdout, which is usually the window where you started

rlm. You can change the location of the debug log with the -dlog_logfile command line argument

to rlm, described above. You can also change the location of the ISV server debug log with the

DEBUGLOG line in the ISV options file. See The ISV Options File on page 69 for more

information.

When starting rlm as a service on windows, the debug logs will be written to the same directory

which contains the rlm.exe binary, so long as this directory is writable. If it is not writable, the log

files will be written to \\Windows\system32. (However, note that RLM will not allow itself to be

installed as a service when an unwritable debug log is specified).

Running the rlm server as a service on Windows

On Microsoft Windows servers, you may want to install and run the rlm server as a Windows

service process. A service process can start automatically at boot time and remain running as long

as the system is up, regardless of user logins and logouts.

You can install RLM as a service in a command window. Once installed as a service, it remains

installed until it is explicitly deleted as a service. Installing RLM as a service does not start RLM;

services are started via the Windows Services control panel, and at boot time.

You can only install RLM as a service in a command window. To do this, use the rlm program

itself (in a command window), with special arguments:

rlm -install_service -dlog [+]logfile [-service_name sname] [-user username] [-password

password] <rlm runtime args>

where:

• logfile is the pathname for the server debug log. This parameter is required. If preceded

by the '+' character, the logfile will be appended, rather than created.

• sname is an optional name for the installed service. If not specified, sname defaults to

"rlm". If sname contains embedded whitespace, it must be enclosed in double quotes.

• <rlm runtime args> are any other command line arguments to be passed to rlm when it is

started.

Example:

rlm -install_service -service_name rlm-xyz -dlog c:\logs\server.log -c c:\licenses\xyz.lic

This installs rlm as a service under the name "rlm-xyz". When started via the Services control

panel or at boot time, rlm will be passed the "-c c:\licenses\xyz.lic" args, and it will write it's

debuglog information to the file c:\logs\server.log

RLM License Administration Manual Page 13 of 139

Installed RLM services are also deleted with the rlm program. Services must be stopped via the

service control panel before they can be deleted. Note that deleting a service deletes it from the

Windows service database; it does not delete the rlm executable or associated license file(s):

rlm -delete_service [-service_name sname]

where:

• sname is an optional name for the installed service. If not specified, service_name

defaults to "rlm". If service_name contains embedded whitespace, it must be enclosed in double

quotes.

Notes:

• It is desirable to use the -c <license file> command line argument with RLM when

installed as a service. Use of environment variables with Windows services is undesirable, as the

environment passed to started services is the one in effect at boot time.

• On systems which run RLM license servers, it is a good idea to install each ISV's

instance of rlm with a service_name argument which reflects the ISV or ISVs whose licenses are

being served by that instance of rlm. For example, if a system ran two instances of RLM as

services, where the first instance served license for ISVs "Blue" and "Green", and the second

instance served license for ISV "Yellow", they might be installed as "rlm Blue-Green" and "rlm

Yellow", respectively.

• Because the Service Controller on Windows invokes services under a special user

account in a special default directory, it is necessary to use full paths:

• for the -c <license file> argument on the rlm command line

• in ISV daemon paths in the license file

• in options file paths in the license file

• in debug log paths in the ISV options file

• in report log paths in the ISV options file

• for the -dlog debug_log argument on the command line

• NOTE on the use of DEBUGLOG when running the server as a Windows Service:

If no DEBUGLOG is specified in the ISV options file, rlm will write the ISV debug log in:

<location of rlm.exe>\<isv>.dlog

This file will be overwritten every time the ISV server starts, since there is no opportunity to

specify that the file should be appended to in the default case. In fact, the ISV server logs a few

lines to this file at startup time even if a DEBUGLOG is specified in the ISV options file. It is

overwritten every time the ISV server starts, but its contents don't change from startup to startup,

so nothing important is lost.

Reprise Software Inc. recommends that the debug log path be specified in the ISV options file, and

that the append behavior be enabled with '+'<path>. However, it is important not to specify the

debug log name as <isv>.dlog, as this specific file is overwritten at each startup.

• Beginning in RLM v8.0, when running as service, rlm now changes its working directory

to the directory where rlm.exe is installed. This is so that log files will be written there instead of

in c:\windows\system32 as in prior versions (if log file paths are not specified as absolute paths.)

rlm.exe checks to make sure that it can write to that directory before changing its working

directory. If it can't be written, rlm leaves its working directory as c:\windows\system32.

• The web interface service installation is new in RLM v7.0

• Prior to RLM v4.0 when running rlm as a service, it is strongly recommended that you

specify a debug log location for each ISV server. This is done in The ISV Options File for each

ISV server, using the DEBUGLOG keyword. If no location is specified for the debug log, the ISV

server's debug information is lost when running as a service. Starting in RLM v4.0, the ISV

RLM License Administration Manual Page 14 of 139

servers place their debug output in the same file as the rlm server's debug log, as specified in the

-dlog option, so no DEBUGLOG specification is necessary.

• Starting in v9.4 when you install RLM as a service, it starts and then stops the installed

service. This is so that if there are any firewall issues - ports blocked that rlm needs to use - the

warnings come at service installation time rather than when rlm is started for the first time.

• Starting in v10.0, RLM checks the path you specify for the debug log (-dlog <log> or in

the "Server Debug Log box in the web interface). If this file cannot be written, an error is printed

and the service install fails.

Starting the rlm server at boot us ing systemd on Linux

1. cd to /etc/systemd/system

2. Create file rlm.service

[Unit]

After=network.target

Description=Reprise License Management Server

[Service]

# Optional environment variables

Environment=RLM_LICENSE=/path/to/license/files

Type=simple

User=<user>

WorkingDirectory=<Directory where rlm is located>

ExecStart=<Path to rlm [arg1 arg2 … argN]>

Restart=always

[Install]

WantedBy=multi-user.target

3. Start the service and enable at boot systemctl enable --now rlm.service

Starting the rlm server at system boot using initd on Linux

On most Unix systems, system services are started at boot time, usually via startup scripts located

in /etc/rc.<something>. For example, on Solaris, the startup script might be placed in

/etc/rc2.d/S98rlm. On Linux systems, the script could be located in /etc/init.d/rlm, with a link to

/etc/rc5.d/S98rlm. Note that you must install this startup script as root.

The startup script should su to a different user so that the rlm servers are not running as root.

The following is an example of a script which would start rlm at boot time on Unix systems.

Modify the first 5 variables for the target system.

RLM License Administration Manual Page 15 of 139

#! /bin/sh

# rlm Start/Stop rlm

#----------------------------------------------------------------

# NOTE:

# NOTE: Configure these 5 variables for your system

# NOTE:

# Set rlmuser to the user under which rlm will run

rlmuser=bobm

# Set rlmdir to the directory where the rlm binary is found

rlmdir=/home/bobm/rlm/dev/rlm

# Set rlmdir to the directory where the rlmdown binary is found

rlmdowndir=$rlmdir

# Set licfile to the path to the license file

licfile=$rlmdir/x.lic

# Set debuglog to the path to the debug log

debuglog=+$rlmdir/rlm.dl

#----------------------------------------------------------------

start() {

echo $debuglog

su - $rlmuser -c "$rlmdir/rlm -c $licfile -dlog $debuglog &"

}

stop() {

su - $rlmuser -c "$rlmdowndir/rlmdown RLM -c $licfile -q"

}

case "$1" in

start)

start

;;

stop)

stop

;;

restart)

stop

sleep 2

start

;;

echo $"Usage: $0 {start|stop|restart}"

exit 1

esac

exit 0

License Server Startup Processing

License servers use The License Environment to find their license file. In addition, any file whose

name ends in .lic in the current directory when the rlm server is started (or when the rlmreread

command is issued) is implicitly added to the end of the license file path. Finally, and file whose

name ends in .lic in the directory where the rlm binary resides is added to the list of license files

processed. (Note: license files in the isv server's binary directory are not processed, only the rlm

RLM License Administration Manual Page 16 of 139

binary directory is searched.)

License servers ignore port@host specifications in the License Environment. Once the list of

license files is created, the license servers process all the resulting license files. The rlm server

starts all ISV servers in all license files, and the ISV servers process and support all licenses in all

license files with valid hostids.

When the rlm server starts, it uses the port # from the first file with the hostname on which it is

running. In rlm v2.0 and later, the rlm server will attempt to use all the port #s in all the license

files. It must be able to bind the port # in the first file. Once this is done, it attempts to use the port

number from each additional file, logging either success or failure in the debug log. This means

that when you receive a new product or license file, it can be installed in the application and rlm

server directories without changing the port number in that file, which simplifies license

administration.

ISV servers process all licenses in all files that have a valid hostid (by this we mean a hostid that

corresponds to the computer on which the license server is running). The ISV servers attempt to

combine licenses whenever possible - see the next section - and when combined the license counts

add to create a single pool of licenses. ISV servers log (in the debug log) licenses with invalid

signatures and (in RLM v2.0) licenses that will expire within 14 days. ISV servers do not process

single-use (count==single) licenses.

Beginning in RLM v5.0, ISV servers will detect that they are running on a virtual machine, and by

default will refuse to run. The decision to run or not on a virtual machine is controlled by your

ISV, and Reprise Software has no part in this decision.

ISV server open file limits

Beginning in RLM v6.0, ISV servers on Unix platforms will attempt to increase their open file

limit. If a server is able to increase its open file limit, a line similar to the following will appear in

the debug log when the server first starts up:

mm/dd hh:mm (isvname) File descriptor limit increased from 256 to 65536

If you do not wish the ISV server to unlimit it's open descriptor limit, set the

RLM_NO_UNLIMIT environment variable in the process where you run the server:

% setenv RLM_NO_UNLIMIT anything

How Licenses are Pooled by the ISV Server

When the ISV server processes all its licenses in the license file, it combines as many as possible

into single pools of licenses. In order for 2 licenses to be combined into a single license pool, the

following license fields must match exactly:

• Product Name

• Product Version

• License Sharing specification

• License Timezone specification

• License Platform list

• Both licenses must be counted or uncounted

• License node-locked hostid

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

RLM License Administration Manual Page 17 of 139

• Neither license can be a named-user license

• License password

• License id (also, an id of 0 will pool with any prior license with non-zero id)

Once pooled, the following fields are processed as shown:

Field Result

count both counts added together

exp-date earlier date is remembered

hold maximum of the 2 values

max_roam minimum of the 2 values

min_checkout maximum of the 2 values

min_timeout maximum of the 2 values

soft_limit both soft_limit values added together

contract if original is empty, use new

customer if original is empty, use new

issuer if original is empty, use new

type if original is empty, use new

For all other fields, the field in the original license (i.e., the first to appear in the license file) is

used. Note that different named_user licenses are never combined into one license pool.

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

License Server Administration

There are various administration commands that can be used to cause the license servers to reread

their license files, to remove licenses from certain users, etc. For a description of these

administration commands, see License Administration Tools on page 40. In addition, options can

be specified for each ISV server in The ISV Options File. You can restrict access to administration

commands via The RLM Options File.

Client timeouts connecting to the server

There are 2 different timeouts that clients can experience when talking to license servers:

CONNECT timeouts and READ/WRITE communication timeouts.

By default, the CONNECT timeout is set to 10 seconds. To change this, set the environment

variable RLM_CONNECT_TIMEOUT to a positive integer, e.g.:

% setenv RLM_CONNECT_TIMEOUT 5

to set the connect timeout to 5 seconds.

The read/write timeout is set to 5 seconds by default. To change this, set the environment variable

RLM_COMM_TIMEOUT to 1000 times the timeout desired, e.g.:

% setenv RLM_COMM_TIMEOUT 10000

to set the comm timeout to 10 seconds.

RLM License Administration Manual Page 18 of 139

A note on server lock files

On occasion, when you start the RLM servers, you will see messages similar to these in the debug

log:

08/08 16:11 (reprise) Cannot set server lock - exiting

08/08 16:11 (reprise) This usually means another copy of "reprise" is running

08/08 16:11 (rlm)

08/08 16:11 (rlm) reprise initialization error: 8, not restarting

08/08 16:11 (rlm)

08/08 16:11 (rlm) reprise - lockfile problems

08/08 16:11 (rlm) This usually means another "reprise" server is running

This happens if another copy of the ISV server is running. Check to make sure that another copy

is not running.

This can also happen if the lockfile directory is not writable by the user who started the server.

Ensure that the lockfile directory is writable by the user who starts the server. The "rlm directory"

is:

/var/tmp on unix/mac, or

ProgramData\Reprise (vista and later) or

Docs and Settings\All Users\Application Data\Reprise (pre-vista).

The server's lock file name is rlmlock<isv> on windows, and .rlmlock<isv> on Linux, where

<isv> is the ISV name. If you have lockfile problems on Linux which can't be attributed to another

copy of the server running, then check the protection on /var/tmp to make sure it allows world

rwx. On Windows, what sometimes happens when the first version of the RLM server to run on a

system is pre-v9.4, is that the lock file is created with restrictive permissions that don't allow a

different user to lock it. 9.4 and later create the Reprise folder with wide-open access that is

inherited by files created in it, so this problem doesn't occur. Deleting the lock file is OK to solve

the immediate problem.

Table of Contents

RLM License Administration Manual Page 19 of 139

The License File

The license file contains information which configures the license servers and describes all the

licenses granted from the ISV to their customer. License Files have 3 types of lines:

1. HOST Lines that specify the license server host

2. ISV Lines which specify the ISV's license server information, and

3. LICENSE Lines which describe license grants from the ISV to the customer.

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

License Environment.

Note: the license file cannot be placed in a path where any component of the pathname contains

the '@' character.

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.

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.

Legal characters in the license file

In general, all license file fields are white-space delimited, meaning that no data item can contain

embedded spaces, tabs, newlines or carriage returns. In addition, the following four characters are

illegal in data items in the license (and options) file except as noted below: "<", ">", "&", and

double quote ("). Note: single quote (') and back-quote (`) were illegal prior to RLM v8.0. ISV

license names cannot begin with the characters "rlm_". As of RLM v12.1, the characters "<", ">",

and "&" are legal in comments (lines beginning with "#"). As of RLM v12.2, “<”, “>”, “&”, single

quote (') and back quote (`) are legal characters in the customer field.

Note that all lines in option files (RLM or ISV) as well as license files must be shorter than 1024

characters. Anything over 1024 characters will be truncated.

Everything in the license file is case-insensitive, with the following three exceptions:

• isv-binary-pathname on ISV lines [Note: case-sensitive on Unix systems only]

• options-file-filename on ISV lines [Note: case-sensitive on Unix systems only]

• short (~62-character) license keys (keys with bits/character of 6)

Note: any time RLM processes a username, it will replace any white space in the name with the

underscore '_' character. This is true for usernames used as hostids, in server option files, or passed

between client and server.

The 4 types of license lines (HOST, ISV, LICENSE, and UPGRADE) are described below.

RLM License Administration Manual Page 20 of 139

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, so you can change it at any time without affecting your licenses.

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 is

not an input to the license key signature algorithm, so it can be changed to any available port.

For a description of the various hostids that RLM supports, see RLM hostids on page 118.

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" – they are 100% equivalent.

ISV line

Format (pre-RLM v9.0):

ISV isvname [isv-binary-pathname [options-file-filename [port-number]]]

Format (RLM v9.0+):

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

binary-pathname] [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.

The isvname is the name assigned by Reprise Software to the ISV and does not change.

RLM License Administration Manual Page 21 of 139

Beginning in RLM v6.0, the ISV server can be delivered as either an executable (as in all older

versions of RLM) or as a small, platform-independent ISV server settings file (named isvname.set

by default).

The isv-binary-pathname is the filesystem location of the ISVs license server binary. This can be

any accessible location. The isv-binary-pathname is not an input to the license key signature

algorithm, so you can change it to relocate the ISV server at any time. Starting in RLM v3.0, the

ISV pathname can be omitted if the isv server is located in the same directory as the rlm binary. If

omitted, RLM will first attempt to open an ISV server settings file (isvname.set), and if that fails,

will attempt to open a license server binary (isvname.exe on windows, or isvname on unix).

The third (optional) parameter specifies whether an options file is to be used for this license server.

If you would like to specify options (see The ISV Options File on page 69), either specify the

location of the file containing these options here, or name the ISV options file isvname.opt and

place it in the directory which contains the license file which the server reads.

The fourth (optional) parameter specifies the port # which the ISV server will use. This should

normally be omitted but can be used if you need to access the ISV server across a firewall and the

firewall needs to be configured to allow access to the port. Note that you must specify an options

file if you want to specify an ISV server port number.

The fifth (optional) parameter (new in RLM v9.2) specifies a license password to be applied to all

LICENSE or FEATURE lines which follow the ISV line in the license file. If an individual

LICENSE line has a password, the password from the LICENSE line is used.

In the old format, the parameters are strictly positional, and, for example, to specify a port #, the

ISV server binary and options file must both be specified. However, in the new format, 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 that, in the new format, 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:

ISV reprise /home/reprise/reprise /home/reprise/reprise.opt (old format)

ISV reprise options=/home/reprise/reprise.opt binary=/home/reprise/reprise (new format)

ISV reprise /home/reprise/reprise port=8765 (new format)

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

In these examples, the license server for ISV reprise is located at /home/reprise/reprise and (in the

first 2 examples) an options file is located at /home/reprise/reprise.opt. In the 3rd example an ISV

server port # is specified. In the fourth example, the ISV server binary name /a/b/reprise will be

used instead of /home/reprise/reprise.

RLM License Administration Manual Page 22 of 139

Note: The keyword "VENDOR" can be used instead of "ISV" – it is 100% equivalent.

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 except for optional parameters whose keywords begin with

the underscore ('_') character.

Types of Licenses

While there is a single format for the LICENSE line, the licenses you receive from

your software suppliers can have many different meanings. The following licensing

attributes are present in all licenses, and define the major meaning of the license

itself:

• Locking: Node-locked (counted or uncounted), Username-locked (counted

or uncounted), or Floating licenses.

RLM can lock a license in a variety of ways:

1. A license can be node-locked. 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 hostids on page 118.

• 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 that single

licenses are checked locally to ensure that only one instance is running.)

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

license line. See the description of the LICENSE line for more information.

2. 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 that any white space in a

username is converted to the underscore ('_') character.

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

• Expiration: Expiring or non-expiring licenses

All licenses have an expiration date. If the license uses the special expiration date of

RLM License Administration Manual Page 23 of 139

permanent, they never expire (any date with a year of 0 is also non-expiring, e.g. 1-

jan-0).

• Version: By version number or by product release date.

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:

* Your ISV could make all your software request version 1.0 with all your licenses

issued for version 1.0, and the version would never be an issue, unless and until they

wanted to obsolete all the old licenses on a new release.

* Or, your ISV could put the product's version number in the rlm_checkout() call,

then licenses for an older version of the product will not work with a newer version of

the product.

* Or, your ISV can use a date-based version. To do this, they might put the year of

release into the rlm_checkout() call, then when you issue licenses, issue them either

for this year, or some year in the future. This allows you, the customer, to use

products released on or before the year in the license. Alternately, the ISV could make

the version be "year.month".

• License Count: Each license has a count of available licenses. If this count

is "0" or "uncounted", the license count is not enforced. Otherwise, only the specified

number of license checkouts are allowed.

Fixed (positional) parameters

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

isv

isv is the name of the ISV granting the rights.

product

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

version

version is the highest-numbered product version supported by this license, in the form "N.M". For

example, 1.0, 2.37, or 2006.12

RLM License Administration Manual Page 24 of 139

exp-date

exp-date is the date the license expires, in the form dd-mmm-yyyy, for example, 1-jul-2007. Any

license with either a year of "0" (ie, "1-jan-0"), or the word "permanent" does not expire.

count

count is the number of licenses granted. 0 or uncounted means an uncounted, node-locked

license. uncounted and 0 are 100% equivalent.

single means a node-locked, single-use license. single 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 for your Software

Provider to issue you a single-use license without you, the License Administrator, having to

configure a license server.

token, token_locked, and token_unlocked are used to specify a Token-Based License; this

license must also have the token=... optional parameter (see Token-Based Licenses on page 84).

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

other optional parameters are ignored.

license-key

license-key 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 that if the license-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 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. akey= first appeared in RLM v11.0.

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.

RLM License Administration Manual Page 25 of 139

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"

disable= first appeared in RLM v4.0, with the single environment TerminalServer. VM was added in RLM

v5.0.

_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. See Failover License Servers on page 92

for more information. This field has no meaning on any license other than an “rlm_failover” or

“rlm_failover_server” license. If the license is an “rlm_failover_server” license, the hostname

must be a port@host specification prior to RLM v12.2. After v12.2, if the hostname is used alone,

the default port (5053) is used.

hold=n

hold specifies that a license is to be "held" checked-out by the license server after the application

performs a check-in call or exits. The license will remain checked-out for the number of seconds n

specified after application check-in 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 on page 28.

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. (For a description of the various hostids that RLM supports, see RLM hostids on page

118.

Starting in RLM v5.0, 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

RLM License Administration Manual Page 26 of 139

characters.

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

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

License ID

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

Licenses will pool only if their ID #s match (assuming all the other attributes make them

eligible to pool.) For the sake of matching ID numbers, a license with no ID matches

licenses with an ID of 0.

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, 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 2 licenses are pooled,

their max_roam_count values are added. Finally, you can lower this value by using the

RLM License Administration Manual Page 27 of 139

ROAM_MAX_COUNT option, however ROAM_MAX_COUNT will never raise this value.

max_roam_count is new in RLM v8.0.

min_checkout=n

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 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 on page 26.

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:

min_checkout=400

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.

NOTE: The license server scans all held licenses once per minute, so the exact time of check-in

can be rounded up to the next 60 seconds. So, in example 3 above, the check-in could happen any

time between 100 seconds and 120 seconds after the rlm_checkin() call.

NOTE: The minimum checkout time specification will be ignored for any license which is

roaming.

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 that min_remove is processed by the license server, so it has no effect on unserved

nodelocked licenses.

min_timeout=n

RLM License Administration Manual Page 28 of 139

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 check-in 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 nodelocked, 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.

Beginning in RLM v9.2, 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.

RLM License Administration Manual Page 29 of 139

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:

Platform RLM Platform name string in platforms=

HP-UX on PA-Risc hp_h1 hp_h

HP-UX 64-bit on PA-Risc hp64_h1 hp64_h

IBM AIX 32-bit ibm_a1 ibm_a

IBM AIX 64-bit ibm64_a1 ibm64_a

Linux on Intel X86 x86_l2 x86_l

Linux 64-bit on Intel x64_l1 x64_l

MAC on Intel X86 x86_m1 x86_m

MAC on PPC ppc_m1 ppc_m

Solaris 64-bit on Intel x64_s1 x64_s

Solaris on Sparc sun_s1 sun_s

Solaris (64-bit) on Sparc sun64_s1 sun64_s

Windows on Intel X86 x86_w2, x86_w3, x86_w4 x86_w

Windows 64-bit on Intel X86 x64_w2, x64_w3, x64_w4 x64_w

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 been issued to you, the ISV

uses the replace[=product-list] option in the new license. replace= causes RLM to ignore the

"replaced" license(s).

Note: If your ISV uses replace, they must also have specified either start= or issued=.

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

RLM License Administration Manual Page 30 of 139

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

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

RLM License Administration Manual Page 31 of 139

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

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

token= specifies the list of products which are checked out when a token-based license is

requested. See Token-Based Licenses on page 84 for a complete description.

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. _line_item first appeared in RLM v3.0.

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"

RLM License Administration Manual Page 32 of 139

• "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:

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, in the form dd-mmm-yyyy 11 characters

count positive integer 2**31 - 1

hold positive integer - seconds 2*31 - 1

host_based int count of licenses which must be reserved

hostid (single) string 72 characters

hostid (list) space-separated, quoted string 200 characters, max of 25 hostids

issued string, in the form dd-mmm-yyyy 11 characters

_line_item

string, License Administrator

defined

64 characters

max_roam positive integer - days 2**31 - 1

max_roam_count positive integer - count 2**31 - 1

min_checkout positive integer - seconds 2*31 - 1

min_remove

integer - seconds (-1 for no remove

available)

2**31

min_timeout positive integer - seconds 2**31 - 1

password string 32 characters

platforms string 80 characters

share enumerated 3 ("uhi") + :integer

soft_limit integer 2**31 - 2

start string of the form dd-mmm-yyyy 11 characters

timezone int bitmap with bits 0-23 set

user_based int count of licenses which must be reserved

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" and/or "beta"

14 characters

Examples:

LICENSE reprise write 1.0 permanent uncounted 987435978345973457349875397345

hostid=IP=172.16.7.3

RLM License Administration Manual Page 33 of 139

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, subject to the rules for combining licenses listed in How Licenses are

Pooled by the ISV Server on page 17.

UPGRADE line

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 except for 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 that 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, or the license will be ineligible 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 licenses are not eligible for upgrades.

In order for a license to be upgraded, the base license and the upgrade license must be eligible to

be pooled by the license server as described in How Licenses are Pooled by the ISV Server on

page 17.

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.

RLM License Administration Manual Page 34 of 139

Note that 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.

Note that the 3rd case above is the most useful - if your ISV wanted to upgrade 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, ie, 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:

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 -

max_roam_count 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 (count-user_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.

RLM License Administration Manual Page 35 of 139

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. Note that these are the same as the 6 fixed parameters of the LICENSE line, with the

version replaced by a pair of versions:

isv

isv is the name of the ISV granting the rights.

product

product is the name of the product for which license rights are being upgraded.

from-version

from-version is the lowest-numbered product version which is eligible for an upgrade, in

the form "vN.M". For example, 1.0, 2.37, or 2006.12

to-version

to-version is the highest-numbered product version supported by the license once it is

upgraded, in the form "vN.M". For example, 1.0, 2.37, or 2006.12

exp-date

exp-date is 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" (ie, "1-jan-0"), or

simply the word "permanent".

count

count is 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 the LICENSE line on page 23 for more information.

token, token_locked, and token_unlocked are not allowed in an UPGRADE license. All

other optional parameters are ignored.

upgrade-key

upgrade-key is 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 that if the upgrade-key is preceded by sig=, it can be present after any or all of the

optional parameters.

Optional Parameters

RLM License Administration Manual Page 36 of 139

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 the License Line for information on the optional parameters.

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 is your ISV-assigned Customer name

isvname is your ISV's name

server-name is the fully qualified hostname of the RLM Cloud license server machine

port# is either 5053 for normal RLM communications, or for HTTPS transport, 443).

yourpw is your assigned password for this server

Note that HTTPS support is new in RLM v14.0 and 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

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:

RLM License Administration Manual Page 37 of 139

license_spec1

license_spec1:license_spec2:license_spec3: .... :license_specN (UNIX)

license_spec1;license_spec2;license_spec3; .... ;license_specN (Windows)

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 -

Note that the separator character is ':' for Unix systems and ';' for Windows systems.

Also note that 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

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

% 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

RLM License Administration Manual Page 38 of 139

Note: The ability to specify the license directly was added in RLM v3.0.

Note: The ability to add a directory to the RLM_LICENSE environment variable was added in

RLM v6.0

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.

Table of Contents

RLM License Administration Manual Page 39 of 139

License Administration Tools

The rlm server is delivered with an embedded Web Server to perform normal administration tasks.

For more information on the web server interface, see The RLM Web Server on page 49.

In addition, the RLM kit is delivered with several command-line administration tools to perform

various administration tasks on the license servers as well as to retrieve information about

licensing parameters. While the RLM web interface is the preferred method to administer RLM

license servers, the command-line tools are provided as a convenience for use in administration

scripts and programs. License Administrators can manage rlm by using the administration tools, as

described in detail below: rlmadduser, rlmanon, rlmdebug, rlmdown, rlmhostid, rlmnewlog,

rlmremove, rlmreread, rlmstat, rlmswitch, and rlmswitchr. On UNIX platforms, rlmutil is an all-in-

one utility which is installed with hard links to all the utility program names. On windows,

separate .exe files are provided for each utility.

RLM has the ability to restrict usage of the remove, reread, shutdown, status and option editing

requests. All restrictions are done via The RLM Options File. For a description of how to restrict

command usage, see The RLM Options File on page 63. In addition, starting in RLM v13.0, ISV

servers can authenticate requests from clients. See Client Authentication in the next chapter on

page 48 for more information.

All utilities take the following options:

option meaning

-c

license_spec

use 'license_spec' instead of the current directory to find license files.

'license_spec' can be either a license file or a port@host specification. Note

that prior to RLM v4.0 the RLM_LICENSE environment variable takes

precedence over a -c license_spec specification. Starting in RLM v4.0, the -c

option overrides RLM_LICENSE.

-dat use *.dat as the license file instead of *.lic (new in rlm v3.0)

-h print usage information and exit

-q

don't prompt/quiet (for rlmdown/rlmremove/rlmswitch/rlmhostid). -q also

turns off the verification of license checksums and corresponding error

messages for all commands.

-v print version number and exit

-z password

use password as license password for command (enclose in quotes if password

contains white space (new in RLM v9.4)

rlmadduser – add a user to the ISV server options file.

Usage: rlmadduser options-filename username password

This command adds the specified username/password pair to the end of the options-file specified.

Note:

▪ Usernames and passwords must be <= 10 characters long

▪ Usernames and passwords are CASE SENSITIVE

RLM License Administration Manual Page 40 of 139

▪ Usernames and passwords cannot contain white space or any of the following characters:

"<", ">", "&", “:”, and single (''' or '`') or double-quotes (")

▪ If there are no USER records in the ISV server options file, the server does no

authentication of clients.

rlmadduser is new in RLM v13.0. All components must be RLM v13.0 or later for this

functionality to work. This functionality is not supported for HTTPS communications in RLM

Cloud.

rlmanon - change user and host names in report log file

Usage: rlmanon logfile

rlmanon reads the report log file logfile, and changes all the user and host names to the form

uNNN and hNNN, where NNN is a sequence number. The result is written into the file

logfile.anon.

There is a one-to-one mapping from a particular user or host name to its corresponding sequence

number, so that reports generated from the log file will accurately reflect the number of unique

users and hosts as well as the sharing of licenses. However, actual user and host information is

removed from the output logfile.anon.

rlmanon creates a new authenticated report log file if the input log file is an unmodified

authenticated log file. If the input file has incorrect authentication records, an error message is

generated, and no output file is written.

rlmanon first appeared in RLM v4.0.

rlmdebug - display debugging information about products

Usage: rlmdebug [product]

rlmdebug prints information about the specified product (or all products if product is not

specified). The debugging information is written to stdout (this requires running in a command

window on Windows systems).

This capability is also built into every RLM v9.0 (or later) application. To use the debugging

information directly from the application, set the RLM_DEBUG environment variable to the

product name (or to an empty string if you wish to debug all products). (Note: you do not need to

use the RLM_DEBUG environment variable with the rlmdebug utility.)

Sample rlmdebug output:

% setenv RLM_DEBUG

When the application is run the following (sample) output is displayed (in addition to any other

output the application may produce):

RLM DEBUG for all products

RLM License Administration Manual Page 41 of 139

In license file: ../rlm/z.lic (5555@paradise):

Product: test1, ISV: reprise, Floating

Product: test2, ISV: reprise, Floating

Product: test3, ISV: reprise, Floating

Product: rlm_roam, ISV: reprise, Uncounted

Product: testr1, ISV: reprise, Floating

Product: testr2, ISV: reprise, Floating

Checking server machine "paradise" ... server UP

Checking RLM server at port 5555 ... server UP

In license file: a.lic:

Product: test, ISV: reprise, Single

8 product instances found

rlmdown - shuts down the license server

Usage: rlmdown [-q] [isv] [-c license_file]

rlmdown shuts down the first license server in the license path RLM_LICENSE. If the -q option is

specified, the shutdown happens without a confirmation prompt. If the optional isv is specified,

only that ISV's server is shut down.

In order to shut down the RLM server itself, specify the isv name as RLM. (Note: RLM must be

in capital letters).

Note that (on Unix systems only) the servers can also be shut down by sending a SIGTERM signal

to the RLM process. SIGTERM shuts down all the servers, including rlm.

rlmhostid - print the hostid of this machine

rlmhostid prints the hostid of the machine it is running on. If the -q flag is specified, the

hostid is printed without any other output.

Hostid types described in RLM hostids on page 118.

Note: Beginning in RLM v4.0, if the rlmhostid command prints "(Virtual: some text)"

after the hostid, this means that the command is run on a virtual system which is not

supported for running an RLM license server. In the case of Solaris systems, license

servers can only be run on zone 0 (the "Global" zone).

rlmnewlog - moves the old report log info to a new file

Usage: rlmnewlog isv new-log-file-name

rlmnewlog causes the ISV server isv to move the current reportlog output to new-log-file-name

and continue logging to the original filename.

RLM License Administration Manual Page 42 of 139

Note that the new-log-file-name must be on the same filesystem as the original reportlog,

otherwise the command will fail. The ISV server renames the old reportlog, it does not copy the

data. rlmnewlog will fail if the server is not currently writing a report log.

rlmremove - remove a checked-out license from a user

Usage: rlmremove [-q] server-host port isv handle

rlmremove removes a checked-out license. If the -q option is specified, the license is removed

without a confirming prompt. server-host, port, and handle are indicated in the rlmstat output.

In the following example rlmstat output, the server-host is melody, the port is 1215, and the

handle is 809f418 and the isv is reprise:

reprise license usage status on melody (port 1215)

test3 v1.000: tom@sun1(v1.0) (809f418) 1/0 at 02/06 09:59

rlmreread - Cause the license server(s) to reread their license and option

file(s)

Usage: rlmreread [isv]

rlmreread causes the specified ISV server isv to reread its license file, and options file if specified

in the license file (or if in the default location isv.opt). If isv is omitted, the reread command is sent

to RLM and all ISV servers. If isv is specified as rlm, then only the RLM server rereads its license

file.

When rlm rereads its license file, it starts any new ISV servers that were not present before.

Note that rlm performs an automatic reread of the license file(s) every night at midnight.

Note also that (on Unix systems only) the servers will do a reread if a SIGHUP signal is sent to the

rlm process.

rlmstat - obtains status from the license servers

Usage: rlmstat [-a] [-f] [-i [isv] ] -I [-l [ isv] ] [-n [host] ] [-p [product] ] [-u [user] ] [-z password]

rlmstat retrieves status from the license servers and prints it. Control over the status retrieved

from rlmstat is specified as follows:

option parameter (meaning if present) result

-a (no parameters) Print all status from rlm and all ISV servers

-avail [-i isv] [-p product] -b Reports free license availability (see below)

-f “full” license listing

Reports more information about the

licenses in use.

RLM License Administration Manual Page 43 of 139

-i display this isv only Display license checkout info from ISVs

-I Display isv-defined checkout data “[I: isv-data]” appended to each user line

- l display this isv only Display license pooling info from ISVs

-n display licenses from this host only Display license checkout info from ISVs

-p display licenses for this product only Display license checkout info from ISVs

-u display licenses from this user only Display license checkout info from ISVs

-z license password Supplies password to license server

Example rlmstat output

% rlmstat -a

rlmstat v9.1

rlm status on bigserver (port 5053), up 00:03:51

rlm software version v9.1 (build:3)

rlm comm version: v1.1

Startup time: Wed Jul 6 13:27:42 2011

Todays Statistics (00:03:50), init time: Wed Jul 6 13:27:43 2011

Recent Statistics (00:03:50), init time: Wed Jul 6 13:27:43 2011

Recent Stats Todays Stats Total Stats

00:03:50 00:03:50 00:03:51

Messages: 9 (0/sec) 9 (0/sec) 9 (0/sec)

Connections: 7 (0/sec) 7 (0/sec) 7 (0/sec)

--------- ISV servers ----------

Name Port Running Restarts

reprise 62503 Yes 0

------------------------

reprise ISV server status on bigserver (port 62503), up 00:03:49

reprise software version v9.1 (build: 3)

reprise comm version: v1.1

reprise Debug log filename: <stdout>

reprise Report log filename: <stdout>

Startup time: Wed Jul 6 13:27:44 2011

Todays Statistics (00:03:49), init time: Wed Jul 6 13:27:44 2011

Recent Statistics (00:03:49), init time: Wed Jul 6 13:27:44 2011

Recent Stats Todays Stats Total Stats

00:03:49 00:03:49 00:03:49

Messages: 17 (0/sec) 17 (0/sec) 17 (0/sec)

Connections: 6 (0/sec) 6 (0/sec) 6 (0/sec)

Checkouts: 2 (0/sec) 2 (0/sec) 2 (0/sec)

Denials: 0 (0/sec) 0 (0/sec) 0 (0/sec)

Removals: 0 (0/sec) 0 (0/sec) 0 (0/sec)

------------------------

reprise license pool status on bigserver (port 62503)

test v1.0

obsolete: 0, min_remove: 20, total checkouts: 1

test2 v1.0

obsolete: 0, min_remove: 20, total checkouts: 1

test3 v1.0

obsolete: 0, min_remove: 20, total checkouts: 0

RLM License Administration Manual Page 44 of 139

------------------------

reprise license usage status on bigserver (port 62503)

test v1.0: joe@library 1/0 at 07/06 13:27 (handle: 41)

test2 v1.0: sam@kitchen 1/0 at 07/06 13:28 (handle: 81)

In this output, the first section (before the line of dashed lines ---------) is the status of the RLM

server, the next section is the status of the ISV server reprise (there would actually be one section

of status for each ISV server if there were more than one running). Next comes the license pool

info for each ISV server (again, only one section for the reprise server), followed by the actual

license usage information.

Also, please note that the expiration date shown in this output is the expiration date of the first

license to expire out of all the licenses used to create the license pool in the license server. When

more than one license is used to create a single license pool (licenses are combined when all

relevant parameters of 2 different licenses match), then only the earliest expiration date is

shown. The other license(s) may have any expiration date that has not yet expired. To determine

the expiration date of all licenses used to make up a license pool the actual license file must be

consulted. Also note that licenses from different license files could be combined to make a single

license pool.

Beginning in RLM v14.2, the first line of the product information (“test v1.0” in the example

above), will contain the server's license pool #, and an ID, if specified. So rather than

test v1.0

it will be something like this:

test v1.0, pool: 7, id: 60

The meaning of the license usage line:

test v1.0: joe@library 1/0 at 07/06 13:27 (handle: 41)

is as follows:

test is the product name

v1.0 is the license version (from the license file) for test

joe is the user who is using the license

library is the host on which tom is using the license

(41) is the license handle in the server. This handle is used by the rlmremove command.

1/0 indicates that 1 unreserved and 0 reserved licenses are in use

at 07/06 13:28 is the time the licenses were checked out

and if the optional “-I” switch is specified, the following will be appended to the line, if there is

any isv-defined checkout data:

[I: isv-data]

where “isv_data” is the isv-defined checkout data.

If the -f option is used with rlmstat, additional information about the license usage will be

displayed. -f is available in RLM v12.5, and in v12.5, the additional information displayed is the

requested version, displayed as such:

test v1.0 (req: v0.8): joe@library 1/0 at 07/06 13:27 (handle: 41)

RLM License Administration Manual Page 45 of 139

rlmstat -avail command

The rlmstat -avail command reports on license availability for a specified license, a specified ISV,

or all licenses from all ISVs.

Usage:

rlmstat -avail [-i isv] [-p product] [-b]

If -i isv is specified, only licenses from the selected isv are displayed.

If -p product is specified, only the selected product is displayed.

If -b is specified, license availability is combined across license servers.

Note that if you are looking for the availability of a license from a particular ISV, it is more

efficient to specify the ISV name in the command. If you do not specify the ISV name, rlmstat

must contact the RLM server to request a list of ISV servers, then request information from each

ISV server. If you specify the ISV, then only that ISV server is contacted.

Note also that there are situations when you may not be able to check out a license that is listed as

available. This can happen if, for example, you are on the EXCLUDE list for a particular product,

not on the INCLUDE list, already exceeded your MAX usage, etc.

Also note that you might be able to check out one that is listed as not available. This could happen

if that license is shared and you can share an existing checked-out license, or if one of the

reservations for the license is for you (rlmstat -avail lists free available licenses; reservations are

not generally available).

Example rlmstat -avail output

% rlmstat -avail -i reprise

rlmstat v9.1

License availability for all products from ISV "reprise"

server host: telecard (port 5053)

test1 v1.000 available: 15

test1 v1.000 hostid: a8c00301 available: 10

test5 v3.000 hostid: a8c00301 available: 2

test5 v3.000 available: 10

test v1.000 available: 10

server host: spinout (port 5053)

test1 v1.000 available: 15

test1 v1.000 hostid: a8c00301 available: 10

test5 v4.000 hostid: ip=172.16.7.28 available: unlimited

test5 v2.300 available: 15

test5 v3.000 hostid: a8c00301 available: unlimited

test5 v3.000 available: 73

Example rlmstat -avail -b output (same situation as above)

% rlmstat -avail -i reprise -b

rlmstat v9.1

RLM License Administration Manual Page 46 of 139

License availability for all products from ISV "reprise"

ISV: reprise

test1 v1.000 available: 30

test1 v1.000 hostid: a8c00301 available: 20

test5 v3.000 hostid: a8c00301 available: unlimited

test5 v3.000 available: 83

test5 v4.000 hostid: ip=172.16.7.28 available: unlimited

test5 v2.300 available: 15

rlmswitch - switches the debug log info to a new file

Usage: rlmswitch [isv] new-log-file-name

rlmswitch causes the server isv to close the current debug log file and begin output to new-log-file-

name. If isv is not specified, or if specified as rlm, the RLM server's debug log is switched.

rlmswitchr - switches the report log info to a new file

Usage: rlmswitchr isv new-log-file-name

rlmswitchr causes the ISV server isv to close the current reportlog file and begin output to new-

log-file-name.

Beginning in RLM v9.1, rlmswitchr will fail if the server is not currently writing a report log.

Table of Contents

RLM License Administration Manual Page 47 of 139

Client Authentication

Beginning in RLM v13.0, ISV servers are able to authenticate clients before doing any processing

on their requests. This ability is entirely under your control, based on information in the ISV

server options file. If there are any USER records in the options file, the server will authenticate

all requests (including checkouts, status, reread, shutdown, etc.). Note that this functionality is

available only with RLM native comms, not with HTTPS communications.

Turning on Authentication

In order to turn on authentication, you must create one or more USER records in the ISV server's

options file. This is done with the new rlmadduser utility (or “rlmutil rlmadduser”).

To add a user, run:

% rlmadduser options-file-name username password

This command adds the specified username/password pair to the end of the options-file specified.

Some notes:

• Usernames and passwords must be <= 10 characters long

• Usernames and passwords are CASE SENSITIVE

• Usernames and passwords cannot contain white space or any of the following characters:

"<", ">", "&", “:”, and single (''' or '`') or double quotes (")

• If there are no USER records in the ISV server options file, the server does no

authentication of clients.

Passing authentication to the Server

In order to pass the authentication data to the license server, set the environment variable

RLMAUTH to “username:password”. The data will be passed on any client request to the server.

Note that this capability requires an RLM v13.0-linked client as well as v13.0 license servers.

Server Processing

If the ISV server encounters any valid USER records in its options file, authentication is

automatically turned on. If the same username is encountered twice in the options file, the

password from the last entry will be used. All components must be RLM v13.0 or greater, both

servers and applications.

If you use authentication on more than one ISV server, you will probably find it useful to have a

single administration user to do shutdowns and rereads.

Table of Contents

RLM License Administration Manual Page 48 of 139

The RLM Web Server

The RLM server contains an embedded Web Server which can be used to perform most

administration of the RLM server itself. The web server contains the functionality of all the

rlmutil-based utilities except rlmhostid. The web server allows you to retrieve server and license

status (similar to rlmstat), cause the servers to re-read the license files (rlmreread), switch debug

(rlmswitch) or report log (rlmswitchr) files, move the current report log file to a new name

(rlmnewlog), or shut down the license servers (rlmdown). Using this web-based interface, you can

administer the license servers from any platform, and you do not need to install the RLM utilities -

you only need a web browser.

Note: Beginning in RLM v15.1, HTTPS can now be enabled in the Web Server via startup options.

See the following section for more details.

In addition, the web server allows you to edit server option files (if you have access to the

edit_options capability - for ISV servers, or the edit_rlm_options capability - for RLM itself.)

Also, the web interface allows you to view the recent debug log information from any of the

servers if you have access to the status capability. Finally, access to the status, reread, and

shutdown commands is controlled by the appropriate capability as specified in The RLM Options

File on page 63 (or by the login credentials for RLM v10.0 or newer servers, see Access Control

to the RLM Web Interface on the following page).

The web server is started automatically on port 5054 when RLM is started. To use the web server,

simply point your browser to: http://ServerHostName:5054 and select the operation you would

like to perform. You will be prompted for any required information. (Note: RLM ran the web

server on port 9000 prior to v6.0).

If you would like to run the web server on a different port, specify the -ws NNNNN command-line

argument when starting RLM, where NNNNN is the desired port.

The RLM web server is 100% self-contained in the RLM binary; no additional html files are

required for operation.

In RLM v14.1, RLM v14.2 and RLM v15.0 the web server is disabled if the user running RLM is

root or an admin user.

The remaining sections will describe some of the main functions of the web interface.

Enabling HTTPS in the RLM Web Server

To enable HTTPS in the web server you should use the two new startup options, -sslcert and

-sslpriv to point to your SSL certificate and SSL private key. E.g.:

% ./rlm -sslcert /path/to/cert.pem -sslpriv /path/to/privkey.pem

Now you can access your web server by typing https://your-server-host:5054 (be sure to include

the https:// if you are not automatically redirecting the url via other means).

If you are running your server as root/administrator, it is possible to set your web server to run on

port 443 (the default HTTPS port) by running the following:

% ./rlm -sslcert /path/to/cert.pem -sslpriv /path/to/privkey.pem -ws 443

RLM License Administration Manual Page 49 of 139

While running on port 443 and pointing at valid SSL certificate and private key, your browser

should automatically redirect to https:// without needing to type it explicitly. i.e., typing your-

server-host/ should take you to https://your-server-host:443.

Note: If you prefer to generate your own self-signed certificates, your traffic to the web server will

still be encrypted, but your browser will likely display a warning before you can get to the web

server. Self-signed certificates can not be generated with a password to use the web server.

Access Control to the RLM Web Interface

Beginning in RLM v10.0, it is possible to require users to log in to the RLM Web Interface.

The login capability is provided via the RLM password file, named rlm.pw. Beginning in RLM

v15.1, if this file doesn’t exist, RLM will create it automatically at startup with a default

admin:admin:all account. Reprise Software recommends that you protect access to this file so that

ordinary users can't write it. The RLM password file, as well as the directory which contains it,

must be read-write to the RLM process.

The RLM password file has one line for each user, formatted as follows:

username:password:list-of-permissions

The username must not contain a ':' character.

If the password field is blank, then the user can log in without supplying a password. When adding

new users, you must set a password within 10 minutes or the server will automatically shut down

if it is running. To change their password, select the "Change Password" menu item once logged in

as that user. The password field is an encrypted hash of the actual password (similar to the Unix

password file).

The list-of-permissions field is a comma-separated list of the various privileges which you can

assign to this user. These names are the same names you would use in the RLM options file if you

were controlling access without logins enabled, with the addition of the special "all" permission,

which enables all operations. If you use the RLM password file to control access, you should not

use the RLM options file to control access.

Beginning in rlm v10.0, you can control the appearance and defaults of the “Activate License”

command with the rlm “-activate” options in the rlm options file.

Beginning in rlm v12.4, if there is no password file present, the edit options and edit rlm options

commands are disabled.

The “Activate License” button in the left-hand menu is controlled by the edit_options privilege

starting in RLM v13.0

Beginning in RLM v14.2, if there are users in the rlm.pw file with blank passwords, rlm will log

this condition and exit after 10 minutes unless started with the -z switch.

Also beginning in RLM v14.2, there is a limit of 20 simultaneously logged in users to the web

interface.

Beginning in RLM v15.1, you are required to be logged in to the web server to use its

functionality.

Also beginning in RLM v15.1, all users are required to have passwords to avoid automatic

shutdown in 10 minutes. The -z switch has been removed.

RLM License Administration Manual Page 50 of 139

RLM privileges assignable in the RLM password file

Privilege Meaning Notes

all Special privilege name, enables all privileges

edit_meter Allows modifying count for meter counters

Enables "status" privilege even

if not present

edit_options

Allows editing options files for ISV servers, the

“Activate” button in the ISV server status line and

the “Activate License” button in the left menu.

Enables "status" privilege even

if not present. Enables

diagnostics.

edit_rlm_options

Allows editing license files and options files for

the rlm server,

Enables "status" privilege even

if not present. Enables

diagnostics

edit_xfer

Allows editing server-server license transfer

settings for ISV servers

Enables "status" privilege even

if not present

extend_roam

Allows this user to extend roam duration for

already-roaming licenses.

logfiles

Enables the functions which change log files -

switch, switchr, newlog.

Enables diagnostics.

remove

Allows the user to remove a license from a

running process

Enables "status" privilege even

if not present

reread

Allows access to the functions which do reread

commands on license servers

shutdown

Allows access to the functions which shut down

license servers

Enables "status" privilege even

if not present

status

Allows display of status and debug log

information from the license servers

A user with no privileges assigned will have access to the "Test License Activation", "RLM

Manual...", "About…", "Change Password", and "Logout" commands.

A couple of example password line entries shown here:

tom:$5ukMApW1jixwcrGqRALO91:all

harry::edit_options,edit_rlm_options,reread

User "tom" has a password assigned and can perform all actions with the web interface.

User "harry" has no password (they should set their password on first login), and has the edit

options, edit rlm options, and reread privileges assigned. He will also be able to view status.

Adding New Users

Beginning in RLM v15.1, a default user with the username admin and password admin is created

if rlm.pw does not already exist.

To add a new user:

1. Open rlm.pw (located in the RLM binary directory)

RLM License Administration Manual Page 51 of 139

2. Add a new user with a blank password and desired permissions:

johndoe::status

3. Log in to the web server as this new user and click Change Password to set a password

for the user.

NOTE: If there are any users without passwords and/or the admin password is still the

default, for longer than 10 minutes the server will shut down automatically.

Intro Screen

The intro screen of the RLM web server is shown below. There are 3 sections to the rlm web

interface:

• a top banner with the Reprise logo and title

• a command area on the lower left, and

• a general view area in the main lower-right hand side of the screen.

The top section of the view area displays some general information about rlm command options to

run the web server. On the left-hand side is a list of administration commands which will be

discussed later.

Note that, beginning in RLM v10.0, every user will not see all the commands on the left-hand side

of the menu, depending on the privileges assigned to that user in the password file or in the RLM

options file.

RLM License Administration Manual Page 52 of 139

Main Status screen

If you select Status from the menu on the left, the main status screen is displayed in the view area

as shown below.

The top section displays the host information where the rlm server is running - host name and port

Below this is the status of the RLM server itself, followed by buttons to edit rlm options and

display the last few lines of the rlm debug log.

Next is a table of ISV servers, one per line, with a number of buttons on the right-hand side of

each line to retrieve ISV server status, license status, display the last few lines of the debug log,

reread or restart the server, edit server options, or shut down the ISV server. Note that these

buttons (and the corresponding columns) will only appear if the user running the web server has

access to these functions, as specified in the rlm options file.

The status screen provides access to the shutdown and reread/restart commands for all the ISV

servers, as well as option file editing and debug log viewing for both rlm and the ISV servers.

Server Status

RLM License Administration Manual Page 53 of 139

If you click on an ISV button in the Server Status column in the ISV server status display, you will

see the detailed status display for this ISV server (shown below) in the view area. This display

shows some server statistics in a table at the top, followed by a table of all the licenses which this

ISV server is serving.

There are several columns in this table which will appear or not, depending on the particulars of

the licenses which this server is serving. For example, there are columns for hostid (in the case of

node-locked licenses), roaming (in the case where some licenses are roamed out to disconnected

systems), and named count (named user count - in the case of named user licenses). In the

example shown here, there are no node-locked licenses, and no licenses are roaming, so these 2

columns do not appear.

Also, please note that the expiration date shown in this table is the expiration date of the first

license to expire out of all the licenses used to create the license pool. When more than one license

is used to create a single license pool (licenses are combined when all relevant parameters of 2

different licenses match), then only the earliest expiration date is shown. The other license(s) may

have any expiration date that has not yet expired. To determine the expiration date of all licenses

used to make up a license pool the actual license file must be consulted. Also note that licenses

from different license files could be combined to make a single license pool.

At the far right-hand side of each license line, there are 2 columns. The first column has buttons

which, if pressed, will generate a list of users of that product. The second column has buttons

which are used to maintain the named user list for named user licenses. Note that if this server is

not serving any named user licenses, the 2nd column will not appear. Also, only named user

licenses will have edit buttons in this column. In the example below, only the first license is a

named user license.

RLM License Administration Manual Page 54 of 139

License Status

If you click on the usage... button in the "Show License Usage" column above, you will see the

license status screen,for the selected products. Clicking on the “usage...” button on the right-hand

side of the License Pool Status section will redisplay to show only license usage for the pool

selected. An example license status screen is shown below.

RLM License Administration Manual Page 55 of 139

Maintaining Named User Licenses

If you click on the edit... button in the "Edit Named User List" column above, you will see the

"Edit Named User Definitions" screen, as shown below. This form contains a table of all the

named users for this license, as well as a list of recently deleted named users. You can delete any

named user from the list by pressing the Delete button to the right-hand side of their name.

Pressing this button will present a confirmation screen, which then allows you to remove that user

from the list. Note that the user cannot be removed from the list if he/she currently has any

licenses checked out at the server (including roaming licenses).

Once deleted, a user must remain off the list for a minimum amount of time as specified in the

license.

At the bottom of this screen are 2 buttons for adding named users to the list. The first button Add

Group... brings up a form which has a choice list of all GROUP definitions from this ISV server's

options file. If you select a group to add, group members will be added to the named user list until

the list is full, or the group is exhausted.

Below the Add Group... button is an Add New User... button, which is used to add an individual

user to the named user list.

Press the Back button if you do not wish to make any changes to the named user list.

RLM License Administration Manual Page 56 of 139

Server Shutdown

If you select Shutdown from the menu on the left (or from the Shutdown column in the ISV server

status display), you will see the Shutdown License Server screen below in the view area. If you

enter an ISV name that particular ISV server will be shut down. If you leave the ISV name blank

or enter "all", all ISV servers will be shut down. Note that you cannot shut down rlm from the

shutdown screen. The shutdown will happen when you click the SHUT DOWN SERVER button.

If you do not wish to shut down any servers, use the browser back button, or select a different

command from the list on the left.

RLM License Administration Manual Page 57 of 139

Server Reread/Restart

If you select //Reread/Restart from the menu on the left (or from the REREAD/RESTART//

column in the ISV server status display), you will see the Reread/Restart Servers screen below

in the view area. If you enter an ISV name that particular ISV server will be restarted if it is not

running, or it will be sent a reread command if it is running. If you leave the ISV name blank or

enter "all", all ISV servers will be restarted or reread their license files, as appropriate. If you

select rlm, the rlm server itself will reread its license and option files. The reread/restart will

happen when you click the REREAD LICENSES button. If you do not wish to send the reread

command to any servers, use the browser back button, or select a different command from the list

on the left.

Switch ISV server Reportlog

If you select Switch Reportlog from the menu on the left, you will see the Switch Reportlog for

License Server screen below in the view area. Enter an ISV name and a new filename for the

reportlog, then that particular ISV server will begin writing its reportlog to the filename specified.

The switch command will be sent when you click the SWITCH REPORT LOG button. If you do

not wish to switch the report log, use the browser back button, or select a different command from

the list on the left.

RLM License Administration Manual Page 58 of 139

New ISV server Reportlog

If you select New Reportlog from the menu on the left, you will see the New Reportlog for

License Server screen below in the view area. Enter an ISV name and a new filename for the

reportlog, then that particular ISV server will rename the current reportlog to the filename

specified and continue logging to the original reportlog filename. The command will be sent when

you click the MOVE DATA TO NEW LOGFILE button. If you do not wish to rename the report

log, use the browser back button, or select a different command from the list on the left.

Switch Debug Log for ISV Server or rlm

RLM License Administration Manual Page 59 of 139

If you select Switch Debuglog from the menu on the left, you will see the Switch Debug Log For License

Server screen below in the view area. Enter an ISV name (or rlm) and a new filename for the debug log,

then that particular ISV server (or rlm) will begin writing its debug log to the filename specified. The

switch command will be sent when you click the SWITCH DEBUG LOG button. If you do not wish to

switch the debug log, use the browser back button, or select a different command from the list on the left.

Note that on Unix systems, all servers (rlm plus all ISV servers) initially write their debug log to the same

file (stdout of the rlm process). Once you switch any server to a different file, it is not possible to combine

the debug log output again.

RLM System Info

If you select System Info from the menu on the left, you will see the RLM system information

screen below in the view area. This information contains the platform type and hostid information

for the system where the rlm process is running (NOTE: not where your browser is running). In

addition, starting in RLM v9.3BL2, this screen will display a list of all rlm processes running on

this computer (including processes which are not currently running but which have run in the prior

24 hours).

RLM License Administration Manual Page 60 of 139

Activate License

If you select Activate License from the menu on the left, you will be prompted for the information

necessary to activate a license from an ISV server's internet site. The information is collected in

several steps. The initial screen is shown below. Click on BEGIN License Activation to step

through the screens which will collect the data required to activate a license.

RLM License Administration Manual Page 61 of 139

Test License Activation

This command allows you to test the activation server specified by the ACTIVATE_TEST line in

the rlm options file. When a test is successful, you will see a screen similar to the following

screen:

See the “ACTIVATION_TEST” line description of the rlm options file in The RLM Options File

on page 63 for information on specifying the activation test parameters.

RLM Manual/About...

These last two commands display RLM information. The RLM Manual button displays the latest

version of this manual from the Reprise Software, Inc. website at

http://www.reprisesoftware.com/RLM_License_Administration.html

The About... command displays the intro screen seen at the beginning of this section.

Table of Contents

RLM License Administration Manual Page 62 of 139

The RLM Options File

The RLM options file allows control over access to the status, reread, shutdown administration

commands as well as control over the editing of options files. Options are provided to either allow

(INCLUDE or INCLUDEALL) or disallow (EXCLUDE or EXCLUDEALL) administration

command usage. Additionally, options are provided to create groups of users (GROUP) or hosts

(HOST_GROUP) or IP addresses (INTERNET_GROUP).

In addition, the RLM options file allows you to turn off logging of status requests (to the debug

log) via the NOLOG option.

Finally, the RLM options file allows you to set the defaults for the "Activate License" command in

the menu.

The RLM options file is called rlm.opt, and should be placed in the directory from which you run

the rlm (or rlm.exe) binary.

If you would like to add comments to the options file, start the line with the '#' character.

There are 8 privileges which can be controlled in the RLM options file. Each privilege is specified

with the appropriate privilege name in the rlm options file. Note that these privilege names are the

same names that are used in the RLM password file if you are controlling access to the RLM web

interface via user login. If you use the RLM password file, you should not use these lines in the

RLM options file - in other words, you should use one mechanism or the other, but not both.

RLM privileges controlled by the RLM options file

Privilege

Name to use in

RLM options file

Meaning

edit_meter edit_meter Allows modifying count for meter counters

edit_options edit_options Allows editing options files for ISV servers

edit_rlm_options edit_rlm_options

Allows editing options files for the rlm server and

license files

edit_xfer edit_xfer

Allows editing server-server license transfer settings

for ISV servers

logfiles logfiles

Enables the functions which change log files -

switch, switchr, newlog

manage_service manage_service Allows editing windows service setup

remove remove

Allows the user to remove a license from a running

process

reread reread

Allows access to the functions which do reread

commands on license servers

shutdown shutdown

Allows access to the functions which shut down

license servers

status status

Allows display of status and debug log information

from the license servers

RLM License Administration Manual Page 63 of 139

The RLM options file syntax is a subset of The ISV Options File syntax. The privilege names

status, reread, shutdown, logfiles, edit_meter, edit_options, edit_rlm_options,

manage_service and edit_xfer are used where a product name would be used in an ISV options

file. By default, all privileges are granted to all users unless otherwise restricted in the rlm options

file.

A user with no privileges assigned will have access to the "Activate License", "Diagnostics",

"RLM Manual...", "System Info", and "About" commands.

Note that the RLM web interface does not have access to the username or hostname (the rlmutil

utilities do pass the username and hostname), so, to be most effective, command restrictions

should be done based on IP addresses. By default, all commands are enabled (unless disabled with

the -x rlmdown or -x rlmremove rlm startup options, in which case rlm options have no effect.).

Legal characters in the RLM options file

In general, all options file fields are white-space delimited, meaning that no data item can contain

embedded spaces, tabs, newlines or carriage returns. In addition, the following four characters are

illegal in data items in the ISV or RLM options (and license) file: "<", ">", "&", and double quote

("). Note: single quote (') and back-quote (`) were illegal prior to RLM v8.0. As of RLM v12.1, the

characters "<", ">", and "&" are legal in comments (lines beginning with "#") but nowhere else.

Note that all lines in option files (RLM or ISV) as well as license files must be shorter than 1024

characters. Anything over 1024 characters will be truncated.

The ACTIVATE option controls whether the "Activate License" button is present, and, if present,

the default activation URL and ISV name.

There is one additional option available in the ISV options file: NO_OLD_RLMUTIL. This option

goes on a line by itself, with no parameters. If specified, the RLM command-line utilities prior to

RLM v9.0 will not be able to perform an rlmdown, rlmreread, or rlmremove on this server. By

default, all versions of the RLM utilities are enabled unless NO_OLD_RLMUTIL is specified in

both the RLM and the ISV options files.

Note that everything in the RLM options file is case-insensitive.

The RLM Options File first appeared in RLM v4.0. The remove privilege and

NO_OLD_RLMUTIL were added in RLM v9.0. The logfile privilege was added in RLM v9.1.

The EDIT_METER privilege was added in RLM v9.3.

In the following example RLM options file, status commands are only allowed from hosts on

subnet 172.16.7.*, no one on host "excluded_host" can do a reread command, and only users on IP

address 172.16.7.93 can do a shutdown. Note that each command (INCLUDE, EXCLUDE, etc)

must be on a separate line. Also, RLM will not process reread or shutdown requests from pre-v9

command-line utilities.

NO_OLD_RLMUTIL

INCLUDE status internet 172.16.7.*

EXCLUDE reread host excluded_host

INCLUDE shutdown internet 172.16.7.93

For a detailed description of each option, see the section below. Note that privilege should be one

of "status", "shutdown", "reread", "edit_options", or "edit_rlm_options":

RLM License Administration Manual Page 64 of 139

ACTIVATE [off | url URL | isv ISVNAME]

The ACTIVATE line allows you to disable the "Activate License" command, or to set the defaults

for the URL and ISV name for activation.

The 3 forms of the ACTIVATE line are:

ACTIVATE off

ACTIVATE url URL

ACTIVATE isv ISVNAME

In the first form, the "Activate License" menu item is disabled and will not appear in the menus.

In the second form "URL" is the default URL used for activation. For example:

ACTIVATE url www.reprisesoftware.com

In the third form "ISVNAME" is the default ISV name used for activation. For example:

ACTIVATE isv reprise

ACTIVATE is new in RLM v10.0

ACTIVATE_TEST url isv [activation_key [hostid [count]]]

The ACTIVATE_TEST line allows you to specify the parameters for the “Test License Activation”

button in the GUI.

You must specify the URL and the ISV on this line. The defaults for the other parameters are:

• akey - “test”

• hostid - “12345678”

• count – 1

No special privs are required to use the “Test License Activation” button.

ACTIVATE_TEST is new in RLM v15.0

[id=nnn]

The EXCLUDE line removes the specified privilege from a particular user, host, group,

host_group, IP address, or project. If you specify group or host_group, it must be defined by a

GROUP or HOST_GROUP line in the RLM options file.

Portions of the INTERNET address can be specified with a '*' which matches any address, e.g.,

172.16.7.*

If specified, the id applies this option to the license with an id of “nnn”.

Note: To use PROJECT the user needs to specify the project name in the environment variable

RLM_PROJECT prior to starting rlm. To use INTERNET specify the internal (vs. external) IP

address of the client machine.

RLM License Administration Manual Page 65 of 139

For a list of the privileges available, see the table at the beginning of this chapter.

The EXCLUDEALL line prevents usage of all capabilities defined by all privileges by a particular

user, host, group, host_group, IP address, or project. If you specify group or host_group, it must be

defined by a GROUP or HOST_GROUP line in the RLM options file.

Portions of the INTERNET address can be specified with a '*' which matches any address, e.g.,

172.16.7.*

Note: To use PROJECT the user needs to specify the project name in the environment variable

RLM_PROJECT prior to starting rlm. To use INTERNET specify the internal (vs. external) IP

address of the client machine.

For a list of the privileges available, see the table at the beginning of this chapter.

GROUP name list-of-usernames

The GROUP line defines a group of users to be used in an EXCLUDE, EXCLUDEALL,

INCLUDE, or INCLUDEALL line. Separate the usernames in the list by spaces. Prior to RLM

v9.0, only the first definition of a particular group name is used. Starting in RLM v9.0, multiple

lines that specify the same GROUP name will have their lists of usernames concatenated.

Example:

GROUP engineers tom dick harry

Example (rlm v9.0+). This example results in a group of 6 users:

GROUP engineers tom dick harry

GROUP engineers larry curly moe

HOST_GROUP name list-of-hostnames

The HOST_GROUP line defines a group of hosts to be used in an EXCLUDE, EXCLUDEALL,

INCLUDE or INCLUDEALL line. Separate the hostnames in the list by spaces. Prior to RLM

v9.0, only the first definition of a particular group name is used. Starting in RLM v9.0, multiple

lines that specify the same HOST_GROUP name will have their lists of hostnames concatenated.

Example:

HOST_GROUP corporate node_a node_b node_c

RLM License Administration Manual Page 66 of 139

Example (rlm v9.0+). This example results in a group of 6 hosts:

HOST_GROUP corporate node_a node_b node_c

HOST_GROUP corporate node_d node_e node_f

INTERNET_GROUP name list-of-ip-addresses

The INTERNET_GROUP line defines a group of IP addresses to be used in an EXCLUDE,

EXCLUDEALL, INCLUDE, INCLUDEALL, MAX or RESERVE line. Separate the ip addresses

in the list by spaces. Multiple lines that specify the same INTERNET_GROUP name will have

their lists of ip addresses concatenated. IP addresses can contain the wildcard ('*') character.

Example:

INTERNET_GROUP corporate 1.2.3.4 2.*.*.7 172.16.7.*

Example 2. This example results in a group of 6 IP addresses:

INTERNET_GROUP corporate 1.1.1.1 2.2.2.2 3.3.3.3

INTERNET_GROUP corporate 4.4.4.4 5.5.5.5 6.6.6.6

who[id=nnn]

The INCLUDE line grants the specified privilege to a particular user, host, group, host_group, IP

address, or project. If you specify group or host_group, it must be defined by a GROUP or

HOST_GROUP line in the RLM options file. Anyone not specified by the INCLUDE line is not

allowed access to the capabilities defined by privilege.

If specified, the id applies this option to the license with an id of “nnn”.

Portions of the INTERNET address can be specified with a '*' which matches any address, e.g.,

172.16.7.*

Note: To use PROJECT the user needs to specify the project name in the environment variable

RLM_PROJECT prior to starting rlm. To use INTERNET specify the internal (vs. external) IP

address of the client machine.

For a list of the privileges available, see the table at the beginning of this chapter.

RLM License Administration Manual Page 67 of 139

The INCLUDEALL line grants all privileges to a particular user, host, group, host_group, IP

address, or project. If you specify group or host_group, it must be defined by a GROUP or

HOST_GROUP line in the RLM options file. Anyone not on the INCLUDEALL list is not

allowed to use a capability controlled by any privilege.

Portions of the INTERNET address can be specified with a '*' which matches any address, e.g.,

172.16.7.*

Note: To use PROJECT the user needs to specify the project name in the environment variable

RLM_PROJECT prior to starting rlm. To use INTERNET specify the internal (vs. external) IP

address of the client machine.

For a list of the privileges available, see the table at the beginning of this chapter.

NO_OLD_RLMUTIL

The NO_OLD_RLMUTIL line prevents pre-RLM-v9 command-line utilities from performing a

reread, remove, or shutdown operation. The pre-v4.0 RLM utilities do not respect the RLM

permissions for the reread or shutdown commands, and the pre-v9.0 utilities do not respect the

permissions for the remove command. Adding NO_OLD_RLMUTIL to your ISV options file will

prevent these older utilities from performing these commands, and only a v9 (or newer) RLM

command-line utility can be used for this purpose.

By default, all operations can be performed by all versions of the RLM command-line utilities.

In order for NO_OLD_RLMUTIL to be effective, it must be specified in both the rlm and the ISV

server options files.

NOLOG status

The NOLOG option instructs the rlm server to omit logging of status requests to the debug log.

Example:

NOLOG status

This example causes the rlm server to omit the logging of status requests in the debug log.

Table of Contents

RLM License Administration Manual Page 68 of 139

The ISV Options File

The ISV options file allows control of the use of licenses by various users and groups of users

within your organization. Options are provided to reserve licenses (RESERVE), and to either

allow (INCLUDE or INCLUDEALL) or disallow (EXCLUDE or EXCLUDEALL) license use.

Additionally, options are provided to create groups of users (GROUP) or hosts (HOST_GROUP),

or IP addresses (INTERNET_GROUP), and to control the maximum number of licenses a user or

group can check out (MAX). Certain users/hosts/groups, etc. can be exempted from the MAX

settings with the EXEMPT_MAX and EXEMPTALL_MAX lines.

Logging of the license servers is controlled by the (DEBUGLOG) and (REPORTLOG) options. In

addition, you can suppress debug logging of check-in/checkout/denied entries with the NOLOG

option. Automatic report log file rotation is supported in ISV servers via the ROTATE option and

automatic purging of old report logs is supported with the PURGE_REPORTLOG option (new in

v12.1).

Control over license roaming is provided with the INCLUDEALL_ROAM,

EXCLUDEALL_ROAM, ROAM_MAX_DAYS, and ROAM_MAX_COUNT options.

License timeout is controlled via the TIMEOUT and TIMEOUTALL options.

License timezone restrictions are controlled with the TIMEZONE option.

Client license caching is controlled with the CLIENT_CACHE option.

License queuing behavior can be modified with the EXPRESS and PRIORITY options.

There is one additional option available in the ISV options file: NO_OLD_RLMUTIL. This option

goes on a line by itself, with no parameters. If specified, the RLM command-line utilities prior to

RLM v9.0 will not be able to perform an rlmdown, rlmreread, or rlmremove on this server. By

default, all versions of the RLM utilities are enabled unless NO_OLD_RLMUTIL is specified in

both the RLM and the ISV options files.

The ISV options file is specified on the ISV line in The License File.

Note that, in RLM v15.0, the server will add the client's external IP address to the list of IP

addresses supplied by the client. This IP address is not added if it is the same as one of the client-

supplied IP addresses. This means that if your license server is on the internet, you can use the

client's external IP address to INCLUDE/EXCLUDE license checkouts.

How The ISV Options File is located

The ISV options file can be located in 3 ways:

• You can specify the ISV options file location on the ISV line in The License File.

RLM License Administration Manual Page 69 of 139

• If no specification is on the ISV line, rlm will look for <ISV>.opt (where <ISV> is the

name of the ISV) in the location with the first license file.

• If there is no options file in either of the first 2 locations, rlm will look for <ISV>.opt in

the working directory where you started the rlm server.

Legal characters in the ISV options file