Project70.Schedule Commands with at

Project 70. Schedule Commands with at

"How do I schedule a shell script to run at 6:30 tomorrow morning?"

This project takes advantage of the Unix at command to schedule a job (a command or shell script) to run at a specific time. It shows you how to enable at, add jobs, and manage the jobs queue. It covers the commands at, atq, atrm and launchctl. Project 71 covers periodic scheduling with the system cron daemon. Project 72 covers periodic maintenance controlled by Apple's Launch Daemon.

The at Queue

The at command manages a queue of jobs, each scheduled to run on a particular date at a particular time. After each job is run, it's removed from the queue, so at is typically used for one-shot operations that need to occur at predetermined times. (Recurring tasks are better handled by the cron command, discussed in Project 71.)

You may add many jobs to the at queue, and each will be run at its scheduled time. If you change your mind about running a job, you can view the at queue and delete the job from it.

The default Mac OS X install has at disabled, so before we can use it, our first task is to enable it. How you enable at depends on whether you're running Mac OS X 10.4 (Tiger) or an earlier version of the operating system. We'll look at the Tiger case first.

The at command itself is scheduled to run every 5 minutes, at which time it checks its job queue for due jobs. It's launched by Apple's Launch Daemon, launchd, but is disabled by default "due to power-management concerns," according to the at man page. To enable it, we use the launchctl command, specifying subcommand load to load the configuration file for that service. The option -w removes the "disabled" key and writes the altered configuration file back to disk.

Type the following launchctl command, which you issue as the root user using sudo, and give your administrator password when prompted.

$ sudo launchctl load -w ¬     /System/Library/LaunchDaemons/com.apple.atrun.plist Password:

Tip

To disable at, issue the same command you used to enable it, but specify subcommand unload instead of load.

You might like to check the Launch Daemon configuration file for at, which is written to this file:

/System/Library/LaunchDaemons/com.apple.atrun.plist

Use a text editor, or if you have installed the Developer Tools, double-click the file to open it in the Property List Editor application. In either case, you'll see a property called StartInterval set to 300. This tells Launch Daemon to launch at once every 300 seconds (5 minutes). The default install also has a property called Disabled set to Yes or true, but we just removed it by issuing the launchctl command.

Learn More

cron is discussed in Project 71.

In versions of OS X before Tiger, at was enabled by the more traditional Unix method of adding a line to the system cron table. Add the following line to the file /etc/crontab. Edit the file as the root user.

*/5   *   *   *   *   root    /usr/libexec/atrun

(The line is probably already in the file but commented out. If so, remove the # character from the start of the line.)

Learn More

Chapter 4 covers several Unix text editors.

Also, if it does not already exist, create the file /var/at/at.deny by typing

$ sudo touch /var/at/at.deny

Schedule a Job

Schedule a simple test command typed from the keyboard to test that at has been successfully enabled. Choose a time in the near future, and type the following (or something similar); then press Control-d, which means "end of input." When the job runs, it creates a file called ~/at-is-running.

$ at 18:18 /usr/bin/touch ~/at-is-running <Control-d> job 1 at Sat Aug 13 18:18:00 2005

Check that the job is queued by issuing the atq command.

$ atq 1      Sat Aug 13 18:18:00 2005

Tip

The actual script that at generates to run a job resides in the directory /var/at/jobs. It's plain text, so you can display it by using cat or a similar command. You'll notice that each job is written as a shell script that reproduces the environment and current working directory at the time when the job was created.

Wait until the designated time (or up to 5 minutes after, because at itself is scheduled to run only every 5 minutes); then see whether the designated file was created.

Write the Job to a File

We can write a more complex job to a file and have at read the file. In the next example, we use the rsync command to copy updated files to a backup disk. Here's the file, called at-backup.

$ cat at-backup /usr/bin/rsync --delete --archive --update -E /Users/saruman/Desktop/ /Users/saruman/Desktop2/

Add the job to the queue by using at with option -f, followed by the name of the file.

$ at -f at-backup 18:56 job 2 at Sat Aug 13 18:56:00 2005

Remove a Job

To remove a job from the queue before it's executed, use the atrm command, and give the job number as an argument.

$ atq 3      Sat Aug 13 19:10:00 2005 $ atrm 3

Capture Output from a Job

When a job is executed, any output it may produce is captured and mailed to you. Use the Unix mail command to view the mail, or simply view it directly with a text editor; you'll find it in a file called /var/mail/your-user-name. To throw away all output, redirect standard output and standard error to /dev/null by appending &> /dev/null to the end of the command.

To redirect output to a file, append &> at.out (or any other filename) to the end of the command. When the job executes, it sees the same working directory that was current when the job was scheduled.

Learn More

Project 6 shows you how to redirect output.

Amusing at Anecdotes

Time travel:

$ at -f at.example ¬     10:15 14.08.04 at: trying to travel back in time

Pedantic, but the job is accepted.

$ at -f at.example ¬     10:15 +1 days at: pluralization is wrong job 10 at Mon Aug 15 10:15:00 2005

Specify Dates

Here are some examples in which we specify dates and times for at to run jobs.

$ at -f at.example 10:15 14.08.05 job 9 at Sun Aug 14 10:15:00 2005 $ at -f at.example 10:15 Aug 15 job 11 at Mon Aug 15 10:15:00 2005 $ at -f at.example now + 1 hour job 14 at Sun Aug 14 01:39:00 2005