GNU Cron Specification

This document is intended to layout the specification for the GNU Cron project.

1. Explanation
2. Goals
3. Specification

1. Explanation

An explanation of why GNU Cron (or gcron for short ) was started is important in understanding the direction the project wishes to head. At the present time the most common cron daemon in use and available is Vixie cron (by Paul Vixie) and although it would seem that this package has fit the needs of a cron daemon so far, we do not see things the same.

Firstly, Vixie cron is very outdated. Vixie Cron v3.0 was released in December of 1993; basically, there is no longer any central active maintainer of the package. Several problems arise from this:

1. Vixie cron is a source of many exploits -- this forces each distribution of a GNU system to maintain separate versions of, essentially, the same package to keep their distributions secure.

2. There are many features that could be added to a modern cron daemon to provide extra functionality to users of a GNU system.

2. Goals

1. Designing and Implementing, from the beginning, with security in mind. We will create a flexible implementation of cron without sacrificing security.

2. Improve the ease of use of crontab and cron for end-users as well as for use in scripts.

3. Provided extended features to users of GNU/Hurd. Such as translators which users can mount under their home directories to add and view entries in a logical fashion within the filesystem.

3. Specification

This chapter covers the actual specification GNU Cron will follow during it's development. It is separated into three sections: Compatibility with Vixie Cron, Compliance with POSIX, and Extra Features.

3.1 Vixie Cron		What needs to be done to maintain backward compatibility
3.3 POSIX		What needs to be done to comply with POSIX
3.4 Extras		Which extra features are being proposed
3.5 at		Description of the 'at' command

3.1 Vixie Cron

3.1.1 File Format		The format of a file parsed by cron
3.1.2 Matching		How cron matches moments in time
3.2 crontab		Specification of the crontab command

3.1.1 File Format

Blank lines, and lines beginning with a pound character ('#') are ignored by cron.

The basic file format consists of lines with 6 fields separated by any number of whitespace characters (excluding newlines). The first five fields describe the times in which each job is to be executed.

1. Minute [0,59]
2. Hour [0,23]
3. Day of the month [1,31]
4. Month of the Year [1,12 | see below]
5. Day of the week [0,7 (where 0 and 7 are Sunday) | see below]

The fourth field, Month of the Year, may also be three letter abbreviations of the months. The abbreviations must only be the first three letters of the month. (XXX: Can we do ranges like this? Jan-Mar?)

The fifth field, Day of the Week, also can be three letter abbreviations. The abbreviations may only be the first three letters of the days of the week. (XXX: Can we do ranges like this? Mon-Fri?) Also of note is that 0 and 7 are both considered Sunday.

The sixth field is the command that is too be executed should cron determine a match with the 5 previous fields (see section 3.1.2 Matching). The sixth field is no longer space delimited so that no special consideration need be taken by the user to pass arguments to the command successfully.

Each of the first five fields may be an asterisk (denoted a match for all possible values), an element, or a list of elements delimited by commas. An element may be a single number, a range of numbers, or a ranger of numbers followed by a '/' and a step value. A range of numbers is denoted by a number followed by a hyphen followed be another number and are inclusive values. Step values tell cron to skip certain numbers in the range given. A step value may also be applied to an asterisk, in which case an asterisk is treated as a range value encompassing the full range of values allowed in that field.

Examples:

1,3-6,10 -- matches the values 1,3,4,5,6,10

1-20/4 -- matches the values 1,5,9,13,17 (XXX: I'm not sure if this is right or not, it might be 4,8,12,16,20?)

2-10/2,5 -- matches 2,4,5,6,8,10 (XXX: again, might not be right--is step like a modulus operator?)

Environment Variables

In addition to this variable and value pairs may be specified (XXX anywhere?) in the file which are set as environment variables, as well as exported to each job's environment. A couple of variables affect the way cron will handle jobs as outlined below.

• HOME - This will be the current working directory of any command that is executed. If it is not provided, it will default to the /etc/passwd entry of the user who installed the job.

• SHELL - This is the interpreter of the sixth field of the file. It's current working directory will be set to the value of $HOME and if no SHELL is specified it will default (XXX /etc/passwd or /bin/sh?).

• PATH - This will be exported to the environment when $SHELL is invoked to run the job.

• MAILTO - This variable tells cron where to mail any output from the jobs specified in the file. This defaults to the user owning the cron jobs.

• TZ - It is also important to note that the TZ variable will not affect the times which cron executes a job, so it's value will not affect cron's behaviour. But it will be exported into any environment before jobs are run.

Variables are denoted in a crontab file by a line starting with a variable identifier followed by an equal sign and finally by the variable's value. Such as: PATH=.:/bin:/usr/bin

Any number of blanks on either side of the equals sign are allowed and discarded by cron. For example: PATH = .:/bin:/usr/bin sets the "PATH" variable to ".:/bin:/usr/bin". (XXX: This (and above) needs to look nicer in output, what's the best way to do it?) Anything after the first non-blank character in a value is literal.

If beginning blanks are needed for the value of a variable the value may be enclosed in either single or double quotes so much as they match. Anything enclosed in the quotes becomes literal to the value of the variable. To put double quotes in the value of a variable, enclose the entire value in single quotes and vice versa.

/etc/crontab

The system file /etc/crontab deviates slightly from the standard format of a cron file. It's location on the system will be a compile time option but for most systems will be /etc/crontab.

This file has an extra field between the fifth and sixth fields of a standard cron file. So, in /etc/crontab, the 'job field' becomes the seventh field. The new sixth field is the name of some user on the system and tells cron to run that job as the specified user.

It is also useful to note that this file is not installed via the crontab command (XXX reference here) but is read by cron on startup and whenever a change is detected.

3.1.2 Matching

(minute && hour && month && (DoM || DoW))

This is somewhat counter-intuitive to the obvious ANDing of all five fields. The follow examples will help clarify.

(XXX insert examples)

3.2 crontab

3.3 POSIX

3.4 Extras

3.5 at

Table of Contents

1. Explanation
2. Goals
3. Specification

3.1 Vixie Cron

3.1.1 File Format
Environment Variables
/etc/crontab
3.1.2 Matching

3.2 crontab
3.3 POSIX
3.4 Extras
3.5 at

Short Table of Contents

1. Explanation
2. Goals
3. Specification

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four