User Guide - Adding a Cron Job
- 17/03/2009 7:53 PM
Applicable Plans - All eApps General VPS Plans
User Guide - Adding a Cron Job
Overview
Cron is a time-based job scheduler in Unix-like computer operating systems. The name cron comes from the word "chronos",Greek for "time". Cron enables users to schedule jobs (commands or shell scripts) to run periodically at certain times or dates. It is commonly used to automate system maintenance or administration, though its general-purpose nature means that it can be used for other purposes, such as connecting to the Internet and downloading email - from http://en.wikipedia.org/wiki/Cron
Cron allows you to schedule a command or a script to run at a specific time of day, or on a specific day of the week or at a particular time of day on a specific day of the month. Cron allow for scheduling down to the minute and up to an annual event.
All eApps VPS plans have cron as part of the default operating system install. The operating system regularly uses cron to rotate logs and run internal updates.
Adding cron jobs - basic concepts to understand
Adding a cron job
Links to other information
Adding cron jobs - basic concepts to understand
Before creating a cron job, you need to understand two basic concepts that affect how cron jobs work. These are the user environment, and the permissions.Cron and the user environment
It is important to understand that the cron application does not inherit the system environment of the user who owns the cron job. Variables that apply to the user, such as PATH, do not apply to cron. This means that you will need to use absolute paths for both commands and file locations in your cron jobs. Relative paths will not work.Here is an example, using the webadmin user. This is the "path" for the webadmin user. The path is the set of directories where executable programs are located.
| [webadmin@eapps-example ~]$ whoami webadmin [webadmin@eapps-example ~]$ echo $PATH /usr/kerberos/bin:/usr/local/bin:/bin:/usr/bin:/home/webadmin/bin [webadmin@eapps-example ~]$ |
This means that the webadmin user can look in the listed directories for commands to run. For example, the copy command (cp) is in /bin.
Here is the directory listing for the eapps-example.com/html directory:
| [webadmin@eapps-example html]$ pwd /home/webadmin/eapps-example.com/html [webadmin@eapps-example html]$ ll total 76 -rw-r--r-- 1 webadmin webadmin 43 Feb 9 13:37 1.gif -rw-r--r-- 1 webadmin webadmin 68 Feb 9 13:37 hspc-wwwroot.html -rw-r--r-- 1 webadmin webadmin 1634 Feb 26 22:19 index.shtml -rw-r--r-- 1 webadmin webadmin 7319 Feb 9 13:37 web_site_lemon_tree.jpg -rw-r--r-- 1 webadmin webadmin 130 Feb 9 13:37 web_site_rt.gif drwxrwsr-x 2 root root 4096 Mar 24 14:49 testdirectory drwxrwxr-x 5 webadmin apache 4096 Feb 10 14:54 wordpress [webadmin@eapps-example html]$ |
If the webadmin user wanted to copy the 1.gif file into the wordpress directory, the command would be:
| [webadmin@eapps-example html]$ cp 1.gif wordpress/ |
The webadmin user has the cp command in its path, and can use the relative paths for the file and directory names.
But because cron does not have access to webadmin's path variable, the same command in a cron script would be this:
| /bin/cp /home/webadmin/eapps-example.com/html/1.gif /home/webadmin/eapps-example.com/html/wordpress |
This calls the full path for the cp command, as well as the full path for the file and directory.
This is a very important concept to understand. You must always use absolute paths for both commands and files/directories when creating cron jobs.
Cron and file permissions
Unlike the user environment, cron does inherit the permissions of the user running the cron job. This means that the user who owns the cron job has to have the permissions to access the file or directory. Here is another example with the webadmin user, trying to copy the file 1.gif into the directory testdirectory, which is owner and group of root.| [webadmin@eapps-example html]$ ll -d testdirectory/ drwxrwsr-x 2 root root 4096 Mar 24 14:49 testdirectory/ [webadmin@eapps-example html]$ cp 1.gif testdirectory/ cp: cannot create regular file `testdirectory/1.gif': Permission denied [webadmin@eapps-example html]$ |
If you find that your cron jobs are failing, check to make sure that the user that is running the cron job has the correct permissions to be able to access or run the files or directories. Some cron jobs cannot be run as a normal user because of this. You will have to create those cron jobs as the root user instead.
Be very careful about changing the default system permissions and ownership for files and directories, especially for files and directories outside the user's home directory. The default file and directory permissions are in place for a reason, so you need to have a very good reason to want to change them. Changing the permissions on certain system files and directories can actually cause your VPS to crash and not restart short of a full restore.
Cron syntax
A cron job is read from left to right, starting with minutes, and moving to the actual command. The specific order is:.---------------- minute (0 - 59)
| .------------- hour (0 - 23)
| | .---------- day of month (1 - 31)
| | | .------- month (1 - 12) OR jan,feb,mar,apr ...
| | | | .---- day of week (0 - 7)(Sunday=0 or 7)OR sun,mon,tue,wed,thu,fri,sat
| | | | |
* * * * * command to be executed
This order is absolute - you have to have all fields represented, even if you have no value in that field.
Cron service and log files
To stop/start/restart the cron service, you can use either the PBA Control Panel, or the command line.Control Panel
To stop/start/restart the cron service (the cron daemon, also called crond) from the Control Panel, login to the Control Panel, and click on the System tab. If necessary, click on Select Another System (Subscription) link on the left and choose the correct Virtuozzo container.Then, scroll down to Service Management, and click on Services. It may take a minute or more before the Services screen populates. In the Services list, find crond, and click on it. This will show you the Status, and will allow you to Stop/Start/Restart depending on the current status.
Command line
To stop/start/restart the cron service from the command line, log in to the VPS using SSH. Then, as the root user, use one of the following commands.Check crond status:
| root@eapps-example ~]# service crond status crond (pid 15903) is running... root@eapps-example ~] |
Stop crond:
| [root@eapps-example ~]# service crond stop Stopping crond: [ OK ] [root@eapps-example ~]# |
Start crond:
| [root@eapps-example ~]# service crond start Starting crond: [ OK ] [root@eapps-example ~]# |
Restarting crond:
| [root@eapps-example ~]# service crond restart Stopping crond: [ OK ] Starting crond: [ OK ] [root@eapps-example ~]# |
Cron log files
The log files for cron are located in /var/log - the files are cron, and cron.1 through cron.4. The files are rotated once a week, and the existing cron.4 file is rotated off every week, and the other files move down one number.| [root@eapps-example log]# pwd /var/log [root@eapps-example log]# ll cron* -rw------- 1 root root 3034 Apr 19 10:28 cron -rw------- 1 root root 17974 Apr 18 04:47 cron.1 -rw------- 1 root root 14728 Apr 11 04:47 cron.2 -rw------- 1 root root 14726 Apr 4 04:47 cron.3 -rw------- 1 root root 14734 Mar 28 04:47 cron.4 [root@eapps-example log]# |
Adding a cron job
Cron jobs can be created in two ways: from the PBA Control Panel, or from the command line. The PBA Control Panel allows you to create cron jobs on a per Site basis (but not at the System level), and the command line allows you to create cron jobs that can run system-wide. If you need to create a cron job that runs as the root user, you will need to use the command line.Control Panel
To add a cron job from the PBA Control Panel, log in to the Control Panel, and click on the Site tab. If necessary, click on Select Another Site, and choose the site where you want to add the cron job.Remember that cron jobs added from the Control Panel are at the Site level only. If you need to create a cron job that will run at the system level, as the root user, you will need to add that cron job from the command line.
Scroll down to the Other section, and click on Crontab.
To create a cron job, click on Add Cron Job.
This brings up the screen for Add Cron Job.
- Command to run - this is the command for the cron job to run. This can be a simple command or the path to an executable script. Remember that cron requires you to put the absolute paths for commands and files in order to work.
- E-mail address the cron output will be sent to - if you need to have a report of the output of the cron job, you can enter an e-mail address here. The e-mail address can be any address, on or off the VPS.
- Enabled - if the Enabled box is checked, the cron job will be added to the crontab file for the site. If this box is not checked, the cron job will not run.
Below this is where you set the time for the cron job to run. The default setup in the Add Cron Job screen is to run Every Minute, of Every Hour, of Every Day, of Every Month, on Every Weekday. Added up, this results in approximately 524,160 times for the cron job to run over the course of a year. Depending on what your cron job is doing, that is probably not the optimal setting.
To set the time the cron job runs, you will need to adjust these settings.
To better understand how cron works, you need to understand the values it uses for time. Cron can be set for Minutes, Hours, Day, Month, and Weekday, and any combination of those values.
- Minutes - cron can be set to run every minute, every other minute, every five minutes, every 10 minutes, every 15 minutes, or at a specific minute. If you wanted your cron job to run on the 12th minute of the hour, you would choose the number 12 from the Minutes list.
- Hours - cron can be set to run every hour, every other hour, every four hours or every six hours. cron can also be set to run at a specific hour of the day. Note that cron uses a 24 hour clock to keep time - http://en.wikipedia.org/wiki/24-hour_clock In the US, this is usually referred to as military time. This means that if you want your cron job to run at 3pm, you will need to choose 15 as the hour. Choosing 3 will cause your cron job to run at 3am.
- Day - cron can be set to run every day, every other day, every seven days, or every 15 days. You can also choose a specific day of the month for the cron job to run on. If you wanted your cron job to always run on the 13th day of the month (no matter what actual weekday that was), you would choose the number 13.
- Month - cron can be set to run every month, or only in a specific month or months. If your cron job only needs to run in July and December, you can select those two months from the list (using cntrl +click or command + click).
- Weekday - cron can be set to run every day of the week, or on a specific day or days of the week.
 |
Day and Weekday are different values. With the Day value, you choose a specific date in a month. For example, if you chose 13, then your cron job would run on the 13th day of the month, no matter what day of the week it was. With Weekday, you can choose what day of the week to run on. If you chose Tuesday, then your cron job would run on every Tuesday, no matter what the date was. |
Set the values for when you want your cron job to run, and then click Save. This restarts the cron daemon (crond) and your cron job will be picked up and run the next time the system time, day, and date match the cron job settings.
The cron daemon (background process) runs every minute. When it runs, it checks the cron files in /var/spool/cron/ and reads the individual cron entries left to right. If all values match for that specific time, the cron job runs. If any values don't match, the cron job is not run, but is checked again in one minute. If your cron job isn't running, or isn't running when you expect it to, double check that you have the correct syntax.
Editing/Changing a cron job from the Control Panel
Once you have added a cron job from the PBA Control Panel, you can edit the cron job again by clicking the Edit button under Actions This is the left button, that looks like a small hammer and wrench. This will bring up the same window that was used to create the cron job, and you can make your changes there.Command line
To add cron jobs from the command line, you will need to be able to log into the VPS using SSH, and be able to navigate the file system and edit files using standard Linux commands and editors. These instructions assume that you already possess these skills. These instructions also assume you know how to edit/create a cron job from the command line.See the SSH User Guide - http://support.eapps.com/hsp/ssh for more information on connecting to the VPS via SSH. If you need more information on how to use Linux commands, there are many references online that can assist you. See Links to other information for a quick pointer to some of them.
 |
The syntax for cron can be quite complex, and you may need to tweak your syntax several times to get it exactly right. See Links to other information for a site with some very good cron syntax examples. |
From the command line you can either add cron jobs for a specific user and site, or for the root user.
Specific user and site
If you are going to manage all your cron jobs from the command line, and do not expect to see them in the PBA Control Panel GUI interface, then you can use the standard crontab -e command to edit the crontab file for the Administrative User for the site.To find the admin user for a site, look at the owner for the site in the /home directory. For example, the eapps-example.com site is located here:
| [root@eapps-example webadmin]# pwd /home/webadmin [root@eapps-example webadmin]# ll -d eapps-example.com/ drwxr-xr-x 4 webadmin webadmin 4096 Apr 11 04:47 eapps-example.com/ [root@eapps-example webadmin]# |
In this case, the webadmin user is the Admin user for the site. You can also see this from the Control Panel, Site tab for that site, Website Settings - the Admin username is listed in the General section of the General Settings tab.
Connect to the VPS either as the Admin user, or change to the Admin user once connected. Then run the crontab -e command to edit the cron file (crontab -l will list the contents of the file).
| [root@eapps-example ~]# su - webadmin [webadmin@eapps-example ~]$ [webadmin@eapps-example ~]$ crontab -e |
This opens the crontab file for the webadmin user. The actual file is located at /var/spool/cron/webadmin
The file is edited with vi commands. Add your cron job to the file, remembering to use the absolute path for commands and file/directory locations. When you are done editing, save and exit the file. This restarts the cron daemon, which will pick up your new cron job.
To view the contents of the crontab, use the crontab -l command.
| webadmin@eapps-example ~]$ crontab -l MAILTO='webadmin@eapps-example.com' 1 0 4 * * /bin/cp /home/webadmin/eapps-example.com/html/1.gif /home/webadmin/eapps-example.com/html/wordpress [webadmin@eapps-example ~]$ |
If you are going to manage your cron jobs from both the command line and from the Control Panel GUI interface, you will need to add two lines to your crontab files for each site you are adding cron jobs for.
This is what a crontab file looks like that was added from the Control Panel:
| ## ----- Begin HSPC generated text. Do not edit! ----- eapps-example.com MAILTO='webadmin@eapps-example.com' 1 0 4 * * /bin/cp /home/webadmin/eapps-example.com/html/1.gif /home/webadmin/eapps-example.com/html/wordpress ## ----- End HSPC generated text. ----- eapps-example.com |
Notice the two lines added to the top and bottom of the cron job entry:
## ----- Begin HSPC generated text. Do not edit! ----- eapps-example.com
## ----- End HSPC generated text. ----- eapps-example.com
You will need to frame your crontab entry with identical lines, pointing to the actual site you are creating the cron job for (substitute eapps-example.com with the site name from the Site tab). Once you save the entry, this cron job will be available from the Crontab section in the Site tab for that site. Make sure that there are no empty lines between the HSPC lines and your cron job. If there are blank lines, then blank entries will show in the Crontab GUI in the Control Panel.
Root user
To add a cron job as the root user, you will have to use the command line. There is no system-wide cron interface from the Control Panel.The same steps apply for adding a cron job as a root user as for adding one for a specific site. You will need to connect to the VPS using SSH, and as the root user enter the crontab -e command to add your cron job.
Cron jobs added for the root user are often used to rotate specific application logs or run commands or scripts that require root permission.
Make sure that the cron jobs that are added for the root user do not conflict with the built in system default cron jobs, which can be found in the system cron files:
/etc/cron.d/
/etc/cron.daily/
/etc/cron.deny
/etc/cron.hourly/
/etc/cron.monthly/
/etc/crontab
Links to other information
Path variable - http://en.wikipedia.org/wiki/Path_(variable)Cron entry from Wikipedia - http://en.wikipedia.org/wiki/Cron
Linux Crontab examples - http://www.thegeekstuff.com/2009/06/15-practical-crontab-examples/ (good examples of cron syntax, very useful)
O'Reilly Linux Command Directory - http://www.oreillynet.com/linux/cmd/
UNIX Guide Linux commands - http://www.unixguide.net/linux/linuxshortcuts.shtml
vi tutorial - http://www.cs.colostate.edu/helpdocs/vi.html