What is Cron?

Cron is a program that enables you to execute a command, or a script with a sequence of commands, at a specified date, time or at set intervals. The commands or scripts that you want cron to run are defined in a file called crontab, and every user has their own independent crontab file. Cron is a system program that is running all the time and is similar to the Windows scheduler which allows you to run commands/programs at predefined times and intervals.

This tutorial will explain how to use Cron and crontab and contains some basic working examples that should hopefully illustrate how it functions.

Note: Cron is only available on the CGI server. It is not possible to run scheduled commands or scripts on the homepages (www) server.


How do I use Cron?

There is a special format for entering crontabs:

Minute Hour Day Month Day Task

Minute = Minute of the hour, 00 to 59. * Will indicate every minute (details later)
Hour = Hour of the day in 24-hour format, 00 to 23. * Will indicate every hour (details later)
Day = Day of the month, 1 to 31. * Will indicate every day (details later)
Month = Month of the year, 1 to 12. * Will indicate every month (details later)
Day = Day of the week, 3 chars - sun, mon, tue, or numeric (0=sun, 1=mon etc).... * Will indicate every day (details later)
Task = The command you want to execute

Note: each of the above must be separated by at least 1 space.

It is advised to include the following line, or similar at the top of the file:

MAILTO=cron@username.domain.com

This ensures any error output from the cron tasks and any output from your script gets emailed to an address you can pick it up from. If you do not add this entry, any errors our script output will be appended to a file called Mailbox in your CGI user account home directory. This insures that you can easily find and resolve any problems that occur when running a command or script through cron. To stop any email or Mailbox file being generated when a command is executed, use MAILTO="". This should only be used once you have established the commands specified in your crontab file are working correctly.

Absolute Pathnames

When entering commands into the crontab file, it is important that you use absolute pathnames (such as "/files/home1/username/script.php") to specify the script in crontab. This is also true for any local scripts you use within other scripts and for any system commands you use within the script you are running. This is because when cron runs your command, it does not have the same $PATH defined for finding system commands. To find the path to a system command, just enter whereis command at the $ prompt and you will get a path to the command returned, which you can then use within your script. One of the common failures is not using an absolute path when run from cron. Even though it runs perfectly when you run it from the $ prompt.

You can use the environment variable $HOME to simplify the path to files and scripts within your home directory as it corresponds to the full path to your home directory. So instead of using /files/home1/username/php/script.php you can use $HOME/php/script.php.

So, an example crontab may look like:

MAILTO=cron@username.plus.com * * * * * /command/to/execute

This would execute /command/to/execute every minute.

Now that you have a basic understanding of how cron works, we will expand on it with some examples.


Examples

How do I run a task every 5 minutes?

One option is to use

MAILTO=cron@username.plus.com 0,5,10,15,20,25,30,35,40,45,50,55 * * * * /command/to/execute

However, there is a special shortcut for this:

MAILTO=cron@username.plus.com */5 * * * * /command/to/execute

The */5 is known as a short form equivalent to 0,5,10,15,20 etc... and achieves the same effect as the previous example, executing the command every 5 minutes. Other examples are: */2 would be every 2 mins, */30 every 30 minutes and so on. You can use the same short form for the hour indicator */2 every 2 hours, */6 every 6 hours etc.

How do I run a task at 6PM every night?

MAILTO=cron@username.plus.com 00 18 * * * /command/to/execute

How do I run a php script at 2am every Sunday?

MAILTO=cron@username.plus.com 00 02 * * sun /usr/local/bin/php $HOME/php/script.php

Notice that the php command is specified using an absolute path because cron will not be able to find it otherwise. If it was not specified, the script.php will fail to execute and an error like: php not found will be reported in the email you receive or in Mailbox. You may not spot this, especially if you run it successfully from the $ prompt as php /absolute/path/to/script.php or even php script.php if it is in the current directory. Also note $HOME is being used instead of /files/homeX/username/

Example MailBox or Email from cron

tutorialsteam@shell2 tutorialsteam $ more Mailbox From root@shell1.cgi.plus.net Sun Feb 01 23:11:27 2004 Return-Path: <root@shell1.cgi.plus.net> Delivered-To: tutorialsteam@shell1.cgi.plus.net Received: (qmail 18527 invoked by uid 10667); 1 Feb 2004 23:11:25 -0000 Date: 1 Feb 2004 23:11:25 -0000 Message-ID: <20040201231125.18514.qmail@shell1.cgi.plus.net> From: root@shell1.cgi.plus.net (Cron Daemon) To: tutorialsteam@shell1.cgi.plus.net Subject: Cron <tutorialsteam@shell2> $HOME/me X-Cron-Env: <SHELL=/bin/sh> X-Cron-Env: <HOME=/files/home2/tutorialsteam> X-Cron-Env: <PATH=/usr/bin:/bin> X-Cron-Env: <LOGNAME=tutorialsteam> I am: uid=10667(tutorialsteam) gid=500(shellcgi) groups=500(shellcgi) PATH is set to: /usr/bin:/bin

Crontab command options

crontab -e

As explained earlier, this will allow you to edit the contents of your crontab file or create a new crontab file if one does not already exist. The editor used is called vi or vim.

crontab -l

This will list the current contents of your crontab file and is very useful for checking you have edited it correctly after crontab -e. It is often useful to make a copy of the crontab file in case you make a mistake with an edit.

$ crontab -l >mycrontab

This will create a local copy of the crontab file called mycrontab.

crontab -r

Use with caution: This will delete the contents of your current crontab file (another reason for making a local copy!)

crontab file

This is an alternative method for setting up your crontab file. Instead of using crontab -e, you can create a file containing the cron commands and use that to replace or overwrite the current contents of your crontab file. Note replace - it will overwrite anything that is currently in your crontab file with the contents of file.