.. _license-administration-tools: ############################ License Administration Tools ############################ The RLM server is delivered with an embedded Web Server to perform normal administration tasks. For more information on the web server interface, see :ref:`rlm-web-server`. In addition, the RLM kit is delivered with several command-line administration tools to perform various administration tasks on the license servers as well as to retrieve information about licensing parameters. While the RLM web interface is the preferred method to administer RLM license servers, the command-line tools are provided as a convenience for use in administration scripts and programs. License Administrators can manage RLM by using the administration tools, as described in detail below: :ref:`rlmadduser`, :ref:`rlmdebug`, :ref:`rlmdown`, :ref:`rlmhostid`, :ref:`rlmnewlog`, :ref:`rlmremove`, :ref:`rlmreread`, :ref:`rlmstat`, :ref:`rlmswitch`, :ref:`rlmswitchr`, :ref:`rlmanon`,. All utilities (with the exception of **rlmremove**) can be run via **rlmutil**: .. code-block:: text rlmutil [utility_name] e.g.: .. code-block:: text rlmutil rlmadduser RLM had the ability to restrict usage of the **remove**, **reread**, **shutdown**, **status** and **option editing** requests via The RLM Options File previously, these are now controlled with user roles in the web interface. For a description of the new roles, see :ref:`access-control-web-interface`. In addition, starting in RLM v13.0, ISV servers can authenticate requests from clients. See :ref:`client-authentication` in the next section for more information. All utilities take the following options: .. list-table:: :header-rows: 1 * - Option - Meaning * - -c license_spec - Use 'license_spec' instead of the current directory to find license files. 'license_spec' can be either a license file or a port\@host specification. The -c option overrides RLM_LICENSE. * - -dat - Use \*.dat as the license file instead of \*.lic. * - -h - Print usage information and exit. * - -q - Don't prompt/quiet (for rlmdown/rlmremove/rlmswitch/rlmhostid). -q also turns off the verification of license checksums and corresponding error messages for all commands. * - -v - Print version number and exit. * - -z - Password use password as license password for command (enclose in quotes if password contains white space). ------ .. _rlmadduser: ********** rlmadduser ********** Add a user to the ISV server options file ========================================= Usage: .. code-block:: text rlmutil rlmadduser [options-filename ] This command adds the specified username/password pair to the end of the options-file specified. .. note:: * RLM Usernames and passwords must be <= 10 characters long * RLM Usernames and passwords are CASE SENSITIVE * Usernames and passwords cannot contain white space or any of the following characters: "<", ">", "&", “:”, and single (''' or '`') or double-quotes ("). * If there are no USER records in the ISV server options file, the server does no authentication of clients. **rlmadduser** is new in RLM v13.0. All components must be RLM v13.0 or later for this functionality to work. This functionality is not supported for HTTPS communications in RLM Cloud. See :ref:`client-authentication` for more information. ------ .. _rlmanon: ******* rlmanon ******* Change user and host names in report log file ============================================= Usage: .. code-block:: text rlmanon [logfile] rlmanon reads the report log file *logfile*, and changes all the user and host names to the form **uNNN** and **hNNN**, where NNN is a sequence number. The result is written into the file *logfile.anon*. There is a one-to-one mapping from a particular user or host name to its corresponding sequence number, so that reports generated from the log file will accurately reflect the number of unique users and hosts as well as the sharing of licenses. However, actual user and host information is removed from the output *logfile.anon*. *rlmanon* creates a new authenticated report log file if the input log file is an unmodified authenticated log file. If the input file has incorrect authentication records, an error message is generated, and no output file is written. .. note:: The **rlmanon** cannot be run via **rlmutil**. ------ .. _rlmdebug: ******** rlmdebug ******** Display debugging information about products ============================================ Usage: .. code-block:: text rlmutil rlmdebug [product] *rlmdebug* prints information about the specified *product* (or all products if *product* is not specified). The debugging information is written to stdout (this requires running in a command window on Windows systems). This capability is also built into every RLM v9.0 (or later) application. To use the debugging information directly from the application, set the *RLM_DEBUG* environment variable to the product name (or to an empty string if you wish to debug all products). (Note: you do not need to use the *RLM_DEBUG* environment variable with the **rlmdebug** utility.) Sample rlmdebug output: .. code-block:: text % setenv RLM_DEBUG When the application is run the following (sample) output is displayed (in addition to any other output the application may produce): .. 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 ------ .. _rlmdown: ******* rlmdown ******* Shuts down the license server ============================= Usage: .. code-block:: text rlmutil rlmdown [-q] [isv] [-c license_file] *rlmdown* shuts down the first license server in the license path RLM_LICENSE. If the *-q* option is specified, the shutdown happens without a confirmation prompt. If the optional *isv* is specified, only that ISV's server is shut down. In order to shut down the RLM server itself, specify the ISV name as **RLM**. (Note: RLM must be in capital letters). .. admonition:: Note for Unix systems The servers can also be shut down by sending a SIGTERM signal to the RLM process. SIGTERM shuts down all the servers, including RLM. ------ .. _rlmhostid: ********* rlmhostid ********* Print the hostid of this machine ================================ Usage: .. code-block:: text rlmutil rlmhostid [[-]32|disksn|ether|gc|internet|ip|ipv6|uuid|host|user|rlmid1] [-q] *rlmhostid* prints the hostid of the machine it is running on. If the *-q* flag is specified, the hostid is printed without any other output. Hostid types described in :ref:`RLM hostids `. ------ .. _rlmnewlog: ********* rlmnewlog ********* Print the hostid of this machine ================================ Usage: .. code-block:: text rlmutil rlmnewlog [new-log-file-name] *rlmnewlog* causes the ISV server isv to move the current reportlog output to new-log-file-name and continue logging to the original filename. .. note:: The *new-log-file-name* must be on the same filesystem as the original reportlog, otherwise the command will fail. The ISV server renames the old reportlog, it does not copy the data. *rlmnewlog* will fail if the server is not currently writing a report log. ------ .. _rlmremove: ********* rlmremove ********* Remove a checked-out license from a user ======================================== Usage: .. code-block:: text rlmutil rlmremove [-q] *rlmremove* removes a checked-out license. If the *-q* option is specified, the license is removed without a confirming prompt. *server-host*, *port*, and *handle* are indicated in the *rlmstat* output. In the following example *rlmstat* output, the *server-host* is **melody**, the *port* is **1215**, and the *handle* is **809f418** and the *isv* is *reprise*: .. code-block:: text reprise license usage status on melody (port 1215) test3 v1.000: tom@sun1(v1.0) (809f418) 1/0 at 02/06 09:59 ------ .. _rlmreread: ********* rlmreread ********* Cause the license server(s) to reread their license and option file(s) ====================================================================== Usage: .. code-block:: text rlmutil rlmreread [isv] *rlmreread* causes the specified ISV server *isv* to reread its license file, and options file if specified in the license file (or if in the default location *isv*.opt). If *isv* is omitted, the reread command is sent to RLM and all ISV servers. If *isv* is specified as *rlm*, then only the RLM server rereads its license file. When *rlm* rereads its license file, it starts any new ISV servers that were not present before. .. note:: RLM performs an automatic reread of the license file(s) every night at midnight. .. admonition:: Unix only The servers will do a reread if a SIGHUP signal is sent to the RLM process. ------ .. _rlmstat: ******* rlmstat ******* Obtains status from the license servers ======================================= Usage: .. code-block:: text rlmutil rlmstat [-a] [-f] [-i [isv] ] [-I] [-l [ isv] ] [-n [host] ] [-p [product] ] [-u [user] ] [-z password] *rlmstat* retrieves status from the license servers and prints it. Control over the status retrieved from *rlmstat* is specified as follows: .. list-table:: :header-rows: 1 * - Option - Parameter (meaning if present) - Result * - -a - (no parameters) - Print all status from RLM and all ISV servers. * - -avail - [-i isv] [-p product] [-b] - Reports free license availability (see below). * - -f - “full” license listing - Reports more information about the licenses in use. * - -i - Display this ISB only - Display license checkout info from ISVs. * - -I - Display isv-defined checkout data - “[I: isv-data]” appended to each user line. * - -l - Display this *isv* only - Display license pooling info from ISVs. * - -n - Display licenses from this *host* only. - Display license checkout info from ISVs. * - -p - Display licenses for this *product* only. - Display license checkout info from ISVs. * - -u - Display licenses from this *user* only. - Display license checkout info from ISVs. * - -z - License password. - Supplies password to license server. Example rlmstat output: ----------------------- .. code-block:: text % rlmutil rlmstat -a rlmstat v9.1 Copyright (C) 2006-2011, Reprise Software, Inc. All rights reserved. rlm status on bigserver (port 5053), up 00:03:51 rlm software version v9.1 (build:3) rlm comm version: v1.1 Startup time: Wed Jul 6 13:27:42 2011 Todays Statistics (00:03:50), init time: Wed Jul 6 13:27:43 2011 Recent Statistics (00:03:50), init time: Wed Jul 6 13:27:43 2011 Recent Stats Todays Stats Total Stats 00:03:50 00:03:50 00:03:51 Messages: 9 (0/sec) 9 (0/sec) 9 (0/sec) Connections: 7 (0/sec) 7 (0/sec) 7 (0/sec) --------- ISV servers ---------- Name Port Running Restarts reprise 62503 Yes 0 ------------------------ reprise ISV server status on bigserver (port 62503), up 00:03:49 reprise software version v9.1 (build: 3) reprise comm version: v1.1 reprise Debug log filename: reprise Report log filename: Startup time: Wed Jul 6 13:27:44 2011 Todays Statistics (00:03:49), init time: Wed Jul 6 13:27:44 2011 Recent Statistics (00:03:49), init time: Wed Jul 6 13:27:44 2011 Recent Stats Todays Stats Total Stats 00:03:49 00:03:49 00:03:49 Messages: 17 (0/sec) 17 (0/sec) 17 (0/sec) Connections: 6 (0/sec) 6 (0/sec) 6 (0/sec) Checkouts: 2 (0/sec) 2 (0/sec) 2 (0/sec) Denials: 0 (0/sec) 0 (0/sec) 0 (0/sec) Removals: 0 (0/sec) 0 (0/sec) 0 (0/sec) ------------------------ reprise license pool status on bigserver (port 62503) test v1.0 count: 1, # reservations: 0, inuse: 1, exp: 1-jan-0 obsolete: 0, min_remove: 20, total checkouts: 1 test2 v1.0 count: 1, # reservations: 0, inuse: 1, exp: 1-jan-0 obsolete: 0, min_remove: 20, total checkouts: 1 test3 v1.0 count: 100, # reservations: 0, inuse: 0, exp: 1-jan-0 obsolete: 0, min_remove: 20, total checkouts: 0 ------------------------ reprise license usage status on bigserver (port 62503) test v1.0: joe@library 1/0 at 07/06 13:27 (handle: 41) test2 v1.0: sam@kitchen 1/0 at 07/06 13:28 (handle: 81) In this output, the first section (before the line of dashed lines ---------) is the status of the RLM server, the next section is the status of the ISV server *reprise* (there would actually be one section of status for each ISV server if there were more than one running). Next comes the license pool info for each ISV server (again, only one section for the *reprise* server), followed by the actual license usage information. Also, please note that the expiration date shown in this output is the expiration date of the **first license to expire** out of all the licenses used to create the license pool in the license server. When more than one license is used to create a single license pool (licenses are combined when all relevant parameters of 2 different licenses match), then only the **earliest expiration date** is shown. The other license(s) may have any expiration date that has not yet expired. To determine the expiration date of all licenses used to make up a license pool the actual license file must be consulted. Also note that licenses from different license files could be combined to make a single license pool. Beginning in RLM v14.2, the first line of the product information (“test v1.0” in the example above), will contain the server's license pool #, and an ID, if specified. So rather than .. code-block:: text test v1.0 it will be something like this: .. code-block:: text test v1.0, pool: 7, id: 60 The meaning of the license usage line: .. code-block:: text test v1.0: joe@library 1/0 at 07/06 13:27 (handle: 41) is as follows: * **test** is the product name * **v1.0** is the license version (from the license file) for test * **joe** is the user who is using the license * **library** is the host on which tom is using the license * **(41)** is the license handle in the server. This handle is used by the rlmremove command. * **1/0** indicates that 1 unreserved and 0 reserved licenses are in use * **at 07/06 13:28** is the time the licenses were checked out And if the optional “-I” switch is specified, the following will be appended to the line, if there is any isv-defined checkout data: .. code-block:: text [I: isv-data] where “isv_data” is the isv-defined checkout data. If the -f option is used with rlmstat, additional information about the license usage will be displayed. -f is available in RLM v12.5, and in v12.5, the additional information displayed is the requested version, displayed as such: .. code-block:: text test v1.0 (req: v0.8): joe@library 1/0 at 07/06 13:27 (handle: 41) rlmstat -avail command ====================== The *rlmstat -avail* command reports on license availability for a specified license, a specified ISV, or all licenses from all ISVs. Usage: .. code-block:: text rlmutil rlmstat -avail [-i isv] [-p product] [-b] If *-i isv* is specified, only licenses from the selected ISV are displayed. If *-p product* is specified, only the selected product is displayed. If *-b* is specified, license availability is combined across license servers. If you are looking for the availability of a license from a particular ISV, it is more efficient to specify the ISV name in the command. If you do not specify the ISV name, rlmstat must contact the RLM server to request a list of ISV servers, then request information from each ISV server. If you specify the ISV, then only that ISV server is contacted. Note also that there are situations when you may not be able to check out a license that is listed as available. This can happen if, for example, you are on the EXCLUDE list for a particular product, not on the INCLUDE list, already exceeded your MAX usage, etc. Conversely, you might be able to check out one that is listed as not available. This could happen if that license is shared and you can share an existing checked-out license, or if one of the reservations for the license is for you (rlmstat -avail lists free available licenses; reservations are not generally available). Example rlmstat -avail output ----------------------------- .. code-block:: text % rlmutil rlmstat -avail -i reprise rlmstat v15.1 Copyright (C) 2006-2011, Reprise Software, Inc. All rights reserved. License availability for all products from ISV "reprise" server host: telecard (port 5053) test1 v1.000 available: 15 test1 v1.000 hostid: a8c00301 available: 10 test5 v3.000 hostid: a8c00301 available: 2 test5 v3.000 available: 10 test v1.000 available: 10 server host: spinout (port 5053) test1 v1.000 available: 15 test1 v1.000 hostid: a8c00301 available: 10 test5 v4.000 hostid: ip=172.16.7.28 available: unlimited test5 v2.300 available: 15 test5 v3.000 hostid: a8c00301 available: unlimited test5 v3.000 available: 73 Example rlmstat -avail -b output (same situation as above) ---------------------------------------------------------- .. code-block:: text % rlmutil rlmstat -avail -i reprise -b rlmstat v15.1 Copyright (C) 2006-2011, Reprise Software, Inc. All rights reserved. License availability for all products from ISV "reprise" ISV: reprise test1 v1.000 available: 30 test1 v1.000 hostid: a8c00301 available: 20 test5 v3.000 hostid: a8c00301 available: unlimited test5 v3.000 available: 83 test5 v4.000 hostid: ip=172.16.7.28 available: unlimited test5 v2.300 available: 15 ------ .. _rlmswitch: ********* rlmswitch ********* Switches the debug log info to a new file ========================================= Usage: .. code-block:: text rlmutil rlmswitch [isv] *rlmswitch* causes the server *isv* to close the current debug log file and begin output to *new-log-filename*. If *isv* is not specified, or if specified as *rlm*, the RLM server's debug log is switched. ------ .. _rlmswitchr: ********** rlmswitchr ********** Switches the report log info to a new file ========================================== Usage: .. code-block:: text rlmutil rlmswitchr [isv] *rlmswitchr* causes the ISV server *isv* to close the current reportlog file and begin output to *new-log-file-name*. This command will fail if the server is not currently writing a report log.