crontab.5

.\" Man page for ncron
.\"
.\" Copyright (c) 2004-2024 Nicholas J. Kain
.\"
.TH crontab 5 "Feburary 9, 2024"
.LO 1
.SH NAME
crontab \- ncron configuration file
.SH DESCRIPTION
.B crontab
specifies job commands, intervals, and constraints.

.SH "FILE FORMAT"
.nf
UINT := integer >= 0
JOBID := '!' integer
TIME_UNIT := "s" or "m" or "h" or "d" or "w"
HH := 0..23
MM := 0..59
WEEKDAY := 1..7
DAY := 1..31
MONTH := 1..12
JOB :=  JOBID
        command=string
        time=HH:MM or HH:MM-HH:MM
        weekday=WEEKDAY or WEEKDAY-WEEKDAY
        day=DAY or DAY-DAY
        month=MONTH or MONTH-MONTH
        interval=(UINT[TIME_UNIT])+
        journal
        maxruns=UINT
        runat=UINT
COMMENT := '#' or ';' ANY

config file :=
        JOB
        ...
        JOB
.fi
.PP
Multiple constraints are allowed, but serve only to permit additional
ranges in which jobs may be run (in other words, they are implicitly
unioned).
.PP.
Comments are denoted by a '#' or ';' at the start of a line.
Whitespace (or any other characters) may not preceed the '#' or ';'.
Comments may be started on any line.
.PP
The default location for configure files is /var/lib/ncron/crontab.

.SH KEYWORDS
.TP
command=STRING
Specifies the full path to a program, followed by any arguments that should be
passed to the program.  Arguments follow the first unescaped space or tab
character and continue to the end of line.  The program name (but not the
arguments) has simple escape rules to allow for program file names that
contain spaces or tabs; backslash functions as an escape character so that the
following character is treated as a literal character that is part of the
program file name.  A terminal single backslash in a program file name passes
through as a single literal backslash that is part of the program file name.

Note that this means that argument quoting and splitting does not work
as it does in shell commands.  If the shell semantics are desired, a wrapper
script ("#!/bin/sh\necho 'like this'\n") should be used.
.TP
time=HH:MM or HH:MM-HH:MM
Specifies a time or time range in which the job may run.  The time is in
24 hour format.  Leading zeros are not allowed.  If a range is provided,
the first time in the range must preceed the second time in the range.
Multiple ranges will be unioned together.
.TP
weekday=RANGE
Either a single weekday value or a '-'-separated range of allowed
weekdays.  Valid weekdays are within the range [1,7], where 1
corresponds to Sunday and 7 maps to Saturday.
.TP
day=RANGE
As above.  Valid days are within the range [1,31].
.TP
month=RANGE
As above.  Valid months are within the range [1,12].
.TP
interval=SECONDS
The time that must elapse between invocations of the job.  In
practice, constraints may force a wait longer than the time specified
by the interval.  Any number before a valid unit (s,m,h,d,w) ==
(seconds, minutes, hours, days, weeks) will be associated with the
next valid unit specifier.  Multiple units are allowed to be in
sequence and will be implicitly added.  No unit specifier (a bare
number) implies a unit of seconds.  Examples would be "interval=300"
or "interval=5m" which both mean "run the job at least five minutes
apart".  Multiple time units may be used at once, such as
"interval=1h5m3s".
.TP
journal
ncron will save execution times and number of runs after each run of this job.
Useful for very critical tasks. If your machine is horribly unstable, I would
suggest using the "execmode" argument to ncron rather than manually forcing
every job to be journalled in the configuration file.
.TP
maxruns=INTEGER
Maximum number of times that a job will be run. The number of runs for a job is
accounted for between invocations of ncron. A value of zero denotes no limit.
.TP
runat=TIME
ncron will run the specified job only one time, at a time greater than or equal
to the time (in seconds since epoch) passed as an argument to runat. The job
will implicitly be journalled.  "interval" is obviously meaningless if this
keyword is to be used, and should be omitted for human readability (although
ncron does not care). This keyword allows ncron to act as an atd as well as a
crond.
.PP
Note that for all constraints, values outside of valid ranges will be treated
as wildcards.
.PP
Multiple ranges of the same type may be used and will be OR'ed together by the
daemon. In other words, "weekday=1" and "weekday=4" in the same job would read
as "run this task on either Sunday or Wednesday".
.PP
Ranges require that the first value is <= the second value.  Ranges where
this is not true will be discarded as invalid.  This simply means that, for
a constraint of running a job between 10pm and 4am, use two constraints:
"time=22:00-23:59" and "time=0:00-2:59".  The ordering does not matter.
.SH SIGNALS
SIGHUP, SIGINT, SIGTERM all cause ncron to save state to disk and shut down.
.SH EXAMPLE
.nf
!1
command=/bin/echo hihi
day=10
interval=10s
.fi
.PP
This job will run "/bin/echo" with a single argument of "hihi" in
ncron's working directory every ten seconds on the 10th day of every
month.  If the 'day=10' line is removed, this configuration is a decent
way to test whether ncron is working; if it is, "hihi" will be printed
to the terminal that ncron is running on every ten seconds.
.SH "SEE ALSO"
ncron(1).
.SH LIMITATIONS
Constraints may not vary as a function of other constraint values (eg, it is
not possible to express unique weekday constraints for each month). This
limitation won't be removed. It would be a major change for little
gain and greatly increased program and config file format complexity.
.PP.
Years may not be used as constraints.  Generally periodic jobs on a
computer don't vary by year.  Technically it would be possible to
support year constraints but it doesn't seem worth the work and complexity.
.SH TIPS
Note that when a job is removed, the history entries will be removed
automatically for interval / non-runat jobs if ncron is shut down and
restarted twice.  Alternatively, lines starting with job ids no longer
in use can be deleted from the history file so long as ncron is not
running.  If ncron is running, it will overwrite any changes made when
it saves out the current history state to disk on shutdown.
.PP.
The "runat" keyword allows ncron to function as either a cron daemon (which
runs tasks at periodic intervals of time) or an at daemon (which runs tasks at
defined times).
.PP
ncron is also designed to run effectively as either a single uid-root daemon,
multiplexing between multiple user accounts, or as a per-user cron daemon, with
one daemon for each user account.  Both models run efficiently, but have
different administrative and security characteristics.
.SH AUTHOR
Nicholas J. Kain : njkain at gmail dot com