Bug 210621 - poor "system crontab" documentation
Summary: poor "system crontab" documentation
Status: Open
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: freebsd-bugs (Nobody)
Keywords: easy, patch
Depends on:
Reported: 2016-06-27 11:26 UTC by Martin S. Weber
Modified: 2021-10-01 06:46 UTC (History)
2 users (show)

See Also:

cron(8) patch (2.62 KB, patch)
2021-09-19 19:34 UTC, Felix Johnson
no flags Details | Diff
crontab(5) patch (11.68 KB, patch)
2021-09-19 19:36 UTC, Felix Johnson
no flags Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Martin S. Weber 2016-06-27 11:26:00 UTC
cron(8) mentions: "The cron utility also searches for /etc/crontab which is in a different format (see crontab(5))"

crontab(5) then mentions, somewhere hidden inside the wall of text, the specifics of the different format: "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."

So the specifics of the format of /etc/crontab are mentioned in a subclause in the middle of crontab(5). What this extra field _does_ is not specified (one would assume it's being used to su to the user, but there's no mention of what effect either :group, nor /login-class would do on top of the user's native group or login class).

I suggest moving the specifics of /etc/crontab's format into an own paragraph, complete with paragraph header so that when glancing over crontab(5) one will find it easily and quickly, along with _detailed_ information about what this extra field does, also in conjunction with cron(8)'s flags, see below.

cron(8) mentions: "-J rootjitter Enable time jitter for superuser jobs.  The same as -j except that it will affect jobs run by the superuser only."
- Does this apply to the "system crontab" only? Or to the root's USER crontab only? Or to any *tab* run by root (i.e., /etc/crontab, root's crontab, toor's crontab, and any other uid=0 user's crontab?) What about the aforementioned sixth-user-name-field jobs in /etc/crontab? Does it apply -j or -J?

I suggest properly documenting this in cron(8), with a reminder in crontab(5).

/etc/crontab mentions: "/etc/crontab - root's crontab for FreeBSD". Well, it is NOT root's crontab. (A) It has support for a special field that users' crontabs don't, (B) root's "crontab -e" will NOT pull up /etc/crontab, but root's own crontab.

I suggest s/root's/system/;s/D/D - cf. crontab(5)/
Comment 1 Felix Johnson freebsd_triage 2021-09-19 19:34:24 UTC
Created attachment 228021 [details]
cron(8) patch

Clarify system vs user crontabs, clarify what superuser means for -J.
Comment 2 Felix Johnson freebsd_triage 2021-09-19 19:36:09 UTC
Created attachment 228022 [details]
crontab(5) patch

Reorder man page, use subsection headers, describe system crontab format, mention the effect of root jitter, clarify errors when a bad group or login class is used.
Comment 3 Felix Johnson freebsd_triage 2021-09-19 19:37:52 UTC
Patched cron.8 and crontab.5 to clarify user crontab vs system crontab format and regular vs superuser jitter.