TASKS.CFG(5)

💅 TASKS.CFG(5) — the File Formats Manual glow-up ✨

okay bestie, sit down, we're learning about tasks.cfg 🎀

---

🌸 NAME 🌸

tasks.cfg — task definitions for the xymonlaunch utility. yes that's the whole name section, it's short and it ate 💅

---

✨ SYNOPSIS ✨

~xymon/server/etc/tasks.cfg

---

🦋 DESCRIPTION 🦋

so like. tasks.cfg holds the list of tasks that xymonlaunch runs to do literally all of the things the Xymon monitor needs done. it's the whole to-do list, no cap 👑

---

💖 FILE FORMAT 💖

a task is defined by a key, a command, and optionally also interval, environment, and logfile. that's the recipe 🍓

blank lines and lines starting with a hash mark (#) are treated as comments and ignored, like they simply don't exist, we ignore them, periodt. long lines can be broken up by putting a backslash at the end of the line and continuing the entry on the next line — the line-wrap of it all 🧚

an entry looks like this:

[xymond]
      ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
      CMD /usr/local/xymon/server/bin/xymond

[updateweb]
      ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
      CMD /usr/local/xymon/server/bin/xymongen
      NEEDS xymond
      GROUP webupdates
      INTERVAL 5m
      ONHOST localhost
      MAXTIME 10m
      LOGFILE /var/log/xymon/updateweb.log

[monthlyreport]
      ENVFILE /usr/local/xymon/server/etc/xymonserver.cfg
      CMD /usr/local/xymon/server/ext/monthlyreport.sh
      CRONDATE 30 4 1 * *

the key is enclosed in angle brackets, and must be unique for each task. you can choose your key-names however you like — they are only used internally in xymonlaunch to identify each task. main character names only, your choice 💜

the command is defined by the CMD keyword. this is the full command including any options you want to use for this task. this is required for all tasks. not optional, bestie, it's mandatory 📌

the DISABLED 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. like, why would you delete them, that's so much drama 😭. 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 ENABLED keyword, to explicitly enable a task.

the ONHOST 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. it's giving ✨ exclusive ✨

the MAXTIME 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 NEEDS 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 key. it's a whole "i'm not going anywhere until my bestie shows up" situation 🫶

the GROUP 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. one at a time, we're not doing chaos 😌

the INTERVAL 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). so many units, pick your fave ⏰

the CRONDATE 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 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. scheduling icon behavior 🗓️👑

the ENVFILE 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 ENVAREA setting modifies which environment variables are loaded, by picking up the ones that are defined for this specific "area". see xymonserver.cfg(5) for information about environment areas 🌈

the LOGFILE 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. receipts, but make them files 📝

⚠️ real talk bestie: DISABLED is your friend, not deletion. remove or comment out a standard task and an upgrade will just bring it right back and you'll be confused and sad. list it as DISABLED instead. lowkey the most important thing in here 🫶

---

👀 SEE ALSO 👀

xymonlaunch(8), xymond(8), crontab(5), xymon(7) — go read those next, i'm obsessed with your commitment to learning 💖

---

okay that's the whole thing and you absolutely ate it 💅✨ this was Xymon, Version 4.3.30: 4 Sep 2019, and yes the file formats manual really said all that. no cap, go configure something 🦋🌸