57.6. The log_parser.pl Log Reporting Script

Like all good Webmin modules, this one logs actions taken by users so that they can be viewed later in the Webmin Actions Log module. The save_cron.cgi, delete_cron.cgi, save_allow.cgi, and exec_cron.cgi programs all call the standard webmin_log function with parameters indicating what action has just taken place. As Section 56.5 “Action Logging” explains, this information is then written to a log file for later reporting.

Even though just about any arguments can be passed to the webmin_log function, it is usually a good idea to follow the standard that this and other modules use. The first action parameter should be the action performed, such as save or delete. The type parameter should be the kind of object to which the action applies, such as cron or user. The object parameter should be the name of the object affected, such as fred or www.foo.com. Finally, the params parameter must be a hash reference containing additional information about the action, such as the structure of the object being modified or the contents of %in. All parameters except action are optional, so it is quite reasonable and common for a module to use code like &webmin_log("stop");.

All of these programs also make use of the lock_file and unlock_file functions to obtain locks on files that they change. This causes the actual changes to the Cron files to be captured for inclusion in the log as well, so that inexperienced administrators can see exactly what the module has been doing. Your module should make use of these functions as well, especially those for locking. They protect critical files from simultaneous access, and give you detailed file change logs for free if you decide to add calls to action_log.

The other aspect of logging is the conversion of the logged parameters into human-readable form, which is done by the log_parser.pl script. If you view the code for this module, you will see that it simply uses the parameters to decide what to pass to text, and returns the resulting string. Note that the html_escape function is used to remove any special HTML characters from Cron commands, which may otherwise cause invalid HTML to be included in the log search results. If your module includes a log_parser.pl script that might return text containing characters like <, >, or &, be sure to call html_escape on the appropriate parts.

Unlike the parse_webmin_log function in most other modules, the one in the Scheduled Cron Jobs module checks the long parameter to decide if a long or short action description should be returned. The long form includes the actual command in the Cron job, which will only fit on the page displaying details of a single log entry in the Webmin Actions Log module. In most modules, however, the message is always short enough to completely ignore this parameter.

If a parameter to webmin_log was omitted or set to undef by the CGI program that created it, the actual value passed to parse_webmin_log will be a single dash (–). This happens because a – is used in the log file to represent a missing parameter.