Explain cron.d

Add details on the format of system cron files, which are mentioned in
cron(8) which refers here but barely explained here.

Reviewed by: imp
Pull Request: https://github.com/freebsd/freebsd-src/pull/1106

Import vixie cron 4.0

Specifically, import the diff from commit e745bd4c10ab to
commit 83563783cc2 in https://github.com/vixie/cron.git

My sole motivation is changing to the common MIT license.
The old license, especially the "buildable source" clause,
is unfriendly for commercial users of this code. Simply
changing the license without importing [most of] the code
accompanying that license seemed legally dubious.

The most regrettable change is losing Paul's uucp path.
I partially atone for this loss by restoring the upstream
$Id$ tags, since $FreeBSD$ is no longer useful.

This is [intended to be] a complete list of the functional
changes in this commit. Some changes were made so that we
could consider vixie cron to be our upstream and reduce our
diffs against it, while others were simply a good idea.

- main() - use putenv instead of setenv for PATH
- open_pidfile no longer needs snprintf to build pidfile
- crontab main() - abort() on impossible errors
- check for truncation when building strings with snprintf
- getdtablesize() -> sysconf(_SC_OPEN_MAX)

These changes were not taken from upstream's 4.0 diff because
they [could] actually change behavior. Some of them might be
beneficial, but should be taken separately.

- config.h - sendmail args: remove -oi and add -or0s
- call setlocale(LC_ALL, "") at the top of main()
- acquire_daemonlock - we already use pidfile
- cast getpid(), uid_t, and gid_t to long for printf
- remove unnecessary braces - I consider them beneficial
- BSDi support
- glue_strings() - use snprintf(), as we often already did

MFC after: on demand
Sponsored by: Dell EMC Isilon
Differential Revision: https://reviews.freebsd.org/D40260

crontab.5: Correct claims on ranges and names

Ranges use the function get_number, which means that ranges of names
are supported and indeed always have been, righ back to the initial
import.

PR: docs/253969
Reported by: Ben Bullock <benkasminbullock@gmail.com>

cron: respect PATH from login.conf

As a followup to the use of login.conf environment vars (other than PATH) in
cron, this patch adds PATH (and HOME) to the list of login.conf settings
respected.

The new logic is as follows:

1. SHELL is always _PATH_BSHELL unless explicitly overridden in the crontab
file itself; no other settings are respected. This is unchanged.

2. PATH is taken from the first of: crontab file, login.conf, _PATH_DEFPATH

3. HOME is taken from the first of: crontab file, login.conf, passwd entry,
unset

4. The current directory for invoking the command is taken from the crontab
file's value of HOME (existing behavior), or the passwd entry, but not
anywhere else (so it might not equal HOME if that was set in login.conf).

Submitted by: Andrew Gierth <andrew_tao173.riddles.org.uk>
Reviewed by: sigsys_gmail.com
Differential Revision: https://reviews.freebsd.org/D23597

cron(8): set the environment variables of the user and/or login class

Prior to processing environment variable set in the crontab file as those
should be of higher precedent, pull in the user or login class environment.

This is another supporting feature for allowing one to configure system-wide
settings that may affect both regular cron jobs as well as services.

This is the final part of D21481.

Submitted by: Andrew Gierth <andrew_tao173.riddles.org.uk>

cron: add log suppression and mail suppression for successful runs

This commit adds two new extensions to crontab, ported from OpenBSD:
- -n: suppress mail on succesful run
- -q: suppress logging of command execution

The -q option appears decades old, but -n is relatively new. The
original proposal by Job Snijder can be found here [1], and gives very
convincing reasons for inclusion in base.

This patch is a nearly identical port of OpenBSD cron for -q and -n
features. It is written to follow existing conventions and style of the
existing codebase.

Example usage:

# should only send email, but won't show up in log
* * * * * -q date

# should not send email
* * * * * -n date

# should not send email or log
* * * * * -n -q date

# should send email because of ping failure
* * * * * -n -q ping -c 1 5.5.5.5

[1]: https://marc.info/?l=openbsd-tech&m=152874866117948&w=2

PR: 237538
Submitted by: Naveen Nathan <freebsd_t.lastninja.net>
Reviewed by: bcr (manpages)
MFC after: 1 week
Differential Revision: https://reviews.freebsd.org/D20046

cron(8): schedule interval jobs that get loaded during execution

Jobs using the @<second> syntax currently only get executed if they exist
when cron is started. The simplest reproducer of this is:

echo '@20 root echo "Hello!"' >> /etc/cron.d/myjob

myjob will get loaded at the next second==0, but this echo job will not
run until cron restarts. These jobs are normally handled in
run_reboot_jobs(), which sets e->lastexit of INTERVAL jobs to the startup
time so they run 'n' seconds later.

Fix this by special-casing TargetTime > 0 in the database load. Preexisting
jobs will be handled at startup during run_reboot_jobs as normal, but if
we've reloaded a database during runtime we'll hit this case and set
e->lastexit to the current time when we process it. They will then run every
'n' seconds from that point, and a full restart of cron is no longer
required to make these jobs work.

Reported by: Juraj Lutter (otis_sk.freebsd.org)
Reviewed by: allanjude, bapt, bjk (earlier version), Juraj Lutter
MFC after: 3 days
Differential Revision: https://reviews.freebsd.org/D19924

cron(8): Add MAILFROM ability for crontabs

This changes the sender mail address in a similar fashion to how MAILTO may
change the recipient. The default from address remains unchanged.

MFC after: 1 week

Add new functionality and syntax to cron(1) to allow to run jobs at a
given interval, which is counted in seconds since exit of the previous
invocation of the job. Example user crontab entry:

@25 sleep 10

The example will launch 'sleep 10' every 35 seconds. This is a rather
useless example above, but clearly explains the functionality.

The practical goal here is to avoid overlap of previous job invocation
to a new one, or to avoid too short interval(s) for jobs that last long
and doesn't have any point of immediate launch soon after previous run.

Another useful effect of interval jobs can be noticed when a cluster of
machines periodically communicates with a single node. Running the task
time based creates too much load on the node. Running interval based
spreads invocations across machines in cluster. Note that -j/-J won't
help in this case.

Sponsored by: Netflix

Add sbin and /usr/local directories to _PATH_DEFPATH.

Set _PATH_DEFPATH to
/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin. This is the
path in the default class in the default /etc/login.conf,
excluding ~/bin which would not be expanded properly in a string
constant.

For normal logins, _PATH_DEFPATH is overridden by /etc/login.conf,
~/.login_conf or shell startup files. _PATH_DEFPATH is still used as a
default by execlp(), execvp(), posix_spawnp() and sh if PATH is not set, and
by cron. Especially the latter is a common trap (most recently in PR
204813).

PR: 204813
Reviewed by: secteam (delphij), alfred

use .Mt to mark up email addresses consistently (part2)

PR: 191174
Submitted by: Franco Fichtner <franco@lastsummer.de>

Second attempt to add @every_second keyword support. Due to multiple
requests, default to the previous 60-seconds scheduling method
unless there is any @every_second entries to conserve CPU cycles and
power.

This change also improves scheduling in the default mode by running
as close to the beginning of the minnute as possible by replacing
sleep(3) with nanosleep(2). Previously, the tasks would run anywhere
within the first second of the minute and that offset drifted back
and forth each time cron(8) was engaged.

MFC after: 1 month

Revert latest changes to cron, until better version is worked out (I hope).

Requested by: few

Add per-second scheduling into the cron(8). Right now it's
only available via the new @every_second shortcut. ENOTIME to
implement crontab(5) format extensions to allow more flexible
scheduling.

In order to address some concerns expressed by Terry Lambert
while discussing the topic few years ago, about per-second cron
possibly causing some bad effects on /etc/crontab by stat()ing
it every second instead of every minute now (i.e. atime update),
only check that database needs to be reloaded on every 60-th
loop run. This should be close enough to the current behaviour.

Add "@every_minute" shortcut while I am here.

MFC after: 1 month

As cron(8) is started with '-s' by default, timezones that observe
DST should not need to worry about scheduling jobs when the DST time
changes.

Rather than removing the BUGS section in crontab(5) regarding this,
note that disabling '-s' may still cause jobs to be executed twice or
not at all.

PR: 166318
Submitted by: Florian k Unglaub (f.unglaub%googlemail!com)
MFC After: 1 week

Since April 2, 2006, Indiana has observed DST.

MFC after: 5 days

Point out that @reboot runs at every cron startup, not just system
startup.

Discussed on: hackers@

Approved by: gjb (mentor)
MFC after: 1 week

A new jail(8) with a configuration file, to replace the work currently done
by /etc/rc.d/jail.

Create the altix project branch. The altix project will add support
for the SGI Altix 350 to FreeBSD/ia64. The hardware used for porting
is a two-module system, consisting of a base compute module and a
CPU expansion module. SGI's NUMAFlex architecture can be an excellent
platform to test CPU affinity and NUMA-aware features in FreeBSD.

Fix typo.

Approved by: ru

- Import the HEAD csup code which is the basis for the cvsmode work.

Mention the default value of PATH and that it may be overridden.

Submitted by: Roman Divacky
MFC after: 3 days

Expand contractions.

Expand *n't contractions.

Mechanically kill hard sentence breaks.

Trim whitespace at EOL.

Discuss the 'MAILTO' option.

PR: 58783
Submitted by: Marc Silver <marcs@draenor.org>

english(4) police.

Grammar fix: "When at least one of the fields .. matches ...".

MFC after: 3 days

mdoc(7) police: s/BSD/.Bx/ where appropriate.

mdoc(7) police: fixed the "new sentence" bogons.

fix misspelling introduced in rev 1.14 (sames as -> same as)

Remove whitespace at EOL.

mdoc(7) police: removed leading whitespaces that are not inside
Bd/Ed; these hardly degrade the quality of the produced output.

Avoid use of direct troff requests in mdoc(7) manual pages.

Revive rev 1.12 (NetBSD improvements including @ shortcuts).

Back out previous commit. The code is not ready for it.

Merge in NetBSD improvements:

* Clarify quoting value in of name = value pairs.
* Describe the @reboot, @yearly, @annually, @monthly, @weekly,
@daily, @midnight and @hourly extensions.

PR: 17261
Submitted by: MIHIRA Yoshiro <sanpei@sanpei.org>
Obtained from: NetBSD

$Id$ -> $FreeBSD$

Christen a BUGS section for an explanation of the impact of Daylight
Savings Time on cron(8). If we ever introduce some work-around code for
handling jobs scheduled for a time that "doesn't happen" due to DST,
the section should be renamed to IMPLEMENTATION NOTES.

PR: 10947
Reported by: Scott Drassinower <scottd@cloud9.net>
Submitted by: Seth Bromberger <seth@freebie.dp.ny.frb.org>
Reviewed by: mpp

Changed 'overriding what /etc/passwd says' to 'overriding default set
by cron'

PR: 12520
Submitted by: (not specified)

.Sh AUTHOR -> .Sh AUTHORS. Use .An/.Aq.

Log run-time parsing errors now

Use getpwnam before getpwuid since two users with same uids can exists
(affects new login classes code only)

The same fixes as in inetd: by default run `system crontab things' with
daemon login class now, not restrict them to user class breaking
compatibility with old way (so-called nobody limits problem)

Implement user[:group][/login-class] syntax in system crontab
for more flexible control (the same as in inetd)

Sort cross refereces in section SEE ALSO.

Use err(3). Rewrote man page in mdoc format.

Revert $FreeBSD$ to $Id$

crontab(5) incorrectly documented the dom/month arguments.
They have valid ranges of 1-31 and 1-12, not 0-31 and 0-12.

Make the long-awaited change from $Id$ to $FreeBSD$

This will make a number of things easier in the future, as well as (finally!)
avoiding the Id-smashing problem which has plagued developers for so long.

Boy, I'm glad we're not using sup anymore. This update would have been
insane otherwise.

Paul Vixie's cron, version 3.0. Munged into bmake format. If this goes
well, expect our two seperate directories for cron and crontab to go away
shortly.
Submitted by: jkh