######################################### 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. .. collapse:: An example of this information is contained here. .. code-block:: text 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= RLM Reference Manual Page 94 of 296RLM_EXTENDED_ERROR_MESSAGES= RLM_LICENSE=2700@paradise:a.lic:b.lic RLM_NO_UNLIMIT= RLM_PATH_RANDOMIZE= RLM_PROJECT= RLM_QUEUE= RLM_ROAM=1 RLMSTAT= REPRISE_LICENSE= HTTP_PROXY= HTTP_PROXY_CREDENTIALS= RLM hostid list: 1d8bbd06 ip=172.16.7.13 License files: 2700@paradise a.lic b.lic rlm_init() parameters: 1: 2: client3 3: 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) | 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 .. collapse:: An example of this information is shown here. .. code-block:: text 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= RLM_EXTENDED_ERROR_MESSAGES=1 RLM_LICENSE=2700@Localhost RLM_NO_UNLIMIT= RLM_PATH_RANDOMIZE= RLM_PROJECT= RLM_QUEUE= RLM_ROAM= RLMSTAT= RLM_LICENSE= HTTP_PROXY= HTTP_PROXY_CREDENTIALS= 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 :ref:`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: .. code-block:: text 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: .. code-block:: text 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