Fix cron running every minute
[project/elysia_cron.git] / README.txt
1 ELYSIA_CRON
2 by Eric Berdondini (gotheric)
3 <eric@void.it>
4
5 For installation instructions read INSTALL.TXT
6 For module developers API documetation read API.TXT
7
8 -----------------------------------------------------------------------------
9 FEATURES
10 -----------------------------------------------------------------------------
11
12 Elysia Cron extends Drupal standard cron, allowing a fine grain control over 
13 each task and several ways to add custom cron jobs to your site.
14
15 - Set the timings and frequencies of each cron task (you can run some jobs every
16   day at a specified hour, other only monthly and so on...).
17   For each task you can simply choose between some frequently used options 
18   ("once a day", "once a month" ...), or use a powerful "linux crontab"-like 
19   syntax to set the accurate timings. You can even define your frequently used 
20   options to speed up site configuration.
21 - Parallel execution of cron task: you can group jobs in channels and execute 
22   then simultaneously: so a task that takes a lot of time to execute won't block
23   other tasks that need to be executed every 5 minutes...
24 - You can disable all tasks, an entire channel or a single task.
25 - Change the priority/order of task execution.
26 - Manual force the execution of a cron tasks.
27 - Detailed overview of cron status with time statistics for single tasks and 
28   channels.
29
30 - Powerful API for module developers: you can define extra cron tasks for your 
31   modules, each one with own default timings (site administrators can override 
32   them by configuration, other modules via hook_alter). Elysia Cron 2.0 gives a 
33   brand new API support (compatible with 1.0 version) with a lot of features.
34 - Administrators can define custom jobs (call to functions with parameters), via
35   the "script" option.
36 - Several optimization for frequent cron calls and error handling.
37 - Protection from external cron calling by cron_key or allowed host list.
38
39 Elysia has no dependencies with contributed modules, and doesn't need to patch
40 the core: it can be used in minimal Drupal installation with only core modules.
41 It also can be used in a Drupal install profile.
42
43 3rd party integration:
44 - Ping feature, for external tracking services like host-tracker to tell whether
45   cron is functioning properly on your site.
46 - Drush support: you can call "drush elysia-cron" to manually run extended cron.
47 - CTools support for exports/backup of task settings.
48 - Features support.
49
50 -----------------------------------------------------------------------------
51 USAGE EXAMPLES
52 -----------------------------------------------------------------------------
53
54 Elysia cron is usually used in large sites that needs performance optimization.
55
56 - Avoid drupal peak loads by distributing heavy load tasks during quiet periods 
57   of the day: for example you may want to rebuild the XML Sitemap of your site 
58   at 2:00AM in the morning, where usually only a few people are visiting your 
59   site. You can even move some tasks to be executed only once a month (log 
60   rotation, old records expiry...).
61
62 - If you have tasks that should be executed very often, but don't want to 
63   execute ALL drupal cron tasks that often! For example, you may want to check 
64   for emails that needs to be sent to your users every 2 minutes. Standard cron 
65   is managed in a "monolithic" way, so even if you find out how to execute it 
66   every 2 minutes, you will end in having all cron tasks executed so often, with
67   a lot of performance problems.
68
69 - Fine tune cron cache management : drupal cron will invalidate variable cache 
70   every cron run, and this is a great performance problem if you have a 
71   frequently called task. Elysia cron optimize cache management, and doesn't 
72   need to invalidate cache.
73
74 - Setup tasks that should be run at a precise time: for example if you want to 
75   send a SimpleNews newsletter every monday at 9:00AM, you can do it.
76
77 - Parallel execution: if you have a task that takes a lot of time to execute, 
78   you can setup a different channel for it so it won't block other tasks that 
79   need to be executed every 5 minutes.
80
81 - Turn off (disable) a cron task/feature you don't need.
82
83 - Debug system cron problems. If your cron does not terminate correctly you can
84   use extended logging, see at each cron timings and disable task to track down 
85   the problem.
86
87 -----------------------------------------------------------------------------
88 CHANNELS
89 -----------------------------------------------------------------------------
90
91 Channels are groups of tasks. Each channel is a "parallel line" of execution
92 (= multiple channels can be executed simultaneously).
93 Tasks inside a channel will be executed sequentially (if they should).
94
95 WARNING: It's not recommended to create more than 2 or 3 channels.
96 Every channel will increase the delay between each cron check (of the same 
97 channel), because each cron call will cycle between all channels.
98 So, for example:
99 If you have 1 channel it will be checked once a minute.
100 If you have 2 channel each one will be checked every 2 minutes (almost usually, 
101 when the other one is running it will be checked once a minute).
102 It you have 10 channels there will be a check every 10 minutes... if you have
103 a job that should be executed every 5 minutes it won't do so!
104
105 -----------------------------------------------------------------------------
106 EXPORT VIA CTOOLS/FEATURES MODULE
107 -----------------------------------------------------------------------------
108
109 With 2.0 version of Elysia Cron you can use "Bulk Export" functionality of 
110 "Chaos Tools Suite" to export cron settings.
111 To use it simply enable all modules, go to Structure > Bulk Exporter and
112 select the tasks you want to export settings. You can also select all 
113 "elysia_cron" prefixed variables to export global options.
114 Than generate the module.
115
116 The generated code will set the new defaults of elysia cron settings. This way
117 you can simply enable it to use them, but you are free to override them in
118 the future using the normal settings page.
119 Note that if you want to delete all overrides, and return to exported settings,
120 you should do a "reset to defaults" from elysia cron settings page. 
121
122 You can also use "Features" module to create a Feature module will the settings
123 you need.
124 Note that if you want to delete the overridden settings it's preferable to use
125 the "reset to defaults" elysia cron's button.
126 You can use the "Revert components" Features's button, but this will reset also
127 all cron statistics (if you are not interested in them you can freely use that
128 button).
129
130 -----------------------------------------------------------------------------
131 DRUSH SUPPORT
132 -----------------------------------------------------------------------------
133
134 Elysia Cron 2.0 adds a simple support for Drush module.
135
136 You can execute the "elysia-cron" command to run cron.
137
138 -----------------------------------------------------------------------------
139 RULES AND SCRIPT SYNTAX
140 -----------------------------------------------------------------------------
141
142 1. FIELDS ORDER
143 ---------------------------------
144
145  +---------------- minute (0 - 59)
146  |  +------------- hour (0 - 23)
147  |  |  +---------- day of month (1 - 31)
148  |  |  |  +------- month (1 - 12)
149  |  |  |  |  +---- day of week (0 - 6) (Sunday=0)
150  |  |  |  |  |
151  *  *  *  *  *
152
153 Each of the patterns from the first five fields may be either * (an asterisk), 
154 which matches all legal values, or a list of elements separated by commas 
155 (see below).
156
157 For "day of the week" (field 5), 0 is considered Sunday, 6 is Saturday (7 is 
158 an illegal value)
159
160 A job is executed when the time/date specification fields all match the current 
161 time and date. There is one exception: if both "day of month" and "day of week" 
162 are restricted (not "*"), then either the "day of month" field (3) or the "day 
163 of week" field (5) must match the current day (even though the other of the two 
164 fields need not match the current day).
165
166 2. FIELDS OPERATOR
167 ---------------------------------
168
169 There are several ways of specifying multiple date/time values in a field:
170
171 * The comma (',') operator specifies a list of values, for example: "1,3,4,7,8"
172 * The dash ('-') operator specifies a range of values, for example: "1-6", which 
173   is equivalent to "1,2,3,4,5,6"
174 * The asterisk ('*') operator specifies all possible values for a field. For 
175   example, an asterisk in the hour time field would be equivalent to 'every hour' 
176   (subject to matching other specified fields).
177 * The slash ('/') operator (called "step") can be used to skip a given number of 
178   values. For example, "*/3" in the hour time field is equivalent to 
179   "0,3,6,9,12,15,18,21".
180
181 3. EXAMPLES
182 ---------------------------------
183
184  */15 * * * : Execute job every 15 minutes
185  0 2,14 * * *: Execute job every day at 2:00 and 14:00
186  0 2 * * 1-5: Execute job at 2:00 of every working day
187  0 12 1 */2 1: Execute job every 2 month, at 12:00 of first day of the month OR
188  at every monday.
189
190 4. SCRIPTS
191 ---------------------------------
192
193 You can use the script section to easily create new jobs (by calling a php 
194 function) or to change the scheduling of an existing job.
195
196 Every line of the script can be a comment (if it starts with #) or a job 
197 definition.
198
199 The syntax of a job definition is:
200 <-> [rule] <ctx:CONTEXT> [job]
201
202 (Tokens betweens [] are mandatory)
203
204 * <->: a line starting with "-" means that the job is DISABLED.
205 * [rule]: a crontab schedule rule. See above.
206 * <ctx:CHANNEL>: set the channel of the task.
207 * [job]: could be the name of a supported job (for example: 'search_cron') or a
208   function call, ending with ; (for example: 'process_queue();').
209
210 A comment on the line just preceding a job definition is considered the job 
211 description.
212
213 Remember that script OVERRIDES all settings on single jobs sections or channel 
214 sections of the configuration
215
216 5. EXAMPLE OF SCRIPT
217 ---------------------------------
218
219 # Search indexing every 2 hours (i'm setting this as the job description)
220 0 */2 * * * search_cron
221
222 # I'll check for module status only on sunday nights 
223 # (and this is will not be the job description, see the empty line below)
224
225 0 2 * * 0 update_status_cron
226
227 # Trackback ping process every 15min and on a channel called "net"
228 */15 * * * * ctx:net trackback_cron
229
230 # Disable node_cron (i must set the cron rule even if disabled)
231 - */15 * * * * node_cron
232
233 # Launch function send_summary_mail('test@test.com', false); every night
234 # And set its description to "Send daily summary"
235 # Send daily summary
236 0 1 * * *  send_summary_mail('test@test.com', false);
237
238 -----------------------------------------------------------------------------
239 CREDITS
240 -----------------------------------------------------------------------------
241
242 Elysia cron is a part of the Elysia project (but could be used stand alone
243 with no limitation).
244
245 Developing is sponsored by :
246 Void Labs s.n.c
247 http://www.void.it