The License Server
The license server consists of at least two processes:
The generic server, called RLM
At least one ISV server, named isv (where isv is the name of the software publisher)
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.
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 <service_name>]
[-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. 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.
- 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. 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 run the service may be specified, via the -user and -password arguments. See the description of running the RLM server as a service below.
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 (a hardware key), 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.
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.
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
Note
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 for more information.
Warning
If the RLM server cannot bind the web server port (5054 by default), it will exit.
Also note that if there is not at least one license file with the current hostname (as returned by gethostname()), or “localhost”, a warning is generated.
If the ISV server pathname is incorrect in a license file which RLM is processing, RLM will attempt to start that ISV server using the path information in other license files, if present.
Starting in RLM v15.1, processing of -iai and -z flags has been removed. 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 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.
Examples:
rlm -install_service -dlog c:\logs\server.log
The most basic installation. This will install the service under the default service name “RLM” with the logfile server.log under C:\logs\.
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
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.
When running as service RLM changes its working directory to the directory where rlm.exe is installed, so log files will be written there 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:windowssystem32.
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 using systemd on Linux
cd to /etc/systemd/system
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
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. You must install this startup script as root.
Warning
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.
#! /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, 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 (meaning 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 controlled by your ISV, and Reprise Software has no part in this decision.
ISV server open file limits
On Unix platforms, ISV servers 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)
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 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.
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.
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:
OS |
Location |
|---|---|
/var/tmp |
Unix |
/var/tmp |
Mac |
C:\ProgramData\Reprise |
Windows |
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.