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

MacEnterprise: Snow Leopard, launchd, and Lunch

More launchd recipes, and a look at changes in Snow Leopard

By Greg Neagle, MacEnterprise.org

In a prior column, we looked at some "recipes" for using launchd for systems administration tasks. The recipes showed how to use launchd to run a script at system startup, on a repeating schedule, and when a filesystem item changed. Finally, we explored a way to use launchd to allow a non-admin to run a script with root permissions.

I promised a few more launchd recipes. We'll get to those, but first, with the release of Snow Leopard, let's look at some of the changes to launchd in OS X 10.6.

There were several major changes in launchd from 10.4 to 10.5. Among these were the more powerful KeepAlive options, and the new LimitLoadToSessionType key, which enabled LaunchAgents to load only in specific contexts, like at the loginwindow, or only during SSH logins. The changes in 10.6 are a bit more subtle, and some of the changes are probably of more interest to software developers than systems administrators.

Launchd plists gain a new optional key: EnableTransactions, which is a Boolean value. If this is set to true, it means the daemon will use the vproc_transaction_begin and vproc_transaction_end system calls to mark outstanding transactions that must be handled before the daemon can be safely terminated. This is an element of the new "faster shutdown" feature of Snow Leopard - if there are no outstanding transactions, launchd will send a SIGKILL signal to the process instead of SIGTERM.

Launchd contexts are now unified between GUI logins and command-line logins: for example, you can copy some text in TextEdit, then ssh into the machine as the same user and do a pbpaste, retrieving the copied text. This wasn't possible before.

There are more restrictions on what root can do to a user session. Apple strongly recommends that if you want a process to run as a specific user, with that user's environment, that you should make the process a launchd agent. Simply performing a setuid or calling su username to "become" a user is no longer recommended or officially supported.

The biggest change in Snow Leopard of interest to systems administrators is how launchd and launchctl handle the Disabled key in the launchd plist. Prior to 10.6, if you disabled a launchd job using launchctl like this:

launchctl unload -w /path/to/launchd.plist

The job would be unloaded, and the Disabled key in the launchd plist would be set to true, causing the job to be disabled. In Snow Leopard, the job is still marked as disabled, but the plist is not changed. The value of the Disabled key is stored elsewhere. The launchctl man page is vague about where it is stored, but it turns out to be in /private/var/db/launchd.db/.

Inside this directory, there are subdirectories like these:

aquaman:launchd.db root# ls -1 
com.apple.launchd
com.apple.launchd.peruser.0
com.apple.launchd.peruser.100
com.apple.launchd.peruser.212
com.apple.launchd.peruser.501
com.apple.launchd.peruser.97

The com.apple.launchd directory holds info for LaunchDaemons, the com.apple.launchd.peruser.* directories hold info for LaunchAgents. Let's look a little deeper:

aquaman:launchd.db root# cd com.apple.launchd
aquaman:com.apple.launchd root# ls
overrides.plist

Let's examine the contents of overrides.plist:

aquaman:com.apple.launchd root# cat overrides.plist 
<?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>com.apple.backupd-attach</key>
   <dict>
      <key>Disabled</key>
      <true/>
   </dict>
   <key>com.apple.backupd-auto</key>
   <dict>
      <key>Disabled</key>
      <true/>
   </dict>

...and so on. So we see that the current state of the Disabled keys for LaunchDaemons is stored in /var/db/launchd.db/com.apple.launchd/overrides.plist.

Since each user now has a separate directory under /var/db/launchd.db/, LaunchAgents can now be enabled/disabled on a per-user basis. In other words, a LaunchAgent located in /System/Library/LaunchAgents/ or /Library/LaunchAgents/ can now be disabled for a single user. For example, I could disable the WacomTabletDriver for only my login:

[aquaman:~] gneagle% launchctl unload -w -S Aqua /Library/LaunchAgents/com.wacom.wacomtablet.plist
[aquaman:~] gneagle% cd /var/db/launchd.db/com.apple.launchd.peruser.4389/
[aquaman:~] gneagle% cat overrides.plist 
<?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>com.wacom.wacomtablet</key>
   <dict>
      <key>Disabled</key>
      <true/>
   </dict>
</dict>
</plist>

The result is that when I log in, the WacomTabletDriver process does not load, but if any other user logs in, the process will load. In prior versions of OS X, there was no way to enable/disable launchd jobs on a per-user basis - enabling or disabling a LaunchAgent in /System/Library/LaunchAgents or /Library/LaunchAgents affected all users of the machine. On the other hand, it is now possible for non-admins to turn off LaunchAgents that run in their context. This might be a problem if you rely on LaunchAgents to run at login and perform certain tasks for the user - the user can now turn these off.

This change may also make it more difficult for a systems administrator to determine the effective enabled/disabled state of a LaunchAgent; the administrator must first check the launchd job's plist to get the initial state of the Disabled key, then check /var/db/launchd.db for any overrides.

Finally, there is a new ServiceManagement framework to provide a supported API to get a list of launchd jobs, submit new jobs to launchd, and to securely install privileged helper tools. Documentation is scarce as of this writing; if you have Snow Leopard and Xcode installed, you can see some basic info in the ServiceManagement header file located at:

/System/Library/Frameworks/ServiceManagement.framework/Headers/ServiceManagement.h

Traditionally, framework APIs like this were mostly of interest to C coders and application developers. But with OS X's BridgeSupport, which allows Python and Ruby access to many OS X frameworks, Python and Ruby scripters can make use of these APIs.

That's a look at the launchd changes in Snow Leopard. Now let's get back to launchd recipes!

This recipe makes use of a launchd LaunchAgent. By default, these are loaded when a user logs into a GUI session, and run as the user. There are several third-party software items that install LaunchAgents to run a background process when a user logs in. Some examples include the Wacom Tablet software, which launches a driver process for the tablet at login, and Timbuktu, which loads the Timbuktu Host.app at login.

You can leverage this same technique to run your own scripts. Perhaps you've written a Setup Assistant for your organization that helps your users configure their mail accounts and so on when they first login. You'd like that assistant to launch automatically at login the first time the user logs in.

Your setup assistant application. For this recipe, it will be /Application/Utilities/MyOrg Setup Assistant.app. If you don't have a setup assistant application, but you do have a web page of setup instructions you'd like your users to follow, you can replace the path to the setup assistant app with an http URL like so: "http://www.myorg.com/help/firsttimeusers/"

A shell script that checks for the existence of a file, say ~/.com.myorg.setupassistant.done and if it doesn't exist, creates the file, then launches your assistant (or opens your web page). Here's an example script:

#!/bin/sh
FLAGFILE=".com.myorg.setupassistant.done"
SETUPASST="/Applications/Utilities/MyOrg Setup Assistant.app"
cd ~
if [ ! -f "$FLAGFILE" ] ; then
   touch "$FLAGFILE"
   open "$SETUPASST"
fi

This is basic shell scripting, nothing fancy here. We define a couple of variables, change to the current user's home directory, then check the existence of the flag file.

If the flag file is missing, we touch the flag file, which creates an empty file of that name, then we open the setup assistant.

We name the script "run_setupassistant.sh", save it someplace convenient, and make sure to mark it as executable:

chmod 755 /path/to/run_setupassistant.sh

A plist to get launchd to run the script at login. Here's one:

<?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>com.myorg.setupassistant</string>
   <key>Program</key>
   <string>/path/to/run_setupassistant.sh</string>
   <key>RunAtLoad</key>
   <true/>
</dict>
</plist>

We'll save this plist as /Library/LaunchAgents/com.myorg.setupassistant.plist, and make sure the owner and permissions are correct:

cd /Library/LaunchAgents 
sudo chown root:wheel com.myorg.setupassistant.plist
sudo chmod 644 com.myorg.setupassistant.plist

Once all the ingredients are in place, we can test by logging out and back in. If you did everything right, your application will launch, or your web page will open in your default browser. Log out and back in again to verify that the assistant doesn't launch on subsequent logins. Remove ~/.com.myorg.setupassistant.done (or whatever you've named your flag file) and log out and back in again, and your assistant should launch again.

(If you want to play with this example, but don't have a custom Setup Assistant handy, just change the script to open any application or URL you want.)

If you read my previous column on this subject, and you have a photographic memory, you might have noticed that I'm specifying the program to be run differently in this plist. In all of the prior recipes, I used the ProgramArguments key, like this:

  <key>ProgramArguments</key>
  <array>
    <string>/usr/sbin/softwareupdate</string>
    <string>-install</string>
      <string>-all</string>
  </array>

but in this recipe, I'm using the Program key:

   <key>Program</key>
  <string>/path/to/run_setupassistant.sh</string>

The Program key takes a single string; ProgramArguments takes an array of strings. You can use the Program key if you are specifying the path to an executable that needs no arguments passed to it. Otherwise, you should use the ProgramArguments key, with the first string in the array being the path to the executable, and subsequent strings each containing one argument. It's possible to use both keys in a plist, but since you'd have to specify the executable path in both keys, it's pretty pointless. For my own use, I tend to stick with ProgramArguments, even if there are no arguments.

OS X 10.5 introduced the ability for launchd to run a job at the loginwindow. To do this, you need a special type of LaunchAgent.

For this recipe, we're going to change the image behind the loginwindow to a randomly selected image at each login. Here's the script:

#!/usr/bin/perl -w
use strict;
my $loginwindowprefs = "/Library/Preferences/com.apple.loginwindow";
my $picdir = "/Library/Desktop Pictures/Nature";
if ( -d "$picdir") {
   my @list = split("\n",`ls -1 "$picdir"`);
   my @pictures = ();
   
   for my $item (@list) {
      if (-f "$picdir/$item") {
         push @pictures, "$picdir/$item";
      }
   }
   
   if (scalar(@pictures)) {
      my $currentpicture = `/usr/bin/defaults read $loginwindowprefs DesktopPicture`;
      if ($currentpicture) { chomp($currentpicture) };
      my $randompicture = $currentpicture;
   
      while ($randompicture eq $currentpicture) {
         my $randomindex = int(rand(scalar(@pictures)));
         $randompicture = $pictures[$randomindex];
      }
   
      my $result = `/usr/bin/defaults write $loginwindowprefs DesktopPicture "$randompicture"`;
   }
}

Sorry about the Perl! I wrote this years ago - it would probably be more readable written in Python, but it gets the job done. Here's what the script does:

Gets a list of all the pictures in $picdir and puts them into the @pictures array.

Gets the path to the current DesktopPicture (the one behind the loginwindow) by calling

defaults read /Library/Preferences/com.apple.loginwindow DesktopPicture

Picks a picture at random from the @pictures array.

If the picture chosen is the same as the current one, try again until we pick one that's different.

Set the loginwindow background by calling

defaults write /Library/Preferences/com.apple.loginwindow DesktopPicture /path/to/new/picture

Save the script as /Library/Scripts/loginwindowPictureChanger, and make sure it's executable.

<?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>com.myorg.loginwindowpictures</string>
  <key>LimitLoadToSessionType</key>
  <array>
    <string>LoginWindow</string>
  </array>
  <key>Program</key>
<string>/Library/Scripts/loginwindowPictureChanger</string>
  <key>RunAtLoad</key>
  <true/>
</dict>
</plist>

The new bit here is the LimitLoadToSessionType key. By setting this to LoginWindow, launchd loads the job when the loginwindow displays. We also set RunAtLoad key to true so the script runs immediately when the job is loaded.

Save the plist as /Library/LaunchAgents/com.myorg.loginwindowpictures.plist, ensuring owner, group, and permissions are correct. See the previous recipe if you forgot how.

The script will now run each time the loginwindow displays.

If you try this, don't be surprised if it doesn't seem to work the first time you log out. Since the loginwindow is already loaded when our script runs, changing the value of the DesktopPicture in the defaults has no effect until the next time the loginwindow is loaded. So we're really changing the DesktopPicture for the next time the loginwindow displays, not the current time.

Prior to 10.5, the only way you could use launchd to run a script when a volume was mounted was to define a WatchPath of "/Volumes". Your job would be launched on any change to /Volumes, which included volumes mounting and unmounting. And if a file system got mounted anywhere else other than /Volumes (not common, but possible), launchd would miss it. 10.5 added a new StartOnMount key which takes a Boolean value. This makes it much simpler to define a job that runs whenever a filesystem is mounted.

Possible uses for this include scanning for viruses on newly mounted filesystems, or doing an automatic backup of a specific directory anytime a specific FireWire or USB disk is mounted. I'll leave that part up to you.

Here's an example plist that runs /path/to/my_diskmount_script.sh whenever a filesystem is mounted.

<?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>com.myorg.diskmountscript</string>
   <key>Program</key>
   <string>/path/to/my_diskmount_script.sh</string>
   <key>StartOnMount</key>
   <true/>
</dict>
</plist>

If you wanted it to run as root (for example, if was a virus scanner), you could make it a LaunchDaemon and put the plist in /Library/LaunchDaemons. If you wanted it to run as a user, you'd make it a LaunchAgent by putting it in /Library/LaunchAgents. If you implement the idea of an automatic backup script, you might want it to run only for a specific user (like you). In that case, you'd put the plist in your home directory:

~/Library/LaunchAgents/com.myorg.diskmountscript.plist

...which would cause it to load only when you logged in.

In two columns, we've looked at seven launchd recipes for common systems administrations tasks. We haven't exhausted every way a systems administrator could use launchd, but we have covered most of the common uses.

If you want even more info on some of the things we've covered here, check out these resources:

Apple Technical Note TN2083: Daemons and Agents

http://developer.apple.com/technotes/tn2005/tn2083.html

An in-depth tech note describing various techniques and issues when working with system daemons and user agents.

MacResearch: Tutorial: Backups with Launchd

http://www.macresearch.org/tutorial_backups_with_launchd

An example of using launchd to run an automatic backup when a disk in mounted. Written with 10.4's launchd in mind, but still contains useful information.

Launchd at Mac OS Forge:

http://launchd.macosforge.org/

http://launchd.macosforge.org/trac/wiki

Apple has released the launchd source code as open source, and it's available at Mac OS Forge. The site hasn't been updated in a while, but there are still some helpful tidbits and info from the launchd developers.

launchd-dev mailing list:

http://lists.macosforge.org/mailman/listinfo/launchd-dev

This list is supposed to be for the discussion of the development of launchd, but there are often "launchd-user" discussions on this list as well.

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.