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 ISV server configuration is contained in a platform-independent settings (isv.set) file, rather than a different binary built for each platform.

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 RLM Embedded Web Server to perform normal administration tasks.

The ISV server consists of either a platform-specific binary file (isvname.exe on Windows, or isvname on Unix), or a platform-independent settings file (isvname.set on either Windows or Unix). When you run the “make” command in your kit, both versions of the ISV server are created. Reprise Software recommends shipping the settings file, which is platform independent, however the older-style executable is built for you as well should you wish to ship this version instead. If you ship the settings file, not only is it platform-independent, but it is also optionally automatically upgradable in the field (this is the default setting in rlm_isv_config.c) - meaning that if your license administrator upgrades to a newer version of RLM (the RLM server), your ISV server will automatically be upgraded as well.

Warning

If you use ISV-defined hostid code, you cannot make use of the Generic ISV server - you must build an ISV server binary on each of your supported server platforms.

RLM Embedded 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 rlmXXXX utilities except rlmhostid. The web server allows you to retrieve server and license status (similar to rlmstat), cause the servers to reread 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.

Important

Beginning in RLM v16.0, HTTPS is now used by default (HTTPS support was first added in v15.1). See Enabling HTTPS in the RLM Web Server for more details.

In addition, the web server allows you to view ISV option files (with Manage permissions; from the action menu ⋮ of each ISV server), and the global RLM option file (as an Admin; from the Settings menu). Also, the web interface allows you to view the recent debug log information from any of the servers (via the action menu ⋮) if you have Manage permissions. The reread and shutdown commands are possible with the Manage permission, while the View user can see the status and usage for running ISV servers. See: Access Control to the RLM Web Interface for more on access permissions.

The web server is started automatically on port 5054 when RLM is started. To use the web server, simply point your browser to: https://ServerHostName:5054 and select the operation you would like to perform. You will be prompted for any required information.

Note

For earlier version of RLM (15.2 and below) you may need to use http://ServerHostName:5054 to access the management interface.

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. For example:

-ws 6000

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

For a description of the RLM web server UI, see the RLM License Administration Manual.

RLM startup options

The RLM command is:

% rlm [-c <license_file>] [-dat] [-dlog [+]<logfile>] [-info] [-l] [-noudp]
[-nows | -ws <port>] [-x [rlmdown|rlmremove]] [-v]
[-install_service] [-service_name <service_name>]
[-user <username> -password <password>] [-isv_startup_delay <seconds>]
[-verify] [-sslcert <certfile> -sslpriv <privkey>]

These options can appear in any order on the command line.
Option	Definition
`-c <license_file>`	Specifies which license file to use. Overrides the setting of the RLM_LICENSE environment variable. The license_file parameter can be a directory containing license files, all of which will be processed.
`-dat`	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.
`-dlog <logfile>`	Specifies the pathname for the server debug log. Logfile will be overwritten unless preceeded by “+” character.
`-info`	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.
`-l`	Causes RLM to only process command-line utilities from the local host.
`-noudp`	Causes RLM to not listen on its UDP port, so that client broadcasts do not work.
`-nows`	Instructs the RLM server to not start the embedded web server.
`ws <port>`	Instructs the RLM server to use `port` as the port number for the web server.
`-verify`	Causes RLM to start all ISV servers to verify their licenses, then all servers will exit.
`-x [rlmdown \| rlmremove]`	Controls whether the rlmdown and/or rlmremove commands will be processed by the server. Specifying only -x will disable both commands.
`-v`	Causes RLM to print its version and exit.
`-install_service`	Installs RLM as a service in Windows. See Running the RLM server as a service on Windows.
`-service_name`	Sets Windows service name (default is “RLM”).
`-isv_startup_delay <seconds>`	Speficies startup delay in `seconds` for Windows service. Useful if a license file specifies a hostid of type rlmid1 (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.
`-user <username>`	1. Windows expects the username argument to be <domain>\<user>. To use the local system domain, specify “.\<username>”.
`-password <password>`	2. In order to run a service, the account specified by the -user argument must have the “Log on as a Service” property set.
`-sslcert <certfile>`	Location of certfile for using web server on HTTPS. Also requires `-sslprivkey`
`-sslprivkey <privkey>`	Specifies location of private key for using web server on HTTPS.

Note

For more information on HTTPS, see Using SSL Certificates (HTTPS) with RLM.

Warning

If the RLM server cannot bind the web server port (5054 by default), it will exit.

Warning

If there is not at least one license file with the current hostname (as returned by gethostname()), or “localhost”, a warning will be generated.

Report Log File

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 for more information.

Running the RLM server as a service on Windows

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

To install RLM as a service in a command window, use the RLM program itself (in a command window), with special arguments:

rlm -install_service -dlog [+]logfile [-service_name sname] <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 its debuglog information to the file c:\logs\server.log.

Installed RLM services are also deleted with the RLM program. Services must be stopped via the command line or service control panel before they can be deleted.

Tip

Deleting a service deletes it from the Windows service database; it does not delete the RLM executable or associated license file(s).

To delete:

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 multiple 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
When running as service, RLM 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.

Important

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 the RLM server at system boot time on Unix systems

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.

Example startup script

#!/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 -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, any 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 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. 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 licenses that will expire within 14 days. ISV servers do not process single-use (count==single) licenses.

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 an ISV-by-ISV decision and is configured in rlm_isv_config.c.

If your server is configured to refuse to run on virtual machines, you can enable it for a particular machine by issuing an rlm_server_enable_vm license. This license can be any license that is valid on the server host (i.e., it can be either a nodelocked license or a floating license for that server), however it CANNOT be locked to an Alternate Server Hostid. So, for example, the following license would enable a license server (where the license is valid) to run on a virtual machine through the end of 2023:

LICENSE ISVNAME rlm_server_enable_vm 1.0 31-dec-2023 1 sig=xxx

Note

The rlm_server_enable_vm license will not be visible in status requests, or in rlm_products() calls.

Building Your ISV Server

Your ISV license server is built from components supplied by Reprise Software. You need to provide 2 custom inputs to the build of your license server:

Your Public Key, for license key verification - rlm_pubkey.c – (see 2. Create your Keys (public/private key pair)).
A file of customizations for the server called rlm_isv_config.c (this file is contained in the src directory on the kit).

Once you have created these 2 files you create your ISV server by typing “make” in the kit directory.

Note

You cannot create or use a server settings file if you use ISV-defined hostids.

There are 2 variables you need to set in isv_config.c:

Your ISV name (“demo” for demonstration purposes)

use_flexlm_lockfile

Only set “use_flexlm_lockfile” to a non-zero value if you want the RLM servers to lock out FLEXlm license servers and vice-versa. This would be done when you want to upgrade your customers’ licenses and ensure that both license servers don’t run. Note that the behavior of server locking is slightly different on Unix and Windows systems. On Unix systems, if either the RLM or the FLEXlm server is started, the other server will not run. On Windows, however, if the FLEXlm server is started first, the RLM server will run, and shortly after it starts (one to two minutes), the FLEXlm server will exit. If the RLM server is started first on Windows, the FLEXlm server will not run. This is due to the fact that the FLEXlm servers changed their locking mechanism, and the new servers check the old locks for a conflict but do not create them.

In addition, you can modify the parameters to the **rlm_set_cfg_set_compat() call to alter the compatibility of your ISV settings file with older and newer versions of RLM. Set the 2nd parameter to a non-zero value if you wish your settings file to work with older versions of RLM than the one in which you created the settings file. Set the 3rd parameter to a non-zero value if you want your settings file to work with newer versions of RLM than the one you used to create the settings file. The default is to enable newer versions, but not older versions.

Settings File

If you ship the settings file, you only need to ship one version of the file for all platforms which you support. This means that you do not need to have a supported server platform in-house in order to provide license server support for it.

ISV Server Open File Limits

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 Disable specification (first checked in v6.0)
License Options
License Sharing specification (share and max_share)
License Timezone specification
License Platform list
License Activation key (if specified)
Both licenses must be counted or uncounted
License node-locked hostid
Both licenses must be user-based, host-based, or personal (or neither)
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
max_roam_count	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

In the case of the contract, customer, issuer, and type fields, once a license with a nonempty field is processed, no subsequent licenses in the license file will override this value, i.e., the first non-blank value will be the value associated with the license pool.

Note

Different named_user licenses are never combined into one license pool.

License ID

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

Changing your ISV server name

Occasionally, an ISV needs to change their RLM ISV name. When this happens, you can set up your ISV server to lock out servers with one or 2 of your old name(s). To do this, modify your rlm_isv_config.c file to include a call to rlm_isv_cfg_set_old_isv_name() and rlm_isv_cfg_old_isv_name2() as follows (assuming your old ISV names were “oldisv” and “oldisv2”):

rlm_isv_cfg_set_old_isv_name(handle, "oldisv");
rlm_isv_cfg_set_old_isv_name2(handle, "oldisv2");

Remember to remove the #if 0/#endif from around these calls. If you only had one old ISV name, only include the first call.

Note

If you have 2 old ISV names, and these servers don’t make the calls above, it is possible for both of those ISV servers to run at the same time. So, for example:

ISV names “a” and “b” are the old names.

ISV name “c” is your new ISV name.

Servers “a” and “b” make neither of the calls above.

Server “c” makes both calls to lock out “a” and “b”.

THEN:

→ servers “a” and “b” can run at the same time.

→ if either “a” or “b” is running, then either “c” won’t run, or “a” and “b” will stop.

In the ideal situation, “a” locks out “b” and “c”, “b” locks out “a” and “c”, and “c” locks out “a” and “b”. However, as long as “c” locks out “a” and “b”, then “c” won’t run if either “a” or “b” is running.