.TH TASKS.CFG 5 "Version 4.3.28: 17 Jan 2017" "Xymon"
.SH NAME
tasks.cfg \- Task definitions for the xymonlaunch utility

.SH SYNOPSIS
.B ~xymon/server/etc/tasks.cfg

.SH DESCRIPTION
The tasks.cfg file holds the list of tasks that xymonlaunch runs 
to perform all of the tasks needed by the Xymon monitor.

.SH FILE FORMAT
A task is defined by a \fBkey\fR, a \fBcommand\fR, and optionally 
also \fBinterval\fR, \fBenvironment\fR, and \fBlogfile\fR.

Blank lines and lines starting with a hash mark (#) are treated as 
comments and ignored.  Long lines can be broken up by putting a 
backslash at the end of the line and continuing the entry on the 
next line.

An entry looks like this:
.sp
    [xymond]
.br
          ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
.br
          CMD /usr/local/xymon/server/bin/xymond
.sp
    [updateweb]
.br
          ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
.br
          CMD /usr/local/xymon/server/bin/xymongen
.br
          NEEDS xymond
.br
          GROUP webupdates
.br
          INTERVAL 5m
.br
          ONHOST localhost
.br
          MAXTIME 10m
.br
          LOGFILE /var/log/xymon/updateweb.log
.sp
    [monthlyreport]
.br
          ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
.br
          CMD /usr/local/xymon/server/ext/monthlyreport.sh
.br
          CRONDATE 30 4 1 * *
.sp
The \fBkey\fR is enclosed in angle brackets, and must be unique
for each task. You can choose your key-names as you like, they
are only used internally in xymonlaunch to identify each task.

The \fBcommand\fR is defined by the \fbCMD\fR keyword. This is
the full command including any options you want to use for this 
task. This is required for all tasks.

The \fBDISABLED\fR keyword means that this command is disabled.
xymonlaunch will not start this task. It is recommended that 
you use this to disable standard tasks, instead of removing them
or commenting them out. Upgrades to Xymon will add standard
tasks back into the file, so unless you have them listed as DISABLED
then tasks may re-appear unexpectedly after an upgrade. There is
also a corresponding \fBENABLED\fR keyword, to explicitly enable 
a task.

The \fBONHOST\fR keyword tells xymonlaunch that this task should
only run on specific hosts. After the ONHOST keyword, you must
provide a "regular expression"; if the hostname where xymonlaunch
runs matches this expression, then the task will run. If it doesn't
match, then the task is treated as if it were DISABLED.

The \fBMAXTIME\fR keyword sets a maximum time that the task may
run; if exceeded, xymonlaunch will kill the task. The time
is in seconds by default, you can specify minutes, hours or
days by adding an "m", "h" or "d" after the number. By default
there is no upper limit on how long a taskmay run.

The \fBNEEDS\fR instructs xymonlaunch not to run this task unless
the task defined by the NEEDS keyword is already running. This
is used e.g. to delay the start of some application until the
needed daemons have been started. The task that must be running
is defined by its \fBkey\fR.

The \fBGROUP\fR keyword can be used to limit the number of tasks 
that may run simultaneously. E.g. if you are generating multiple
pagesets of webpages, you don't want them to run at the same time.
Putting them into a GROUP will cause xymonlaunch to delay the start
of new tasks, so that only one task will run per group. You can
change the limit by defining the group before the tasks, with
a "GROUP groupname maxtasks" line.

The \fBINTERVAL\fR keyword defines how often this command is
executed. The example shows a command that runs every 5 minutes.
If no interval is given, the task is only run once - this is
useful for tasks that run continually as daemons - although
if the task stops for some reason, then xymonlaunch will attempt
to restart it. Intervals can be specified in seconds (if you 
just put a number there), or in minutes (5m), hours (2h), or
days (1d).

The \fBCRONDATE\fR keyword is used for tasks that must run at
regular intervals or at a specific time. The time specification
is identical to the one used by cron in
.I crontab(5)
entries, i.e. a sequence of numbers for minute, hour, day-of-month, 
month and day-of-week. Three-letter abbreviations in english can
be used for the month and day-of-week fields. An asterisk is a
wildcard. So in the example above, this job would run once a
month, at 4:30 AM on the 1st day of the month.

The \fBENVFILE\fR setting points to a file with definitions of
environment variables. Before running the task, xymonlaunch will
setup all of the environment variables listed in this file.
Since this is a per-task setting, you can use the same xymonlaunch
instance to run e.g. both the server- and client-side Xymon 
tasks. If this option is not present, then the environment 
defined to xymonlaunch is used.

The \fBENVAREA\fR setting modifies which environment variables
are loaded, by picking up the ones that are defined for this
specific "area". See 
.I xymonserver.cfg(5)
for information about environment areas.

The \fBLOGFILE\fR setting defines a logfile for the task.
xymonlaunch will start the task with stdout and stderr redirected
to this file. If this option is not present, then the output
goes to the same location as the xymonlaunch output.

.SH "SEE ALSO"
xymonlaunch(8), xymond(8), crontab(5), xymon(7)