mods/wiki/tools/cron.d/HOWTO

   1
   2 This is an advanced extension; and most people won't need it. It is
   3 meant for big Wiki installations, where automating tasks makes sense.
   4 Don't worry if it looks ugly and overly complex or even useless to
   5 you - it then most likely is.
   6
   7
   8 what is it?
   9 ¯¯¯¯¯¯¯¯¯¯¯
  10 The scripts in the cron.d/ are to be executed regularily to automatically
  11 do certain administration tasks. Scripts that shall be executed MUST have
  12 a name like "Snn______.php" to be detected by the "run-parts.php" script.
  13
  14 Put all the configuration setting into run-parts.php, or simply create a
  15 "S02myconfig.php" to override settings from all the other snippets (which
  16 all too often are disabled per default). You can get a list of all possible
  17 config settings with `grep define * | sort | uniq ` or so.
  18
  19 Coding is less clean than in ewiki, but works for what is to be achieved.
  20
  21
  22 how often?
  23 ¯¯¯¯¯¯¯¯¯¯
  24 It is recommended that you activate the run-parts every day, if you can
  25 automate this via a cron daemon. But running them once a week (or depending
  26 on activity on your wiki even rarer) would do too.
  27
  28 There is an internal dispatcher ("anacron") which ensures that certain
  29 parts are run only once a week/month anyhow, so it doesn't hurt if this
  30 got triggered hourly or so.
  31
  32
  33 local cron activation
  34 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  35 If your provider gives you shell access and a real cron service, then
  36 use this to get your cron scripts running (use "EDITOR=joe crontab -e"
  37 on the commandline):
  38
  39 00 03 * * 5     \
  40   php -q /www/u54321/example.com/htdocs/ewiki/tools/cron.d/run-parts.php
  41
  42 (will run everything on Fridays at 03:00 - once a week is enough for
  43 most tasks)
  44
  45
  46 remote cron activation
  47 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  48 If you have a cron daemon running somewhere, then you can start the cron
  49 scripts in here with it too, by simply setting up a remote activation
  50 with wget:
  51
  52 00 03  * * *    \
  53      wget -o /dev/null -O /dev/stdout   \
  54      http://example.net/ewiki/tools/cron.d/run-parts.php
  55
  56 Will give you a log of what was run (-O /dev/stdout, cron will mail it
  57 automatically for correctly configured server accounts).
  58
  59 There are also free services which provide this form of web based
  60 cron activation.
  61
  62
  63 Using plugins/feature/anacron.php
  64 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  65 If you seriously can't get a real cron service, then use your Windows
  66 box` built-in task planner! ;)
  67
  68 No seriously, you can then simply use the script we provide as "anacron"
  69 extension. It hooks into ewiki and enables itself once a day, whenever
  70 a person or a search engine or spam bot visits your site. It does not
  71 delay page delivery by that, because it runs after the page has been
  72 finished.
  73
  74 It is highly recommended to use this, but as usual you can forget it if
  75 your provider has no PHP installed and only gives you "Safe-Mode-PHP".
  76
  77
  78 Or even starting by hand
  79 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  80 If there is not all that much activity on your Wiki, you may even want
  81 to start the scripts yourself every while in a month or so. Just point
  82 your browser to the directory, the index.php script will show up a form
  83 which eases starting. (This is only made so we can add an entry on the
  84 admin tools/ overview page.)
  85
  86
  87 password protection
  88 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
  89 There is no need to "protect" these scripts from getting run by anyone.
  90 Nobody can do you harm if he activates it, because the tools herein
  91 run automated and do only what they were configured to do and don't
  92 accept commands from outside. Also they run locked, cannot be interrupted
  93 once started and then typically don't slow down the server any much.
  94
  95 If you really want it, then please just create a file like "S04auth.php"
  96 and place a link - an include("...") or require statement - to the usual
  97 '../../fragments/funcs/auth.php' script.
  98
  99
 100 numbering scheme
 101 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 102 The S** ("start") scripts are run in their numeric order,
 103 the Z** and K** ("kill") scripts get run in reverse order.
 104
 105 The numbering scheme has been designed to group actions into how
 106 often they are to be executed. The "anacron" scripts and everything
 107 with two underscores in its name controls this behaviour - it has
 108 little to do with how the "run-parts.php" script operates.
 109
 110 There are however a few special ranges (subject to change at any
 111 later time):
 112
 113   S00-S09  pre-init
 114   S10-S19  config
 115            - start, preparations
 116            - locking, "anacron" stop watch init
 117   ---
 118   S20-S29  ALWAYS executed
 119            - on every run
 120   S30-S49  HOURLY run scripts
 121            - email2wiki gateway/import
 122   S50-S69  DAILY run scripts
 123            - creation of cache files,
 124            - preparing data for certain plugins
 125            - automated page deletion and cache file purging
 126            - syncing with other wikis
 127   S70-S89  WEEKLY run scripts
 128            - collecting statistical info, diffs
 129            - sending out mails where users signed on for (RecentNotify
 130              and WeekDiff, ...)
 131            - exchanging blacklists (spam)
 132   S90-S98  MONTHLY run scripts
 133            - backups
 134   S98,S99  ALWAYS executed
 135            - final actions
 136   ---
 137   Z00-S99  shutdown stuff
 138   K00-K99  hard clean-up
 139
 140 There is no requirement that you don't do something completely different
 141 in any stage as you see fit. And you can have two different files with
 142 the same numeric entry - in that case you just didn't know 102%-exactly
 143 which one of the two was started first.
 144
 145
 146 rearrangement tricks (COMPLICATED READING, UNINTERESTING NOTES)
 147 ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
 148 If it happens that you want one of the actions in a different time slice
 149 than it is per default, then you must use a trick if you don't want to
 150 rearrange the cron.d/ script directory after every update.
 151
 152 For example, if you want S92mimebackup to activate __weekly__ instead of
 153 __monthly__, you simply make a symlink (get the according utility for
 154 NT/Win32, or use include-wrapper there) to let's say "S82mybackup.php".
 155
 156 Then you only have to ensure that the "S92mimebackup.php" doesn't actually
 157 gets activated twice in every fourth week, so you create a "S92_jump93.php"
 158 script with simply "<?php $GOTO=93; ?>" in it. This will skip the other
 159 two existing "S92*" parts, because it is sorted (alphabetically) exactly
 160 before the other two.
 161
 162   HintTwo: If you needed the "S92binbackup" as well for some obscure
 163   reasons, then a name like "S92jump93.php" would do the trick, because it
 164   is alphabetically directly in between "...binback" and "...mimebackup".
 165   Typically the 'ls -l' directory listing shows exactly how PHPs asort()
 166   would order the scripts as well.
 167
 168 Though it's a bit complicated, this should work in most cases. Else you
 169 could simply create a "mycron/" directory and symlink only the plugins
 170 you really need and order them however you want. You could also use
 171 multiple such directories and start each collection by a different cron
 172 daemon timing rule to achieve the same our "anacron scheduler" script
 173 parts were meant to.
 174