Debian Codegraph @

upstream/fedora-44/man5/crontab.5

raw
1 .\"/* Copyright 1988,1990,1993,1994 by Paul Vixie
2 .\" * All rights reserved
3 .\" */
4 .\"
5 .\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
6 .\" Copyright (c) 1997,2000 by Internet Software Consortium, Inc.
7 .\"
8 .\" Permission to use, copy, modify, and distribute this software for any
9 .\" purpose with or without fee is hereby granted, provided that the above
10 .\" copyright notice and this permission notice appear in all copies.
11 .\"
12 .\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
13 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
14 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR
15 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
16 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
17 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
18 .\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
19 .\"
20 .\" $Id: crontab.5,v 1.6 2004/01/23 19:03:33 vixie Exp $
21 .\"
22 .TH CRONTAB 5 2012-11-22 "cronie" "File Formats"
23 .SH NAME
24 crontab \- files used to schedule the execution of programs
25 .SH DESCRIPTION
26 A
27 .I crontab
28 file contains instructions for the
29 .BR cron (8)
30 daemon in the following simplified manner: "run this command at this time
31 on this date". Each user can define their own crontab. Commands defined
32 in any given crontab are executed under the user who owns that particular
33 crontab. Uucp and News usually have their own crontabs, eliminating the
34 need for explicitly running
35 .BR su (1)
36 as part of a cron command.
37 .PP
38 Blank lines, leading spaces, and tabs are ignored. Lines whose first
39 non-white space character is a pound-sign (#) are comments, and are not
40 processed. Note that comments are not allowed on the same line as cron
41 commands, since they are considered a part of the command. Similarly,
42 comments are not allowed on the same line as environment variable
43 settings.
44 .PP
45 An active line in a crontab is either an environment setting or a cron
46 command. An environment setting is of the form:
47 .PP
48 name = value
49 .PP
50 where the white spaces around the equal-sign (=) are optional, and any
51 subsequent non-leading white spaces in
52 .I value
53 is a part of the value assigned to
54 .IR name .
55 The
56 .I value
57 string may be placed in quotes (single or double, but matching) to
58 preserve leading or trailing white spaces.
59 .PP
60 Several environment variables are set up automatically by the
61 .BR cron (8)
62 daemon.
63 .I SHELL
64 is set to /bin/sh, and
65 .I LOGNAME
66 and
67 .I HOME
68 are set from the /etc/passwd line of the crontab\'s owner.
69 .I HOME
70 and
71 .I SHELL
72 can be overridden by settings in the crontab; LOGNAME can not.
73 .PP
74 (Note: the
75 .I LOGNAME
76 variable is sometimes called
77 .I USER
78 on BSD systems and is also automatically set).
79 .PP
80 In addition to
81 .IR LOGNAME ,
82 .IR HOME ,
83 and
84 .IR SHELL ,
85 .BR cron (8)
86 looks at the
87 .I MAILTO
88 variable if a mail needs to be send as a result of running any commands
89 in that particular crontab. If
90 .I MAILTO
91 is defined (and non-empty), mail is sent to the specified address. If
92 .I MAILTO
93 is defined but empty
94 .RI ( MAILTO="" ),
95 no mail is sent. Otherwise, mail is sent to the owner of the crontab.
96 This option is useful if you decide to use /bin/mail instead of
97 /usr/lib/sendmail as your mailer. Note that /bin/mail does not provide
98 aliasing and UUCP usually does not read its mail. If
99 .I MAILFROM
100 is defined (and non-empty), it is used as the envelope sender address,
101 otherwise, the username of the executing user is used. This variable is
102 also inherited from the crond process environment.
103 .PP
104 (Note: Both
105 .I MAILFROM
106 and
107 .I MAILTO
108 variables are expanded, so setting them as in the following example works as expected: [email protected] ($USER is replaced by the system user) )
109 .PP
110 By default, cron sends a mail using the 'Content-Type:' header
111 of 'text/plain' with the 'charset=' parameter set to the 'charmap/codeset'
112 of the locale in which
113 .BR crond (8)
114 is started up, i.e., either the default system locale, if no LC_*
115 environment variables are set, or the locale specified by the LC_*
116 environment variables (see
117 .BR locale (7)).
118 Different character encodings can be used for mailing cron job outputs by
119 setting the
120 .I CONTENT_TYPE
121 and
122 .I CONTENT_TRANSFER_ENCODING
123 variables in a crontab to the correct values of the mail headers of those
124 names.
125 .PP
126 The
127 .I CRON_TZ
128 variable specifies the time zone specific for the cron table. The user
129 should enter a time according to the specified time zone into the table.
130 The time used for writing into a log file is taken from the local time
131 zone, where the daemon is running.
132 .PP
133 The
134 .I MLS_LEVEL
135 environment variable provides support for multiple per-job SELinux
136 security contexts in the same crontab. By default, cron jobs execute
137 with the default SELinux security context of the user that created the
138 crontab file. When using multiple security levels and roles, this may
139 not be sufficient, because the same user may be running in different
140 roles or in different security levels. For more information about roles
141 and SELinux MLS/MCS, see
142 .BR selinux (8)
143 and the crontab example mentioned later on in this text. You can set the
144 .I MLS_LEVEL
145 variable to the SELinux security context string specifying the particular
146 SELinux security context in which you want jobs to be run.
147 .B crond
148 will then set the execution context of those jobs that meet the
149 specifications of the particular security context. For more information,
150 see
151 .BR crontab (1)\ -s\ option.
152 .PP
153 The
154 .I RANDOM_DELAY
155 variable allows delaying job startups by random amount of minutes with
156 upper limit specified by the variable. The random scaling factor is
157 determined during the cron daemon startup so it remains constant for
158 the whole run time of the daemon.
159 .PP
160 The
161 .I XDG_SESSION_CLASS
162 variable specifies the session class to be used when PAM creates a systemd
163 session for the cron job. If set (e.g., to "background-light"), this value
164 is forwarded to the PAM environment so that
165 .BR pam_systemd (8)
166 can use it for session classification. This allows cron jobs to run in
167 lighter-weight sessions that consume fewer system resources. This variable
168 has no effect if crond was built without PAM support.
169 .PP
170 The format of a cron command is similar to the V7 standard, with a number
171 of upward-compatible extensions. Each line has five time-and-date fields
172 followed by a
173 .BR user name
174 (if this is the
175 .BR system
176 crontab file), and followed by a command. Commands are executed by
177 .BR cron (8)
178 when the 'minute', 'hour', and 'month of the year' fields match the
179 current time,
180 .I and
181 at least one of the two 'day' fields ('day of month', or 'day of week')
182 match the current time (see "Note" below).
183 .PP
184 Note that this means that non-existent times, such as the "missing hours"
185 during the daylight savings time conversion, will never match, causing
186 jobs scheduled during the "missing times" not to be run. Similarly,
187 times that occur more than once (again, during the daylight savings time
188 conversion) will cause matching jobs to be run twice.
189 .PP
190 .BR cron (8)
191 examines cron entries every minute.
192 .PP
193 The time and date fields are:
194 .IP
195 .ta 1.5i
196 field allowed values
197 .br
198 ----- --------------
199 .br
200 minute 0-59
201 .br
202 hour 0-23
203 .br
204 day of month 1-31
205 .br
206 month 1-12 (or names, see below)
207 .br
208 day of week 0-7 (0 or 7 is Sunday, or use names)
209 .br
210 .PP
211 A field may contain an asterisk (*), which always stands for
212 "first\-last".
213 .PP
214 Ranges of numbers are allowed. Ranges are two numbers separated with a
215 hyphen. The specified range is inclusive. For example, 8-11 for
216 an 'hours' entry specifies execution at hours 8, 9, 10, and 11. The first
217 number must be less than or equal to the second one.
218 .PP
219 Randomization of the execution time within a range can be used.
220 A random number within a range specified as two numbers separated with
221 a tilde is picked. The specified range is inclusive.
222 For example, 6~15 for a 'minutes' entry picks a random minute
223 within 6 to 15 range. The random number is picked when crontab file is parsed.
224 The first number must be less than or equal to the second one. You might omit
225 one or both of the numbers specifying the range. For example, ~ for a 'minutes'
226 entry picks a random minute within 0 to 59 range.
227 .PP
228 Lists are allowed. A list is a set of numbers (or ranges) separated by
229 commas. Examples: "1,2,5,9", "0-4,8-12".
230 .PP
231 Step values can be used in conjunction with ranges. Following a range
232 with "/<number>" specifies skips of the number's value through the range.
233 For example, "0-23/2" can be used in the 'hours' field to specify command
234 execution for every other hour (the alternative in the V7 standard is
235 "0,\:2,\:4,\:6,\:8,\:10,\:12,\:14,\:16,\:18,\:20,\:22"). Step values are
236 also permitted after an asterisk, so if specifying a job to be run every
237 two hours, you can use "*/2". Please note that steps are evaluated just
238 within the field they are applied to. For example "*/23" in hours field
239 means to execute the job on the hour 0 and the hour 23 within a calendar
240 day. See "NOTES" below for a workaround.
241 .PP
242 Names can also be used for the 'month' and 'day of week' fields. Use the
243 first three letters of the particular day or month (case does not
244 matter). Ranges and lists of names are allowed. Examples: "mon,wed,fri",
245 "jan-mar".
246 .PP
247 If the UID of the owner is 0 (root), the first character of a crontab
248 entry can be "-" character. This will prevent cron from writing a syslog
249 message about the command being executed.
250 .PP
251 The "sixth" field (the rest of the line) specifies the command to be run.
252 The entire command portion of the line, up to a newline or a "%"
253 character, will be executed by /bin/sh or by the shell specified in the
254 SHELL variable of the cronfile. A "%" character in the command, unless
255 escaped with a backslash (\\), will be changed into newline characters,
256 and all data after the first % will be sent to the command as standard
257 input.
258 .PP
259 Note: The day of a command's execution can be specified in the following
260 two fields \(em 'day of month', and 'day of week'. If both fields are
261 restricted (i.e., do not contain the "*" character), the command will be
262 run when
263 .I either
264 field matches the current time. For example,
265 .br
266 "30 4 1,15 * 5" would cause a command to be run at 4:30 am on the 1st and
267 15th of each month, plus every Friday.
268 .PP
269 A crontab file syntax can be tested before an install using the -T option. See
270 .BR crontab (1)
271 for details.
272 .SH EXAMPLE CRON FILE
273 .nf
274 # use /bin/sh to run commands, no matter what /etc/passwd says
275 SHELL=/bin/sh
276 # mail any output to `paul', no matter whose crontab this is
277 MAILTO=paul
278 #
279 CRON_TZ=Japan
280 # run five minutes after midnight, every day
281 5 0 * * * $HOME/bin/daily.job >> $HOME/tmp/out 2>&1
282 # run at 2:15pm on the first of every month -- output mailed to paul
283 15 14 1 * * $HOME/bin/monthly
284 # run at 10 pm on weekdays, annoy Joe
285 0 22 * * 1-5 mail -s "It's 10pm" joe%Joe,%%Where are your kids?%
286 23 0-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday"
287 5 4 * * sun echo "run at 5 after 4 every sunday"
288 .fi
289 .SH Jobs in /etc/cron.d/
290 The jobs in
291 .I cron.d
292 and
293 .I /etc/crontab
294 are system jobs, which are used usually for more than one user, thus,
295 additionally the username is needed. MAILTO on the first line is
296 optional.
297 .SH EXAMPLE OF A JOB IN /etc/cron.d/job
298 .nf
299 #login as root
300 #create job with preferred editor (e.g. vim)
301 MAILTO=root
302 * * * * * root touch /tmp/file
303 .fi
304 .SH NOTES
305 As noted above, skip values only operate within the time period they\'re
306 attached to. For example, specifying "0/35" for the minute field of a
307 crontab entry won\'t cause that entry to be executed every 35 minutes;
308 instead, it will be executed twice every hour, at 0 and 35 minutes past.
309 For more fine-grained control you can do something like this:
310 .nf
311 * * * * * if [ $(expr \\( $(date +%s) / 60 \\) % 58) = 0 ]; then echo this runs every 58 minutes; fi
312 0 * * * * if [ $(expr \\( $(date +%s) / 3600 \\) % 23) = 0 ]; then echo this runs every 23 hours on the hour; fi
313 .fi
314 Adjust as needed if your
315 .BR date (1)
316 command does not accept "+%s" as the format string specifier to output
317 the current UNIX timestamp.
318 .SH SELinux with multi level security (MLS)
319 In a crontab, it is important to specify a security level by
320 .I crontab \-s
321 or specifying the required level on the first line of the crontab. Each
322 level is specified in
323 .IR /etc/selinux/targeted/seusers .
324 When using crontab in the MLS mode, it is especially important to:
325 .br
326 - check/change the actual role,
327 .br
328 - set correct
329 .I role for
330 .IR directory ,
331 which is used for input/output.
332 .SH EXAMPLE FOR SELINUX MLS
333 .nf
334 # login as root
335 newrole -r sysadm_r
336 mkdir /tmp/SystemHigh
337 chcon -l SystemHigh /tmp/SystemHigh
338 crontab -e
339 # write in crontab file
340 MLS_LEVEL=SystemHigh
341 0-59 * * * * id -Z > /tmp/SystemHigh/crontest
342 .fi
343 .SH FILES
344 .I /etc/crontab
345 main system crontab file.
346 .I /var/spool/cron/
347 a directory for storing crontabs defined by users.
348 .I /etc/cron.d/
349 a directory for storing system crontabs.
350 .SH "SEE ALSO"
351 .BR cron (8),
352 .BR crontab (1)
353 .SH EXTENSIONS
354 These special time specification "nicknames" which replace the 5 initial
355 time and date fields, and are prefixed with the '@' character, are
356 supported:
357 .PP
358 .nf
359 @reboot : Run once after reboot.
360 @yearly : Run once a year, ie. "0 0 1 1 *".
361 @annually : Run once a year, ie. "0 0 1 1 *".
362 @monthly : Run once a month, ie. "0 0 1 * *".
363 @weekly : Run once a week, ie. "0 0 * * 0".
364 @daily : Run once a day, ie. "0 0 * * *".
365 @hourly : Run once an hour, ie. "0 * * * *".
366 .fi
367 .SH CAVEATS
368 .BR crontab
369 files have to be regular files or symlinks to regular files, they must
370 not be executable or writable for anyone else but the owner. This
371 requirement can be overridden by using the
372 .B \-p
373 option on the crond command line. If inotify support is in use, changes
374 in the symlinked crontabs are not automatically noticed by the cron
375 daemon. The cron daemon must receive a SIGHUP signal to reload the
376 crontabs. This is a limitation of the inotify API.
377 .PP
378 cron requires that each entry in a crontab end in a newline character. If the
379 last entry in a crontab is missing a newline (i.e.\& terminated by EOF),
380 cron will consider the crontab (at least partially) broken.
381 A warning will be written to syslog.
382 .SH AUTHOR
383 .MT [email protected]
384 Paul Vixie
385 .ME