Whenjobs

What are whenjobs

This document is a work in progress, as we are still investigating whenjobs for funtoo usage. For information about it see Funtoo tickets about whenjobs, initscript, User Feedback and this document.

Whenjobs are written by Richard Jones from RedHat Linux. They are designed to be a cron daemon replacement with some improvements over normal cron-jobs. Further more we from Funtoo Linux added some improvements to them already. Whenjobs give users a simpler syntax for jobs to run and with funtoo improvements a good way of user-management for whenjobs, that way we fixed the default behaviour of whenjobs to not been able to run as root and let us execute the daemon on a userbasis by default.

Question for help and testing

With this tutorial we like to ask users to help us and test whenjobs. We would like to get your feedback to FL-338. So please test and report there what you think and what you think should be improved.

How to install whenjobs

The installation of whenjobs is really easy, just merge them and you would get all that is needed for a first testrun and later perhaps also a production usage.

# emerge -avt whenjobs

That's what is needed for installing whenjobs, nothing big so far.

How to get started

As mentioned above we added a user-management and whenjobs has a changed syntax compared to normal cronjobs so we will discuss all these parts now. :)

user management

The user management for whenjobs is done with a single file located at /etc/whenjobs.users.conf just add a user to that file by a commaseperated list like

root,user1,user2,user3

where user1-user3 have to be system-usernames as they are checked. please do not add any other lines to that file, as there is atm now way for comments in the file and adding other lines will break so far the usage and you won't be able to start the daemon later. ATM there is no initscript, but we are working on one and that initscript will then use that file in the same way. :)

whenjobs commands

There are some basic commands for whenjobs you should be aware of before we get to explain the script syntax for whenjobs. this part will explain them.

To edit/list a job script use

# whenjobs -e | --edit
# whenjobs -l | --list

in the above case we added both the short and long version in one line so please use either the -e or the --edit version as there is no piping done at that part. We will use the same syntax for further examples if there are multiple ways of calling the function we need.

Another import part is to set or get variables we want to set or set in whenjobs, that can be done with:

to get a variable:
# whenjobs --get variable
to set a variable or multiple varibles:
# whenjobs --set variable=value [variable=value ...]
and to display all set variables:
# whenjobs --variables

Another important function in whenjobs is the way to start, stop and request the status of the per-user daemon.

# whenjobs --daemon-start
# whenjobs --daemon-stop
# whenjobs --daemon-status
# whenjobs --daemon-restart

Finally we have the ability to inspect running jobs:

# whenjobs --jobs
# whenjobs --cancel serial
# whenjobs --start "name"
# whenjobs --tail serial

How to get started with whenjobs now

First edit the above mentioned whenjobs.users.conf file if not already done and start a daemon on a per-user basis with

# whenjobs --daemon-start

Thats all for starting whenjobs and now we have time to write some whenjobs-scripts. We will use here some basic examples nothing for real time usage but it should be able to give you the impression on how to write your own scripts and use the variables in the later process. First we need to edit our whenjobs-script. This can be done by two ways:

Version A) (manual way, not recommended)
# EDITOR ~/.whenjobs/jobs.ml
Edit the file with the scripts you want to use and save it, but after that you need to upload it so that whenjobs knows about it
# whenjobs --upload
Version B) (automatically by whenjobs, recommended)
# whenjobs -e  | --edit
just save your script now and whenjobs will upload it automatically for you.

So far we are now fine with getting to the scripts, next let us add some basics. We will now start with a periodic call, like if we would like to check out load everyage every 10 minutes we would do it like this:

every 10 minutes :
<<
  # Get the current load average.
  load=`awk '{print $1}' /proc/loadavg`
  whenjobs --set --type float load=$load
>>

The power of whenjobs comes in game when you would like to base on a variable you set somewhere else:

when load >= 6 :
<<
  mail -s "ALERT: high load average: $load" MAILADDRESS < /dev/null
>>

That part will notify a user via email when his load average is greater or equal to 6, as when statements are "edge-triggered".

The --type switch above for setting a variable can be one of bool, int, float, string or unit

For Periodic expressions you have to use the following syntax

every <period> :
<<
  # shell script
>>

where <period> is one of the following period expressions:

<period>	Description		Special <period>	Description
second	runs every second		X seconds	runs every X seconds
minute	runs every minute		X minutes	runs every X minutes
hour	runs every hour		X hours	runs every X hours
day	runs every day, at midnight UTC		X days	runs every X days, at midnight UTC
week	runs every week, on a Thursday at midnight UTC		X weeks	runs every X weeks, on a Thursday at midnight UTC
month	runs every month, on the 1st at midnight UTC		X months	runs every X month, on the 1st at midnight UTC
year	runs every year, on the 1/1 at midnight UTC		X years	runs every X years, on the 1/1 at midnight UTC
decade	runs every 10 years		X decades	runs every X decades
century	runs every 100 years		X centuries	runs every X centuries
millenium	runs every 1000 years		X millenia	runs every X mellenia