From: Christian Kastner Date: Mon, 28 Dec 2015 01:35:31 +0100 Subject: Debian manpage and doc updates A collection of various corrections, clarifications, and additions to the manpages cron.8, crontab.1, and crontab.5 which are not specific to Debian's version of vixie cron. Fixes mostly provided originally by Steve Greenland , with numerous smaller contributions by others. Forwarded: not-needed Last-Update: 2016-01-16 --- README | 6 +++++ cron.8 | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- crontab.1 | 28 +++++++++++++++++----- crontab.5 | 55 ++++++++++++++++++++++++++++++++++++++---- 4 files changed, 157 insertions(+), 14 deletions(-) diff --git a/README b/README index 751f04f..03a4051 100644 --- a/README +++ b/README @@ -24,6 +24,12 @@ December 27, 1993 [V1.0 was May 6, 1987] Paul Vixie +[Note from Debian cron maintainer: This is the original README from +the the vixie-cron package. The location of many cron files has been +changed in order to comply with Debian policy and common sense -- look +in the cron(8), crontab(1) and crontab(5) man pages for more info, as +well as the README.Debian file in this directory.] + This is a version of 'cron' that is known to run on BSD 4.[23] systems. It is functionally based on the SysV cron, which means that each user can have their own crontab file (all crontab files are stored in a read-protected diff --git a/cron.8 b/cron.8 index eaca890..97cc48f 100644 --- a/cron.8 +++ b/cron.8 @@ -17,7 +17,7 @@ .\" .\" $Id: cron.8,v 2.2 1993/12/28 08:34:43 vixie Exp $ .\" -.TH CRON 8 "20 December 1993" +.TH CRON 8 "19 April 2010" .UC 4 .SH NAME cron \- daemon to execute scheduled commands (Vixie Cron) @@ -41,6 +41,12 @@ command should be used to access and update them. .I cron also reads /etc/crontab, which is in a slightly different format (see .IR crontab (5)). +In Debian, the content of /etc/crontab is predefined +to run programs under /etc/cron.hourly, /etc/cron.daily, +/etc/cron.weekly and /etc/cron.monthly. This configuration is specific to +Debian, see the note under +.B DEBIAN SPECIFIC +below. /etc/crontab must be owned by root, and must not be group-or other-writable. .I cron @@ -72,8 +78,78 @@ logs its action to the syslog facility 'cron', and logging may be controlled using the standard .IR syslogd (8) facility. +.SH ENVIRONMENT +If configured in +.I /etc/default/cron +in Debian systems, the +.I cron +daemon localisation settings environment can be managed through the use of +.I /etc/environment +or through the use of +.I /etc/default/locale +with values from the latter overriding values from the former. These +files are read and they will be used to setup the LANG, LC_ALL, and +LC_CTYPE environment variables. These variables are then used to set the +charset of mails, which defaults to 'C'. +.PP +This does +.B NOT +affect the environment of tasks running under cron. For more information +on how to modify the environment of tasks, consult +.IR crontab (5). +.PP +The daemon will use, if present, the definition from +.I /etc/localtime +for the timezone. +.PP +The environment can be redefined in user's crontab definitions but +.I cron +will only handle tasks in a single timezone. + +.SH DEBIAN SPECIFIC +.PP +Debian introduces some changes to +.I cron +that were not originally available upstream. The most significant +changes introduced are: + +.IP \(em +Support for /etc/cron.{hourly,daily,weekly,monthly} via /etc/crontab, +.IP \(em +Debian-specific file locations and commands, +.IP \(em +Debian-specific configuration (/etc/default/cron), +.IP \(em +numerous other smaller features and fixes. + +.PP +Support for /etc/cron.hourly, /etc/cron.daily, /etc/cron.weekly and +/etc/cron.monthly is provided in Debian through the default setting +of the /etc/crontab file (see the system-wide example in +.IR crontab (5)). +The default system-wide crontab contains four tasks: run every hour, every +day, every week and every month. Each of these tasks will execute +.B run-parts +providing each one of the directories as an argument. +These tasks are disabled if +.B anacron +is installed (except for the hourly task) to prevent conflicts between +both daemons. +is controlled by +.I /etc/default/cron +which is read by the init.d script that launches the +.I cron +daemon. This file determines whether +.I cron +will read the system's environment variables and makes it possible to add +additional options to the +.I cron +program before it is executed. .SH "SEE ALSO" crontab(1), crontab(5) .SH AUTHOR -.nf -Paul Vixie +Paul Vixie is the author of +.I cron +and original creator of this manual page. This page has also been modified for +Debian by Steve Greenland, Javier Fernandez-Sanguino and Christian Kastner. + diff --git a/crontab.1 b/crontab.1 index 92b69f0..7daf75b 100644 --- a/crontab.1 +++ b/crontab.1 @@ -17,7 +17,7 @@ .\" .\" $Id: crontab.1,v 2.4 1993/12/31 10:47:33 vixie Exp $ .\" -.TH CRONTAB 1 "29 December 1993" +.TH CRONTAB 1 "19 April 2010" .UC 4 .SH NAME crontab \- maintain crontab files for individual users (Vixie Cron) @@ -58,7 +58,8 @@ is not considered and your user must be listed in in order to be able to use the crontab. .PP Regardless of the existence of any of these files, the root administrative -user is always allowed to setup a crontab. +user is always allowed to setup a crontab. For standard Debian systems, all +users may use this command. .PP If the .I \-u @@ -92,7 +93,10 @@ The option is used to edit the current crontab using the editor specified by the \s-1VISUAL\s+1 or \s-1EDITOR\s+1 environment variables. After you exit -from the editor, the modified crontab will be installed automatically. +from the editor, the modified crontab will be installed automatically. If +neither of the environment variables is defined, then the +default editor /usr/bin/editor is used. +.PP .SH "SEE ALSO" crontab(5), cron(8) .SH FILES @@ -125,10 +129,22 @@ SVR3 syntax. A fairly informative usage message appears if you run it with a bad command line. -cron requires that each entry in a crontab end in a newline character. If the +cron requires that each entry in a crontab end in a newline character. If the last entry in a crontab is missing the newline, cron will consider the crontab (at least partially) broken and refuse to install it. +The files under +.I +/var/spool/cron/crontabs +are named based on the user's account name. +Crontab jobs will not be run for users whose accounts have been +renamed either due to changes in the local system or because they are +managed through a central user database (external to the system, for +example an LDAP directory). + + .SH AUTHOR -.nf -Paul Vixie +Paul Vixie is the author of +.I cron +and original creator of this manual page. This page has also been modified for +Debian by Steve Greenland, Javier Fernandez-Sanguino and Christian Kastner. diff --git a/crontab.5 b/crontab.5 index 9db8166..f4405f2 100644 --- a/crontab.5 +++ b/crontab.5 @@ -17,7 +17,7 @@ .\" .\" $Id: crontab.5,v 2.4 1994/01/15 20:43:43 vixie Exp $ .\" -.TH CRONTAB 5 "24 January 1994" +.TH CRONTAB 5 "19 April 2010" .UC 4 .SH NAME crontab \- tables for driving cron @@ -64,12 +64,13 @@ The .I value string is .B not -parsed for environmental substitutions or replacement of variables, thus lines -like +parsed for environmental substitutions or replacement of variables or +tilde(~) expansion, thus lines like .PP .in +4n .nf PATH = $HOME/bin:$PATH +PATH = ~/bin:/usr/bin:/bin .fi .in .PP @@ -237,6 +238,8 @@ MAILTO=paul 0 22 * * 1\-5 mail \-s "It's 10pm" joe%Joe,%%Where are your kids?% 23 0\-23/2 * * * echo "run 23 minutes after midn, 2am, 4am ..., everyday" 5 4 * * sun echo "run at 5 after 4 every Sunday" +0 */4 1 * mon echo "run every 4th hour on the 1st and on every Monday" +0 0 */2 * sun echo "run at midn on every Sunday that's an uneven date" # Run on every second Saturday of the month 0 4 8\-14 * * test $(date +\e%u) \-eq 6 && echo "2nd Saturday" # Same thing, efficient too: @@ -245,6 +248,23 @@ MAILTO=paul #Thursday of each month 57 2 * * 5 case $(date +\%d) in 0[2-8]) echo "After 1st Thursday"; esac .fi + +.PP +All the above examples run non-interactive programs. If you wish to run a +program that interacts with the user's desktop you have to make sure the proper +environment variable +.I DISPLAY +is set. + +.\" Note: Based on some web searches, below example might not fully +.\" work in all systems, as notify-send might require also +.\" to have knowledge of the dbus session in use (through the environment) +.\" However, adding that code here is an overkill +.nf +# Execute a program and run a notification every day at 10:00 am +0 10 * * * $HOME/bin/program | DISPLAY=:0 notify-send "Program run" "$(cat)" +.fi + .SH EXAMPLE SYSTEM CRON FILE The following lists the content of a regular system-wide crontab file. Unlike a @@ -260,6 +280,13 @@ user's crontab, this file has the username field, as used by /etc/crontab. SHELL=/bin/sh PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin +# Example of job definition: +# .---------------- minute (0 - 59) +# | .------------- hour (0 - 23) +# | | .---------- day of month (1 - 31) +# | | | .------- month (1 - 12) OR jan,feb,mar,apr ... +# | | | | .---- day of week (0 - 6) (Sunday=0 or 7) OR sun,mon,tue,wed,thu,fri,sat +# | | | | | # m h dom mon dow user command 17 * * * * root cd / && run-parts \-\-report /etc/cron.hourly 25 6 * * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.daily ) @@ -267,6 +294,12 @@ PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin 52 6 1 * * root test \-x /usr/sbin/anacron || ( cd / && run-parts \-\-report /etc/cron.monthly ) # .fi + +Note that all the system-wide tasks will run, by default, from 6 am to 7 am. In +the case of systems that are not powered on during that period of time, only +the hourly tasks will be executed unless the defaults above are changed. + + .SH SEE ALSO cron(8), crontab(1) .SH EXTENSIONS @@ -303,6 +336,15 @@ environment variable in his this will affect only the commands executed in the crontab, not the execution of the crontab tasks themselves. +POSIX specifies that the day of month and the day of week fields both need to +match the current time if either of them +.I is +a *. However, this implementation only checks if the +.I first character +is a *. This is why "0 0 */2 * sun" runs every Sunday that's an +uneven date while the POSIX standard would have it run every Sunday and on +every uneven date. + The .I crontab syntax does not make it possible to define all possible periods one can @@ -334,5 +376,8 @@ cron will consider the crontab (at least partially) broken. A warning will be written to syslog. .SH AUTHOR -.nf -Paul Vixie +Paul Vixie is the author of +.I cron +and original creator of this manual page. This page has also been modified for +Debian by Steve Greenland, Javier Fernandez-Sanguino, Christian Kastner and +Christian Pekeler.