Attachment 228022 Details for Bug 210621 – crontab(5) patch

[patch] crontab(5) patch

crontab.5.patch (text/plain), 11.68 KB, created by Felix Johnson on 2021-09-19 19:36:09 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Felix Johnson

Created: 2021-09-19 19:36:09 UTC

Size: 11.68 KB

patch

obsolete

>diff --git a/usr.sbin/cron/crontab/crontab.5 b/usr.sbin/cron/crontab/crontab.5
>index 0e48a0d804f..3349285e3f1 100644
>--- a/usr.sbin/cron/crontab/crontab.5
>+++ b/usr.sbin/cron/crontab/crontab.5
>@@ -29,23 +29,36 @@ A
> file contains instructions to the
> .Xr cron 8
> daemon of the general form: ``run this command at this time on this date''.
>-Each user has their own crontab, and commands in any given crontab will be
>-executed as the user who owns the crontab.
>-Uucp and News will usually have
>-their own crontabs, eliminating the need for explicitly running
>+.Pp
>+Each user (including any superusers) can have their own crontab, and commands 
>+in any user crontab will be executed as the user who owns the crontab. 
>+Accounts for services (such as Uucp or News) can be given user crontabs, 
>+eliminating the need for explicitly running 
> .Xr su 1
> as part of a cron command.
> .Pp
>+.Fx also has a system crontab format, for /etc/crontab, /etc/cron.d files, 
>+or /usr/local/etc/cron.d files. The system crontab has an 
>+additional field 
>+.Pq Em who
>+to specify the user, group, or login class to run the 
>+command as
>+.Po see 
>+.Sx SYSTEM CRONTAB
>+.Pc .
>+.Pp
>+An active line in a crontab will be either an environment setting or a cron
>+command. Non-active lines (whitespace and comments) are ignored.
>+.Pp
>+.Ss WHITESPACE AND COMMENTS
> Blank lines and leading spaces and tabs are ignored.
> Lines whose first
> non-space character is a pound-sign (#) are comments, and are ignored.
>-Note that comments are not allowed on the same line as cron commands, since
>+Comments are not allowed on the same line as cron commands, since
> they will be taken to be part of the command.
> Similarly, comments are not
> allowed on the same line as environment variable settings.
>-.Pp
>-An active line in a crontab will be either an environment setting or a cron
>-command.
>+.Ss ENVIRONMENT SETTING
> An environment setting is of the form,
> .Bd -literal
>     name = value
>@@ -62,107 +75,33 @@ string may be placed in quotes (single or double, but matching) to preserve
> leading or trailing blanks.
> The
> .Em name
>-string may also be placed in quote (single or double, but matching)
>+string may also be placed in quotes (single or double, but matching)
> to preserve leading, trailing or inner blanks.
> .Pp
>-Several environment variables are set up
>-automatically by the
>-.Xr cron 8
>-daemon.
>-.Ev SHELL
>-is set to
>-.Pa /bin/sh ,
>-and
>-.Ev LOGNAME
>-and
>-.Ev HOME
>-are set from the
>-.Pa /etc/passwd
>-line of the crontab's owner.
>-In addition, the environment variables of the
>-user's login class will be set from
>-.Pa /etc/login.conf.db
>-and
>-.Pa ~/.login_conf .
>-(A setting of
>-.Ev HOME
>-in the login class will override the value from
>-.Pa /etc/passwd ,
>-but will not change the current directory when the command is
>-invoked, which can only be overridden with an explicit setting of
>-.Ev HOME
>-within the crontab file itself.)
>-If
>-.Ev PATH
>-is not set by any other means, it is defaulted to
>-.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
>-.Ev HOME ,
>-.Ev PATH
>-and
>-.Ev SHELL ,
>-and any variables set from the login class,
>-may be overridden by settings in the crontab;
>-.Ev LOGNAME
>-may not.
>-.Pp
>-(Another note: the
>-.Ev LOGNAME
>-variable is sometimes called
>-.Ev USER
>-on
>-.Bx
>-systems...
>-On these systems,
>-.Ev USER
>-will be set also).
>-.Pp
>-If
>-.Xr cron 8
>-has any reason to send mail as a result of running commands in
>-``this'' crontab, it will respect the following settings which may be
>-defined in the crontab (but which are not taken from the login class).
>-If
>-.Ev MAILTO
>-is defined (and non-empty), mail is
>-sent to the user so named.
>-If
>-.Ev MAILFROM
>-is defined (and non-empty), its value will be used as the from address.
>-.Ev MAILTO
>-may also be used to direct mail to multiple recipients
>-by separating recipient users with a comma.
>-If
>-.Ev MAILTO
>-is defined but empty (MAILTO=""), no
>-mail will be sent.
>-Otherwise mail is sent to the owner of the crontab.
>-This
>-option is useful if you decide on
>-.Pa /bin/mail
>-instead of
>-.Pa /usr/lib/sendmail
>-as
>-your mailer when you install cron --
>-.Pa /bin/mail
>-does not do aliasing, and UUCP
>-usually does not read its mail.
>+.Ss CRON COMMAND
>+The format of a user cron command is very much the V7 standard, with 
>+a number of upward-compatible extensions.  Each line has five time 
>+and date fields, followed by a command.
> .Pp
>-The format of a cron command is very much the V7 standard, with a number of
>-upward-compatible extensions.
>-Each line has five time and date fields,
>-followed by a user name
>-(with optional ``:<group>'' and ``/<login-class>'' suffixes)
>-if this is the system crontab file,
>-followed by a command.
> Commands are executed by
> .Xr cron 8
> when the minute, hour, and month of year fields match the current time,
> .Em and
> when at least one of the two day fields (day of month, or day of week)
>-matches the current time (see ``Note'' below).
>-.Xr cron 8
>+matches the current time 
>+.Po see 
>+.Sx TIME AND DAY OPTIONS
>+.Pc .
>+.Xr cron 8 
> examines cron entries once every minute.
>-The time and date fields are:
>+.Pp
>+If time jitter is enabled, 
>+.Xr cron 8
>+will sleep a random number of seconds in the range from 0 to 
>+.Ar jitter
>+prior to executing commands.
>+.Pp
>+The user cron command fields are:
> .Bd -literal -offset indent
> field         allowed values
> -----         --------------
>@@ -171,8 +110,26 @@ hour          0-23
> day of month  1-31
> month         1-12 (or names, see below)
> day of week   0-7 (0 or 7 is Sun, or use names)
>+command       [command options] command
> .Ed
> .Pp
>+The command field (the rest of the line) specifies the command to be
>+run.
>+One or more command options may precede the command to modify processing
>+behavior.
>+The entire command portion of the line, up to a newline or %
>+character, will be executed by
>+.Pa /bin/sh
>+or by the shell
>+specified in the
>+.Ev SHELL
>+variable of the cronfile.
>+Percent-signs (%) in the command, unless escaped with backslash
>+(\\), will be changed into newline characters, and all data
>+after the first % will be sent to the command as standard
>+input.
>+.Pp
>+.Ss TIME AND DAY OPTIONS
> A field may be an asterisk (*), which always stands for ``first\-last''.
> .Pp
> Ranges of numbers are allowed.
>@@ -205,39 +162,8 @@ Use the first three letters of the particular
> day or month (case does not matter).
> Ranges and lists are also allowed.
> .Pp
>-The ``sixth'' field (the rest of the line) specifies the command to be
>-run.
>-One or more command options may precede the command to modify processing
>-behavior.
>-The entire command portion of the line, up to a newline or %
>-character, will be executed by
>-.Pa /bin/sh
>-or by the shell
>-specified in the
>-.Ev SHELL
>-variable of the cronfile.
>-Percent-signs (%) in the command, unless escaped with backslash
>-(\\), will be changed into newline characters, and all data
>-after the first % will be sent to the command as standard
>-input.
>-.Pp
>-The following command options can be supplied:
>-.Bl -tag -width Ds
>-.It Fl n
>-No mail is sent after a successful run.
>-The execution output will only be mailed if the command exits with a non-zero
>-exit code.
>-The
>-.Fl n
>-option is an attempt to cure potentially copious volumes of mail coming from
>-.Xr cron 8 .
>-.It Fl q
>-Execution will not be logged.
>-.El
>-.sp
>-Duplicate options are not allowed.
>-.Pp
>-Note: The day of a command's execution can be specified by two
>+.Ss DAY OF COMMAND EXECUTION
>+The day of a command's execution can be specified by two
> fields \(em day of month, and day of week.
> If both fields are
> restricted (ie, are not *), the command will be run when
>@@ -279,6 +205,155 @@ Note, however, that overlap may occur if the job is running when the file
> containing the job is modified and subsequently reloaded.
> The first run is scheduled for the specified number of seconds after cron
> is started or the crontab entry is reloaded.
>+.Pp
>+.Ss COMMAND OPTIONS
>+The following command options can be supplied:
>+.Bl -tag -width Ds
>+.It Fl n
>+No mail is sent after a successful run.
>+The execution output will only be mailed if the command exits with a non-zero
>+exit code.
>+The
>+.Fl n
>+option is an attempt to cure potentially copious volumes of mail coming from
>+.Xr cron 8 .
>+.It Fl q
>+Execution will not be logged.
>+.El
>+.sp
>+Duplicate options are not allowed.
>+.Pp
>+.Ss SYSTEM CRONTAB
>+The system crontab format is identical to the user crontab format with 
>+the addition of a field between the time and day fields and the command.
>+This required field is used to specify the user to run the command as.
>+.Pp
>+To specify the group to run as, append a colon ``:'' followed by the 
>+group name. The group must have an entry in /etc/group, see
>+.Xr group 5 .
>+The group is not required.
>+.Pp
>+To specify the login class to run as, append a forward-slash ``/''
>+followed by the login class. The login class must have an entry in 
>+the login capabilities database, see 
>+.Xr login.conf 5 .
>+The login class is optional, but if not specified, the login class will be ``daemon''.
>+.Pp
>+If both the group and login class are specified, the group 
>+must precede the login class.
>+.Pp
>+The system cron command fields are:
>+.Bd -literal -offset indent
>+field         allowed values
>+-----         --------------
>+minute        0-59
>+hour          0-23
>+day of month  1-31
>+month         1-12 (or names)
>+day of week   0-7 (0 or 7 is Sun, or use names)
>+who           username:groupname/loginclass
>+command       [command options] command
>+.Ed
>+.Pp
>+All fields other than 
>+.Em who
>+function the same as in a user cron command.
>+.Pp
>+If root time jitter is enabled, and
>+.Em who
>+specifies a superuser (user id 0), 
>+.Xr cron 8
>+will sleep a random number of seconds in the range from 0 to 
>+.Ar rootjitter
>+prior to executing superuser commands.
>+.Pp 
>+If an invalid group or login class is specified, 
>+.Xr cron 8
>+will stop processing the crontab, and no further 
>+commands will be loaded from that crontab.
>+.Sh ENVIRONMENT
>+Several environment variables are set up
>+automatically by the
>+.Xr cron 8
>+daemon.
>+.Ev SHELL
>+is set to
>+.Pa /bin/sh ,
>+and
>+.Ev LOGNAME
>+and
>+.Ev HOME
>+are set from the
>+.Pa /etc/passwd
>+line of the crontab's owner.
>+In addition, the environment variables of the
>+user's login class will be set from
>+.Pa /etc/login.conf.db
>+and
>+.Pa ~/.login_conf .
>+(A setting of
>+.Ev HOME
>+in the login class will override the value from
>+.Pa /etc/passwd ,
>+but will not change the current directory when the command is
>+invoked, which can only be overridden with an explicit setting of
>+.Ev HOME
>+within the crontab file itself.)
>+If
>+.Ev PATH
>+is not set by any other means, it is defaulted to
>+.Pa /sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin .
>+.Ev HOME ,
>+.Ev PATH
>+and
>+.Ev SHELL ,
>+and any variables set from the login class,
>+may be overridden by settings in the crontab;
>+.Ev LOGNAME
>+may not.
>+.Pp
>+(Another note: the
>+.Ev LOGNAME
>+variable is sometimes called
>+.Ev USER
>+on
>+.Bx
>+systems...
>+On these systems,
>+.Ev USER
>+will be set also).
>+.Pp
>+.Sh MAIL FROM COMMANDS
>+If
>+.Xr cron 8
>+has any reason to send mail as a result of running commands in
>+``this'' crontab, it will respect the following settings which may be
>+defined in the crontab (but which are not taken from the login class).
>+If
>+.Ev MAILTO
>+is defined (and non-empty), mail is
>+sent to the user so named.
>+If
>+.Ev MAILFROM
>+is defined (and non-empty), its value will be used as the from address.
>+.Ev MAILTO
>+may also be used to direct mail to multiple recipients
>+by separating recipient users with a comma.
>+If
>+.Ev MAILTO
>+is defined but empty (MAILTO=""), no
>+mail will be sent.
>+Otherwise mail is sent to the owner of the crontab.
>+This
>+option is useful if you decide on
>+.Pa /bin/mail
>+instead of
>+.Pa /usr/lib/sendmail
>+as
>+your mailer when you install cron --
>+.Pa /bin/mail
>+does not do aliasing, and UUCP
>+usually does not read its mail.
> .Sh EXAMPLE CRON FILE
> .Bd -literal
>

Actions: View | Diff

Attachments on bug 210621: 228021 | 228022