Reportlog File Format

The RLM servers create a reportlog in three formats, selectable by the License Administrator. The 3 formats are “std”, “small”, and “detailed”.

Note that prior to RLM v9.3 there was no “detailed” format on Windows; specifying “detailed” would produce a standard report output. Starting in RLM v9.3, the detailed report will be produced, but all fractional seconds fields will be 0.

The formats differ only in the contents of the checkout and check-in records, as described below. Common to all formats are the classes of data logged, and the data for all except check-in and checkout records.

The reportlog format has a version number in the start record. All data described applies to all versions of the reportlog, except where indicated.

The data is:

  • authentication data

  • check-in

  • checkout

  • dequeue

  • dynamic reservation created/removed (added in RLM v12.2)

  • isv-specific data

  • license denial

  • license in use (added in RLM/reportlog v10.0)

  • log file start

  • log file end (can correspond to a switch to a new logfile)

  • meter transaction data (added in RLM v9.3)

  • periodic timestamps

  • queue

  • roam extend

  • server shutdown

  • server time jumped

  • server reread of license/option file

  • support for a product (feature) - one for each license pool at log file start time

  • temporary license creation/removal (added in v14.1 – RLM Cloud servers only)

Note

In every reportlog entry which contains a username or a hostname, the field is presented without quotes. However, if the corresponding value is empty, a pair of double-quotes (“”) will be placed in the reportlog where the username or hostname would be.

A reportlog consists of the following data:

  • log file start records

  • one PRODUCT support line for each supported product

  • one license in use record for each currently-checked-out license

  • all license activity data, including checkouts, check-ins, AUTH records, etc.

  • one license in use record for each currently-checked-out license

  • optional SWITCH line

  • END line

  • final AUTH line

The format of the data logged is described in the following sections.

Authentication data

All formats:

AUTH section signature

This line specifies the authentication signature (signature) for the preceding data in the file. If any of the data since the last AUTH line is modified, the authentication value will no longer be correct. This would typically be used by an ISV if they are using the report log data for post-use billing. The ISV can run a utility in order to verify the authentication records in a report log. Report writers can (and should) ignore this line.

BADAUTH (x errors, y sessions, z authentication sections)

When rlmanon processes a reportlog with AUTH errors, it rewrites the file with all bad AUTH records, and places this line in each section. Prior to RLM v12.3, rlmanon simply stopped processing when a bad AUTH section was encountered. In v12.3, the entire report log will be processed, but all sections will have bad AUTH sections, allowing you to process the anonymized report log but not verify the integrity of the data in it.

check-in

“standard” format:

IN why product version user host “isv_def” count cur_use cur_resuse server_handle mm/dd hh:mm:ss

“detailed” format:

IN why product version user host “isv_def” count cur_use cur_resuse server_handle mm/dd hh:mm:ss.tenths_of_msec

“small” format:

IN why count server_handle hh:mm

The server_handle parameter is a hex number. All other numbers are decimal.

The isv_def field contains the value of the optional ISV-defined field.

The why parameter is one of:

why value

Reason

1

“Normal” check-in by application

2

Application exited, automatic check-in

3

License removed by (rlmremove) utility

4

License removed by server after timeout

5

License hold/minimum checkout period expired

6

Client requested license dequeue

7

Portable hostid removed

8

Failed host back up

9

Server lost its transferred licenses

10

Meter ran out of count during a periodic decrement

11

Client failed to send heartbeat within “promise” interval.

12

Temporary License expired (RLM Cloud only)

13

Temporary license returned (RLM Cloud only)

Note

why value 12 is new in RLM v14.1, on RLM Cloud only.

The cur_use and cur_resuse fields indicate the current number of free licenses in use and reservations in use after this check-in.

The ver parameter will be the version requested, not the version of the license which satisfied the request. To find the version of the license that satisfied the request, check the version field in the matching checkout request referenced by “server_handle”.

Note

On Windows, tenths_of_msec will always be 0.

checkout

“standard” format:

OUT product version pool# user host “isv_def” count cur_use cur_resuse server_handle share_handle process_id “project” “requested product” “requested version” mm/dd hh:mm:ss

“detailed” format:

OUT product version pool# user host “isv_def” count cur_use cur_resuse server_handle share_handle process_id “project” “requested product” “requested version” mm/dd hh:mm:ss.tenths_of_msec “client_machine_os_info” “application argv0” roam_days roam_handle client-ip-address

“small” format:

OUT product version user host “isv_def” count server_handle share_handle hh:mm

Note

The project field will contain the contents, if any, of the RLM_PROJECT environment variable of the application that checked out the license. This project name has a maximum of 32 characters.

The isv_def field contains the value of the optional ISV-defined field.

The cur_use and cur_resuse fields indicate the current number of free licenses in use and reservations in use after this checkout.

The server_handle, share_handle, and process_id parameters are hex numbers. All other numbers are decimal.

The share_handle field contains the value of the handle of a shared license.

Note

The share_handle is the handle of the first license that was checked out in this group of shared licenses. It is possible (and perhaps even likely) that the handle associated with the group will change if the first license is checked in before other shared licenses are checked in. In this case, new checkouts will specify a share_handle of a different license in the group of shared licenses.

The requested product and requested version fields represent the requested product and version in the application’s checkout call. In the case of a token-based license, the product (or products) actually checked out will differ, and requested product and requested version provide what the application actually requested.

The process_id field is the PID of the process requesting the license. The PID will be -1 (ffffffff), when the server logs a roaming “checkout” at startup time.

The client_machine_os_info field is a combination of the platform type and OS version running on the client machine. This string is a maximum of 41 bytes long, and is in the format:

“rlm_platform_name os_version”

For example:

“x64_w42 5.1” - a windows system running Windows XP.

The application argv0 field is the argv[0] of the product requesting the license.

The roam_days field is the (hex) number of days for which the license will roam PLUS 1. This will appear on the initial checkout of a roaming license as well as on the subsequent checkout when the server checks out an already-roaming license. Beginning in rlm v11.1, roam_days is one greater than it had been in prior versions, so a value of 2 means a license roaming for 1 day (i.e., RLM_ROAM set to 1), meaning until the end of tomorrow.

On Windows, tenths_of_msec will always be 0.

The roam_handle field is the server handle (in hex) of a roaming license re-checkout. This field will be non-zero when the server checks out an already-roaming license (as it does when starting up).

The client-ip-address is new in reportlog v14.1. It is of the form a.b.c.d If the client’s IP address is unknown, it will appear as 0.0.0.0.

dequeue

“standard” format:

DEQUE why product version user host “isv_def” count server_handle mm/dd hh:mm:ss

“detailed” format:

DEQUE why product version user host “isv_def” count server_handle mm/dd hh:mm:ss.tenths_of_msec

“small” format:

DEQUE why count server_handle hh:mm

The server_handle parameter is a hex number. All other numbers are decimal.

On Windows, tenths_of_msec will always be 0.

Note

The dequeue record is identical to the check-in record except the keyword is “DEQUE” rather than “IN”. A dequeue record is generated on all other servers when a client is granted a license on one server.

dynamic reservation

All formats:

DYNRES [create | remove] user host license-pool count “string” mm/dd hh:mm:ss

All numbers are decimal.

string is the identifier used to create the reservation.

The DYNRES record is new in v12.2.

isv-specific data

All formats:

log mm/dd hh:mm:ss isv-specific-data-here

Individual ISVs can log unformatted data to the report log. This data appears in a “log” record.

license denial

“standard” and “small” formats:

DENY product version user host “isv_def” count why last_attempt pid mm/dd hh:mm

“detailed” format:

DENY product version user host “isv_def” count why last_attempt pid mm/dd hh:mm:ss.tenths_of_msec

The why parameter is an RLM_LICENSE error status return (RLM_EL_xxxx) as documented in Status Values.

The last_attempt parameter is 0 if the application will attempt another checkout, or non-zero if this is the last attempt it will make to check the license out. Thus, denials with last_attempt set to 0 are not “true” denials of the license to the application, they are simply denials of the license at this license server. A report writer should only report application license denials when last_attempt is set to a non-zero value.

The pid field is the process’s PID, in hex. The pid field is new in reportlog v11.3.

The isv_def field contains the value of the optional ISV-defined field.

On Windows, tenths_of_msec will always be 0.

license in use

All formats:

INUSE product version pool# user host “isv_def” count server_handle share_handle process_id mm/dd hh:mm:ss

The isv_def field contains the value of the optional ISV-defined field.

The server_handle and process_id parameters are hex numbers. All other numbers are decimal.

The process_id field is the PID of the process requesting the license.

License in use records are new in RLM v10.0 and appear both at the beginning and the end of the report log if any licenses are in use at that time.

The share_handle field contains the value of the handle of a shared license. This field is new in reportlog v12.2.

log file start

All formats:

  • SWITCH from old-reportlog-name (new in v14.0, not authenticated)

  • RLM Report Log Format d, version x.y authentication flag

  • REPROCESSED with rlmanon vx.y

  • ISV: <isvname>, RLM version a.b BLc

  • <several lines of header text>

  • START hostname mm/dd/yyyy hh:mm

  • TIMEZONE minutes-west-of-UTC daylight rules # readable version of data

  • LICENSE FILE filename

The d in the first line is the format: 0 for “std”, 1 for “small”, and 2 for “detailed” x.y is the reportlog version. Reportlog v1.0 corresponds to RLM version 1.0. reportlog v1.1 corresponds to RLM v1.1. The authentication flag is either blank (no authentication) or the string “, authenticated”. All report logs are authenticated.

The second line will be present if the rlmanon utility was used to anonymize the reportlog data. The version of rlmanon corresponds to the RLM version. rlmanon first appeared in RLM v4.0, however while this was added in RLM v4.0, this line can appear in any reportlog version, since rlmanon can process any version of reportlog. Note that this line can be repeated if multiple runs of rlmanon were made on the same log file.

The third line displays the ISV name, and the RLM software version of the ISV server (a.b BLc, BL means “Build”).

In general, numeric data is in decimal format. The 3 exceptions to this are server_handle, share_handle, and process_id parameters which are always hex numbers.

The TIMEZONE line is new in RLM v12.3 This represents the server’s timezone data: the first number is the minutes west of UTC time; the second number indicates whether daylight savings rules ever apply in this timezone. The data after the # is a human-readable version of the timezone information.

There will be one LICENSE FILE line(s) for each license file which the server is processing.

Note that the “SWITCH from” line is not included in the report authentication.

log file end

All formats:

SWITCH to filename (if an rlmswitch was done)

END mm/dd/yyyy hh:mm

meter decrement

All formats:

METER_DEC license_handle meter_counter amount_decremented mm/dd hh:mm:ss[.tenths_of_msec]

A meter decrement record will immediately follow a checkout record for a metered license. In addition, an additional meter decrement record will appear periodically when the meter is decremented for this product. The license handle is a hex value; both meter counter and amount decremented are decimal.

The format is the same for all reportlog types, with the exception of the time - in the detailed reportlog format, tenths of milliseconds are added.

periodic timestamp

All formats:

mm/dd/yyyy hh:mm

Timestamps are performed by the ISV servers every night just after midnight.

Timestamps are added to the log file every 30 minutes.

queue

“standard” format:

QUE product version user host “isv_def” count server_handle “project” “requested product” “requested version” mm/dd hh:mm:ss

“detailed” format:

QUE product version user host “isv_def” count server_handle “project” “requested product” “requested version” mm/dd hh:mm:ss.tenths_of_msec

“small” format:

QUE product version user host “isv_def” count server_handle hh:mm

The server_handle parameter is a hex number. All other numbers are decimal.

The project field will contain the contents, if any, of the RLM_PROJECT environment variable of the application that checked out the license. This project name has a maximum of 32 characters.

The isv_def field contains the value of the optional ISV-defined field.

On Windows, tenths_of_msec will always be 0.

If the queued license becomes available, a checkout record will be logged with the same handle. If the client abandons the checkout, however, no other records will be logged.

roam extend

The roam extend record has only a single format, for all 3 reportlog formats:

ROAM_EXTEND product version pool# user host “isv_def” #days_extended server_handle process_id mm/dd hh:mm:ss

The isv_def field contains the value of the optional ISV-defined field.

The #days_extended parameter is the # of days which the roam was extended. So, if a license was originally roaming for 6 days, then extended to 10 days, this parameter will be 4, independent of which day the extension was done.

The server_handle and process_id parameters are hex numbers. All other numbers are decimal.

The process_id field is the PID of the process requesting the license. Note that if the pid is -1 (ffffffff), this means that the roam was extended by the RLM web interface when the client was no longer connected to the server.

Roam extend records are new in RLM v10.0.

server shutdown

All formats:

SHUTDOWN user host mm/dd hh:mm:ss

server time jump

All formats:

TIMEJUMP [+ | -]minutes mm/dd hh:mm:ss

The ISV server logs this when the time changes by more than 15 minutes on subsequent passes thru its main loop. The main loop executes whenever there is a message to process, but not less frequently than once/minute.

server reread of license/option file

All formats:

REREAD user host mm/dd hh:mm:ss

support for a product

There will be one record per license pool for each product served. These lines come immediately after a START or REREAD record. Note that there is not a one-to-one correspondence between the support records and LICENSE lines in the license file.

All formats:

PRODUCT name version pool# count #reservations soft_limit “hostid” “contract” “customer” “issuer” “line_item” “options” share max_share type named_user_count meter_type meter_counter meter_initial_decrement meter_period meter_period_decrement

  • count is the number of free licenses (i.e., non-reserved licenses)

  • #reservations is the number of reserved licenses (not generally available).

  • pool# is an internal server pool identifier. This number appears in checkout records in some formats.

  • line_item is the contents of the product’s _line_item field, used for mapping license product names to actual purchased products.

  • meter_type is always 0 in RLM v9.3. Other values may be defined in later versions. A non-zero value in meter_counter indicates a metered license.

  • meter_counter is the counter which is used for this product.

  • meter_initial_decrement is the amount to be decremented from the meter when a license is checked out.

  • meter_period is the number of minutes before an additional decrement is performed (0 means no periodic decrements)

  • meter_period_dec is the amount to be decremented from the meter each meter_period minutes.

Temporary license creation/removal

All formats:

TEMP [create | remove | restart | expired] product version license-pool user host “isv_def” expdate exptime server_handle mm/dd hh:mm:ss

The server_handle is a hex number. All other parameters are strings.

  • server_handle is the handle of the associated checkout. Temporary licenses are created after a successful checkout.

  • expdate is the expiration date (local time on the server) of the temporary license.

  • exptime is the expiration time (local time on the license server) of the temporary license.

On a server restart, there will be a TEMP restart record with (possibly) a different license-pool value if the server’s licenses have been modified before the restart. This is not a new temporary license, it is essentially a checkout of the same temporary license which was created earlier.

When a temporary license is refreshed, a new TEMP create record will be logged, with the same time as the original TEMP create record (or INUSE record, if the server preformed a reread). This new record does not represent an additional checkout, however the expdate and exptime fields will be updated. For example, a server had a temporary license and performed a reread:

Before the reread, a temp license was created that expired at 15:55:

TEMP create test2 2.0 2 matt zippy "" 2020-05-19 15:55 41 05/19 15:45:43

After the reread, the in-use temp license is logged, then later refreshed to 15:58:

INUSE test2 2.0 2 matt zippy "" 1 41 41 4a07 05/19 15:45:43
TEMP create test2 2.0 2 matt zippy "" 2020-05-19 15:58 41 05/19 15:45:43

The TEMP record is new in v14.1 and appears on RLM Cloud servers only.

Reportlog version change history

V14.1 reportlog changes

The OUT record in detailed format now includes the client’s IP address

The TEMP_CREATED record is new (RLM Cloud servers only)

The check-in why values 12 and 13 are new (RLM Cloud servers only)

V14.0 reportlog changes

SWITCH from old-reportlog added to header

V12.3 reportlog changes

The TIMEZONE record is added to the header information.

The BADAUTH record is added by rlmanon when processing logs with AUTH errors.

V12.2 reportlog changes

The share handle is added to INUSE records

The DYNRES record is added.

V12.1 reportlog changes

The Server Time Jump (TIMEJUMP) record is added.

V11.3 reportlog changes

The DENY records now include the process’s PID.

V11.1 reportlog changes

roam_days is now one greater than prior versions (and one greater than the value of

RLM_ROAM). roam_days == 2 now means roaming until midnight tomorrow.

v10.0 reportlog changes

All logfiles will now log all licenses currently in use both at the start and the end of the reportlog, with the new “INUSE” record.

The ROAM_EXTEND record is added.

v9.3 reportlog changes

Windows systems will now produce a detailed reportlog, however, all fractional seconds fields will be 0.

meter decrement records added.

metering parameters added to the support record

The logfile is timestamped every 30 minutes

v9.0 reportlog changes

roam days and roam handle added to the OUT record for detailed format.

All fields which have a username or a hostname will now contain only an empty pair of double-quotes (“”) if the corresponding value is empty. This only happens when rlm cannot determine the username or hostname on the system using the standard system calls.

v8.0 reportlog changes

client machine OS version added to the OUT record for detailed format.

application argv[0] added to the OUT record for detailed format.

v5.0 reportlog changes

requested product and requested version added to QUE record for std and detailed formats.

requested product and requested version will always be empty strings in OUT records that result from a de-queueing of a previously queued request.

options, share, max_share, type, and named_user_count added to PRODUCT support record

Portable hostid removed - status 7 - added to checkin reasons.

v4.0 reportlog changes

REPROCESSED line added for rlmanon. Note that this line can appear in any version reportlog, since rlmanon can process all reportlog versions. Report writers can ignore this line, it is in the file for informational purposes only.

“detailed” format added to DENIAL records to add seconds and fractional seconds.

REREAD END records were not generated prior to v4.0. This record is removed.

New denial status -45 (RLM_EL_NOT_NAMED_USER) added

All report logs are authenticated.

v3.0 reportlog changes

NOTE: the v3.0 reportlog is incorrectly logged as v2.0 in the “RLM Report Log” line. The version in the ISV line will correctly indicate that it is a v3.0 logfile.

line_item added to PRODUCT records

“, authenticated” added to the end of the ‘RLM Report Log’ (first) record if this reportlog is authenticated

AUTH records added (for authenticated reportlogs)

v2.0 reportlog changes

LICENSE FILE line added in header section

isv-specific data (“log” records) added

cur_use and cur_resuse fields added to IN records (standard and detailed formats)

process_id, requested_product, and requested_version added to OUT records (standard and detailed formats)

hostid and pool# added to PRODUCT records