Logging MathLM

Enabling Logging

You can enable logging in two ways.

  • Log server messages to stdout by using the option -foreground to keep mathlm in the foreground.
    • Log server messages to a specific file using the option -logfile file.

    The log file records messages as they occur, building up a detailed record of license activity over a period of time.

    Logging supports both IPv4 and IPv6 environments with no additional configuration required.

Syntax of the Log File

By default, MathLM generates all log files in the W3C Common Logfile Format used by web servers such as Apache. However, you can customize the format by using the option -logformat. This option takes a string argument that specifies the format in which server messages are displayed. The string contains a series of commands of the form %var#, where

  • var is a letter representing one of nine variables, such as the host, user, day, time, or event.
    • # is a number defining a specific format for the variable var.

    For example, %y1 means that the year is displayed in two-digit format (e.g., 10), while %y2 displays the year in four-digit format (e.g., 2010).

    In addition to the %var# commands, the string can also include plain text such as brackets, dashes, quotation marks, and arbitrary comments. The text can be used to include comments and separators in the server messages for formatting purposes. All text included in the string appears literally in the server message with the following two exceptions: use %q to include a double quote ("), and use %% to include a percentage sign (%).

    You must specify the type of messages that should be logged using the option -loglevel, as explained in "Launching MathLM".

    Here is a list of variables that can be included in the string, along with their numeric values and formats.

    Variable Name
    Possible Values
    %h#1 IP address 2 hostname 3 fully qualified domain name host
    %u#1 user ID 2 username user
    %m#[1...31] day of month
    %w#1 numeric [ 1 ... 7 ] 2 abbreviated [ Sun ... Sat ] 3 verbose [ Sunday ... Saturday ] day of week
    %m#1 numeric [ 01 ... 12 ] 2 abbreviated [ Jan ... Dec ] 3 verbose [ January ... December ] month
    %y#1 two-digit [ 10 ] 2 four-digit [ 2010 ] year
    %t#1 twelve-hour (10:20:15) 2 twenty-four-hour (22:20:15) 3 GMT offset (-0500) time
    %e#1 numeric 2 verbose event
    %r#1 numeric 2 verbose response

    MathLM logging variables.

Note: All Windows clients on a network have the same user ID (set to the number 65535 by default). Hence, the user ID setting is only meaningful for clients running Unix, Linux, or Mac OS X.

Note: To use the GMT offset format (%t3), you must also use the -localtime option when starting MathLM.

Samples and Behavior

Running the command mathlm -logfile log.txt, without the option -logformat, generates messages in the default format. An example of messages in the default format, as contained in log.txt, follows.

The default format string, which mimics the Common Logfile Format, can be invoked by the following.

%h3 - %u2 [%d/%m2/%y2:%t2 %t3] %q%e2%q %q%r2%q -

To specify the Common Logfile Format manually, you must specify this string as the value of the -logformat option, as in the following command. The messages generated by this command are in the same format as the previous example.

mathlm -logfile log.txt -logformat "%h3 - %u2 [%d/%m2/%y2:%t2 %t3] %q%e2%q %q%r2%q -"

By default, time is displayed in GMT. If you want local time to be displayed instead, you must use the -localtime command-line option with either the %t1 tag or the %t2 tag. The %t3 tag should not appear in the format string if you want local time to be displayed.

An alternate format string using local time follows.

mathlm -logfile log.txt -localtime -logformat "%h1 - %u2 [%m1-%d-%y1: %t1] %q%e2%q %q%r2%q -"

An example of server messages in this user-specified format, as contained in log.txt, is displayed here.

Note: Server messages in IPv6 networks will display IPv6 addresses automatically, with no additional configuration required.