/ 
App-Cronjob-1.200014
River stage zero No dependents
/ cronjob

NAME

cronjob - wrap up programs to be run as cron jobs

VERSION

version 1.200014

SYNOPSIS

cronjob [-cEfhjrs] [long options...]
  --command STR (or -c)          command to run (passed to ``)
  --subject STR (or -s)          subject of mail to send (defaults to
                                 command)
  --rcpt STR... (or -r)          recipient of mail; may be given many
                                 times
  --errors-only (or -E)          do not send mail if exit code 0, even
                                 with output
  --sender STR (or -f)           sender for message
  --jobname STR (or -j)          job name; used for locking, if given
  --timeout INT                  fail if the child isn't completed
                                 within n seconds
  --ignore-errors STR...         error types to ignore (like: lock)
  --email-header STR... (or -h)  add header to the report email, if you
                                 send one
  --temp-ignore-lock-errors INT  failure to lock only signals an error
                                 after this long
  --[no-]lock                    lock this job (defaults to true;
                                 --no-lock for off)

DESCRIPTION

cronjob is a fairly simple Perl program that's meant to be used to wrap anything you want run from a crontab. It was originally written to cope with the highly deficient Solaris crond, but now provides features that are useful even under relatively sane and otherwise tolerable cron daemons.

The most important argument to cronjob is --command (aka -c). It gives the command to be run. If you want to run some-maintenance-job every day at noon, you might put this in your crontab:

0 12 * * *           cronjob -c 'some-maintenance-job --xyzzy'

Here's what will happen when that job is run:

Unless you provided --no-lock, an exclusive lock will be created on a temporary file in /tmp. The locking process is described more below. Basically, it tries to prevent more than one of the same, or closely-related, jobs from running concurrently.

The job will be run with no input. Its combined STDOUT and STDERR are captured, along with its exit (wait) status.

When the command has terminated, a report is sent if:

  • the command couldn't lock (unless --ignore-errors lock or, if --temp-ignore-lock-errors=secs was given, the lock was created no more than secs seconds ago.

  • the command had any output (unless --errors-only)

  • the command exited non-zero (always)

The report will include a summary of the process and its behavior, including the time taken to run, the exit status, any signal received, and whether core was dumped. It will also include the full (combined) output of the process.

The report will be send from --sender (or a reasonable default) to --rcpt (or root). Its In-Reply-To header will be set to a hashed value that will cause all same-subject jobs to thread together in threaded mail readers. The --subject switch sets the message subject, so it's responsible for deciding which jobs thread together. For jobs that run with variable arguments, providing a --subject argument is a very good idea.

locking

The default lockfile name is generated with code something like this:

my $lockname = $opt->jobname || ( md5_sum( $opt->subject || $opt->command ) );
my $lockfile = sprintf '/tmp/cronjob.%s', $lockname;

In other words, if you specify a --jobname option, that will be used for naming the lockfile. This lets you force otherwise unrelated cronjobs to block each other. If you don't provide a job name, one is created by hashing the subject (of the report to send) or, failing that, the command itself. The hashing is a simple measure to prevent long or metacharacter-ridden filenames.

The lockfile will contain information about the process that has the lock, including when it was begun.

By default, all jobs are locked and failure to acquire a lock causes immediate failure of the cronjob. A failure report will be sent. To suppress failure reports in the event of lock failure, pass --ignore-errors lock to the command. To skip locking, pass --no-lock.

Note that ignoring lock failures only ignores failure to flock the lockfile. If the file can't even be created, an error will still be reported. It will be of type lockfile, and can be ignored by adding another --ignore-errors option for that type.

PERL VERSION

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl.

AUTHOR

Ricardo Signes <cpan@semiotic.systems>

COPYRIGHT AND LICENSE

This software is copyright (c) 2009 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.