TweetFollow Us on Twitter

MacEnterprise: launchd for Lunch

Volume Number: 25
Issue Number: 09
Column Tag: MacEnterprise

MacEnterprise: launchd for Lunch

Recipes for using launchd for systems administration

By Greg Neagle, MacEnterprise.org

Introduction

A few months ago, we looked at how to run administrative scripts - how a systems administrator could run a script at startup, or a schedule, at user login, and more. There are many mechanisms to launch scripts at specific times and under specific conditions, but the one that came up over and over was launchd.

This shouldn't be surprising. Apple introduced launchd with the release of OS X 10.4 Tiger, and their stated goal was to make launchd replace most the other ways of launching processes on OS X. Specifically, launchd was designed to take over tasks from cron, xinetd, mach_init, and init, and to largely replace the StartupItem mechanism.

Recently on the MacEnterprise mailing list there was a discussion about accomplishing a certain task with a login hook. There was a reply that if one could accomplish the task using a launchd LaunchAgent, that would be preferred. Then the floodgates opened. A big discussion ensued about LaunchAgents versus login and logout hooks, launchd jobs as compared to cron jobs, and so on. It was quickly apparent that launchd was still not completely understood or trusted by many Mac OS X systems administrators. More specifically, it became clear there is still a need for concrete examples of how systems administrators can use launchd to replace other launching methods, like cron or a StartupItem, and to do things those launching mechanisms cannot. So in this column, I will present some "launchd recipes" - code snippets you can adapt to use for your own tasks.

Recipe Ingredients

Before we can look at some recipes, let's do a quick review of some of the ingredients we'll be working with.

A key concept is that launchd is just a mechanism to launch processes under certain conditions, and to optionally keep them running even if they unexpectedly exit. Launchd is not a scripting language. To do anything useful with launchd, you must have two ingredients:

A launchd plist. This is a configuration file that tells launchd what to launch, and under which conditions. We'll be looking at several example plists in this month's column.

The actual executable task. This can be a script, or a pre-compiled binary. This is what launchd runs for you when the conditions described in the launchd plist are met.

In most of these recipes, I leave it to you to supply the script. The focus of this column is how to get launchd to execute your script under the right conditions.

If you compare launchd to some of the more traditional methods of running tasks, you'll see the other methods support a more limited set of conditions. For example, the StartupItem mechanism can run a task only at startup. cron can run a task only at a certain time. periodic runs tasks only at certain intervals. xinetd can run a task only when a connection is attempted on a certain network port. Login items are executed when a user logs in. Launchd can run tasks based on all of these conditions, and more.

Launchd plists typically go in one of three locations: /Library/LaunchDaemons, /Library/LaunchAgents, and ~/Library/LaunchAgents. (There are two more directories containing launchd plists - /System/Library/LaunchAgents and /System/Library/LaunchDaemons, but these are reserved for use by Apple.) The launchd plists in /Library/LaunchDaemons are loaded at startup (this does not necessarily mean that the jobs themselves are run at startup, though) and the plists in the two LaunchAgents directories are loaded at user login (or other login-related contexts).

Two more things to know about launchd plists: they must be owned by root, and have permissions 0644. If launchd doesn't like the ownership or permissions of a plist, it will refuse to load it.

Now that we've reviewed the ingredients - on to the recipes!

Recipe 1: Run a script at startup

This is the simplest recipe. We have a script we'd like to run at startup.

Create a plist in /Library/LaunchDaemons with contents similar to these:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
      "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
   <key>Label</key>
   <string>org.myorg.startup.scriptname</string>
   <key>ProgramArguments</key>
   <array>
      <string>/path/to/script</string>
      <string>-argument</string>
   </array>
   <key>RunAtLoad</key>
   <true/>
</dict>
</plist>

You can name the plist anything you'd like ending in ".plist,' but the normal convention is to use the same name as the Label, so this plist would be named "org.myorg.startup.scriptname.plist". This launchd plist defines only three keys: Label, ProgramArguments, and RunAtLoad. Label defines a unique name for this launchd job. ProgramArguments contains the path to the command or script, plus any arguments, options, or switches to be passed to the command. If you wanted to remove the Apple Type Services databases at each startup, this command:

atsutil databases -remove

would become this in a launchd plist:

<key>ProgramArguments</key>
<array>
   <string>/usr/bin/atsutil</string>
   <string>databases</string>
   <string>-remove</string>
</array>

Note that this doesn't work:

<key>ProgramArguments</key>
<array>
   <string>/usr/bin/atsutil databases -remove</string>
</array>

The script or command itself and each argument or flag must be in a separate <string> element.

The RunAtLoad key simply tells launchd to run the job as soon as it loads this plist. Since a plist in /Library/LaunchDaemons is loaded at startup, the job is run at startup.

Recipe Variation: Run once at startup, but never again

A common systems administration need is for "run-once" startup scripts - typically these do some sort of configuration and so only need to run once. Unfortunately, launchd plists provide no explicit support for this sort of thing. (The man page for launchd.plist mentions a "LaunchOnlyOnce" key - but this causes a job to be launched only once per boot.) Your options for a job that runs only once are:

Have the script delete the launchd plist after it runs. On the next boot, since the launchd plist no longer exists, the job will not be run again.

Have the script execute

 launchctl unload -w /Library/LaunchDaemons/myjobname.plist 

as the last thing it does. This adds the Disabled key to the launchd plist and sets its value to True, so the job won't load on future reboots unless you remove the Disabled key or set it to False. You must call launchctl unload as the last thing the script does, though, because a side effect of unloading the plist is that the script will be killed as well.

Alternately, you could use a tool like PlistBuddy to write the Disabled key to the plist; this would avoid the issue of killing the process at the same time. Here's a Perl snippet, stolen from /usr/libexec/configureLocalKDC:

my $rerun_plist = '/System/Library/LaunchDaemons/com.apple.configureLocalKDC.plist';
chomp (my $status = qx{/usr/libexec/PlistBuddy -c "Print :Disabled" $rerun_plist});
if ($status ne 'true') {
        system '/usr/libexec/PlistBuddy', '-c', 'Add :Disabled bool True', $rerun_plist;
}

Have the script check for something else to see if it has already run. The script will still run at every startup, but if it finds the existence of a certain file or directory, it exits without doing anything else. An example of something using this strategy is the Setup Assistant that runs when you first install OS X, or when you first startup a new Mac. If the file /var/db/.AppleSetupDone doesn't exist, the Setup Assistant runs on boot. When the Setup Assistant exits, it creates the .AppleSetupDone file, stopping the Setup Assistant from running on future boots. An advantage of this approach is that if you ever need to re-run the script or application for any reason, you can remove the flag file to do so.

Recipe 2: Run a script on a repeating schedule

Cron and periodic are two traditional ways to run jobs on repeating schedules. Periodic is typically used to run a job on a daily, weekly, or monthly schedule. Cron can run a job on virtually any schedule you can imagine - once a minute; every Friday at 3:45pm; every two hours between 8AM and 6PM, Monday through Friday, and more. Cron and periodic are still around in OS X Leopard (and work fine), but launchd can replace most of what they do.

Here's an example of a launchd plist that runs a script every day at 5:15 AM:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>  
   <key>Label</key>
   <string>org.myorg.daily.radmind</string>
   <key>ProgramArguments</key>
   <array> 
      <string>/usr/local/radmind/run_radmind</string>
   </array>
   <key>StartCalendarInterval</key>
   <dict>  
      <key>Hour</key>
      <integer>5</integer>
      <key>Minute</key>
      <integer>15</integer>
   </dict>
</dict>
</plist>

This plist has no RunAtLoad key, since we don't want the script to run at startup. Instead, it has a StartCalendarInterval key, which describes the repeating schedule for the script. StartCalendarInterval is either a single dictionary or an array of dictionaries. Each dictionary can have any combination of the keys Hour, Minute, Day, Weekday, and Month. In this example, the job will run whenever the hour is 5 and the minute is 15. Since the keys Day, Weekday, and Month aren't specified, the job will run every day of every month. The only key that might be non-obvious is Weekday. This takes an integer from 0 to 7, and both 0 and 7 correspond to Sunday.

It's possible to replicate almost all of the scheduling possibilities that cron offers, though the launchd plist version will be much more verbose. You can specify multiple calendar intervals by setting the StartCalendarInterval value to an array of dictionaries, like this:

<key>StartCalendarInterval</key>
<array>
   <dict>
      <key>Hour</key>
      <integer>3</integer>
      <key>Minute</key>
      <integer>15</integer>
   </dict>
   <dict>
      <key>Hour</key>
      <integer>10</integer>
      <key>Minute</key>
      <integer>30</integer>
   </dict>
</array>

This StartCalendarInterval would cause the job to be run at 3:15 AM and 10:30 AM.

The other launchd key that is of interest in scheduling repeating jobs is StartInterval. The value for this key is an integer representing the number of seconds between job runs. The following example causes the job to be run every five minutes:

<key>StartInterval</key>
<integer>300</integer>

Variation: Run a script at startup and on a schedule

If you have a script you'd like to run at startup and also on a regular schedule - for example, a script that uploads asset information about the current machine - you can add both a StartCalendarInterval and a RunAtLoad key to the launchd plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>  
   <key>Label</key>
   <string>org.myorg.assetinfoupload</string>
   <key>ProgramArguments</key>
   <array> 
      <string>/usr/local/scripts/asset_info_update</string>
   </array>
   <key>StartCalendarInterval</key>
   <dict>  
      <key>Hour</key>
      <integer>12</integer>
      <key>Minute</key>
      <integer>15</integer>
   </dict>
   <key>RunAtLoad</key>
   <true/>
</dict>
</plist>

Recipe 3: Run a script on filesystem change

Launchd can run a job when a file or directory changes. There are two relevant keys: WatchPaths, which takes an array of strings, each of which is a path to a file or a directory, and QueueDirectories, which also takes an array of strings, but these must point to directories only.

When using WatchPaths, any change to the path triggers the job. In the case of a file, touching the file or changing its contents will cause the launchd job to run. With directories, adding or removing files will start the job.

QueueDirectories are monitored a bit differently. If a QueueDirectory is not empty, your job will be started. If your job quits and the directory is still not empty, your job will be started again. The idea here is a script or program that is started when items appear in a directory, processes each one, and removes each item from the directory as it goes. This acts much like a mail queue or print queue. Prior to launchd, systems administrators would often implement a cron job that ran every minute or so and checked the directory to see if anything had been added. With launchd, you can just let launchd notify you if something appears in the directory.

A WatchPaths example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>org.myorg.sudoers-check</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/logger</string>
    <string>/etc/sudoers was changed!</string>
  </array>
  <key>WatchPaths</key>
  <array>
    <string>/etc/sudoers</string>
  </array>
</dict>
</plist>

This launchd job watches the /etc/sudoers file and writes a message to the log if it changes. If you were really interested in being notified when the sudoers file changed, you'd probably want to use a mechanism that sent email or posted data to a database or via a web CGI.

Recipe 4: Allow a non-admin to run a script as root

Sometimes there is a need to allow a standard user to run a command or script that only works properly when run as root. Building on Recipe 3, we can use launchd to enable this. By default, jobs run by launchd LaunchDaemons run as root. (LaunchAgents are a different matter.) If we set up launchd to run our script when a file changes, and that file is changeable by a standard user, then the user can run the script by changing the file.

This recipe requires some additional ingredients. We need a file that the user can change but not accidentally remove, since launchd's behavior is - shall we say - inconsistent if the WatchPath disappears. One way to do this is to create a directory that is readable by everyone, but writeable only by root:

mkdir /Library/Management/Triggers
sudo chown root /Library/Management/Triggers
sudo chmod 755 /Library/Management/Triggers

Within this directory, create a file to use as the trigger, but make it world-writable:

sudo touch /Library/Management/Triggers/softwareupdate
sudo chmod 666 /Library/Management/Triggers/softwareupdate

Now any user may change the softwareupdate file, but only root can remove it. Our launchd plist can now specify our trigger file as an item in the WatchPaths array:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>org.myorg.softwareupdate</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/sbin/softwareupdate</string>
    <string>--install</string>
      <string>--all</string>
  </array>
  <key>WatchPaths</key>
  <array>
    <string>/Library/Management/Triggers/softwareupdate </string>
  </array>
</dict>
</plist>

This launchd plist watches the trigger file. When it changes, it runs:

softwareupdate --install --all

We need one more ingredient - a way for the user to easily modify the file. You could tell the user to open a Terminal window and type "touch /Library/Management/Triggers/softwareupdate", but they'd look at you like you're insane. So let's do something a little more "Mac-like". This could simply be an AppleScript applet that touches the file:

display dialog "Do you want to run Software Update and install all available updates?" buttons {"No", "Yes"} default button "Yes"
if button returned of result is "Yes" then
   do shell script "touch /Library/Management/Triggers/softwareupdate"
end if

When compiled and run the AppleScript presents the dialog in Figure 1.


Figure 1 - A GUI to trigger softwareupdate as root

If the user clicks Yes, the AppleScript touches our trigger file. launchd notices the change, and runs softwareupdate as root.

This example would need a lot more fleshing out before I'd consider deploying it to real users. Instead of directly calling softwareupdate, you'd probably want to write a script that called softwareupdate, provided progress feedback to the user, and handled the case where a restart is needed after updates are installed. The launchd job could then call that script. Still, the basic idea is there: a method to allow a non-privileged user to run a process as root.

Hungry for more recipes?

There are at least a few more things systems administrators might want to do with launchd. Some examples:

Run a script (or an application) when any user logs in.

Run a script when the loginwindow loads.

Run a script when a volume is mounted.

I hope to have some recipes for these and more, and maybe cover some new Snow Leopard features in a future MacEnterprise column. Until then, you can find more info here:

"Getting Started with launchd" - hhttp://developer.apple.com/macosx/launchd.html

"Creating launchd daemons and agents" -

http://developer.apple.com/documentation/MacOSX/Conceptual/BPSystemStartup/Articles/LaunchOnDemandDaemons.html

"Launchd in depth" - http://www.afp548.com/article.php?story=20050620071558293 (This one is a few years old; written when Tiger was new - but has a good example of WatchPaths and a quick introduction to launchctl.)

And of course, read the man pages for launchd, launchd.plist, and launchctl!


Greg Neagle is a member of the steering committee of the Mac OS X Enterprise Project (macenterprise.org) and is a senior systems engineer at a large animation studio. Greg has been working with the Mac since 1984, and with OS X since its release. He can be reached at gregneagle@mac.com.

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

FotoMagico 6.2.2 - Powerful slideshow cr...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Default Folder X 5.7 - Enhances Open and...
Default Folder X attaches a toolbar to the right side of the Open and Save dialogs in any OS X-native application. The toolbar gives you fast access to various folders and commands. You just click on... Read more
f.lux 42.1 - Adjusts the color of your d...
f.lux makes the color of your computer's display adapt to the time of day, warm at night and like sunlight during the day. Ever notice how people texting at night have that eerie blue glow? Or wake... Read more
Spotify 1.1.94.872 - Stream music, creat...
Spotify is a streaming music service that gives you on-demand access to millions of songs. Whether you like driving rock, silky R&B, or grandiose classical music, Spotify's massive catalogue puts... Read more
Vitamin-R 4.15 - Personal productivity t...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
OfficeTime 2.0.628 - Easy time and expen...
OfficeTime is time and expense tracking that is easy, elegant and focused. Other time keepers are clumsy or oversimplified. OfficeTime balances features and ease of use, allowing you to easily track... Read more
Slack 4.28.182 - Collaborative communica...
Slack brings team communication and collaboration into one place so you can get more work done, whether you belong to a large enterprise or a small business. Check off your to-do list and move your... Read more
DEVONthink Pro 3.8.6 - Knowledge base, i...
DEVONthink is DEVONtechnologies' document and information management solution. It supports a large variety of file formats and stores them in a database enhanced by artificial intelligence (AI). Many... Read more
FileMaker Pro 19.5.4 - Quickly build cus...
FileMaker Pro is the tool you use to create a custom app. You also use FileMaker Pro to access your app on a computer. Start by importing data from a spreadsheet or using a built-in Starter app to... Read more
Backblaze 8.5.0.628 - Online backup serv...
Backblaze is an online backup service designed from the ground-up for the Mac. With unlimited storage available for $6 per month, as well as a free 15-day trial, peace of mind is within reach with... Read more

Latest Forum Discussions

See All

SwitchArcade Round-Up: Reviews Featuring...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 26th, 2022. In today’s article, we kick off the week with a bang. And by “bang", I mean four reviews. Family Man, Radiant Silvergun, The Legend of Heroes: Trails from Zero... | Read more »
‘Romancing SaGa: Minstrel Song Remastere...
Following its showing at TGS 2022, Square Enix has released a new gameplay trailer for the previously announced remaster of the PS2 remake of the Super Famicom original (yes) Romancing SaGa game, Romancing SaGa: Minstrel Song Remastered. | Read more »
Gamabilis reveal release date for realis...
Realistic Sims are very fun experiences and give gamers an excellent chance to experience other walks of life, and Gamabilis has released its hyper-real farm management game Roots of Tomorrow. Whilst the more arcade-type games like Stardew Valley... | Read more »
Best iPhone Game Updates: ‘Streets of Ra...
Hello everyone, and welcome to the week! It’s time once again for our look back at the noteworthy updates of the last seven days. We’ve got a nice mix of Apple Arcade, free-to-play, and even a proper paid game. We don’t see those often! So yes, a... | Read more »
The House of Da Vinci 3 launches on Andr...
Following its earlier release on iOS this year, The House of Da Vinci 3 has also officially launched on Android devices. Blue Brain Games' 3D puzzle adventure boasts an average rating of 4.9/5 and will give players the much-awaited conclusion to... | Read more »
‘Oxenfree: Netflix Edition’ Is Out Now o...
Over the weekend, Netflix and Nightschool Studio announced and released Oxenfree: Netflix Edition (Free) worldwide on iOS and Android. This new version of Oxenfree: Netflix Edition is a separate release, and the prior version that I own, is no... | Read more »
‘Genshin Impact’ Version 3.1 Update Pre-...
Genshin Impact (Free) version 3.1 ‘King Deshret and the Three Magi’ goes live in a few days across iOS, Android, PC, PS5, and PS4. As with prior updates, pre-installation for the upcate has just gone live a few days before release. | Read more »
We’re Digging ‘Shovel Knight Dig’ – The...
We spend the bulk of this week’s podcast talking about the new iPhone 14. Specifically, the iPhone 14 Pro Max which both Eli and myself picked up. The consensus seems to be: They’re great! They’re iPhones! We do lay down our hot takes on all the new... | Read more »
TouchArcade Game of the Week: ‘Loose Noz...
There aren’t a lot of stories like that of the development of Loose Nozzles, and of those games that do have an interesting development story, even fewer are actually decent games to play. Loose Nozzles nails both, though. The way it was created is... | Read more »
SwitchArcade Round-Up: ‘Shovel Knight Di...
Hello gentle readers, and welcome to the SwitchArcade Round-Up for September 23rd, 2022. In today’s article, we’ve got the rest of this week’s releases to look at. There are actually a few big games today, including the hot-hot-hot Shovel Knight Dig... | Read more »

Price Scanner via MacPrices.net

13-inch Apple MacBook Airs with M2 processors...
Amazon has 13″ MacBook Airs with M2 CPUs in stock today and on sale for $1099. Shipping is free. Their prices are $100 off Apple’s MSRP, and they are the lowest prices available for M2-powered Macs... Read more
AR Glasses That Work With Apple’s Hardware? T...
NEWS – Lenovo has created quite the spectacle(s) with its latest product. “Apple Glass” — the purported name of Apple’s forthcoming AR glasses — is not expected to be released until 2025 (at the... Read more
New today at Apple: 13-inch M2 MacBook Pros f...
Apple 13″ MacBook Pros with M2 CPUs in stock and available today starting at $1169, Certified Refurbished, and ranging up to $150 off original MSRP. These are the cheapest 13″ M2 MacBook Pros for... Read more
Sunday Sale: 13″ Apple M1 MacBook Air availab...
Amazon has Space Gray Apple 13″ M1 MacBook Airs on sale for $690.95 for an extremely limited time. Other models are on sale for $849. Their price for the Space Gray model is the cheapest we’ve ever... Read more
Use our exclusive Apple Price Trackers to fin...
Our Apple award-winning price trackers are the best place to look for the lowest prices and latest sales on all the latest Apple gear this season. Scan our price trackers for the latest information... Read more
New promo at Verizon: Get Apple Watch Series...
Purchase a new iPhone 14 at Verizon, and get an Apple Watch Series 8 for as low as $5 per month. $120 in promo credits for the Watch are spread over a 36 month term, reducing the price of the Watch... Read more
Visible drops prices on Apple iPhone 13 model...
Verizon’s low-cost wireless cell service, Visible has dropped prices on iPhone 13 models to new low prices starting at $599: – iPhone 13 Pro Max: starting at $980 + free $200 gift card – iPhone 13... Read more
Back in stock! 14″ MacBook Pros with Apple M1...
Amazon has restocked 14″ MacBook Pros M1 Pro CPUs for $400 off MSRP, starting at only $1599. Shipping is free. Be sure to make your purchase from Amazon rather than a third-party seller. Their prices... Read more
This is the final week to take advantage of A...
Apple’s Back to School promotion for 2022 ends on September 26, 2022. As part of this promotion, Apple will include a free $150 Apple Gift Card with the purchase of any MacBook Air, MacBook Pro, or... Read more
Mac Studio with M1 Max CPU back in stock toda...
Apple has the base standard-configuration Mac Studio available again in their Certified Refurbished section for $1799, and it’s in stock today. Each Mac Studio comes with Apple’s one-year warranty,... Read more

Jobs Board

Physician Assistant, Primary Care, *Apple*...
Physician Assistant, Primary Care, Apple Valley (1.07FTE) + Job ID: 65766 + Department: AV Primary Care + City: Apple Valley, MN + Location: HP - Apple Read more
Operations Manager - Mac/ *Apple* Engineerin...
…Responsible for the day-to-day activities relating to the engineering of Apple Macs in a complex, multi-platform environment. Demonstrates strong leadership, Read more
Lead Developer - *Apple* tvOS - Rumble (Uni...
…earnings, and positive sentiment About the role: We are looking for a Lead Apple tvOS Developer to join our application engineering team to expand our video centric Read more
Systems Administrator - *Apple* Devices / J...
…Administration **Duties and Responsibilities** + Configure and maintain the client's Apple Device Management (ADM) solution. The current solution is JAMF supporting Read more
Sr Product Manager, *Apple* TV Platforms -...
…an experienced senior product manager to drive the strategy and requirements for our Apple TV devices, acting as the champion and owner of the holistic experience in Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.