Daemons

A daemon is a program that runs in the background as part of the overall system (that is, it is not tied to a particular user). A daemon cannot display any GUI; more specifically, it is not allowed to connect to the window server. A web server is the perfect example of a daemon.

Historically, Mac OS X had a number of different ways to start daemons (for details, see Deprecated Daemonomicon). On current systems there is only one recommend way: launchd.

A launchd daemon is configured by a sophisticated property list file. This file allows the daemon to be launched based on a variety of criteria (connections to listening sockets, items being modified in the file system, periodically, and so on). For details, see the launchd.plist man page.

A third party launchd daemon should be installed by adding a property list file to the /Library/LaunchDaemons directory.

It is important to realize that not all launchd daemons interact with launchd in the same way. The single unifying feature of all launchd daemons is the property list file. This tells launchd how to interact with the daemon. For example:

• A launchd-aware launchd daemon is typically launched on demand and must explicitly check in with launchd. For an example of this, see Sample Code 'SampleD'.

• If you have a daemon that was previously launched via inetd (or xinetd), you can run it from launchd by creating a property list file with the inetdCompatibility property set appropriately. This results in an inetd-compatible launchd daemon. For an example of this, check out /System/Library/LaunchDaemons/finger.plist.

• Virtually any program can be run as a launchd daemon by creating a minimal property list file with the OnDemand property set to false.

Keep in mind that, regardless of how it interacts with launchd, a launchd daemon must not daemonize itself; doing so would undermine launchd's ability to monitor the daemon.

For more information about launchd daemons, read the launchd documentation.

Agents

An agent is a process that runs in the background on behalf of a particular user. Agents are useful because they can do things that daemons can't, like reliably access the user's home directory or connect to the window server. A calendar monitoring program is a good example of an agent because:

• there should be an instance of the program per GUI login session

• each agent has access to that user's calendar

• the agent can launch the calendar application when certain events occur

The difference between an agent and a daemon is that an agent can display GUI if it wants to, while a daemon can't. The difference between an agent and a regular application is that an agent typically displays no GUI (or a very limited GUI).

Agents have acquired a variety of different names over the years. These include background-only applications (BOAs), faceless background-only applications (FBAs), and UI elements (implying that the agent displays some GUI, but is not a full blown application with a menu bar). These names are more-or-less irrelevant to this discussion. What is relevant, and what distinguishes different types of agents, is how the agent is launched.

Ancient Daemons (and Agents)

For information about older ways to launch daemons and agents, see Deprecated Daemonomicon.

UIDs and GIDs

A process's UIDs (its effective (EUID), real (RUID), and saved (SUID) UIDs) are the most well known elements of the process's context. These UIDs control various capabilities of the process, mostly centered on the BSD portions of the system (file system, networking, BSD process control). For example, a process's ability to open a file is controlled by its EUID, and its ability to signal another process is controlled by its EUID and the EUID and RUID of the target.

Processes also have a set of group IDs (GIDs) that are analogous to the UIDs, plus a list of supplemental group IDs.

For more information about these UIDs and GIDs, and how they affect the capabilities of your process, see Security Overview.

Mach Bootstrap Basics

Many Mac OS X subsystems work by exchanging Mach messages with a central service. For such a subsystem to work, it must be able to find the service. This is typically done using the Mach bootstrap service, which allows a process to look up a service by name. All processes inherit a reference to the bootstrap service from their parent.

To get an idea of how this works, you can run launchctl with the bslist argument. This lists all of the services registered with the bootstrap service. Listing 1 shows an example of its output.

Listing 1  BootstrapDump from Terminal

$ launchctl bslist
D  com.apple.rcd
A  com.apple.finder.ServiceProvider
A  com.apple.systemuiserver.ServiceProvider
A  com.apple.systemuiserver-ServicesPortName
A  com.apple.dockling.server
A  com.apple.SUISMessaging
A  com.apple.ipodserver
A  com.apple.dock.server
D  BezelUI
D  edu.mit.Kerberos.KerberosAgent.ipcService
[...]

As you can see, there are numerous services published via the bootstrap service. Virtually all of them are private. For example, you are not expected to send messages directly to the "com.apple.dock.server" service; rather, you would call a routine exported by a framework (perhaps SetApplicationDockTileImage) and, behind the scenes, it exchanges messages with the service to do the job you requested.

$ sudo BootstrapDump MAP
Password:********
0x0
  launchd (root, 1/0)
  launchd (quinn, 82/1)
0x30b
  kextd (root, 7/1)
  DirectoryService (root, 8/1)
  notifyd (root, 9/1)
  configd (root, 10/1)
  [...]
  0x10f
    0x100b
      sshd (root, 443/1)
      sshd (quinn, 447/443)
      bash (quinn, 449/447)
      BootstrapDump (root, 477/449)
    0x20b
      loginwindow (root, 24/1)
      ARDAgent (root, 92/82)
      Spotlight (quinn, 94/82)
      UserEventAgent (quinn, 95/82)
      Dock (quinn, 97/82)
      AppleVNCServer (root, 98/92)
      pboard (quinn, 99/82)
      SystemUIServer (quinn, 100/82)
      Finder (quinn, 101/82)
      ATSServer (quinn, 102/82)

$ # The killall goop in the following command is a sneaky way 
$ # to get the process ID for a process name.
$ #
$ pid=`sudo killall -s kextd | cut -f 3 -d ' '`
$ sudo launchctl bslist $pid
[...]
A  com.apple.KernelExtensionServer
D  com.apple.KerberosAutoConfig
D  com.apple.java.updateSharingD
D  com.apple.installdb.system
D  com.apple.IIDCAssistant
D  com.apple.system.hdiejectd
D  com.apple.gssd
A  com.apple.FSEvents
[...]
$ sudo launchctl bslist $pid | grep dock
$ # No results because Dock is not registered in the global namespace.

Namespace Exploration

All of this might seem a little theoretical, and you're probably wondering how it affects you. Let's make things crystal clear by looking at a concrete example of how bootstrap namespaces affect application functionality.

1. Launch Activity Monitor (in /Applications/Utilities) from the Finder.

2. If it's not currently showing its main window, choose Activity Monitor from the Window menu to reveal that window.

3. Configuring it to show a CPU usage meter in its dock icon by choosing Show CPU Usage from the Dock Icon submenu of the View menu. You'll note that the Dock icon now displays a up-to-date representation of the CPU usage, and that the Dock menu works correctly. Figure 1 shows what I'm talking about.

4. Now quit Activity Monitor.

5. Next, open a Terminal window and SSH to yourself, as shown in Listing 4.

   
   
   

   Listing 4  Connecting to yourself via ssh

   $ ssh localhost Password:******** Last login: Fri Sep 30 10:07:59 2005 Welcome to Darwin! $

   When you log in via ssh, the system creates a new per-session bootstrap namespace for your session. So, anything you execute in this Terminal window is running in a different per-session bootstrap namespace from the GUI applications that you're running.

6. Now run Activity Monitor from this Terminal window, as shown in Listing 5.

   
   
   

   Listing 5  Running Activity Monitor from within SSH login session

   $ /Applications/Utilities/Activity\ Monitor.app/Contents/MacOS/Activity\ Monitor

   Figure 2 shows what you get. You'll notice two anomalous things:

   • The Dock tile CPU meter is not displayed.

   • If you control click on the Dock tile, the contextual menu contains an "Application Not Responding" item.

   These problems occur because the application is running in a different per-session bootstrap namespace, and is unable to look up the services that it needs to operate correctly (for example, "com.apple.dock.server").

Window Server

The window server (on Mac OS X 10.5 this is /System/Library/Frameworks/ApplicationServices.framework/Frameworks/CoreGraphics.framework/Resources/WindowServer) is a single point of contact for all applications. It is central to the implementation of the GUI frameworks (AppKit and HIToolbox) and many other services (for example, Process Manager).

Most of the services provided by the window server are implemented using Mach messages. Thus, to use the window server reliably, you must inherit a reference to a valid GUI per-session bootstrap namespace. This is an expected consequence of the rules given earlier.

What's unexpected, however, is that applications do work (somewhat) if you run them from outside of a GUI login session (that is, if they inherit a reference to the global bootstrap namespace, or some other non-GUI bootstrap namespace). This is because the window server advertises its services in the global bootstrap namespace! This is known as the global window server service.

The reasons for this non-obvious behavior are lost in the depths of history. However, the fact that this works at all is pretty much irrelevant because there are important caveats that prevent it from being truly useful. The following sections describe these caveats in detail.

$ ssh ${USER}@localhost
Password:********
Last login: Wed Jun 20 11:49:23 2007
$ id
uid=502(quinn) gid=20(staff) groups=20(staff),81(_appserveradm),
104(com.apple.sharepoint.group.1),79(_appserverusr),80(admin),
101(com.apple.access_remote_ae),103(com.apple.access_ssh-disabled)
$ ls -l /dev/console
crw------- 1 quinn  staff    0,   0 Jun 20 11:50 /dev/console
$ # Launch Activity Monitor and then quit it.
$ /Applications/Utilities/Activity\ Monitor.app/Contents/MacOS/\
Activity\ Monitor 
$ logout
Connection to localhost closed.
$ ssh mrgumby@localhost
Password:********
Last login: Wed Jun 20 11:49:23 2007
$ id
uid=503(mrgumby) gid=20(staff) groups=20(staff),105(com.apple.sharepoint.group.2),
104(com.apple.sharepoint.group.1)
$ ls -l /dev/console 
crw------- 1 quinn  quinn    0,   0 Oct  3 21:31 /dev/console
$ # Activity Monitor fails to launch at all.
$ /Applications/Utilities/ctivity\ Monitor.app/Contents/MacOS/Act
_RegisterApplication(), FAILED TO establish the default connection to \
the WindowServer, _CGSDefaultConnection() is NULL.
2007-06-20 11:54:31.798 Activity Monitor[863:10b] An uncaught exception 
was raised
[...]
Trace/BPT trap
$ logout
Connection to localhost closed.

#include <assert.h>
#include <stdio.h>
#include <stdlib.h>

#include <Carbon/Carbon.h>

static OSStatus EventHandlerProc(
    EventHandlerCallRef inHandlerCallRef, 
    EventRef            inEvent, 
    void *              inUserData)
{
    fprintf(stderr, "  Switch\n");
    return noErr;
}

int main(int argc, char **argv)
{
    static const EventTypeSpec kEvents[] = { 
        { kEventClassApplication, kEventAppFrontSwitched} 
    };
    OSStatus err;

    err = InstallEventHandler(
        GetApplicationEventTarget(), 
        NewEventHandlerUPP( EventHandlerProc ), 
        sizeof(kEvents) / sizeof(kEvents[0]), 
        kEvents, 
        NULL, 
        NULL
    );
    assert(err == noErr);

    while (true) {
        fprintf(stderr, "Running runloop\n");
        RunApplicationEventLoop();
    }

    return EXIT_SUCCESS;
}

$ ssh victim.local. Password:******** Last login: Thu Jun 21 09:05:00 2007 victim$ ./AppSwitchMonitor  Running runloop   Switch   Switch   Switch Running runloop Killed victim$ echo $? 137

Untrusted apps are not allowed to connect to or launch Window Server before login.

Security Context

The security context is another piece of execution context associated with a process. The security context is explicitly managed by the Mac OS X security server (securityd). The security context almost always follows the bootstrap namespace: that is, there is a single global security context (also known as the root security context), per-user security contexts (for per-user launchd agents), and a per-session security context for each login session.

In most cases the security context is not directly relevant to your program; more often than not, the bootstrap namespace is the thing that trips you up.

On the other hand, the security context has one nice attribute: you can get useful information about the context using the SessionGetInfo routine (from <Security/AuthSession.h>). This routine return two useful pieces of information.

The first is the session identifier, a 32-bit number that uniquely identifies this session. This can be helpful in a number of places. For example, if you want to create a shared memory object (perhaps using shm_open) whose scope is limited to processes running within a particular login session, you can fold the session identifier into the object's name. Thus, two shared memory objects from different session won't collide in the shared memory object namespace, and client processes within the login session can easily find the correct shared memory object.

Additionally, SessionGetInfo returns a set of flags that describe the current security context. These are:

• sessionIsRoot — set if this is the global security context

• sessionHasGraphicAccess — set if programs running in this context can access the window server

• sessionHasTTY — set if programs running in this context can access the terminal (/dev/tty)

• sessionIsRemote — set if this context is the being run over the network

Execution Context Summary

Table 2 shows how the execution context of your daemon or agent is affected by the mechanism used to launch it.

Notes:

1. Configured using the UserName property in the property list file; defaults to root if the attribute is not specified.

2. Uses the global bootstrap namespace unless the SessionCreate property is specified in the property list file, in which case the daemon runs in its own per-session bootstrap namespace.

3. Uses the global security context unless the SessionCreate property is specified in the property list file, in which case the daemon runs in its own per-session security context.

4. Prior to Mac OS X 10.5 there was no way to control the target session type of a launchd agent; launchd agents were executed per-user in an unpredictable context. See Agents for details.

5. Once the user has logged in, this pre-login bootstrap namespace and security context become the bootstrap namespace and security context of the logged in user's login session.

Execution Context Example

Figure 3 is graphical example of this information. Each box is a process. The text after the process name is either the UID of that process (text in round brackets) or a note that you can look up below (text in square brackets) or both. A directed line represents the parent/child relationship between two processes. Each blue box represents a per-user bootstrap namespace. Each red box represents a per-session bootstrap namespace. Items that aren't in any shaded box are in the global bootstrap namespace. There are two GUI login sessions (user A logged in first and then fast user switched to user B) and two non-GUI login session (user A and user C).

Notes:

1. WindowServer runs with an EUID of _windowserver (88) and an RUID of root (0).

2. loginwindow runs with an EUID of the logged in user and an RUID of root (0).

3. ftpd runs with an EUID of the logged in user and an RUID of root (0). Currently ftpd runs in the global security context, but this may change in future systems; it will then will act more like sshd, and create a per-user security context for each FTP session.

As you look at Figure 3, consider the various different types of process that it shows.

• There is a global instance of launchd (PID 1). There is also an instance of launchd for each user.

• There is a single instance of the WindowServer process that resides in the global security context. However, it knows about all GUI login sessions and can register its services in each of them.

• The first instance of loginwindow, the one associated with user A's login session, is a child of the global launchd. The second instance, created when user A fast user switched to user B, is a child of the window server.

• Each per-user instance of launchd manages the context for all of that user's login sessions.

• The pasteboard server (pboard) is a typical GUI launchd agent.

• StdIOAgent is a hypothetical non-GUI launchd agent. It's included to illustrate where this type of agent would appear in the diagram. Mac OS X does not currently install any non-GUI launchd agents by default.

• CCacheServer is a per-user launchd agent that maintains the Kerberos credentials cache for a specific user.

• The ReportCrash program is a GUI launchd agent with special values in its property list that tell launchd to run it in response to crashes.

• sshd is a launchd daemon with the SessionCreate property set, which means that it runs in its own bootstrap namespace. Once a user logs in, the launchd PAM session module (/usr/lib/pam/pam_launchd.so, as configured by /etc/pam.d/sshd) moves the bootstrap namespace to within the appropriate per-user bootstrap namespace.

• configd is a run-of-the-mill launchd daemon.

• ftpd is a launchd daemon that is launched when someone connects to the TCP port specified in its property list file.

Living Dangerously

If your daemon uses frameworks that aren't daemon-safe, you can run into a variety of problems.

• Some frameworks fail at load time. That is, the framework has an initialization routine that assumes it's running in a per-session context and fails if it's not.

  This problem is rare on current systems because most frameworks are initialized lazily.

• If the framework doesn't fail at load time, you may still encounter problems as you call various routines from that framework.

  • A routine might fail benignly. For example, the routine might fail silently, or print a message to stderr, or perhaps return a meaningful error code.

  • A routine might fail hostilely. For example, it's quite common for the GUI frameworks to call abort if they're run by a daemon!

  • A routine might work even though its framework is not officially daemon-safe.

  • A routine might behave differently depending on its input parameters. For example, an image decompression routine might work for some types of images and fail for others.

• The behavior of any given framework, and the routines within that framework, can change from release-to-release.

The upshot of this is that, if your daemon links with a framework that's not daemon-safe, you can't predict how it will behave in general. It might work on your machine, but fail on some other user's machine, or fail on a future system release, or fail for different input data. You are living dangerously!

If you must call a framework that's not daemon-safe from your daemon, you should start by filing a bug describing what you're doing and why. Apple will consider your input as it develops future system software.

Next, you should try to minimize the number of potentially unsafe routines that you call. This will reduce (but not eliminate) the compatible risk.

Finally, you should test your daemon on a wide variety of platforms. And make sure you test with the pre-release builds Mac OS X that are available via Apple's developer software seeding program.

Framework Cross Reference

Table 3 summarizes which frameworks are daemon-safe.

Notes:

1. This framework has been daemon-safe since at least Mac OS X 10.4. However, a previous version of this technote documented it as not being daemon safe.

2. This is not a framework that you would usually call yourself.

3. You should define the Java property java.awt.headless as true, which causes Java to throw an exception if you run code that connects to the window server. See Technical Q&A QA1328, 'Server Processes and the Dock'.

4. With restrictions; please write to Developer Technical Support (DTS) for the details.

5. Core Python functionality is daemon safe, but certain modules are not. Thus, depending on the modules you use, your Python program may not be daemon safe.

This table lists the frameworks as of Mac OS X 10.5. If a framework is not listed here, it is best to assume that it is not daemon-safe.

If you're interested in the status of a subframework, and that subframework is not listed here, you should look up the status of the framework's umbrella. For example, you can tell that the OSServices framework is safe because its umbrella framework, CoreServices, is safe.

If a framework is listed as safe, it will continue to be safe in future system releases. If a framework is listed as not being safe, it may become safe in future releases.

Is It Necessary?

When contemplating a background program, the first thing to consider is whether you need it at all. Background programs consume resources all the time (although you can minimize the resources they consume by launching on demand), so if you can avoid using one you'll be doing the user a favor. Also, a background program can make the system less robust because it introduces a common point of failure (in this respect, a daemon is worse than an agent, which is worse than no background program at all). On the other hand, using a background program is often better than using a convoluted mechanism for distributed state management.

If you've decided to implement a background program, you must then determine whether you need an agent or a daemon. The main reason for using a daemon is that you need to share some state between multiple processes in different login sessions. If you don't need this, consider using an agent.

The Perils of the Monolith

A common question we get in DTS is "How can I launch a GUI application from my daemon?" The answer is that you can't. This is a direct consequence of Mac OS X's layered architecture: a daemon can't launch a GUI application because the daemon is running in the wrong context. Even if it could choose which context to run the GUI application in, which would it choose? And what happens if the computer is sitting at the login window, which means there are no valid GUI contexts?

The correct solution to this problem is to split your program into multiple components, each specialized for a particular role. So, you might have a daemon for managing the global state and an agent operating on behalf of each of the logged in users. If the daemon needs the user to answer a question, it signals all the agents and the agents use local knowledge to decide what to do. For example, the agent might behave differently depending on whether it's running in a GUI or non-GUI login session, or whether the GUI session is active (that is, using the console in a fast user switched environment).

The nice thing about this approach is that it simplifies the daemon's state. The daemon just knows that it's expecting one of the agents to provide the answer to the question; it doesn't care how many agents there are, what type of login context they're running in, or how they go about interacting with the user.

The Client/Server Model

If you do split your program into multiple components, try to use the client/server model. Specifically, remember that clients connect to servers, and not the other way around. This might sound obvious, but it's easy to forget this point and find yourself in the weeds.

In this context, a server is the background program that contains the global state that's being shared, while the clients are the programs that want to access that state. The server might be an agent (if all of the clients run in the same login session), or it might be a daemon (if it handles clients from multiple login sessions, or it handles other daemons as clients); the key point is that there is a one-to-many relationship between the server and its clients.

In this design, the server should not try to discover or connect to the clients. Rather, the clients should connect to the server. This approach is a good match for the common inter-process communication (IPC) APIs. For example, if you're using UNIX domain sockets, it's easy for a daemon to listen on a single UNIX domain socket and have the clients connect to that socket. It's also easy for the server to handle a client disconnecting (either because it quit or because it died unexpectedly). If you do things the other way around, things start to get messy.

Mach Considered Harmful

The Mach APIs represent the lowest level interface to the kernel. As such, they are the most likely to change as the system evolves. Apple has consistently recommended that third party developers avoid them. This applies to daemons and agents as it does to everything else.

However, in the case of daemons and agents, Mach APIs are particularly troublesome because you have to worry about bootstrap namespaces. While it's possible—some would even claim easy—to manage bootstrap namespaces correctly, it's better to just avoid the problem altogether by avoiding Mach APIs.

Apple's general recommendation for avoiding the use of Mach APIs includes the advice that it's better to use high-level wrappers. For example, rather than send and receive Mach messages using Mach APIs directly, it's better to use the higher-level CFMessagePort API. This is good advice in general; but, if you're writing a daemon or agent, you will still run into bootstrap namespace problem. Under the covers, CFMessagePortCreateLocal registers the service with the bootstrap service, and CFMessagePortCreateRemote uses the bootstrap service to look up a registered service by name. So, even if you avoid using Mach messages directly, if you use an API that's layered on top of Mach messages, you still have to worry about bootstrap namespaces.

The high-level IPC APIs that are most likely to trip you up are:

• CFMessagePort — Within this API, all named message ports are implementing using the bootstrap service.

• Distributed Objects (DO) — Named DO connections (such as you would register using -[NSConnection registerName:]), are implemented using the bootstrap service.

• Apple events — Apple events are implemented in terms of Mach messages. While it is possible to use Apple events in a daemon (using the routines from <AE/AEMach.h>, it's still a tricky exercise.

Overall, it is easier to just avoid Mach messages entirely. Mac OS X provides numerous alternative IPC mechanisms. My personal favorite is UNIX domain sockets.

UNIX Domain Sockets Are Your Friend

UNIX domain sockets are somewhat like TCP/IP sockets, except that the communication is always local to the computer. You access UNIX domain sockets using the same BSD sockets API that you'd use for TCP/IP sockets. The primary difference is the address format. For TCP/IP sockets, the address structure (that which you pass to bind, connect, and so on) is (struct sockaddr_in), which contains an IP address and port number. For UNIX domain sockets, the address structure is (struct sockaddr_un), which contains a path.

When the server binds to a UNIX domain socket, the system creates a file system object that represents the socket. For example, the PPP daemon's UNIX domain socket is /var/run/pppconfd. When you look at this with ls -l (see Listing 10), you'll see the first character of the listing is 's', indicating that this object is a socket.

Listing 10  Looking at PPP's UNIX domain socket

$ ls -l /var/run/pppconfd  srwxrwxrwx  1 root  daemon  0  9 May 12:57 /var/run/pppconfd

Once the server is running, the client can connect to it by simply passing this path to the connect call. Once the connection is in place, communication proceeds as it would for TCP/IP sockets.

To learn more about UNIX domain sockets, consult any standard UNIX reference. I particularly recommend UNIX Network Programming by Stevens et al.

For an example of using UNIX domain sockets in a client/server environment, see Sample Code 'CFLocalServer'.

Cross Architecture IPC

Regardless of what IPC mechanism you use, you will have to deal with cross-architectural issues. For example, a given daemon may have clients that have a different:

• byte order (endianness) — The most common case of this is an Intel daemon with a PowerPC client (being run using Rosetta).

• pointer size — For example, a 32-bit daemon with 64-bit clients, or vice versa.

You must design your IPC mechanism to cope with these issues. Common strategy include:

• use a text-base protocol — For example, you might use a CFPropertyList that's been flattened to XML.

• define a byte order and stick to it — For example, you could require that all communications be in network byte order (big endian) and require little endian clients to swap the byte order.

• use native byte order and require compatibility code to swap

• include an indication of the byte order with the message (commonly called a byte order mark)

• don't pass pointers over the wire (doing so is a little strange anyway)

• when passing a size, define it in architecture neutral terms — For example, use uint32_t or uint64_t rather than size_t.

Alternatively, require that all clients be of the same architecture.

Launching On Demand

To minimize your use of system resources, it's best to launch your background program (daemon or agent) on demand. That is, rather than always launching at startup (or, for an agent, at login), your program only launches when its services are required.

The basic strategy for launching on demand is:

• You install a launchd configuration file that indicates the criteria under which you should be launched.

• launchd will read this file and waits for your launch criteria to be satisfied.

• When your launch criteria are satisfied, launchd starts your program, providing it some way to get information about the event that triggered the launch.

The launch criteria supported by launchd are listed in Table 4. See launchd.plist for the details.

Notes:

1. launchd will create a Mach port and register it in the appropriate bootstrap namespace. It launches your background program if any messages arrive on that port.

2. Typically this is either a TCP socket or a UNIX domain socket. Launching on demand based on a connection to a UNIX domain socket was not feasible until Mac OS X 10.4.6. Specifically, the SockPathMode property list key was not supported on PowerPC until Mac OS X 10.4.6 (r. 4252903) .

3. Typically this is a UDP socket.

By default launchd assumes that your background program wants to run on demand. This behavior is controlled by the KeepAlive property on Mac OS X 10.5 and later, and the now-deprecated OnDemand property on Mac OS X 10.4.x. Table 5 shows the more common behaviors, and the properties that you need to set in order to get that behavior.

As you can see, the KeepAlive property has a lot more flexibility than the OnDemand property that it replaces.

Daemons Accessing User State

It is not possible for a daemon to act on behalf of a user with 100% fidelity. While this might seem like a controversial statement, it's actually pretty easy to prove. For example, consider something as simple as accessing a preference file in the user's home directory. It's not possible for a daemon to reliably do this. If the user has an AFP home directory, or their home directory is protected by FileVault, the volume containing the home directory will only be mounted when the user is logged in. Moreover, it is not possible to mount the that volume without the user's security credentials (typically their password). So, if a daemon tries to get a user preference when the user is not logged in, it will fail.

In some cases it is helpful to impersonate the user, at least as far as the permissions checking done by the BSD subsystem of the kernel. A single-threaded daemon can do this using seteuid and setegid. These set the effective user and group ID of the process as a whole. This will cause problems if your daemon is using multiple threads to handle requests from different users. In that case you can set the effective user and group ID of a thread using pthread_setugid_np. This was introduced in Mac OS X 10.4.

Logging

In most cases you will want your background program to log information about its activity. These logs are useful during initial bring up, and can also help the user troubleshoot problems. Mac OS X supports a number of different logging facilities.

Daemon Security Considerations

By definition, a daemon is a system-wide service. Thus, when creating a daemon, you need to worry about security. While a detailed discussion of secure programming is outside the scope of this document, here's a short list of things that you should consider.

• If possible, create an agent rather than a daemon. This will limit the scope of any security problems.

• If your daemon uses the network, do not trust data you receive from the network. Doing so might allow a remote attacker to subvert your daemon.

• When you install your daemon, make sure that you set the file system permissions correctly. Apple recommends that daemons be owned by root, have an owning group of wheel, and use permissions 755 (rwxr-xr-x) for executables and directories, and 644 (rw-r--r--) for files. In addition, every directory from your daemon up to the root directory must be owned by root and only writable by the owner (or owned by root and sticky). If you don't do this correctly, a non-admin user might be able to escalate their privileges by modifying your daemon (or shuffling it aside).

• Try to avoid running your daemon with elevated privileges (for example, running it as root). If your daemon must run with elevated privileges, do not trust data received from non-privileged processes. Doing so might allow a local user to escalate their privileges.

• Watch out for denial of service attacks. If your daemon sends a message to a client, make sure that it works correctly if the client never responds. Don't allow clients to run your daemon out of memory, or file descriptors, or any other resource.

• Watch out for other common security problems, particularly buffer overruns. The nature of daemons makes these problems more worrisome.

For more information about writing secure software, consult one of the numerous texts available on the topic. I highly recommend Building Secure Software.

Agents and Fast User Switching

If you're writing an agent, you should be aware of the subtleties associated with fast user switching. For example, your agent might need to know:

• whether it's running in a GUI or non-GUI login session

• whether its GUI login session is active (that is, using the console)

• and so on

For the detailed information about this, see Multiple User Environments.

Process Manager and Launch Services

Historically, neither Process Manager nor Launch Services were daemon safe. This represents a significant gotcha for daemon writers who, quite reasonably, expect that process services should be available to a daemon. However, if you look at the these APIs in their historical context, you can understand why this restriction existed.

Consider the Process Manager routine GetNextProcess. Numerous programs, from both Apple and third parties, use this routine to display a list of running applications. It wouldn't make sense for this list to show applications running in other GUI login sessions. Thus, this routine uses the bootstrap namespace as an implicit parameter to determine the login session, and hence the list of running applications to return.

Launch Services, which is layered on top of the Process Manager, had similar issues.

Thus, both Process Manager and Launch Services have, historically, been located in the ApplicationServices framework, and were not available to daemons.

Apple recognizes that this restriction is quite inconvenient and is working to improve things. Mac OS X 10.5 represents the first step on that path. Specifically, the underlying implementation of Process Manager has moved from the window server to the CoreServices daemon (coreservicesd). With this change, it is now possible to create daemon-safe system services that deal with Process Manager processes.

The first beneficiary of this change in Launch Services. In Mac OS X 10.5 Launch Services has been moved down to the Core Services layer (it is now a subframework of the CoreServices framework). Thus, it is now daemon-safe.

This raises the question of what happens when you use Launch Services to launch an application from a daemon. Because the daemon is running in the global bootstrap namespace, Launch Services can't use the bootstrap namespace to derive the login session. Rather, Launch Services uses the EUID of the calling process. The behavior is as follows:

• If the EUID of the calling process is zero, the application is launched in the context of the currently active GUI login session. If there is no currently active GUI login session (no one is logged in, or a logged in user has fast user switched to the login window), the behavior is unspecified (r. 5321293) .

• If the EUID of the calling process is not zero and it matches that of a user logged in via the GUI, the application is launched in the context of that user's GUI login session.

• If the EUID of the calling process is not zero but it does not match that of a user logged in via the GUI, the behavior is unspecified (r. 5321281) .

Unfortunately, while the underlying implementation of Process Manager is now at the CoreServices layer, Process Manager itself remains in the ApplicationServices framework. Thus, it's still not possible to use Process Manager from a daemon.

Starting a Daemon

If you're writing a daemon, you may encounter problems when you start the daemon immediately after installing it. There are two essentially conflicting requirements.

• You don't want to force the user to reboot.

• If you launch your daemon directly from your configuration application (or installer), it inherits the wrong context (see Execution Contexts for details).

There are a number of ways that you can resolve this conundrum, listed in order of most- to least-preferable.

• If you have a launchd daemon, you can start it by running launchctl. launchctl works by sending a message to launchd, asking it to launch the daemon on your behalf, so your daemon is a child of launchd and inherits the correct context.

• Otherwise, you can launch the daemon in the global bootstrap namespace using the StartupItemContext tool. This tool is not perfect (r. 4283301) , but it works in most situations.

• Finally, if your daemon only uses daemon-safe frameworks and it doesn't use or register Mach messaging services directly or indirectly, you should be able to just launch it. It will be running in the wrong context, but that probably won't cause serious problems.

Debugging Startup

Because background programs are usually run indirectly (that is, they're sublaunched by a system service, such as launchd), it can be tricky to debug their startup code. There are three tricks you can use here.

• You can add a command line option (traditionally it's "-d" for "debug") that causes your program to run as a standard tool (for example, a startup item wouldn't daemonize itself). This allows you to debug it directly from the GDB.

• If you're developer a launchd daemon or agent, you can add the WaitForDebugger property to your property list file. A true value will cause launchd to start your program in a suspended state, whereupon you can attach with the debugger.

  This property is supported in Mac OS X 10.5 and later.

• If the preceding options don't help, you can add a pause system call to your startup code, as illustrated by Listing 11. This stops the program until a signal arrives and, as it turns out, attaching to the process with GDB sends a signal to the process and unblocks it.

Listing 11  Pausing at startup

if (1) {     fprintf(         stderr,          "Process %ld waiting for debugger.\n",          (long) getpid()     );     pause(); }

Debugging Rogue Window Server Use

If your daemon dies with a message like that shown in Listing 6, and you can't think of any reason why it should be attaching to the window server, there are a variety of things you can do to debug the problem. The first is to set the INIT_Processes environment variable. When you see the resulting message in the system log, you can attached with GDB and do a backtrace to see what triggered the connection. For more details about this environment variable, see Technical Note TN2124, 'Mac OS X Debugging Magic'.

Watch Your Logs!

While developing a background program, it's a good idea to habitually monitor its log file. You'd be amazed how often an unexpected log message will let you quickly isolate an obscure problem. This can be as simple as logging using ASL or printf and running the Console application in the background.

If you're writing a daemon that's launched at startup time (before you can launch the Console application or even SSH info the machine), you may be able to see its log messages by holding down command-V at startup (for "verbose boot"). To permanently enable verbose boots, add the "-v" argument to your boot-args NVRAM variable, as shown in Listing 12.

Listing 12  Enabling verbose boots

$ sudo nvram boot-args="-v" Password:********

Bootstrap Namespaces: One More Thing

The earlier discussion of bootstrap namespaces (see Bootstrap Namespaces) talked extensively about how they are created, but it glossed over the issue of how they are destroyed. It turns out that a bootstrap namespace exists until the last process that references it quits. So, as long as your process is running, you are guaranteed that your bootstrap namespace will be valid.

There is one gotcha, however. When the system creates a bootstrap namespace, it associates it with the process that created it. When that process quits, the namespace is deactivated. For example, if you start a daemon from within an SSH login session and then log out, the process that created the bootstrap namespace (effectively this is sshd) quits, and the bootstrap namespace that it created, which is the namespace that your daemon inherited, is deactivated.

A deactivated bootstrap namespace allows you to look up services, but it does not allow you to register new services. Any attempt to register a service in a deactivate namespace will fail with an error BOOTSTRAP_NOT_PRIVILEGED (1100). Similarly, any high-level wrapper that registers a service will fail. For example, CFMessagePortCreateLocal will print an error message and return NULL if you call it after your namespace has been deactivated.

Earlier versions of Mac OS X (prior to Mac OS X 10.2) did not deactivate bootstrap namespaces; rather, when the process that created a namespace quits, the bootstrap service would destroy the namespace immediately. Any process still referencing that namespace would find itself without any bootstrap namespace (technically, their bootstrap port would now be a Mach dead name).

Apple started deactivating, rather that destroying, bootstrap namespaces as a stopgap measure to improve compatibility for programs that were incorrectly running in the wrong namespace (typically due to a lack of understand of bootstrap namespaces on behalf of the program's author). Future systems may eliminate the concept of deactivated bootstrap namespaces, and thus revert to the pre-10.2 behavior. As long as your program is running in the correct namespace, this should not cause any compatibility problems.

Careful With That Fork, Eugene

Starting in Mac OS X 10.5 launchd works to garbage collect any child processes of a launchd daemon or agent process when that process quits. Specifically, when a launchd daemon or agent quits, launchd will send a SIGTERM to the associated process group.

This can cause problems if you're developing a launchd daemon that creates a child process to run some other program (by the traditional fork and exec combination, or via posix_spawn). The child process will inherit its process group ID from your daemon. If your daemon quits before the child process, the child process will receive a SIGTERM because it's in the same process group as your daemon.

There are a number of ways to avoid being tripped up by this, listed below in order of most- to least-preferable.

• run the 'child' via launchd — If you make the 'child' a separate launchd job, everything will Just Work™.

• create a new session for the child — If you must continue to create the child process manually, have the child process run in a new session (and, consequently, in a new process group) by calling setsid.

• use the AbandonProcessGroup property — If you add this property to your program's property list file, launchd will not attempt to garbage collect your child processes.

Traditionally you would isolate the child process from the daemon by having the child call daemon. And, if you did this, the child would indeed end up in a separate process group, and would not be garbage collected by launchd. Keep in mind, however, that the daemon routine is officially deprecated in Mac OS X 10.5 and later.

Deprecated Daemonomicon

A number of mechanisms used to launch background programs are now deprecated or unsupported. This section describes these mechanisms.

Execution Context Summary for Deprecated Technologies

Table 6 shows how the execution context of a deprecated background program is affected by the mechanism used to launch it.

Notes:

1. Configured using the fifth column of the daemon's entry in inet.conf.

2. Configured using the user attribute in the configuration file; defaults to root if the attribute is not specified.

3. Uses the global bootstrap namespace unless the session_create attribute is specified in the configuration file, in which case the daemon runs in its own per-session bootstrap namespace.

4. Uses the global security context unless the session_create attribute is specified in the configuration file, in which case the daemon runs in its own per-session security context.

Execution Context Example on Mac OS 10.4

Figure 6 is graphical example of execution contexts on Mac OS X 10.4. Before consulting this figure, you should read the up-to-date information in Execution Context Example. This explains the overall thrust of the diagram. The text in this section concentrates on the differences between this diagram and the equivalent diagram for a modern system.

In this diagram there are three per-session bootstrap namespaces, two for GUI login sessions (users A and B) and one for an SSH login session (user A). These are represented by red boxes. Items that aren't in any red box are in the global bootstrap namespace.

Notes:

1. WindowServer runs with an EUID of windowserver (88) and an RUID of root (0).

2. loginwindow runs with an EUID of the logged in user and an RUID of root (0).

3. ftpd runs with an EUID of the logged in user and an RUID of root (0).

As you look at Figure 6, consider the various different types of process that it shows.

• There is a single instance of the WindowServer process that resides in the global bootstrap namespace. However, the window server knows about all GUI per-session bootstrap namespaces. In this case, there's a GUI per-session bootstrap namespace for user A's login session, and another for user B's.

• All applications are children of window server, which does the work to ensure that they run in the correct bootstrap namespace.

• The first instance of loginwindow, the one associated with user A's login session, is a child of launchd. The second instance, created when user A fast user switched to user B, is a child of the window server.

• Each instance of loginwindow manages the context for its associated login session.

• loginwindow also runs pbs (the pasteboard server) directly.

• The Crash Reporter application is actually a mach_init agent. Note how its parent process is launchd, but it runs in the appropriate user's bootstrap namespace.

• sshd is a launchd daemon with the SessionCreate property set, which means that it runs in its own non-GUI login session

• lookupd is a mach_init daemon.

• mds (the Spotlight daemon) is a startup item.

• ftpd is a launchd daemon.

Differences between this and Mac OS X 10.5 include:

• In Mac OS X 10.4 you rarely see per-user instances of launchd.

• In Mac OS X 10.4, all applications are children of the window server. In Mac OS X 10.5, that responsibility has been taken over by the per-user instances of launchd.

• In Mac OS X 10.4 there are no per-user bootstrap namespaces. Thus, it is not possible to register a service, like the Kerberos credentials cache server (CCacheServer) on Mac OS X 10.5, that is available to all login sessions of a particular user.

• In Mac OS X 10.4 the pasteboard server (pbs) was launched directly by loginwindow. In Mac OS X 10.5, the pasteboard server (pboard) is a standard launchd agent.

• In Mac OS X 10.4 launchd agents are launched per-user, with no regard to the user's login session type. This severely limits their usefulness. In fact, Mac OS X 10.4 makes no use of launchd agents. In contrast, on Mac OS X 10.5 a launchd agent can specify which types of login sessions that it supports, and launchd agents are used extensively by the system.

• The mechanism by which the crash reporting application (Crash Reporter on 10.4, ReportCrash on 10.5) is launched has changed, making the crash reporting process simpler and more reliable.

Getting Launched Prior To Mac OS X 10.5

Prior to Mac OS X 10.5, launchd was significantly less powerful than it is today. Thus, a number of the techniques shown in the figures in Getting Launched are not available. If you need to support older systems, you should consult Figure 7 and Figure 8 when deciding on the best approach to launching your program.

Obsolete Programming Techniques

This section covers some programming techniques that are only interesting if you're developing a deprecated background program.

The process has forked and you cannot use this CoreFoundation \
functionality safely. You MUST exec().
Break on __THE_PROCESS_HAS_FORKED_AND_YOU_CANNOT_USE_THIS_\
COREFOUNDATION_FUNCTIONALITY___YOU_MUST_EXEC__() to debug.

#include <getopt.h>
#include <stdlib.h>
#include <string.h>
#include <sys/param.h>
#include <syslog.h>
#include <mach-o/dyld.h>

extern char ** environ;

int main(int argc, char **argv)
{
    if ( (argc >= 2) && (strcmp(argv[1], "daemon") == 0) ) {
        optind = 2;

        // ... process any post-daemonization arguments ...

        // ... run as a daemon ...
    } else {
        char **     args;
        char        execPath[PATH_MAX];
        uint32_t    execPathSize;

        // ... process any pre-daemonization arguments ...

        // Calculate our new arguments, dropping any arguments that 
        // have already been processed (that is, before optind) and 
        // inserting the special flag that tells us that we've 
        // already daemonized.
        //
        // Note that we allocate and copy one extra argument so that 
        // args, like argv, is terminated by a NULL.
        // 
        // We get the real path to our executable using 
        // _NSGetExecutablePath because argv[0] might be a relative 
        // path, and daemon chdirs to the root directory. In a real 
        // product you could probably substitute a hard-wired absolute 
        // path.

        execPathSize = sizeof(execPath);
        (void) _NSGetExecutablePath(execPath, &execPathSize);

        args = malloc((argc - optind + 1) * sizeof(char *));
        args[0] = execPath;
        args[1] = "daemon";
        memcpy(
            &args[2], 
            &argv[optind], 
            (argc - optind + 1) * sizeof(char *)
        );

        // Daemonize ourself.

        (void) daemon(0, 0);

        // exec ourself.

        (void) execve(execPath, args, environ);
    }

    return EXIT_SUCCESS;
}