html/cron.html

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
   2 <html>
   3   <head>
   4     <title>Crontab - doing things periodically</title>
   5
   6
   7         <meta name="Keywords" content="DX Cluster, DXSpider, Spider, Packet Cluster, DXCluster, Pavillion Software, AK1A, AX25, AX.25, WWV, Packet Radio, Amateur Radio, Propagation, DX, DXing, G1TLH, GB7TLH, Dirk Koopman, Mailing list, Linux, RedHat, PERL">
   8         <meta name="Description" content="Software and systems for realtime digital communications between amateur radio stations for the provision of information on propagation conditions and stations operating">
   9         <meta name="Author" content="Dirk Koopman G1TLH">
  10     <link rel=stylesheet href="style.css" type="text/css" title="default stylesheet">
  11   </head>
  12
  13   <body TEXT="#000000" LINK="#0000ff" VLINK="#800080" BGCOLOR="#FFFFFF">
  14         <FONT COLOR="#606060">
  15           <hr>
  16           <h2>Crontab - doing things periodically</h2>
  17           <hr>
  18         </font>
  19
  20
  21         <address><a href="mailto:djk@tobit.co.uk">Dirk Koopman G1TLH</a></address>
  22         <p>
  23           <!-- Created: Sun Dec 13 20:25:14 GMT 1998 -->
  24           <!-- hhmts start -->
  25 Last modified: Mon Apr 23 01:00:44 BST 2001
  26 <!-- hhmts end -->
  27         <h4>Introduction</h4>
  28
  29         There are a number of jobs that need to be done periodically. The
  30         principle one being starting <a
  31         href="connect.html">connections</a> to other clusters if you are
  32         not connected. The <tt>crontab</tt> allows you to do this.
  33
  34         <h4>Location</h4>
  35
  36         There two locations for the <tt>crontab</tt> files. The first and standard one (which
  37         in common with other 'issue' files should not be changed) lives at <b>/spider/cmd/crontab</b>.
  38         The sysop changable one lives at <b>/spider/local_cmd/crontab</b>.
  39
  40         <p>The files will automatically be re-read whenever you change them.
  41
  42         <h4>The <tt>Crontab</tt> File </h4>
  43
  44         The <tt>crontab</tt> file defines what is to be done and
  45         when. It consists of lines of text created by your favorite editor. Completely blank
  46         lines or lines starting with '#' are ignored.
  47
  48         <p>Each line of a <tt>crontab</tt> file contains six fields
  49         each separated with white space. The first five fields are times when the
  50         command is to be executed and the last field is the command
  51         itself. The time fields consist of:-
  52
  53         <p><table border=2>
  54           <tr><td>field</td><td>Allowed Values</td></tr>
  55           <tr><td>minute</td><td>0 - 59</td></tr>
  56           <tr><td>hour</td><td>0 - 23</td></tr>
  57           <tr><td>day of month</td><td>1 - 31</td></tr>
  58           <tr><td>month</td><td>1 - 12</td></tr>
  59           <tr><td>day of week</td><td>0 - 6 (0 is Sunday)</td></tr>
  60         </table>
  61
  62         <p>A field may be '*', which means 'any when' for that field.
  63
  64     <p>Ranges of numbers are allowed.  Ranges are two numbers
  65     separated with a hyphen.  The specified range is inclusive.  For
  66     example, 8-11 for an <tt>hours</tt> entry specifies execution at hours
  67     8, 9, 10 and 11.
  68
  69     <p>Lists are allowed.  A list is a set of numbers (or ranges)
  70     separated by commas.  Examples: <tt>1,2,5,9</tt> or <tt>0-3,5,8-12</tt>.
  71
  72         <p>Commands are actually small snippets of perl. They can be anything legal within
  73           perl and the context of the DXSpider <tt>cluster.pl</tt> daemon. The normal use will be connecting
  74           to another cluster and a set of routines are specially provided in the context
  75           of the <tt>DXCron</tt> package to make this easy. For example
  76         <pre>
  77   start_connect('gb7tlh') unless connected('gb7tlh')
  78     </pre>
  79         this could have also been written:
  80         <pre>
  81   start_connect('gb7tlh') if !connected('gb7tlh')
  82     </pre>
  83         but the first method is more 'perlish',
  84         <p>Either of these commands will attempt to start a <a href="connect.html">connection</a>  process to GB7TLH if it isn't
  85         already locally connected.
  86
  87         <p>There is absolutely no reason why you could not do something more complicated using information
  88           contained inside the DXSpider daemon, but this will obviously require a more complex line of code.
  89           You can also write your own functions, include them within the DXSpider system and call them from
  90           the <tt>crontab</tt>
  91
  92         <p>A full <tt>crontab</tt> file could like like:-
  93         <pre>
  94   #
  95   # This is a sample crontab file
  96   #
  97   #
  98   # check every 10 minutes to see if gb7tlh is connected and if not
  99   # start a connect job going
 100
 101   0,10,20,30,40,50 * * * * start_connect('gb7tlh') unless connected('gb7tlh')
 102
 103   # at 03:15 on Sundays start a job called 'analyse.pl' which does something
 104   # or other. This starts a new process and runs to completion, be careful
 105   # what you do with stdin and stdout as they are the same as those of
 106   # cluster.pl
 107
 108   15 3 * * 0 spawn('/spider/local/analyse.pl')
 109
 110   # this is a pointless command which will echo the string shown
 111   # on the same terminal as the cluster.pl program after substituting
 112   # the values for mycall and version
 113
 114   15,30 * * * spawn("echo $main::mycall is a DXSpider Version $main::version DX Cluster system")
 115
 116   # then there is always the highly contentious one like this little jem which
 117   # checks every hour to see if a certain callsign is connected to another cluster
 118   # and silently disconnects him. This is an example only (of course...)
 119
 120   23 * * * * rcmd('rcmd/gb7dxm disc/noinform G9TLH') if present_on('G9TLH', 'GB7DXM')
 121
 122   # some people like to do an hourly announce to say who they are. There is a
 123   # slight complication about this because of the announce duplicate checking
 124   # so you need to make each announce unique. I do this by adding a date and time
 125   # stamp on the end
 126
 127   0 * * * * run_cmd('ann CLUSTER: GB7DJK JO02LQ at ' . cldate . ' ' . ztime)
 128
 129         </pre>
 130
 131         It is important remember that these <tt>crontab</tt> routines execute in line with the main
 132         cluster code, so if you create a long, slow <tt>crontab</tt> command, it will impact on the speed
 133         and usability of the cluster as a whole.
 134
 135         <p>If you want to see what commands are being run and/or the syntax errors in the
 136           crontab, then run: <em>set/debug cron</em> on the console and monitor the
 137           debuging output (I use <em>watchdbg</em> in another window).
 138
 139         <P> To set the debugging back to normal do: <em>unset/debug cron</em>.
 140
 141         <h4>Standard Routines</h4>
 142
 143         As mentioned earlier, there are a small number of routines that are declared in <tt>DXCron</tt>
 144         context. They are there basically to make the starting of connections and external programs easy.
 145         They are:-
 146
 147         <ul>
 148           <li><b>run_cmd(&lt;cluster command string>)</b> - run any cluster command as
 149                 the node callsign. Any output is sent to the 'cron' debug channel
 150                 (<em>set/debug cron</em> to see this).
 151                 <br><br><li><b>connected(&lt;callsign>)</b> - returns true if the &lt;callsign> is directly connected
 152                 to this cluster node.
 153                 <br><br><li><b>start_connect(&lt;script-name>)</b> - starts a <a href="connect.html">connection</a>
 154                 script just as if you had typed in <tt>connect script-name</tt> on the sysop console client.
 155                 <br><br><li><b>spawn(&lt;command>)</b> - start a &lt;command> as a new process. This is used to do
 156                 various batch jobs that you may wish to happen at certain times of the day or week that operate
 157                 on your machine but don't require access to the real-time internals of the cluster daemon. You can
 158                 execute just about any command you like, but <em>be warned</em> <b>stdin</b> and <b>stdout</b> are
 159                 still connected to the same terminal (if any) as the cluster daemon. Any unix command and arguments
 160                 can used, see <tt>exec</tt> in the <a href="http://www.perl.com">perl</a> documentation.
 161                 <br><br><li><b>disconnect(&lt;callsign>)</b> - disconnects a locally connected station from your node.
 162                 <br><br><li><b>rcmd(&lt;node-call>, &lt;command>)</b> - send a command to another node in exactly the
 163                 same way as, for example, <tt>RCMD/GB7TLH disc GB7DJK</tt> typed on a sysop console.
 164                 <br><br><li><b>present(&lt;exact-callsign>)</b> and <b>presentish(&lt;callsign-no-ssid>)</b> - returns
 165                 true if the
 166                 callsign is connected anywhere on the cluster either with the exact callsign or with the callsign
 167                 minus its ssid respectively.
 168                 <br><br><li><b>present_on(&lt;exact-callsign>, &lt;node>)</b> and <b>presentish_on(&lt;callsign-no-ssid>, &lt;node>)</b> - returns
 169                 true if the
 170                 callsign is connected on the node specified either with the exact callsign or with the callsign
 171                 minus its ssid respectively.
 172                 <br><br><li><b>last_connect(&lt;callsign>)</b> - Returns the last connect time of the callsign or the
 173                 current time if it is currently connected locally.
 174         </ul>
 175
 176 <!-- Standard Footer!! -->
 177         <p>&nbsp;</p>
 178         <p>
 179           <FONT COLOR="#606060"><hr></font>
 180         <font color="#FF0000" size=-2>
 181           Copyright &copy; 1998 by Dirk Koopman G1TLH. All Rights Reserved<br>
 182         </font>
 183         <font color="#000000" size=-2>$Id$</font>
 184   </body>
 185 </html>