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 The 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: rlmadduser, rlmdebug, rlmdown, rlmhostid, rlmnewlog, rlmremove, rlmreread, rlmstat, rlmswitch, rlmswitchr, rlmanon,.

All utilities (with the exception of rlmremove) can be run via rlmutil:

rlmutil [utility_name]

e.g.:

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 Access Control to the RLM Web Interface. In addition, starting in RLM v13.0, ISV servers can authenticate requests from clients. See Client Authentication in the next section for more information.

All utilities take the following options:

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

Add a user to the ISV server options file

Usage:

rlmutil rlmadduser [options-filename <username> <password>]

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 Client Authentication for more information.

rlmanon

Change user and host names in report log file

Usage:

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

Display debugging information about products

Usage:

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:

% setenv RLM_DEBUG

When the application is run the following (sample) output is displayed (in addition to any other output the application may produce):

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

Shuts down the license server

Usage:

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).

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

Print the hostid of this machine

Usage:

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 RLM hostids.

rlmnewlog

Print the hostid of this machine

Usage:

rlmutil rlmnewlog <isv> [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

Remove a checked-out license from a user

Usage:

rlmutil rlmremove [-q] <server-host> <port> <isv> <handle>

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:

reprise license usage status on melody (port 1215)

test3 v1.000: tom@sun1(v1.0) (809f418) 1/0 at 02/06 09:59

rlmreread

Cause the license server(s) to reread their license and option file(s)

Usage:

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.

Unix only

The servers will do a reread if a SIGHUP signal is sent to the RLM process.

rlmstat

Obtains status from the license servers

Usage:

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:

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:

% 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: <stdout>
        reprise Report log filename: <stdout>
        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

test v1.0

it will be something like this:

test v1.0, pool: 7, id: 60

The meaning of the license usage line:

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:

[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:

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:

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

% 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)

% 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

Switches the debug log info to a new file

Usage:

rlmutil rlmswitch [isv] <new-log-file-name>

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

Switches the report log info to a new file

Usage:

rlmutil rlmswitchr [isv] <new-log-file-name>

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.