tools/whenjobs.pod

   1 =encoding utf8
   2
   3 =head1 NAME
   4
   5 whenjobs - A powerful but simple cron replacement
   6
   7 =head1 SYNOPSIS
   8
   9 Editing the jobs script:
  10
  11  whenjobs -e | --edit
  12  whenjobs -l | --list
  13
  14 Get and set variables:
  15
  16  whenjobs --get variable
  17  whenjobs --set variable value [--type bool|int|float|string]
  18  whenjobs --variables
  19
  20 Start and stop the per-user daemon:
  21
  22  whenjobs --daemon-start
  23  whenjobs --daemon-stop
  24  whenjobs --daemon-status
  25  whenjobs --daemon-restart
  26
  27 =head1 DESCRIPTION
  28
  29 Whenjobs is a powerful but simple replacement for cron.  It lets you
  30 run jobs periodically like cron, but it also lets you trigger jobs to
  31 run when user-defined variables are set or change value.
  32
  33 Periodic jobs are written like this:
  34
  35  every 10 minutes :
  36  <<
  37    # Get the current load average.
  38    load=`awk '{print $1}' /proc/loadavg`
  39    whenjobs --set load $load --type float
  40  >>
  41
  42 When-statements let you create jobs that run based on variables set
  43 elsewhere:
  44
  45  when load >= 6 :
  46  <<
  47    mail -s "ALERT: high load average: $load" $LOGNAME < /dev/null
  48  >>
  49
  50 (When statements are "edge-triggered", meaning that this job will only
  51 run when the load goes from under 6 to E<ge> 6).
  52
  53 Like L<crontab(5)>, whenjobs are controlled by a jobs file which can
  54 be edited from the command line:
  55
  56  $ whenjobs -e
  57
  58 Whenjobs uses a daemon called L<whenjobsd(8)>.  Unlike crond, this
  59 daemon runs as the same user.  Each user who wants to use whenjobs
  60 starts their own daemon:
  61
  62  $ whenjobs --daemon-start
  63
  64 You can also have the daemon start as you when the machine boots by
  65 adding the following line to a boot file such as C</etc/rc.local>.
  66 Replace C<username> with your username:
  67
  68  su username -c /usr/sbin/whenjobsd
  69
  70 Variables are the key to expressing dependencies between whenjobs.
  71 Variables are stored (per-user) in the daemon.  You can use the
  72 command line tool to examine and set variables:
  73
  74  $ whenjobs --variables
  75  load=0.9
  76  $ whenjobs --set cat sushi
  77  $ whenjobs --get cat
  78  sushi
  79
  80 The act of setting a variable (using I<--set>) can trigger jobs to run.
  81
  82 =head1 OPTIONS
  83
  84 =over 4
  85
  86 =item B<--daemon-start>
  87
  88 =item B<--daemon-stop>
  89
  90 Start and stop the per-user daemon.
  91
  92 =item B<--daemon-status>
  93
  94 Prints the status of the daemon: C<up> or C<down>.
  95
  96 =item B<--daemon-restart>
  97
  98 Restart the daemon.  (If it is not running, then this command
  99 starts it).
 100
 101 =item B<-e>
 102
 103 =item B<--edit>
 104
 105 Edit the jobs script.  If you make changes to the jobs script, then it
 106 is automatically uploaded to the daemon.
 107
 108 The C<$EDITOR> environment variable is used for editing.  If not set,
 109 C<vi> is used.
 110
 111 =item B<--get> variable
 112
 113 Print the value of a variable.
 114
 115 =item B<-l>
 116
 117 =item B<--list>
 118
 119 List the jobs script.
 120
 121 =item B<--lib> directory
 122
 123 Set the library directory which needs to contain the auxiliary files
 124 C<pa_when.cmo> and C<whenlib.cma>.  Normally you do not need to
 125 specify this.  However if you are running whenjobs without installing
 126 it, then you need to point this to the C<lib/> directory from the
 127 source, eg:
 128
 129  whenjobs --lib $builddir/lib -e
 130
 131 =item B<--set> variable value
 132
 133 =item B<--type> bool|int|float|string
 134
 135 I<--set> sets the variable named C<variable> to the new C<value>.  The
 136 variable is created if it does not already exist.  Note that setting a
 137 variable can cause jobs to run immediately.
 138
 139 To unset a variable, set it to the empty string:
 140
 141  whenjobs --set var ""
 142
 143 By default variables are untyped (more precisely, they are treated as
 144 strings).  You can also set the type of a variable when setting it by
 145 adding the optional I<--type> parameter:
 146
 147  whenjobs --set free_space 10000 --type int
 148
 149 See the discussion of variable types in the L</REFERENCE> section
 150 below.
 151
 152 =item B<--upload>
 153
 154 Compile the jobs script and upload it to the daemon, without editing.
 155 Note that the I<--edit> option does this automatically.  Furthermore,
 156 when the daemon is started it checks for a jobs script and loads it if
 157 found.
 158
 159 =item B<--variables>
 160
 161 Display all the variables and their values, in the format C<name=value>.
 162
 163 =item B<-V>
 164
 165 =item B<--version>
 166
 167 Display the name and version of the program and exit.
 168
 169 =item B<-help>
 170
 171 =item B<--help>
 172
 173 Display brief usage and exit.
 174
 175 =back
 176
 177 =head1 REFERENCE
 178
 179
 180
 181
 182
 183 =head1 FILES
 184
 185
 186
 187 =head1 ENVIRONMENT VARIABLES
 188
 189
 190
 191 =head1 SEE ALSO
 192
 193 L<whenjobsd(8)>
 194
 195 =head1 AUTHOR
 196
 197 Richard W.M. Jones L<http://people.redhat.com/~rjones/>
 198
 199 =head1 COPYRIGHT
 200
 201 Copyright (C) 2012 Red Hat Inc.
 202
 203 This program is free software; you can redistribute it and/or modify
 204 it under the terms of the GNU General Public License as published by
 205 the Free Software Foundation; either version 2 of the License, or
 206 (at your option) any later version.
 207
 208 This program is distributed in the hope that it will be useful,
 209 but WITHOUT ANY WARRANTY; without even the implied warranty of
 210 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 211 GNU General Public License for more details.
 212
 213 You should have received a copy of the GNU General Public License
 214 along with this program; if not, write to the Free Software
 215 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.