(updated
I started using launchd and encounter a peculiar issue. When I send a 'display notification' it works fine from within Script Editor but not from launchd. The 'say' command actually does work from launchd. For testing I also tried the 'display dialog' command, which also doesnt work from launchd. A final say command after this is also not audible.
Launchd is Apple's replacement in OS X for several Unix process managementutilities, most notably cron. I use it to run several scripts atscheduled times or fixed intervals. Every day my computer is set to download mytwitter statuses and check my library card for overdue books. Every morning mycomputer resets its volume to medium. Every week it backs up the WordPressdatabase of my 'family pictures' blog. It syncs my work files between mycomputer and the university file server.
- While the default editing mode in LaunchControl supports all documented features of launchd(8), you may sometimes need to use unofficial features. Switch to 'Expert Mode' and you're set.
- Wikipedia defines launchd as 'a unified, open-source service management framework for starting, stopping and managing daemons, applications, processes, and scripts. Written and designed by Dave Zarzycki at Apple, it was introduced with Mac OS X Tiger and is licensed under the Apache License.'
- Absolute freedom - While the default editing mode in LaunchControl supports all documented features of launchd(8), you may sometimes need to use unofficial features. Switch to 'Expert Mode' and you're set. Both modes are fully synchronized. Changes in one editor will instantly show up in the other one.
Almost anything you can do with cron you can do with launchd, but with morepower and flexibility. Unlike cron, launchd does not assume that your computeris always running. So if your computer happens to be sleeping at the time a jobis scheduled, it will run the job when it wakes up. This is probably the bestfeature of launchd, because it allows me to run scripts on my iMac while stillletting it sleep when I'm not using it.
I have pieced together what I know about using launchd to schedule jobs fromtutorials across the internet, trial and error, and the manuals. This is myattempt to gather all my knowledge about this in one place. If there issomething you think I should add or fix, let me know.
(This article has been updated from the original version,most notably with information about new software tools.)
Contents
Because this article is longer than usual.
- Tools to manage your agents
Quick start
The best way to get started is to buy LaunchControl.
LaunchControl doesn't have to stay running in the background.It just sets up the job and gets out of the way, letting OS X do the rest. Andsince OS X already uses launchd to run just about everything, from Spotlight tossh-agent to the bezel notifications that appear when you change the volume,scheduling jobs will not add any overhead.
Launchd basics
Each launchd agent is stored in an xml plist file. The file containsinformation about what program to run, when to run it, which arguments to use,and other options. Although technically you can make things work no matterwhere the plist file is saved, it is best to put it in~/Library/LaunchAgents, because plists in this folder are automaticallyloaded into launchd when you log in.
Launchd Editor
Each agent has a label, which must be unique. Apple uses reverse domain syntaxcom.apple.whatever, but it doesn't matter. The plist filename can beanything, but you would be crazy to use anything other than the label, e.g.com.apple.whatever.plist. Sometimes agents are referred to by the file, andsometimes by the label.
Warning: At some point you will use one of your plists as a template tocreate another. You will of course give them different filenames, but you willforget to change the label, which means only one of them will work. Hopefullythis warning will then enter your mind and you will solve the problem.
Apple uses the terms load and unload to mean that an agent is in thesystem, ready to go, and start or stop to talk about running or killing theactual process. So all agents in your LaunchAgents folder are loaded when thecomputer starts up. Then it pays attention to when they are scheduled andstarts them at the appropriate time. If you create a new plist file you need toload it manually. If you change a plist file, you need to unload it and load itagain.
Tools to manage your agents
- Launchctl is Apple's tool, which gives you most control at the expense ofcomplexity.
- LaunchControl is a graphical interface for managing your agents. It gives youyou full control and does a good job of taming the complexity.
- Lingon is another graphical interface for managing your agents.
- Lunchy is like launchctl, but slightly more convenient.
Launchctl
Apple provides launchctl to manage your agents. The main commandsyou need are
Notice that load and unload require the filename, while start and stoprequire the label. The start command will manually run the job, even if itisn't the right time. This can be useful for testing. The stop command justkills the process, but is convenient because you don't need to know the pid.The list command shows all loaded agents, with the pid if they are currentlyrunning and the exit code returned the last time they ran.
LaunchControl
I mentioned LaunchControl earlier, and it is the tool Irecommend. It can create and edit your plist files, giving youhelpful information when you need it. It can start, stop, load, and unload youragents and help you debug them when they fail.
(LaunchControl was released after the first version of this article, and it is good enough that it makes a lot of what is written here unnecessary.)
Lingon
Lingon is a simple tool for creating and managing launchd agents. It does notgive you as much control as LaunchControl, but it has been around longer. Whenyou use Lingon to edit an agent, pressing the Save button automatically loadsand unloads the job.
Lunchy
One other useful tool is Lunchy by Mike Perham. This is a ruby scriptthat speeds up the loading and unloading of agents by allowing you to refer toa plist by any unique substring of the filename. My only issue is that it usesterminology that conflicts with Apple's. Lunchy uses start to mean load andstop to mean unload. It mostly compensates by providing very usefulcommands restart to unload and then load and edit to edit the file in yourdefault editor.
Install it using gem install lunchy and then edit the file using
Now reload it using
Format of the plist file
Here is a very basic plist file to run a script every 86,400 seconds.
There are several other keys you can insert between lines 4 and 13 to activateother options. If you want to see what is available, read the launchd.plistmanual.
Note that I have provided the full path to the script, since globs aren'texpanded by default. If you want to expand globs, you can include anEnableGlobbing key followed by .
If your script requires arguments, you would supply these in extra stringtags after line 9.
If you download a script from the internet or write one yourself, make sure itis executable, or this might not work.
By default, anything written to standard out or standard error ends up in thesystem log. If you would like it to be somewhere else, you can use theStandardOutPath and StandardErrorPath keys.
The KeepAlive key allows a script to be run multiple times, depending oncertain conditions. If you set it to , then the script will be runover and over again forever. The following snippet will rerun the script if itreturns a nonzero exit code. Read the xml as 'Keep the process alive as long asit doesn't successfully exit'.
In most cases, the system will wait 10 seconds between runs of the script tosave system resources. You can adjust this with a ThrottleInterval key, whichtakes an integer argument, and should be outside the KeepAlive dictionary.You can also set the agent to stay alive depending on the (non)existence of aninternet connection using NetworkState or of a file using PathState.
In older versions of OS X, there was an OnDemand key which was required. Itis now obsolete and has been replaced by KeepAlive, which is optional. Manyof the other examples on the internet still have an OnDemand key, but youdon't need it.
Permissions
For security reasons, launchd will not run LaunchAgents whose plist files havethe wrong permissions. For example, they must not be writable by anyone otherthan the owner. Root LaunchAgents stored in /Library/LaunchAgents must beowned by the root user.
Disabled agents
Both launchctl and lunchy allow you to disable an agent using the -w flagwith unload/stop. I do not recommend this. An agent that has been disabledwill not load when you log in and cannot be loaded usingload/start without using the -w flag again. You will probably just beconfused later about why an agent is not loading even though it is in the rightplace. Information about which agents have been disabled in this manner isstored in a separate file. In Lion, this is the file
where NNN is your user id number (find it using id -u).
Random thoughts
Your launchd agents are loaded when you log in, but not unloaded when you logout. So the only time your agents aren't loaded is during the time between arestart and when you log in. If you have multiple users and need something torun no matter who is logged in, you should put it in/Library/LaunchAgentsor/Library/LaunchDaemons.
If your computer sleeps often, it will be asleep when jobs should run, whichmeans it will run them right when it wakes up, possibly before it connects tothe internet. I have experimented with KeepAlive and NetworkState to get ajob to repeat itself until there is a network connection. You could also useSuccessfulExit and write the script so that it only returns a nonzero code tomean 'run again in 10 seconds.' Either method would have the script running(and presumably failing) every 10 seconds when you have no internet connection.A better idea would be to just sleep 5 seconds at the beginning of your script.Or you could double the run frequency and hope for the best.
The challenge: keeping my IP address up to date
I recently wanted to find a way to keep dynamic DNS updated for a smart DNS service at home (to keep MOG, Pandora and LastFM running without using the hassle of a VPN). It turns out my home DSL router's IP address changes all the time and I was updating my DNS mapping service multiple times per day.
It was a bit of a hunt to find a suitable dynamic DNS solution as dyndys.org went (expensive) paid at $25/year recently. After looking at some of the competitors, I finally chose DNSmadeeasy to avoid creating managing more logins. We already have work accounts and DNSmadeeasy includes dynamic DNS with every name in your account (fabulous value if you need a lot of dynamic DNS). If you are looking for free dynamic DNS, the amusingly named http://afraid.org appears to be the last good free solution operating.
While on Afraid.org's site, I found a nice quick Bash script which could be customised for DNSmadeasy. Unfortunately I couldn't get Curl to work well in bash, with DNSmadeeasy's update command failing (personal data removed) even with -d data variables or with a simple http command:
http://cp.dnsmadeeasy.com/servlet/updateip?username=custom&password=yourpassword&id=yourkey&ip=12.13.14.15
I was able to find a Perl script for DNSmadeeasy. The DME Update scrip I was able to customise (yes, unlike wget Perl is included in Mac OS X 10.6.8 (you can check for Perl with a quick 'perl -v': I got v.5.10.0 back). Troubleshooting was a cinch once I enabled the '-f -v' flags for forcing an update and for verbose feedback.
Once I finally had a working update script the next question was how to make it run repeatedly to keep with the constantly changing IP. There are three good choices on OS X, either a cron job, LaunchD or a dedicated application.
LaunchD: Lingon + launched.zerowidth.com
LaunchD is what Apple recommends. If that's the path you want to follow, setting up one of these plists by hand is like a trip to the dentist. There's two solutions. Lingon which has a watered down version in the app store or a full fledged version at the Peter Borg's site. Whatever you do, don't choose the app store version, it's crippled. What's obnoxious is Borg charges more for the non-app store version (even though he's not paying Apple a cut). You can actually get the old free version (which is apparently compatible with 10.7 and 10.8 and definitely worked on 10.6.8) back on SourceForge.
lingon edit window
Even more fun than Lingon if you are creating new LaunchD plists is ZeroWidth's Launched online service. Here you just, fill in the name, your command, set up your schedule and press 'Create .plist'. What happens on the other side is even more amazing.
launched launchd plist nathan witmer
You get three options for install.
- A quick command line version.
- The .plist itself with options to edit and/or download.
- Manual command line.
Launchd Editor App
launched zerowidth launchd plists
Launched is one of the best web services I've ever seen and a model for the genre. If everyone would write web applications like Nathan Witmer, the world would be a better place.
Crons: Cronnix
Crons can be edited by hand. Unotelly has a pretty good tutorial here.
- Open Terminal
- Type 'crontab -e'
- Press 'i' to enter insert mode.
- Write or paste in your Cron, something like: '* 1 * * * curl -o /dev/null http://www.unotelly.com/unodns/auto_auth/hash_update/updateip.php?user_hash=YOUR_HASH_HERE'
- Press 'Esc'
- Type ':wq' to save
Frankly, editing cron from the command line is a bit fiddly. Fortunately, there's a very sexy OS X application called Cronnix from Sven Schmidt.
cronnix icon
Unfortunately there's only a very lean Google Code site there. What's very cool about Cronnix is you only need to run it when you want to edit your crons. Bad Apple for slowly deprecating the industry standard crons. Apparently even Apple is not presumptuous enough yet to remove cron from Unix, though they would like to.
cronnix gui schedule
Dedicated Application: Scheduler
Finally, there's an ultra flexible dedicated application that almost no one has heard of but which is incredibly flexible and powerful called simply Scheduler which is on version 6 and has only been downloaded 19,469 times. Unbelievably Scheduler is free. Why would anyone want a dedicated application for repeated programs when both Cron and launchD are built in to OS X. Author Joao Varela explains:
Launchd Editor Download
Scheduler goes far beyond cron and launchd in several aways, as it has built-in functions for posting reminders together with your favorite music (including iTunes songs), launch and open web pages and download files with your favorite browser, among may other features and options. Moreover, Scheduler has many, many scheduling options that are very difficult to do with launchd or cron, such as with a few clicks you can schedule a script to be launched every 2 minutes on the last Monday of the month of June, but not in July, and so and on.
Varela scheduler
There's versions that work as far back as 10.2 with wide compatibility between major revisions. How Varela manages to maintain this application as freeware is miraculous to me. All he gets out of his users is an email address. If you are totally uncomfortable with command line type tools or have very complex scheduling needs, Scheduler is a fantastic application.
Winner
The solution I've chosen for myself is Cronnix and Cron. Cron is an open source technology which works on both desktop and server Linux and Unix. Regardless of what foolishness Apple comes up with next, skills in working with Cron will help me work on my servers and my own computers. LaunchD skills are only guaranteed to be worth something as far as Apple's next OS update (Apple has hidden all the Library and System folders in recent updates, xCode won't output Snow Leopard compatible applications and Apple Script has been deprecated, Apple are more than capable of throwing LaunchD overboard at the most inconvenient moment).
Launchd Editores
Alec has been helping businesses succeed online since 2000. Alec is an SEM expert with a background in advertising, as a former Head of Television for Grey Moscow and Senior Television Producer for Bates, Saatchi and Saatchi Russia.
