Webmin Module Writers Help

Action Logging

Also in Webmin 0.81 is 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 a HTTP logfile 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 directory /var/webmin/diffs. Note that nothing will be recorded in this file if logging is not enabled in the Webmin Configuration module.

The function webmin_log should be called by CGI programs 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 effected by the program. Often something like 'user' or 'group', though can be left blank if not appropriate.
object - The name of the thing effected, 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 detail logfile 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'}\n";
close(USERS);
&unlock_file("/etc/foo.users");
&webmin_log("create", "user", $in{'username'}, \%in);

Because the raw logfiles 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 file log_parser.pl in each module subdirectory to convert logs records from that module into a readable message.

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

user - The Webmin user who run the program that generated this 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 log exactly what file changes have been made by each CGI program before calling webmin_log. Under Logging in Webmin Configuration there is an option marked Log changes made to files by each action which 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 files updates, creations and deletions by the chosen action. If locking of directories and symbolic links is done as well, it will show their creation and modification as well.

As well as having their file changes logged, programs can also use the common functions system_logged, kill_logged and rename_logged which 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 which works similar to the Perl backquote operator (it takes a command an 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 be actually recorded, as in this example :

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