Launchcontrol 1 38 – Create Manage And Debug Launchd(8) Services

1. Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Manager
2. Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Online
3. Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Free

(updated

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.

Descriptions for LaunchControl 1.37 Build 1037 Name: LaunchControl for Mac Version: 1.37 Release Date: 19 Dec 2017 Mac Platform: Intel OS version:OS X 10.7 or later Processor type(s) & speed: 64-bit processor Includes: Pre-K'ed (The Shark) Web Site: Overview LaunchControl is a launchd(8) frontend allowing you to manage and debug system. About; Archive; Projects; RSS; Schedule jobs using launchd July 24, 2012 (updated March 15, 2014). Launchd is Apple's replacement in OS X for several Unix process management utilities, most notably cron.I use it to run several scripts at scheduled times or fixed intervals.

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.

1. Tools to manage your agents

Quick start

The best way to get started is to buy LaunchControl.

Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Manager

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.

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

Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Online

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 .

Launch Control 1 38 – Create Manage And Debug Launchd(8) Services Free

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.