5 whenjobs - A powerful but simple cron replacement
9 Editing the jobs script:
14 Get and set variables:
16 whenjobs --get variable
17 whenjobs --set variable=value [variable=value ...]
20 Start and stop the per-user daemon:
22 whenjobs --daemon-start
23 whenjobs --daemon-stop
24 whenjobs --daemon-status
25 whenjobs --daemon-restart
30 whenjobs --cancel serial
31 whenjobs --start "name"
32 whenjobs --tail serial
36 Whenjobs is a powerful but simple replacement for cron. It lets you
37 run jobs periodically like cron, but it also lets you trigger jobs to
38 run when user-defined variables are set or change value.
40 Periodic jobs are written like this:
44 # Get the current load average.
45 load=`awk '{print $1}' /proc/loadavg`
46 whenjobs --set --type float load=$load
49 When-statements let you create jobs that run based on variables set
54 mail -s "ALERT: high load average: $load" $LOGNAME < /dev/null
57 (When statements are "edge-triggered", meaning that this job will only
58 run when the load goes from under 6 to E<ge> 6).
60 Like L<crontab(5)>, whenjobs are controlled by a jobs file which can
61 be edited from the command line:
65 Whenjobs uses a daemon called L<whenjobsd(8)>. Unlike crond, this
66 daemon runs as the same user. Each user who wants to use whenjobs
67 starts their own daemon:
69 $ whenjobs --daemon-start
71 You can also have the daemon start as you when the machine boots by
72 adding the following line to a boot file such as C</etc/rc.local>.
73 Replace C<username> with your username:
75 su username -c /usr/sbin/whenjobsd
77 Variables are the key to expressing dependencies between whenjobs.
78 Variables are stored (per-user) in the daemon. You can use the
79 command line tool to examine and set variables:
81 $ whenjobs --variables
83 $ whenjobs --set cat=sushi
87 The act of setting a variable (using I<--set>) can trigger jobs to run.
93 =item B<--cancel> serial
95 Cancel the job with the given serial number.
97 Use I<--jobs> to list running jobs along with their serial numbers.
98 The serial number is also available in the job script (as
99 C<$JOBSERIAL>) and in the log file.
101 =item B<--daemon-start>
103 =item B<--daemon-stop>
105 Start and stop the per-user daemon.
107 =item B<--daemon-status>
109 Prints the status of the daemon: C<up> or C<down>.
111 =item B<--daemon-restart>
113 Restart the daemon. (If it is not running, then this command
120 Edit the jobs script. If you make changes to the jobs script, then it
121 is automatically uploaded to the daemon.
123 The C<$EDITOR> environment variable is used for editing. If not set,
126 =item B<--get> variable
128 Print the value of a variable.
132 List the names of all loaded jobs (whether they are running or not).
133 Use I<--jobs> to list running jobs.
137 List all running jobs.
139 Note that it is possible for the same job to be running more than once
140 (for example, a periodic job that takes longer than the period to run).
146 List the jobs script.
148 =item B<--lib> directory
150 Set the library directory which needs to contain the auxiliary files
151 C<pa_when.cmo> and C<whenlib.cma>. Normally you do not need to
152 specify this. However if you are running whenjobs without installing
153 it, then you need to point this to the C<lib/> directory from the
156 whenjobs --lib $builddir/lib -e
158 =item B<--set> variable=value [variable=value ...]
160 =item B<--type> bool|int|float|string|unit
162 I<--set> sets the variable named C<variable> to the new C<value>. The
163 variable is created if it does not already exist. Note that setting a
164 variable can cause jobs to run immediately.
166 To unset a variable, set it to the empty string like this:
170 By default variables are strings. You can also set the type of a
171 variable when setting it by adding the optional I<--type> parameter.
172 The I<--type> parameter should come I<before> the variable
173 declaration, like this:
175 whenjobs --set --type int free_space=10000
177 See the discussion of variable types in the L</REFERENCE> section
180 You can set multiple variables. When setting multiple variables in a
181 single command, the values are all changed in a single atomic
184 whenjobs --set cat=sushi food=fish
186 When using I<--type> and multiple variables, the type changes the
187 remaining command line parameters until the next I<--type>, eg:
189 whenjobs --set cat=sushi --type float weight=3.5 --type string food=fish
191 (C<cat> and C<food> are strings, and C<weight> is a float).
193 =item B<--start> "job name"
195 Start the job immediately and unconditionally.
197 This runs the job even if its normal preconditions are not met. This
198 may cause unexpected results, so use with caution.
200 =item B<--tail> serial
202 Tail the output of the running job identified by its serial number.
203 Use the I<--jobs> flag to get a list of running jobs.
205 =item B<--test> variable=value [variable=value ...]
207 This works the same way as the I<--set> option, but the difference is
208 that the variables are not set. Instead, it lists out the jobs that
209 I<would> run, I<if> the variables were updated to these new values.
211 The variables are not actually updated, and the jobs are not actually
214 The output is a list of job names that would run.
218 Compile the jobs script and upload it to the daemon, without editing.
219 Note that the I<--edit> option does this automatically. Furthermore,
220 when the daemon is started it checks for a jobs script and loads it if
225 Display all the variables and their values, in the format C<name=value>.
231 Display the name and version of the program and exit.
237 Display brief usage and exit.
243 A whenjobs file consists of a series of one or more "every" or "when"
246 Comments in the file can be written using C<(* ... *)>. Comments
249 Shell script fragments are written using C<E<lt>E<lt> ... E<gt>E<gt>>.
250 Within shell script fragments, use C<#> for comments (as in ordinary
251 shell scripts). Because C<E<gt>E<gt>> has a special meaning, it
252 cannot be used in the shell script (ie. for redirection). You have to
253 write C<E<gt>\E<gt>> instead which is replaced with C<E<gt>E<gt>> when
254 the shell script is parsed.
256 =head2 EVERY STATEMENTS (PERIODIC JOBS)
258 An every statement has the form:
265 where C<E<lt>periodE<gt>> is a I<period expression>, which may take
266 one of the forms below. Don't forget the colon character between the
267 period expression and the shell script.
269 An every statement is a job which runs periodically.
271 =head3 PERIOD EXPRESSIONS
275 =item B<every second>
277 The job runs every second.
279 =item B<every minute>
281 The job runs every minute.
285 The job runs every hour.
289 The job runs every day, at midnight UTC.
293 The job runs every week, on a Thursday at midnight UTC.
297 The job runs every month, on the first of the month at midnight UTC.
301 The job runs every year, on the first day of the year at midnight UTC.
303 =item B<every decade>
305 =item B<every century>
307 =item B<every millenium>
309 The job runs every 10, 100 or 1000 years.
311 =item B<every I<N> seconds>
313 The job runs every I<N> seconds (I<N> is any number E<ge> 1).
315 =item B<every I<N> minutes>
317 The job runs every I<N> minutes.
319 =item B<every I<N> hours>
321 The job runs every I<N> hours.
323 =item B<every I<N> days>
325 The job runs every I<N> days.
327 =item B<every I<N> weeks>
329 The job runs every I<N> weeks.
331 =item B<every I<N> months>
333 The job runs every I<N> months.
335 =item B<every I<N> years>
337 =item B<every I<N> decades>
339 =item B<every I<N> centuries>
341 =item B<every I<N> millenia>
343 The job runs every I<N>, I<10*N>, I<100*N> or I<1000*N> years.
347 =head2 WHEN STATEMENTS (DEPENDENT JOBS)
349 A when statement has the form:
356 where C<E<lt>exprE<gt>> is a I<when expression>, described below.
357 Don't forget the colon character between the period expression and the
360 A when statement is a job which runs when the conditions described in
361 its when-expression become true.
363 When jobs are I<edge triggered>. This means that they run when the
364 condition changes from false to true (or in the case where the
365 expression has not been evaluated before, when it evaluates initially
368 =head3 WHEN EXPRESSIONS
370 When expressions are fully recursive expressions constructed from the
375 =item I<expr> B<&&> I<expr>
377 =item I<expr> B<||> I<expr>
379 The boolean "and" or "or" of the two sub-expressions.
381 =item I<expr> B<E<lt>> I<expr>
383 =item I<expr> B<E<lt>=> I<expr>
385 =item I<expr> B<==> I<expr>
387 =item I<expr> B<E<gt>=> I<expr>
389 =item I<expr> B<E<gt>> I<expr>
391 The two sub-expressions are evaluated and the usual comparison
392 operator is performed.
394 If the sub-expressions are numeric, then numeric comparison is done.
395 If either sub-expression is non-numeric, then both expressions are
396 converted (if necessary) to strings and string comparison is done.
400 Boolean negative of I<expr>.
402 =item I<expr> B<+> I<expr>
404 For numeric sub-expressions, this performs addition.
406 If both sub-expressions are strings, this performs string
409 Other types give an error.
411 =item I<expr> B<-> I<expr>
413 =item I<expr> B<*> I<expr>
415 =item I<expr> B</> I<expr>
417 =item I<expr> B<mod> I<expr>
419 Both sub-expressions are evaluated, and if both are numeric, then the
420 result is subtraction, multiplication, division or modulo.
422 Other types give an error. Note that I<mod> really is an infix
427 If I<expr> is a string, this returns the length of the string.
431 The value of the named variable.
433 Previously undefined variables are automatically initialized to the
436 =item B<prev> I<variable>
438 The I<previous> value of the named variable. This means, the value
439 that it had last time this when-job ran.
441 If the when-job has not run yet, then this returns C<"">.
443 Job state is preserved across file reloads, but I<only> for jobs that
444 are explicitly named. If you find that jobs using C<prev>, C<changes>
445 etc are running unnecessarily when the jobs file is edited or
446 uploaded, try giving the jobs an explicit name.
448 =item B<changes> I<variable>
450 If the named variable has changed since this job last ran, then this
451 evaluates to true, else false.
453 This is the same as writing C<prev variable == variable>.
455 =item B<increases> I<variable>
457 If the named variable has changed and increased since this job last
458 ran, then this evaluates to true, else false.
460 This is the same as writing C<prev variable E<lt> variable>.
462 =item B<decreases> I<variable>
464 If the named variable has changed and decreased since this job last
465 ran, then this evaluates to true, else false.
467 This is the same as writing C<prev variable E<gt> variable>.
469 B<Note:> There is a subtle gotcha with the I<decreases> operator: The
470 first time the expression is evaluated, the job has (by definition)
471 not yet run. Therefore C<prev variable> evaluates to C<""> (see
472 definition of I<prev> above). Since it is always true that
476 the I<decreases> operator evaluates to false, and since this usually
477 means the job does not run, the operator always evaluates to false.
479 To fix this, ensure that the variable is initialized (see
480 L</SETTING THE INITIAL VALUE OF VARIABLES> below).
484 This evaluates to true the first time the expression is evaluated
485 after the jobs file has been reloaded or the daemon restarted.
486 Thereafter it evaluates to false.
488 Don't use this to initialize variables: it won't do what you mean.
494 Constants that evaluate to boolean false or true respectively.
496 =item I<"any string">
500 In a boolean context, the empty string evaluates to false, and
501 non-empty strings evaluate to true.
505 Any integer. (Arbitrarily large integers are supported.)
507 In a boolean context, 0 evaluates to false, and non-zero evaluates to
518 Any floating point number.
520 In a boolean context, 0 evaluates to false, and non-zero evaluates to
527 The code between C<E<lt>E<lt> ... E<gt>E<gt>> is a shell script. It
528 is executed using C<$SHELL>, or if that environment variable is not
531 =head3 SHELL SCRIPT VARIABLES
533 Every variable that has been set (using the whenjobs I<--set> option)
534 is exported to the script, so you can simply get the value of any
535 variable by writing C<$name>.
537 In addition, there are some special variables available:
543 The name of the job. If the job has been named explicitly, then that
544 name is available through this variable, else it will be some implicit
549 The serial number of the job. This is simply a variable that
550 increments each time a job is run, and is unique to that run of the
555 Other environment variables such as C<$HOME>, C<$LOGNAME> etc are
558 =head3 SHELL SCRIPT TEMPORARY CURRENT DIRECTORY
560 The shell script runs with its current directory set to a temporary
561 directory. The temporary directory is removed when the shell script
562 exits. Therefore you can write temporary files here without worrying
563 about cleaning them up.
565 If you want to store permanent state, then you have to save it to a
566 well-known directory, eg. C<$HOME>, C</var> etc.
568 =head3 SHELL SCRIPT USER
570 The shell script runs as the ordinary user. It has no special
575 Jobs are given implicit names (C<job$1>, C<job$2> etc.). You can also
576 name jobs explicitly by preceeding the "every" or "when" statement
585 The job name is passed to the shell script in the C<$JOBNAME>
586 environment variable.
588 =head2 OCAML EXPRESSIONS
590 As well as simple "every" and "when" expressions, advanced users may
591 want to use arbitrary OCaml expressions, functions, etc in the jobs
592 script. These are useful for factoring common code or strings, for
593 setting the initial values of variables, or for defining pre and post
596 A simple example of an OCaml expression is:
598 let prefix = "daily_"
600 job (prefix ^ "virus_scan")
606 job (prefix ^ "disk_check")
612 which creates two jobs called C<"daily_virus_scan"> and
613 C<"daily_disk_check"> (C<^> is the OCaml string concatenation
616 OCaml expressions have access to a library of functions called
617 B<Whentools> which is described below. It lets you set variables,
618 create jobs algorithmically, etc.
620 The OCaml expressions run once, when the jobs file is being loaded or
623 =head3 SETTING THE INITIAL VALUE OF VARIABLES
625 Variables are created when they are referenced, and until set they
626 have the value empty string (just like the shell). Across file
627 reloads, the previous values of variables are preserved.
629 To initialize a variable to a known value when the jobs file is
630 loaded, call one of the C<Whentools.set_variable*> functions as in
634 Whentools.set_variable "name" "Richard";
635 Whentools.set_variable_int "counter" 0
639 Before a job runs, you can arrange that a C<pre> function is called.
640 This function may decide not to run the job (by returning C<false>).
642 One use for this is to prevent a particular job from running if there
643 is already an instance of the same job running:
646 pre (Whentools.one ())
649 # Takes longer than 10 seconds to run, but 'Whentools.one ()'
650 # will ensure only one is ever running.
654 When using pre functions, jobs must be given an explicit name, ie.
655 you must use the C<job> statement.
657 A number of pre functions are available in the library; see below.
659 You can also write your own post functions (in OCaml). The function
660 is passed one argument which is a C<Whentools.preinfo> struct, defined
661 below. It should return a boolean: C<true> if the job should run, and
662 C<false> if the job should not run.
664 Note that a fresh serial number (see L</JOBSERIAL>) is assigned to
665 each run, whether or not the job actually runs because of
668 =head3 POST FUNCTIONS
670 After a job runs, you can control what happens to its output by
671 writing a C<post> function. To write a post function you have to
672 name the job (ie. have an explicit C<job> statement). Put C<post ...>
673 after the job name like this:
676 post (Whentools.mailto "you@example.com")
682 A number of post functions are available in the library; see below.
684 You can also write your own post functions (in OCaml). The
685 function is passed one argument which is a C<Whentools.result> struct,
688 =head3 WHENTOOLS LIBRARY
694 =item B<Whentools.mailto> [I<~only_on_failure:true>]
695 [I<~from:from_address>] I<email_address> I<result>
697 This built-in post function sends the result of the script by email to
698 the given email address.
700 If the optional C<~only_on_failure:true> flag is set, then it is only
701 sent out if the script failed.
703 If the optional C<~from> flag is set, then the from address is set
704 accordingly. This is sometimes needed when sending mail.
706 Note the C<result> parameter is passed implicitly by the daemon. You
707 do not need to add it.
709 Here are some examples of using the mailto function:
712 post (Whentools.mailto "you@example.com")
719 post (Whentools.mailto ~only_on_failure:true
726 let from = "me@example.com"
727 let to_addr = "you@example.com"
730 post (Whentools.mailto ~from to_addr)
736 =item B<Whentools.max> I<n>
738 This built-in pre function ensures that a maximum of I<n> instances of
741 It checks the list of running jobs, and if I<n> or more instances are
742 already running, then it returns C<false>, which ensures that the new
745 =item B<Whentools.one> I<()>
747 This built-in pre function ensures that only one instance of the job
748 is running. It is the same as calling:
752 =item B<Whentools.set_variable> I<name> I<string>
754 Set variable I<name> to the string.
756 =item B<Whentools.set_variable_bool> I<name> I<b>
758 Set variable I<name> to the boolean value I<b>.
760 =item B<Whentools.set_variable_int> I<name> I<i>
762 Set variable I<name> to the integer value I<i>.
764 =item B<Whentools.set_variable_string> I<name> I<s>
766 Set variable I<name> to the string value <s>. This is
767 the same as I<Whentools.set_variable>.
769 =item B<Whentools.set_variable_float> I<name> I<f>
771 Set variable I<name> to the floating point value I<f>.
779 =item B<Whentools.preinfo>
781 This structure is passed to pre functions. It has the following
785 pi_job_name : string; # Job name.
786 pi_serial : Big_int.big_int; # Job serial number.
787 pi_variables : (string * variable) list; # Variables set in job.
788 pi_running : preinfo_running_job list; # List of running jobs.
790 and preinfo_running_job = {
791 pirun_job_name : string; # Running job name.
792 pirun_serial : Big_int.big_int; # Running job serial number.
793 pirun_start_time : float; # Running job start time.
794 pirun_pid : int; # Running job process ID.
797 =item B<Whentools.result>
799 This structure is passed to post functions. It has the following
803 res_job_name : string; # job name
804 res_serial : big_int; # job serial (same as $JOBSERIAL)
805 res_code : int; # return code from the shell script
806 res_tmpdir : string; # temporary directory script ran in
807 res_output : string; # filename of stdout/stderr output
808 res_start_time : float; # when the job started
817 =head1 ENVIRONMENT VARIABLES
827 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
831 Copyright (C) 2012 Red Hat Inc.
833 This program is free software; you can redistribute it and/or modify
834 it under the terms of the GNU General Public License as published by
835 the Free Software Foundation; either version 2 of the License, or
836 (at your option) any later version.
838 This program is distributed in the hope that it will be useful,
839 but WITHOUT ANY WARRANTY; without even the implied warranty of
840 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
841 GNU General Public License for more details.
843 You should have received a copy of the GNU General Public License
844 along with this program; if not, write to the Free Software
845 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.