Debugging Licensing Problems in the Field
In order to diagnose a licensing problem in the field, you will need some information from your customer. Primarily, you need to figure out whether there are any nodelocked, uncounted licenses (including roaming licenses) which are available to satisfy your checkout request, and, if not, whether the application can connect to a license server to obtain a license.
There are 2 tools to help you diagnose these problems in the field:
client-side diagnostics which show the application environment and local licenses available for checkout
server-side diagnostics which show which licenses are available on the license server.
Product debugging information is also available.
Client-side Diagnostics
Built into every RLM client is the ability to output environmental information about the application’s use of RLM. To enable this, your customer simply sets the environment variable RLM_DIAGNOSTICS to the name of a file, then runs your application. Once you call rlm_init(), RLM will write diagnostic information to the file name specified.
Note
Except on Windows, if you simply set RLM_DIAGNOSTICS without a value, the output will be sent to standard out - which may not be what you want. On Windows, if you want diagnostics in the console window, set RLM_DIAGNOSTICS=con in that window.
The resulting output will give the following information:
Time the program was run.
The working directory.
Relevant environment variables.
List of RLM’s idea of the hostids on the machine where the application was run (including your ISV-defined hostids).
The license files in use, in the order RLM will use them (can be re-ordered from your normal list if RLM_PATH_RANDOMIZE is set).
The parameters you used in your call to rlm_init()
A list of all local licenses which can be checked out. This list will have any roaming licenses listed first if RLM_ROAM is set, otherwise roaming licenses will be at the end of the list. In other words, the list will be in the order which RLM attempts to check them out. Each license file will also have an indication of what license server would be contacted if no local licenses can satisfy the request.
Note
For client-cached licenses, only the highest-numbered version will appear, even if there are lower-version licenses available. And only licenses cached by the same RLM version will appear in this output.
An example of this information is contained here.
RLM Diagnostics at 10/09/2009 15:40
Environment:
Hostname: paradise
Working directory: /user/matt/rlm/test
RLM platform: x64_s1
OS version: 5.10
RLM_CONNECT_TIMEOUT=<not set>
RLM Reference Manual Page 94 of 296RLM_EXTENDED_ERROR_MESSAGES=<not set>
RLM_LICENSE=2700@paradise:a.lic:b.lic
RLM_NO_UNLIMIT=<not set>
RLM_PATH_RANDOMIZE=<not set>
RLM_PROJECT=<not set>
RLM_QUEUE=<not set>
RLM_ROAM=1
RLMSTAT=<not set>
REPRISE_LICENSE=<not set>
HTTP_PROXY=<not set>
HTTP_PROXY_CREDENTIALS=<not set>
RLM hostid list:
1d8bbd06 ip=172.16.7.13
License files:
2700@paradise
a.lic
b.lic
rlm_init() parameters:
1: <empty>
2: client3
3: <empty>
Nodelocked/roaming licenses which can be checked out
Roaming Licenses:
test v1.0 OK
In license file a.lic
(no server)
test1 v1.0 OK
test2 v1.0 error:-5
test2 v1.0 error:-3
In license file b.lic
(server at: 2800@host2)
<none>
In this example, you can see that a checkout of “test2” would not succeed with a nodelocked license in license file a.lic, because the first test2 license has a bad license signature (error -5, RLM_EL_BADKEY) and the second test2 license has expired (error -3, RLM_EL_EXPIRED).
You can also see that this application will attempt a checkout from the license server running on node paradise at port 2700, if none of the local licenses will satisfy the checkout request.
Server-side Diagnostics
Pressing the “Diagnostics” button in the web interface will cause RLM to obtain the diagnostic information from all ISV servers, and put this information into a file ready for your customer to attach to an email message to send to your support department.
This information contains:
The time the diagnostics were run.
The working directory of rlm and the ISV servers.
Relevant environment variables.
A list of RLM’s idea of the hostids on the machine where the license server is running (including your ISV-defined hostids)
The license files in use, in the order RLM will use them.
The contents of all license files.
RLM status and statistics
For each ISV server:
The server status and statistics.
The license pool descriptions for all license pools.
The list of users for each license pool.
The RLM debug log file.
And, for each ISV server:
The last 20kb of ISV server debug log output (or 20 lines if output is going to stdout).
The last 20kb of report log output.
Note
For each license pool, the parameters of the pool are displayed followed by a list of users of that set of licenses. The userlist is displayed in this format:
user:host:pid:isv_def:rprod:ver:normal:res:out:hold
where:
user - is the username of the person holding the license
host - is the hostname where the license is in use
pid - is the process ID of the process holding the license
isv_def - is any ISV-defined data provided to RLM before checkout
rprod - is the requested product name
ver - is the requested version
normal - is the number of “normal” (ie, non-reservation) licenses in use
res - is the number of reservations in use
out - is the checkout time
hold - is the license hold time
An example of this information is shown here.
RLM Server Diagnostics at 10/20/2009 13:58
Environment:
Hostname: paradise
Working directory: /user/matt/rlm/rlm
RLM platform: x64_s1
OS version: 5.10
RLM_CONNECT_TIMEOUT=<not set>
RLM_EXTENDED_ERROR_MESSAGES=1
RLM_LICENSE=2700@Localhost
RLM_NO_UNLIMIT=<not set>
RLM_PATH_RANDOMIZE=<not set>
RLM_PROJECT=<not set>
RLM_QUEUE=<not set>
RLM_ROAM=<not set>
RLMSTAT=<not set>
RLM_LICENSE=<not set>
HTTP_PROXY=<not set>
HTTP_PROXY_CREDENTIALS=<not set>
RLM hostid list:
1d8bbd06 ip=172.16.7.13
License files:
a.lic
===========================================================
LICENSE FILE: a.lic ---- contents
===========================================================
HOST paradise ANY 2700
ISV reprise reprise.set reprise.opt
LICENSE reprise foo2 1.0 permanent uncounted hostid=ANY _ck=c91efcffc7
sig="60P0450NFBEQT82V5DJTY7VPJSFXW70963B791R22G3TEVDBUUS8FE2MNJKHTW0
K9DNED2D330"
LICENSE reprise test 1.0 permanent 2 _ck=13d7fcfe93 sig="60P04539JPQH1
UHD8S4JHU55J4HTAX9371F9WSG22HRTERSD0RY5DMDE424TMEGR7GQHDGX730"
===========================================================
Status for "rlm" on paradise (port 2700)
RLM software version v8.0 (build:1)
RLM comm version v1.1
debug log file: _stdout_
rlm Statistics --- Since Start --- Since Midnight --- Recent ---
Start time 10/20 13:58:12 10/20 13:58:13 10/20 13:58:13
Messages: 0 ( 0/sec) 0 ( 0/sec) 0 ( 0/sec)
Connections: 0 ( 0/sec) 0 ( 0/sec) 0 ( 0/sec)
ISV Servers
Name port Running Restarts
reprise 51391 Yes 0
===========================================================
ISV reprise status on paradise (port 51391)
reprise software version v8.0 (build:1)
reprise comm version v1.1
debug log file: _stdout_
report log file: /user/matt/rlm/rlm/reprise.rpt
reprise Statistics --- Since Start --- Since Midnight --- Recent ---
Start time 10/20 13:58:14 10/20 13:58:14 10/20 13:58:14
Messages: 2 ( 2/sec) 2 ( 2/sec) 2 ( 2/sec)
Connections: 1 ( 1/sec) 1 ( 1/sec) 1 ( 1/sec)
Checkouts: 0 ( 0/sec) 0 ( 0/sec) 0 ( 0/sec)
Denials: 0 ( 0/sec) 0 ( 0/sec) 0 ( 0/sec)
License removals: 0 ( 0/sec) 0 ( 0/sec) 0 ( 0/sec)
License pool status ----------
Userlist fmt: user:host:pid:isv_def:rprod:ver:normal:res:out:hold
Pool 1: foo2 v1.0 permanent 0+0 soft:0 inuse:0
h:ANY timeout:0 share:None trans:0
Usage for pool 1
matt:paradise:16253:::1.0:1:0:10/20 14:08:None
matt:paradise:16254:::1.0:1:0:10/20 14:08:None
Pool 2: test v1.0 permanent 0+2 soft:2 inuse:0
h: timeout:0 share:None trans:0
No Licenses in use for for pool 2
===========================================================
RLM debug log file last 20 lines
===========================================================
10/20 13:58 (rlm) RLM License Server Version 8.0BL1
Copyright (C) 2006-2009, Reprise Software, Inc. All rights reserved
10/20 13:58 (rlm) License server started on paradise
10/20 13:58 (rlm) Server architecture: x64_s1
10/20 13:58 (rlm) License files:
10/20 13:58 (rlm) a.lic
10/20 13:58 (rlm)
10/20 13:58 (rlm) Using options file rlm.opt
RLM Reference Manual Page 97 of 29610/20 13:58 (rlm) Web server starting on port 5054
10/20 13:58 (rlm) Using TCP/IP port 2700
10/20 13:58 (rlm) Starting ISV servers:
10/20 13:58 (rlm) ... reprise on port 51391
===========================================================
End rlm debug log
===========================================================
===========================================================
ISV reprise debug log file last 20 lines
===========================================================
10/20 13:58 (reprise) RLM License Server Version 8.0BL1 for ISV "reprise"
10/20 13:58 (reprise) Settings from RLM Version 8.0BL1 for ISV "reprise"
10/20 13:58 (reprise) Server architecture: x64_s1
Copyright (C) 2006-2009, Reprise Software, Inc. All rights reserved.
RLM contains software developed by the OpenSSL Project
for use in the OpenSSL Toolkit (http//www.openssl.org)
Copyright (c) 1998-2003 The OpenSSL Project. All rights reserved.
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com) All rights reserved.
10/20 13:58 (reprise) Using options file reprise.opt
10/20 13:58 (reprise) Report log started on /user/matt/rlm/rlm/reprise.rpt
10/20 13:58 (reprise)
10/20 13:58 (reprise) Server started on paradise (hostid: ANY) for:
10/20 13:58 (reprise) foo2 test
10/20 13:58 (reprise)
10/20 13:58 (reprise) License files:
10/20 13:58 (reprise) a.lic
10/20 13:58 (reprise)
10/20 13:58 (reprise) File descriptor limit increased from 256 to 65536
===========================================================
End reprise debug log
===========================================================
===========================================================
ISV reprise report log file contents (/user/matt/rlm/rlm/reprise.rpt)
(last 20kb only)
===========================================================
2 1.0 1 0 0 0 "ANY" "" "" "" "" "" 0 0 0 0
PRODUCT test 1.0 2 0 2 2 "" "" "" "" "" "" 0 0 0 0
10/19/2009 21:20
RLM Report Log Format 2, version 8.0, authenticated
ISV: reprise, RLM version 8.0 BL1
Logfile format Copyright (C) 2006-2009 Reprise Software, Inc.
For documentation on this format, email info@reprisesoftware.com
You are encouraged to build tools to process this data.
START paradise 10/19/2009 21:23:13
LICENSE FILE a.lic
PRODUCT foo2 1.0 1 0 0 0 "ANY" "" "" "" "" "" 0 0 0 0
PRODUCT test 1.0 2 0 2 2 "" "" "" "" "" "" 0 0 0 0
10/19/2009 21:23
.....
===========================================================
END ISV reprise report log file contents (/user/matt/rlm/rlm/reprise.rpt)
===========================================================
Product Debugging Information
To enable your application to output diagnostic information about any or all product names, set the environment variable RLM_DEBUG as follows:
RLM_DEBUG set to an empty value – show information about all products
RLM_DEBUG set to a string – show information about the product specified
Warning
DO NOT SET RLM_DEBUG WHEN RUNNING THE LICENSE SERVER!
This information can be obtained from the new rlmdebug utility (part of rlmutil), or directly from your application. If the RLM_DEBUG environment variable is set, the debugging information will be output to stdout at the end of the rlm_init() call. For use of rlmdebug (which does not require the RLM_DEBUG environment variable), see the RLM License Administration Manual.
Note
The most accurate information will be obtained from your application, since the exact license file path used by the application will be available to the rlm debugging routines. The stand-alone utility cannot know about default license files and paths which you set in your rlm_init() call. Please note that RLM_DEBUG will only report on licenses which are present in local license files. In other words, if you have a license path like “5053@server”, RLM_DEBUG will report on whether the server is up, but it will not report on individual licenses served by that server.
For example, with RLM_DEBUG set to an empty string:
% setenv RLM_DEBUG
The following (sample) output is displayed:
RLM DEBUG for all products
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
On the other hand, with RLM_DEBUG set to the name test:
% setenv RLM_DEBUG test
The following (sample) output is displayed:
RLM DEBUG for product "test"
In license file: ../rlm/z.lic (5555@paradise):
Checking server machine "paradise" ... server UP
Checking RLM server at port 5555 ... server UP
No matching products found in license file
In license file: a.lic:
Product: test, ISV: reprise, Single
1 product instances found