Functions from module cron

cron-lib.pl

Functions for listing, creating and managing Unix users’ cron jobs.

foreign_require("cron");
my @jobs = cron::list_cron_jobs();
my $job = { 'user' => 'root',
            'active' => 1,
            'command' => 'ls -l >/dev/null',
            'special' => 'hourly' };
cron::create_cron_job($job);
list_cron_jobs

Returns a lists of structures of all cron jobs, each of which is a hash reference with the following keys:

  • user - Unix user the job runs as
  • command - The full command to be run
  • active - Set to 0 if the job is commented out, 1 if active
  • mins - Minute or comma-separated list of minutes the job will run, or * for all
  • hours - Hour or comma-separated list of hours the job will run, or * for all
  • days - Day or comma-separated list of days of the month the job will run, or * for all
  • month - Month number or comma-separated list of months (started from 1) the job will run, or * for all
  • weekday - Day of the week or comma-separated list of days (where 0 is sunday) the job will run, or * for all
cron_job_line(&job)

Internal function to generate a crontab format line for a cron job.

copy_cron_temp(&job)

Copies a user’s current cron job configuration to the temp file. For internal use only.

create_cron_job(&job)

Add a cron job to a user’s file. The job parameter must be a hash reference in the same format as returned by list_cron_jobs.

insert_cron_job(&job)

Add a cron job at the top of the user’s file. The job parameter must be a hash reference in the same format as returned by list_cron_jobs.

renumber(file, line, offset)

All jobs in this file whose line is at or after the given one will be incremented by the offset. For internal use.

renumber_index(index, offset)

Internal function to change the index of all cron jobs in the cache after some index by a given offset. For internal use.

change_cron_job(&job)

Updates the given cron job, which must be a hash ref returned by list_cron_jobs and modified with a new active flag, command or schedule.

delete_cron_job(&job)

Removes the cron job defined by the given hash ref, as returned by list_cron_jobs.

read_crontab(user)

Return an array containing the lines of the cron table for some user. For internal use mainly.

copy_crontab(user)

Copy the cron temp file to that for this user. For internal use only.

parse_job(job-line)

Parse a crontab line into an array containing: active, mins, hrs, days, mons, weekdays, command

user_sub(command, user)

Replace the string USER in the command with the user name. For internal use only.

list_allowed

Returns a list of all Unix usernames who are allowed to use Cron.

list_denied

Return a list of all Unix usernames who are not allowed to use Cron.

save_allowed(user, user, …)

Save the list of allowed Unix usernames.

save_denied(user, user, …)

Save the list of denied Unix usernames.

read_envs(user)

Returns an array of “name value” strings containing the environment settings from the crontab for some user

save_envs(user, [name, value]*)

Updates the cron file for some user with the given list of environment variables. All others in the file are removed.

expand_run_parts(directory)

Internal function to convert a directory like /etc/cron.hourly into a list of scripts in that directory.

is_run_parts(command)

Returns the dir if some cron job runs a list of commands in some directory, like /etc/cron.hourly. Returns undef otherwise.

can_edit_user(&access, user)

Returns 1 if the Webmin user whose permissions are defined by the access hash ref can manage cron jobs for a given Unix user.

show_times_input(&job, [nospecial])

Print HTML for inputs for selecting the schedule for a cron job, defined by the first parameter which must be a hash ref returned by list_cron_jobs. This must be used inside a <table>, as the HTML starts and ends with <tr> tags.

parse_times_input(&job, &in)

Parses inputs from the form generated by show_times_input, and updates a cron job hash ref. The in parameter must be a hash ref as generated by the ReadParse function.

show_range_input(&job)

Given a cron job, prints fields for selecting it’s run date range.

parse_range_input(&job, &in)

Updates the job object with the specified date range. May call error function for invalid inputs.

fix_names(&cron)

Convert day and month names to numbers. For internal use when parsing the crontab file.

create_wrapper(wrapper-path, module, script)

Creates a wrapper script which calls a script in some module’s directory with the proper webmin environment variables set. This should always be used when setting up a cron job, instead of attempting to run a command in the module directory directly.

The parameters are:

  • wrapper-path - Full path to the wrapper to create, i.e. /etc/webmin/yourmodule/foo.pl
  • module - Module containing the real script to call
  • script - Program within that module for the wrapper to run
cron_file(&job)

Returns the file that a cron job is in, or will be in when it is created based on the username.

when_text(&job, [upper-case-first])

Returns a human-readable text string describing when a cron job is run.

can_use_cron(user)

Returns 1 if some user is allowed to use cron, based on cron.allow and cron.deny files.

swap_cron_jobs(&job1, &job2)

Swaps two Cron jobs, which must be in the same file, identified by their hash references as returned by list_cron_jobs.

find_cron_process(&job, [&procs])

Finds the running process that was launched from a cron job. The parameters are:

  • job - A cron job hash reference
  • procs - An optional array reference of running process hash refs
extract_input(command)

Given a line formatted like command%input, returns the command and input parts, taking any escaping into account.

convert_range(&job)

Given a cron job that uses range.pl, work out the date range and update the job object command. Mainly for internal use.

unconvert_range(&job)

Give a cron job with start and end fields, updates the command to wrap it in range.pl with those dates as parameters.

convert_comment(&job)

Given a cron job with a # comment after the command, sets the comment field

unconvert_comment(&job)

Adds an comment back to the command in a cron job, based on the comment field of the given hash reference.

check_cron_config

Returns an error message if the cron config doesn’t look valid, or some needed command is missing.

check_cron_config_or_error

Calls check_cron_config, and then error function if any problems were detected.