56.5. Action Logging

Webmin versions 0.81 and above have support for detailed logging by CGI programs of the actions performed by users for later viewing in the Webmin Actions Log module. While previous versions wrote an HTTP log file to /var/webmin/miniserv.log, this did not contain the information required to work out exactly what each Webmin user had been doing. To improve on this, Webmin now logs detailed information to the file /var/webmin/webmin.log and optionally to files in the /var/webmin/diffs directory. Note that nothing will be recorded in this file if logging is not enabled in the Webmin Configuration module.

CGI programs should call the webmin_log function after they have successfully completed all processing and file updates. The parameters taken by the function are:

action The action the program has performed. Usually something like save or delete.

type The type of thing affected by the program. Often something like user or group, although it can be left blank if not appropriate.

object The name of the thing affected, such as jcameron or root or www.foobar.com.

parameters A reference to a hash containing additional information that the program wants to log. Often just passing \%in is useful.

All of these parameters can contain any information you want, as they are merely logged to the actions log file and not interpreted by webmin_log in any way. For example, a module might call the function like this:

&lock_file("/etc/foo.users");
open(USERS, ">>/etc/foo.users");
print USERS "$in{'username'} $in{'password'}
";
close(USERS);
&unlock_file("/etc/foo.users");
&webmin_log("create", "user", $in{'username'}, \%in);

Because the raw log files are not easy to understand, Webmin also provides support for converting detailed action logs into human-readable format. The Webmin Actions Log module makes use of a Perl function in the log_parser.pl file in each module's subdirectory to convert log records from that module into a readable message.

This file must contain the parse_webmin_log function, which is called once for each log record for this module. It will be called with the following parameters:

user The Webmin user who runs the program that generates the log record.

script The filename of the CGI script that generated this log, without the directory.

action Whatever was passed as the action parameter to webmin_log to create this log record.

type Whatever was passed as the type parameter to webmin_log.

object Whatever was passed as the object parameter to webmin_log.

parameters A reference to a hash, the same as the one passed to webmin_log.

long If non-zero, this indicates that the function is being called to create the description for the Action Details page and thus can return a longer message than normal. You can ignore this if you like.

The function should return a text string based on the parameters passed to it that converts them into a readable description for the user. For example, your log_parser.pl file might look like:

require 'foo-lib.pl';

sub parse_webmin_log
{
local ($user, $script, $action, $type, $object, $params, $long) = @_;
if ($action eq 'create') {
        return &text('log_create', $user);
        }
elsif ($action eq 'delete') {
        return &text('log_delete', $user);
        }
}

Because the log_parser.pl file is read and executed in a similar way to how the acl_security.pl file is handled by the Webmin Users module, it can require the module's own library of functions just like any module CGI program would. This means that the text function and %text hash are available for accessing the module's translated text strings, as in the example above.

Webmin can also be configured to record exactly what file changes are made by each CGI program before calling webmin_log. Under Logging in the Webmin Configuration module is a checkbox labeled Log changes made to files by each action that, when enabled, will cause the webmin_log function to use the diff command to find changes made to any file locked by each program.

When logging of file changes is enabled, the action details page in the Actions Log module will show the diffs for all file updates, creations, and deletions by the chosen action. If locking of directories and symbolic links is done as well, it will show their creations and modifications, too.

As well as having their file changes logged, programs can also use the common system_logged, kill_logged, and rename_logged functions that take the same parameters as the Perl system, kill, and rename functions but also record the event for viewing on the action details page. There is also a backquote_logged function that works in a similar fashion to the Perl backquote operator (it takes a command and executes it, returning the output), but also logs the command. If these functions are used, they must be called before webmin_log for the logging to actually be recorded, as in this example:

if ($pid) {
        &kill_logged('TERM', $pid);
        }
else {
        &system_logged("/etc/init.d/foo stop");
        }
&webmin_log("stop");