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 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.
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's subdirectory to convert logs records
from that module into a readable message. This 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.
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 have been 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 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 creations and modifications too.
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 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 be actually recorded, as in this example :
if ($pid) {
&kill_logged('TERM', $pid);
}
else {
&system_logged("/etc/init.d/foo stop");
}
&webmin_log("stop");