57.2. The cron-lib.pl Library Script

The real work in this module is done by the functions in cron-lib.pl, which actually read and write the various Cron job files in their different formats. This is the way a Webmin module should be written, as it cleanly separates the user interface from the configuration file management. This prevents unnecessary duplication of code and makes it easy to add support for a specific new Cron file if one arises.

The functions in this library that CGI programs call are:

list_cron_jobs() Returns an array of hash references, each of which contains the details of a specific Cron job. This information is actually read from several different files, and each job hash contains the name of the file that it came from in the file key, the position of the line key in that file, and the format in the type key. This is used when the job is saved with change_cron_job, so that it gets put back in the same place with the correct format. Many other Webmin modules store this kind of information in hashes that they create from configuration files, so they know which part of the file to update.

create_cron_job(job) Takes a hash reference containing Cron job details with the same keys as those returned by list_cron_jobs, which is then converted to a correctly formatted line, and appended to a temporary copy of the user's Cron jobs file. The copy_crontab function is used to activate it, using the method explained below.

change_cron_job(job) Takes a hash reference returned by list_cron_jobs but with some of the details updated and converts it to a correctly formatted line of text. If it is a user's personal Cron job, then the line must be updated in a copy of the jobs file. Otherwise, the original file that it came from can be updated directly.

delete_cron_job(job) Deletes the job passed in as a parameter by removing its line from the original file. If it was a user's personal Cron job, this is done in a temporary copy of his file instead of directly updating the original source.

list_allowed and list_denied Return arrays of users who are allowed or not allowed to access Cron, respectively. These functions are primarily used by edit_allow.cgi, and just read the contents of /etc/cron.allow and /etc/cron.deny. However, save_cron.cgi also uses them to check whether or not the user that you are creating a Cron job for can actually use it, as the crontab command will often fail if this is not the case.

save_allowed(user, …) and save_denied(user, …) These functions write the lists of users given as parameters to the /etc/cron.allow or /etc/cron.deny files, respectively. They are only used by save_allow.cgi.

can_edit_user(access, user) This function is used to check to see if the current Webmin user can access the Cron jobs of a particular UNIX user, based on the hash reference and username passed in as parameters. The reference is assumed to be the return value from get_module_acl, which contains settings made in the Webmin Users module. Most of the CGI programs use it to limit their displays and prevent attempts to access jobs belonging to unauthorized users. If your module has access control features that can limit what objects a user can access, a function like this is useful to prevent the duplication of code that checks ACL settings. It should be noted that it is called in both edit_cron.cgi and save_cron.cgi to block sneaky users who try to invoke the save program directly instead of going through the form.

show_times_input(job) This code prints HTML for the part of a form for editing the times at which a Cron job is run. It used to be in edit_cron.cgi, but was moved into the library so that other modules that set up Cron jobs (such as Filesystem Backup) can make use of the same inputs in their user interface.

parse_times_input(job, in) This function parses the inputs from the form created by show_times_input. Again, other modules use it as well as save_cron.cgi.

You might wonder why some of the functions above update a temporary file instead of directly editing the files in /var/spool/cron that contain user Cron jobs. The reason is that the crontab command must be used to install a modified file in order for the Cron daemon to notice the change and for it to take effect. This is done by the copy_crontab function, which invokes the appropriate crontab command for the operating system. Normally, when crontab is run by a user, it starts an editor like vi for the user to edit a temporary copy of the file, which is then moved back into /var/spool/cron.

This module sets the EDITOR environment variable to the cron_editor.pl script, however, which just copies the temporary file created by the module over the file passed to the script for editing by crontab. When it exists, the changes made by the module are properly installed and the temporary file can be deleted.

This process is not necessary for Cron jobs in /etc/crontab or /etc/cron.d, however, as the Cron daemon automatically detects when those files have been updated. For this reason, the change_cron_job and delete_cron_job functions can edit them directly.

Because Cron is a great tool for running scripts on a regular basic, several other modules make use of this one to set up jobs of their own. For example, Webmin Configuration uses it to schedule the automatic download of updated modules, Webalizer Logfile Analysis uses it to have logs processed regularly, and System and Server Status uses it to set up scheduled monitoring.

All of this is done by making foreign calls to the cron module, as explained in Section 56.7 “Functions in Other Modules”. If your module needs to do the same, it is advisable to make use of the code in cron-lib.pl that already supports a wide variety of operating systems and creates jobs in the correct way.