/ 
Cron-Sequencer-0.01
River stage zero No dependents
/ cron-sequencer

NAME

cron-sequencer - show the sequence of commands that cron would run

SYNOPSIS

cron-sequencer crontab-file             # show today's events
cron-sequencer --show tomorrow cronfile # or tomorrow's
cron-sequencer cronfile1 cronfile2      # show events from both crontabs
cron-sequencer --ignore 6,9,43 file     # ignore events from these lines

DESCRIPTION

cron-sequencer takes one or more crontab files, and shows the sequence of commands that cron would run, with the source line and time fields that triggered the event at that timestamp. The default is to show events for today, and to show environment variables set in the crontab file.

GLOBAL OPTIONS

--show period

Show events for the given period. Options are

  • today

  • yesterday

  • tomorrow

  • last week

  • this week

  • next week

All are treated as starting at midnight (inclusive) and ending at midnight (exclusive). The default is today

--from epoch time
--to epoch time

Specify an exact range of events to show. The start time is inclusive, the end time exclusive. Values can be

positive integer

Absolute time in Unix epoch seconds (ie seconds since 1970-01-01)

+integer

Relative time offset in seconds. For from, this specifies a start time relative to midnight gone. For to this specifies an end time relative to the start time (so gives the number of seconds of crontab events to show)

-integer

A negative integer is only permitted for from, and specifies a start time before midnight gone.

Hence --from +0 --to +3600 shows events from midnight until 00:59 inclusive.

--hide-env

Don't show environment variables in the output.

--help

Shows this documentation

--version

Shows the version

PER-FILE OPTIONS

These options can be specified independently for each crontab file (or group of crontab files), and can be repeated multiple times.

--ignore <line numbers>

Ignore the given line(s) in the crontab. Specify line numbers as comma-separated lists of integers or integer ranges (just like crontab time files, aside from you can't use * or skip syntax such as /2). Line numbers start at 1.

"Ignore" is the first action of the parser, so you can ignore all of

  • command entries (particularly "chatty" entries such as * * * * *)

  • setting environment variables

  • lines with syntax errors that otherwise would abort the parse

--env NAME=value

Pre-define an environment variable for this crontab file. The variable declaration won't be shown in the output if the crontab defines the variable with the same value. Without this a crontab that starts

MAILTO=god@heaven.mil

and has 42 events to show would generate 42 lines of MAILTO=god@heaven.mil output, once for each command.

If you define an environment variable on that command line that isn't set in scope in the crontab file then an unset ... line is shown. This makes it clear that the event doesn't match your expected default value.

You can't declare both --env and --hide-env

--

Use a pair of dashes to separate options for different files on the command line. Effectively -- resets the state to no lines ignored and no environment variables defined.

EXAMPLES

cron-sequencer cronfile1 cronfile2

Shows events from both crontab files for today, in time order, annotated with file name, line number, time specification and environment variables.

cron-sequencer --env MAILTO=alice cron1 -- --env MAILTO=bob cron2

Shows events from both files, but will create clearer output if cron1 declares MAILTO=alice and cron2 declares MAILTO=bob

cron-sequencer -- cron1 --env MAILTO=alice -- --env MAILTO=bob cron2

Identical output. (This is a side effect of how options are parsed first, and then filenames.)

cron-sequencer --env MAILTO=bob cron1 cron2 -- --ignore 3-5 cron3

Shows events from the first two files assuming the both declare MAILTO=bob, along with events from cron3 except for lines 3, 4 and 5 (with all environment variables shown, unless they were declared on the ignored lines 3, 4 and 5)

BUGS

Currently the code assumes that all crontabs are run with a system timezone of UTC. Similarly all display output is shown for UTC. The work systems all run in UTC, so we don't have pressing need to fix this ourselves.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. If you would like to contribute documentation, features, bug fixes, or anything else then please raise an issue / pull request:

https://github.com/Humanstate/cron-sequencer

AUTHOR

Nicholas Clark - nick@ccl4.org