RLM builds a list of license files, in the following order:

• <isvname>_LICENSE environment (if it exists) - this can be a list of license files, or [email protected] specifications
• RLM_LICENSE environment (if <isvname>_LICENSE doesn't exist) a list, similar to the above
• LF specified in argument 1 to rlm_init() - this is a single license file or [email protected] or directory. Typically software publishers set this to the current directory (".")
• license files in directory specified by argument 2 to rlm_init()

These are all put into a single list, in that order.

However, if the you set the environment variable RLM_PATH_RANDOMIZE, then the list is started from some random point, wrapping back around to the front of the original list.

When license checkouts are much slower on one (or a few) systems, the problem is usually something in the environment on that particular system. Most likely, there is a license file (or [email protected] in RLM_LICENSE) that specifies a server which is unreachable from that system, so the request to the (unreachable) server times out, then succeeds from the "good" server.

Another possibility, if your Software Provider has integrated an ISV-defined hostid, is that there may be something about the particular system causing the ISV-defined hostid code to take longer to run. Note that the ISV-defined hostid code will be called before the call to check out the license.

When RLM is looking for a match between the hostid in the license file and a hostid on the machine, it looks on the at all instances of the hostid type in the license file. If you have an ethernet hostid in the license file, RLM looks at the addresses of all ethernet devices in the system. If the device whose address is in the license file is no longer in the system configuration, RLM will not find a hostid match. Sometimes these devices come and go on laptops - we call these transient devices. For example, a wireless adapter might not always appear.

On Windows, RLM uses the device description (as you see in ipconfig /all) to sort the list of ethernet devices returned by "rlmhostid [ether]", such that transient devices such as wireless interfaces and VPN devices are at the end of the list. Thus choosing the first device in the list returned by rlmhostid yields the best chance of having a stable hostid.

Q: I have recently upgraded RLM versions, but now my software doesn't recognize licenses which I had made for customers with the old version. What's wrong?

A: RLM uses a public/private key pair to authenticate licenses. In this case, you probably generated a new key pair when you installed the new version of RLM, thus RLM can't authenticate your old licenses.

All you need to do is to copy src/rlm_pubkey.c and src/rlm_privkey.c from your old RLM SDK to your new RLM SDK, and rerun (n)make in the platform directory. Finally, re-link your app with the new RLM library. This will produce binaries that can authenticate your old licenses

With RLMpe, you supply the username and password to the rlmpe_checkout() call every time you do a checkout. How you acquire the username/password (and whether you save it) is up to you. For example, you could prompt every time for this information, or you could put it into the user's environment so you never have to prompt after you set it up.

With RLMpe, you supply a "promise", which is the amount of time during which you guarantee to contact the server with rlmpe_heartbeat(). If your application crashes (or fails to call rlmpe_checkin(), the license will remain in use until the end of that promise interval. (Note that in v14.0BL4, the "promise" interval is fixed at 10 minutes).

Q: I read the docs of another license server product which would not hold a license unless the clients refresh the license in a certain time frame, otherwise the server would reclaim the license. Does RLM do this?

RLM uses TCP so the server can check the connection independent of data sent from the application. A license manager that uses UDP or rpc calls would need the application to send data periodically. This is not strictly required in RLM.

Note that if you use rlm_init_disconn() in place of rlm_init(), then you will need to refresh the connection periodically, but this is not required if you call rlm_init().

RLM Activation Requests can time out for a number of reasons. Please see this blog post for help diagnosing these problems.

Q: The documentation says: "...you need to periodically check the health of the connection...". How often? What if my application does not manage to check 'often enough' (whatever this means)?

Checking the health of the connection is done to make sure that the server has not been shut down or exited for any reason. The license count is maintained in the server in memory. If the server is restarted, then it starts over with a fresh count of licenses available. So, for example, if you have 10 licenses checked out, then the server is shut down and restarted, those 10 licenses become available again. Checking with the server in your application prevents your application from continuing to run while it thinks it has a license and the server giving that license out again to a new client.

If you check every couple of minutes, that should be sufficient. On the other hand, if your product only runs for a couple of minutes, you can skip this check completely.

If you call rlm_init_disconn(), you must check with the server at least as often as the promise parameter you specified.

Q: I cannot check out licenses on one platform from a server on another - what's wrong?

If you installed the RLM kit on 2 different platforms and ran the default INSTALL procedure, you may have created different publc/private key pairs. Decide which key pair you want to use, and copy them to all the platforms you are using, and re-compile //rlmsign//, your //isv server//, and any applications, and re-sign any licenses on that platform.

Q. My product is a library / DLL / shared object that may be linked into a program that also uses RLM.
How do I avoid name collisions between the 2 copies of RLM when linking?

A. Windows: Create a DLL that contains the code for your product as well as the RLM code.
When you create the list of exports from the DLL, don't include any RLM functions.

A. Linux: Create a shared object (.so) that contains the code for your product as well as the
RLM code. When you link your shared object, include the following on the command line:

-Wl,--version-script=file
(Note: the character after the capital W on the command above is a lowercase l, as in "license").

file should contain:
{
global:
function1;
function2;
...
function N;

local:
*;
};

function1, function2, etc, are your functions that can be called from outside the shared object.

Q: putenv() does not work in my windows application. What is wrong?

A: You can always use the rlm_putenv() call in place of putenv(). rlm_putenv() takes the same parameters as putenv()

Q: I call rlm_init() then rlm_close() but my memory leak detector reports memory leaks. What should I do?

A: OpenSSL, which RLM uses to create and authenticate digital signatures on licenses, dynamically allocates some crypto tables the first time it is used in a program.

There are 2 OpenSSL api calls to free allocated memory: CRYPTO_cleanup_all_ex_data() and ERR_remove_state(). As such they are not part of the RLM API, but are used in conjunction with it if you really care about memory leak detection at program exit. In practice almost nobody does.

If you use multiple threads with RLM, then call ERR_remove_state(0) just before the thread exits (and before your main thread exits as well).

CRYPTO_cleanup_all_ex_data() frees OpenSSL data when your program is no longer going to use OpenSSL (and hence RLM). The problem with it is that it is irreversible - once you call it, you cannot use OpenSSL (or RLM) again in that run of the program. Hence RLM cannot call it in rlm_close(), because a program might well call rlm_init() again.

The only legitimate place to use CRYPTO_cleanup_all_ex_data() is right before the program exits, and then only for the purpose of keeping leak detectors quiet, not for any practical purpose.

Note that CRYPTO_cleanup_all_ex_data() is not thread-safe, so use it with caution. For that reason, and because some applications create multiple RLM handles, it's not practical for RLM itself to call this routine as part of rlm_close(). But your application can call it if you wish.

So, in summary, call ERR_remove_state(0) at the end of every thread that uses RLM, and at the end of your program, call ERR_remove_state(0) followed by CRYPTO_cleanup_all_ex_data().

Q: When I run the java sample application, I get the following error:
Exception in thread "main" java.lang.UnsatisfiedLinkError: no rlmXXX in java.library.path
at java.lang.ClassLoader.loadLibrary(Unknown Source)
at java.lang.Runtime.loadLibrary0(Unknown Source)
at java.lang.System.loadLibrary(Unknown Source)
at com.reprisesoftware.rlm.RlmHandle.createHandle(RlmHandle.java:94 )
at com.reprisesoftware.rlm.RlmHandle.(RlmHandle.java:128 )
at net.dirtt.icelib.dirtt.wall.RLMClient.main(RLMClient.java:32)

What is wrong?

A: You need to ensure that the rlmXXX shared object is in your path.

On Unix you may need to set LD_LIBRARY_PATH to point to the rlmXXX shared object

On Mac you may need to set DYLD_LIBRARY_PATH to point to the rlmXXX shared object

On Windows rlmXXX.dll needs to be in your PATH.

How do I create universal binaries for the MAC?

In order to create universal binaries for the MAC platform, use the ''lipo'' command as follows:

   % lipo -create -output universal_binary ppc_binary x86_binary//

Where:

   universal_binary is the output universal binary name
   ppc_binary is the input PPC architecture binary
   x86_binary is the input X86 architecture binary

In order to verify the architectures present in a binary called ''binary_name'', use:

   % lipo -info binary_name

Q: rlm_act_request() returns RLM_ACT_SERVER_ERROR (-1019). What should I do?

A: This error is returned when the http request receives an internal server error from the HTTP server (status 500).

This means that something is misconfigured on your web server, and the only way to find out what it is is to look at the web server error log.

In this case, the first thing you should do is to look at the web server error log and attempt to resolve the configuration problem that way. We cannot help you without this information, and it is likely that you will be able to solve the problem when you see the error log.

Q: When attempting to activate a license (using either rlm_act_request() or the rlm web interface), the license is not generated and an error of "Bad HTTP transaction with activation server" RLM_EH_BADHTTP (-136) is generated. What is the problem?

The HTTP error will be listed along with the error message. This may help you to find the problem.

This problem generally occurs when there is some problem with the installation.
This can happen for a number of reasons:

• you have specified an ISV name which is incorrect
• the ISV web server is not configured correctly
• the ISV_mklic binary is not for the correct architecture

One way to test whether you have a correct binary is to attempt to run it by hand. If your webserver is running on a unix system, try the following:

ISV_mklic << EOF
akey=1&hostid=2&
EOF

This should result in output indicating that the activation key was not found (unless you have an activation key of "1"). If the program fails to run, you either have a bad binary or a permission problem.

This error (-134, RLM_EH_ACT_BADSTAT, Bad return data from webserver) most likely means that there is a problem with the license generator, ISV_mklic.

Try running the license generator by hand on the webserver machine. When you run it from the command line, you should see something like the following:

% demo_mklic
Content-type: text/html

If you get no output, or the program fails in some way, it's likely that you have a binary for the wrong architecture or a permission problem, etc.

If you get a "Server rejected client (-57)" error from a v11 client, or a "Communications error with license server (-17)" error from a v10 client when using a v11 server, it is likely that you disabled the use of generic servers.

RLM v11 has a new "disable generic server" capability, which will cause the generic server (ie, rlm + an ISV server settings file) to reject client requests.

Make sure that the call to rlm_isv_cfg_disable_generic_server() has a 0 parameter as the 2nd parameter is you want to use the ISV server settings file.

If you want to serve licenses across a firewall, both license servers, i.e. RLM and the ISV server, need known port numbers in order for your firewall to pass requests on these ports.
The RLM server is always at a known port number - specified in the license file on the SERVER or HOST line.
Typically, RLM starts up all the ISV servers with dynamic port numbers which are not known before startup time.

It is possible to have RLM assign fixed port numbers to the ISV servers. To do this, specify the port number for the ISV server on the ISV line. The port number is the fifth parameter in the isv line:

ISV isvname isv-binary options-file port-number



In order to specify the port number, you must also specify an options file for this ISV server.

Once you have specified the port number, instruct your firewall to allow connections to both the port number on the SERVER line (for RLM) and the port numbers on any ISV lines.

You must restart RLM in order for any port changes to take effect. Restarting the ISV server via the web interface or rlmreread does not restart RLM.

Note: Beginning in RLM v9.0, you can specify the ISV server port number with the optional "port=xxx" parameter on the ISV line, as such:

ISV isvname binary=isv-binary port=port-number
or
ISV isvname isv-binary port=port-number



Using this method, you do not have to specify an ISV options file.

That error message typically indicates another copy of RLM is running which is using port 5054 or 9000.

Check your system for other running copies of the RLM server and if they should not be running, stop them. Then, restart the RLM server.

Another possible problem is that another program is using the port. Use the "netstat" command to see if another program is using this port.

Finally, we have reports that some systems get this error, even when no program is using port 5054, if the machine's name and IP address are not present in the hosts file. Adding the hostname and IP address to the hosts file will resolve this problem.

Q: I have software from 2 different Software Companies, and when I attempt to run the license servers, they give "port in use" errors. What should I do?

A: You have the choice to run one rlm for many ISV servers, or one rlm for each ISV server that you have.

Unlike older license managers, each instance of rlm requires one client connection port (specified on the HOST or SERVER line in the license file), and one web server port. The rlm server can bind multiple client connection ports if it is started with multiple license files which have different port numbers on their HOST or SERVER lines.

The web server port defaults to 5054 (or 9000 in older releases), and can be changed on the rlm command line with "-ws ". Or the web server can be disabled altogether with "-nows", but we don't recommend disabling it.

If you want to run one rlm for multiple ISV servers:

This is the easiest way to configure rlm.

You'll need (at least) 1 client connection port and 1 web server port. Note that you can use one or multiple client connection ports. rlm listens for client connections on each unique port it finds on the HOST or SERVER line of the license files it reads. RLM does this so that you can add a new license file from a new ISV without having to change it, and the client software from the new ISV is then unaware that the rlm process is serving other ISVs licenses.

The easiest way to accomplish this is to put the license files and ISV servers in the same directory as rlm, and then just start rlm with its normal defaults.

If you want to run one rlm per ISV server for 2 ISVs:

You'll need 2 client connection ports and 2 web server ports. This means you will have to ensure that both license files specify different port numbers on the HOST (or SERVER) line, and you must be sure to start at least one copy of rlm with the "-ws port" option, specifying a different port # than the default.

In this case, you must keep the license files in separate directories, or at a minimum, keep them in a directory that is separate from any of the rlm binaries and reference them with a "-c license_file" specification for each copy of rlm.

The failover server checks the health of the "failed" server every 2 minutes. It can then take up to one additional minute before the failover server begins serving licenses.

This error nearly always means that another copy of the ISV server is running.

Check the running processes on the system and kill the other copy of the ISV server. Generally, there may be another copy of rlm (or rlm.exe) running as well. Of course, the other server may be operating and everything may be fine, so you may not need to kill it. If the ISV server is running without an rlm server running, you will need to kill the ISV server.

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.

This message nearly always means that there is another copy of RLM running on this port. Check the system and kill the running rlm process.

In certain cases, Symantec anti-virus software blocks some rlm messages. The symptoms vary, but usually the application receives network read errors (-104), or licenses are simply not checked back in.

In order to solve this problem, run your ISV server on a known port # (use port=xxx on the ISV line), and tell the Symantec software to exclude that port.

WAN access to the license server should be no problem. We don't have any feedback from RLM customers who have tried this, but back in the FLEXlm days a number of end users did this with no problem - and RLM and FLEX use the network in similar ways. The checkout message is less than 100 bytes, but before checkout there's an initial connection message that's on the order of 1KB. Still pretty small in the scheme of things, and that only needs to happen once per client connection to the server.

Here are a couple of configuration/policy items that bear on WAN use of RLM:

- RLM_CONNECT_TIMEOUT is an environment variable that the end user can set (or you can set it programatically in your code). By default, an RLM client uses a 10-second timeout when making a connection to a license server. In a WAN with a lot of latency, this can be used to up the connect timeout and prevent connection failures.

- The application's heartbeat usage could be an issue on extremely slow and/or flakey networks. If the heartbeat interval is less than the maximum round-trip latency (of tiny messages) on your network AND if the application's tolerance of missed heartbeats is 0, you could have a situation where your app decides that the license server has gone away when it's really just a slow network. That would be an extreme situation though, as the minimum heartbeat interval that RLM allows is 30 seconds.

The RLM License Administrator Bundle contains a performance test suite that you can run on your WAN. The reports are in terms of how long it takes to get a given unit of work done (say, 300 checkouts). Running that will give you an idea of how well RLM will perform in a specific environment.

Q: On Windows, what version of the RLM kit do I use with my compiler?

If you are using VS6 or VS2003, use the x86_w1 RLM kit.

If you are using VS2005 or VS2008, use the x86_w2 RLM kit, unless you are building 64-bit binaries, in which case you should use x64_w2

If you are using VS2010 or later, use the x86_w3 RLM kit, unless you are building 64-bit binaries, in which case you should use x64_w3

v11.0 uses some functions from winhttp.lib to get information on proxy servers. VS2005 did not have winhttp.lib among its libraries, so it must be downloaded. You can get it in the Windows SDK, downloadable here:
http://www.microsoft.com/en-us/download/details.aspx?id=6510

Q: On Windows, I've followed the installation instructions in the "Quick-Start Guide", but the linker reports: fatal error LNK1181: cannot open input file 'ws2_32.lib'. What's wrong?

ws2_32.lib is the Windows winsock2 library, not part of RLM.

Most likely the issue is that on your system some piece of the environment isn't getting defined correctly for Visual Studio. To set up Visual Studio for use on the command line, run:

"\Program Files\Microsoft Visual Studio 8\VC\vcvarsall.bat"

Q: I've just downloaded the kit. Are there instructions for how to use RLM when I use the Visual Studio GUI to compile and link my application, rather than the command line?

In order to use the RLM kit with the Visual C++ GUI, the procedure is as follows:

In a command window, build the RLM SDK as specified in the manual section "Installing RLM". You need do this only once per release of RLM. In your project settings / properties in Visual Studio:

Under C/C++, add ''\src'' to the Additional Include Directories (where '''' is the path to the installed RLM SDK)

Under the Link/Input/Additional Dependencies or Additional Library Path, add ''\\rlmclient.lib'' (where '''' is either ''x86_w1'' or ''x64_w1'', depending on whether the project is a 32-or 64-bit project)

Under the Link Command Line or Project Options section, make sure the following libraries are included:

    ws2_32.lib
    Advapi32.lib
    Gdi32.lib
    winhttp.lib
    User32.lib
    netapi32.lib
    kernel32.lib
    oldnames.lib
    shell32.lib
    libcmt.lib

Then you will be able to use RLM in your project without leaving the GUI.

The RLM server log file frequently contains information that identifies the startup problem.

The RLM log file file location is specified by the "-dlog logfile" argument on the RLM command line when using the "-install_service" option. If you install the RLM service via the RLM web interface, the log file location is specified in the box labeled "Server Debug Log".

In RLM v8 and later if you specify a relative path, that path will be relative to the location of rlm.exe. For example, if the debug log path is specified as "myrlmlog.log" and rlm.exe is located in "c:\rlm", the debug log will be "c:\rlm\myrlmlog.log".

In versions prior to v8, the specified relative path is relative to \windows\system32.

When running as a Windows service, rlm.exe and the ISV server run under the user name "SYSTEM". Make sure that the log file location that you specify can be written to by that user.

Launch a command window using "Run as administrator", and install RLM from the new command window. "Run as administrator" is an option when you right-click on the command window icon on the desktop or in the start menu.

Reprise has had reports on a very limited number of systems that RLM fails to start the ISV server, with errors similar to the following written to the debug log (note: the ISV name will be your ISV name, not necessarily "demo"):

03/16 04:12 (demo) select() failure: Unknown error
03/16 04:12 (demo) Out of file descriptors: Cannot clone communications handle: Unknown error
<last error repeats 10 times>
03/16 04:12 (demo) Too many errors on main socket, exiting



This error sometimes results in debug log output similar to the following:

01/06 10:11 (rlm) Starting ISV demo
01/06 10:11 (rlm) Error in getsockname() call 13
01/06 10:11 (rlm) ... demo on port 57809
01/06 10:11 (rlm) New thread created to watch ISV demo
01/06 10:11 (rlm) demo initialization error: 1, not restarting



Or the following:

01/05 12:50 (rlm) Starting ISV servers:
01/05 12:50 (rlm) ... demo on port 1088
01/05 12:50 (rlm) New thread created to watch ISV demo
01/05 12:50 (rlm) demo - communication (socket) problems



This problem is caused by a registry corruption (not induced by RLM) that affects some network operations. The fix is to open a command window and type the command:

$ netsh winsock reset



Should the above "netsh" command not solve the problem, Microsoft has published the following article on how to correct the registry when this occurs. Note that the error message indicating the problem is different in the article than the RLM error message indicating the problem, but the underlying cause is the same.

http://support.microsoft.com/default.aspx?scid=kb;en-us;817571

Q: When I try to use rlm to install rlm.exe as a service on Windows 7 I get a message that says "Access to Service Control Manager denied" even though I'm running in an account with Administrator rights. What should I do?

A: In some cases on Windows 7 a program doesn't get the rights of the invoking user. But if you launch rlm.exe by right-clicking on its icon and selecting "Run as administrator", then rlm will run with the sufficient rights, and it can install itself as a service.

Sometimes RLM on Windows uses a MAC address as hostid which is later not present in the system, leading to a wrong hostid error when the application tries to check out a license, or when starting up a license server. What should we do about this?

A: The rlmhostid utility, and the internal routines which determine hostids, return all the MAC addresses found in the system. Some of those may be for devices that are not always present in the system, for example Virtual Private Networks, wireless adapters, wireless phones plugged in to USB ports, etc. If a license is created which is locked to one of these transient hostids, the license will be valid if the transient device is present. Thus it is a good idea to lock licenses to non-transient device addresses.

In RLM v8 and later, the list of MAC addresses returned by rlmhostid, and returned by internal routines, is ordered such that the addresses of potentially transient devices are at the end of the list. Thus it is a good idea when choosing from a list of MAC addresses to choose from the beginning of the list if using RLM v8 or above. If using a version prior to v8, you can use "ipconfig /all" to see the list of MAC addresses along with a description of each one. You can use the description to choose one that isn't transient.

Note that when RLM is matching the hostid from a license with the hostids present on the machine at runtime, it only requires one of the hostids to match the one in the license.

Q: Certain RLM operations fail on Windows 2000 when attempted by a restricted user account. These operations include checking out a "single" license and starting up the rlm server. How do I fix this?

A: RLM uses the common application data folder to store operational files. On Windows 2000, restricted users cannot write to this folder by default. The workaround is to grant write access to the common application folder to restricted accounts. The folder is typically "\Documents and Setings\All Users\Application Data". In a non-restricted user account, right-click on this folder and select Properties, then select the Security tab. In the "name" portion of the tab, click on "Everyone". In the "permissions" portion of the tab on the bottom, click the "Full Control" checkbox. Then click the OK button.

Repeat the instructions above for the "Reprise" folder (if it exists). The Reprise folder is inside the Application Data folder, e.g.:

"\Documents and Setings\All Users\Application Data\Reprise".

We have had reports of 32-bit RLM servers failing to execute on a 64-bit Ubuntu system.

The symptom, when attempting to run the RLM servers, is an error similar to:

bash: ./rlm: No such file or directory

This is due to the system not having the 32-bit system libraries. To correct this problem, execute the following on the target system:

sudo apt-get install ia32-libs (for older systems)

or on newer systems:

dpkg --add-architecture i386
sudo apt-get update
sudo apt-get install libc6:i386 libstdc++6:i386