FreeBSD Handbook
Prev | Chapter 12 Configuration and Tuning | Next

# 12.6 Configuring the `cron` Utility

Contributed by Tom Rhodes.

One of the most useful utilities in FreeBSD is cron(8). This utility runs in the background and regularly checks `/etc/crontab` for tasks to execute and searches `/var/cron/tabs` for custom `crontab` files. These files store information about specific functions which `cron` is supposed to perform at certain times.

The `cron` utility uses two different types of configuration files, the system crontab and user crontabs. These formats only differ in the sixth field and later. In the system crontab, `cron` will run the command as the user specified in the sixth field. In a user crontab, all commands run as the user who created the crontab, so the sixth field is the last field; this is an important security feature. The final field is always the command to run.

> Note: User crontabs allow individual users to schedule tasks without the need for `root` privileges. Commands in a user's crontab run with the permissions of the user who owns the crontab.

> The `root` user can have a user crontab just like any other user. The `root` user crontab is separate from `/etc/crontab` (the system crontab). Because the system crontab effectively invokes the specified commands as root there is usually no need to create a user crontab for `root`.

Let us take a look at `/etc/crontab`, the system crontab:

    # /etc/crontab - root's crontab for FreeBSD
    #
    # $FreeBSD: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $
    #
    #
    SHELL=/bin/sh
    PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin
    HOME=/var/log
    #
    #
    #minute	hour	mday	month	wday	who	command
    #
    #
    */5	*	*	*	*	root	/usr/libexec/atrun

  Like most FreeBSD configuration files, lines that begin with the `#` character are comments. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on the same line as a command or else they will be interpreted as part of the command; they must be on a new line. Blank lines are ignored.
  First, the environment must be defined. The equals (`=`) character is used to define any environment settings, as with this example where it is used for the `SHELL`, `PATH`, and `HOME` options. If the shell line is omitted, `cron` will use the default, which is `sh`. If the `PATH` variable is omitted, no default will be used and file locations will need to be absolute. If `HOME` is omitted, `cron` will use the invoking users home directory.
  This line defines a total of seven fields. Listed here are the values `minute`, `hour`, `mday`, `month`, `wday`, `who`, and `command`. These are almost all self explanatory. `minute` is the time in minutes the command will be run. `hour` is similar to the `minute` option, just in hours. `mday` stands for day of the month. `month` is similar to `hour` and `minute`, as it designates the month. The `wday` option stands for day of the week. All these fields must be numeric values, and follow the twenty-four hour clock. The `who` field is special, and only exists in `/etc/crontab`. This field specifies which user the command should be run as. The last field is the command to be executed.
  This last line will define the values discussed above. This example has a `*/5` listing,followed by several more `*` characters. These `*` characters mean “first-last”, and can be interpreted as every time. In this example, `atrun` is invoked by `root` every five minutes regardless of the day or month. For more information on `atrun`, refer to atrun(8).

  Commands can have any number of flags passed to them; however, commands which extend to multiple lines need to be broken with the backslash “\” continuation character.

This is the basic setup for every `crontab`, although there is one thing different about this one. Field number six, which specifies the username, only exists in the system `crontab`. This field should be omitted for individual user `crontab` files.

## 12.6.1 Installing a Crontab

> Important: Do not use the procedure described here to edit and install the system crontab, `/etc/crontab`. Instead, use an editor: `cron` will notice that the file has changed and immediately begin using the updated version. See this FAQ entry for more information.

To install a freshly written user `crontab`, first use an editor to create and save a file in the proper format. Then, specify the file name with `crontab`:

    % crontab crontab-file

In this example, `crontab-file` is the filename of a `crontab` that was previously created.

To list installed `crontab` files, pass `-l` to `crontab`.

For users who wish to begin their own crontab file from scratch, without the use of a template, the `crontab -e` option is available. This will invoke the selected editor with an empty file. When the file is saved, it will be automatically installed by `crontab`.

In order to remove a user `crontab` completely, use `crontab -r`.

Prev | Home | Next
Starting Services | Up | Using rc(8) Under FreeBSD