Writing a “Hello World!” launchd Job

The following simple example launches a daemon named hello, passing world as a single argument, and instructs launchd to keep the job running:

<?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.example.hello</string>

    <key>ProgramArguments</key>

    <array>

        <string>hello</string>

        <string>world</string>

    </array>

    <key>KeepAlive</key>

    <true/>

</dict>

</plist>

In this example, there are three keys in the top level dictionary. The first is Label, which uniquely identifies the job. when. The second is ProgramArguments which has a value of an array of strings which represent the tokenized arguments and the program to run. The third and final key is KeepAlive which indicates that this job needs to be running at all times, rather than the default launch-on-demand behavior, so launchd should always try to keep this job running.

Listening on Sockets

You can also include other keys in your configuration property list file. For example, if your daemon monitors a well-known port (one of the ports listed in /etc/services), add a Sockets entry as follows:

<key>Sockets</key>
<dict>
    <key>Listeners</key>
    <dict>
        <key>SockServiceName</key>
        <string>bootps</string>
        <key>SockType</key>
        <string>dgram</string>
        <key>SockFamily</key>
        <string>IPv4</string>
    </dict>
</dict>

The string for SockServiceName typically comes from the leftmost column in /etc/services. The SockType is one of dgram (UDP) or stream (TCP/IP). If you need to pass a port number that is not listed in the well-known ports list, the format is the same, except the string contains a number instead of a name. For example:

<key>SockServiceName</key>

<string>23</string>

Debugging launchd Jobs

There are some options that are useful for debugging your launchd job.

The following example enables core dumps, sets standard out and error to go to a log file, and instructs launchd to temporarily increase the debug level of its logging while acting on behalf of your job (remember to adjust your syslog.conf accordingly):

<?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.example.sleep</string>

    <key>ProgramArguments</key>

    <array>

        <string>sleep</string>

        <string>100</string>

    </array>

    <key>StandardOutPath</key>

    <string>/var/log/myjob.log</string>

    <key>StandardErrorPath</key>

    <string>/var/log/myjob.log</string>

    <key>Debug</key>

    <true/>

    <key>SoftResourceLimits</key>

    <dict>

        <key>Core</key>

        <integer>9223372036854775807</integer>

    </dict>

    <key>HardResourceLimits</key>

    <dict>

        <key>Core</key>

        <integer>9223372036854775807</integer>

    </dict>

</dict>

</plist>

Running a Job Periodically

The following example creates a job that is run every five minutes (300 seconds):

<?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.example.touchsomefile</string>

    <key>ProgramArguments</key>

    <array>

        <string>touch</string>

        <string>/tmp/helloworld</string>

    </array>

    <key>StartInterval</key>

    <integer>300</integer>

</dict>

</plist>

Alternately, you can specify a calendar-based interval. The following example starts the job on the 7th day of every month at 13:45 (1:45 pm). Like the Unix cron subsystem, any missing key of the StartCalendarInterval dictionary is treated as a wildcard—in this case, the month is omitted, so the job is run every month.

<?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.example.touchsomefile</string>

    <key>ProgramArguments</key>

    <array>

        <string>touch</string>

        <string>/tmp/helloworld</string>

    </array>

    <key>StartCalendarInterval</key>

    <dict>

        <key>Minute</key>

        <integer>45</integer>

        <key>Hour</key>

        <integer>13</integer>

        <key>Day</key>

        <integer>7</integer>

    </dict>

</dict>

</plist>

Monitoring a Directory

The following example starts the job whenever any of the paths being watched have changed:

<?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.example.watchhostconfig</string>

    <key>ProgramArguments</key>

    <array>

        <string>syslog</string>

        <string>-s</string>

        <string>-l</string>

        <string>notice</string>

        <string>somebody touched /etc/hostconfig</string>

    </array>

    <key>WatchPaths</key>

    <array>

        <string>/etc/hostconfig</string>

    </array>

</dict>

</plist>

An additional file system trigger is the notion of a queue directory. The launchd daemon starts your job whenever the given directories are non-empty, and it keeps your job running as long as those directories are not empty:

<?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.example.mailpush</string>

    <key>ProgramArguments</key>

    <array>

        <string>my_custom_mail_push_tool</string>

    </array>

    <key>QueueDirectories</key>

    <array>

        <string>/var/spool/mymailqdir</string>

    </array>

</dict>

</plist>

Emulating inetd

The launchd daemon emulates the older inetd-style daemon semantics if you provide the inetdCompatibility key:

<?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.example.telnetd</string>

    <key>ProgramArguments</key>

    <array>

        <string>/usr/libexec/telnetd</string>

    </array>

    <key>inetdCompatibility</key>

    <dict>

        <key>Wait</key>

        <false/>

    </dict>

    <key>Sockets</key>

    <dict>

        <key>Listeners</key>

        <dict>

            <key>SockServiceName</key>

            <string>telnet</string>

            <key>SockType</key>

            <string>stream</string>

        </dict>

    </dict>

</dict>

</plist>

Required Behaviors

To support launchd, you must obey the following guidelines when writing your daemon code:

• You must provide a property list with some basic launch-on-demand criteria for your daemon. See Creating a launchd Property List File.

• You must not daemonize your process. This includes calling the daemon function, calling fork followed by exec, or calling fork followed by exit. If you do, launchd thinks your process has died. Depending on your property list key settings, launchd will either keep trying to relaunch your process until it gives up (with a “respawning too fast” error message) or will be unable to restart it if it really does die.

• Daemons and agents that are installed globally must be owned by the root user. Agents installed for the current user must be owned by that user. All daemons and agents must not be group writable or world writable. (That is, they must have file mode set to 600 or 400.)

Recommended Behaviors

To support launchd, it is recommended that you obey the following guidelines when writing your daemon code:

• Wait until your daemon is fully initialized before attempting to process requests. Your daemon should always provide a reasonable response (rather than an error) when processing requests.

• Register the sockets and file descriptors used by your daemon in your launchd configuration property list file.

• If your daemon advertises a socket, check in with launchd as part of your daemon initialization. For an example implementation of the check-in process, see SampleD.

• During check-in, get the launch dictionary from launchd, extract and store its contents, and then discard the dictionary. Accessing the data structure used for the dictionary is very slow, so storing the whole dictionary locally and accessing it frequently could hurt performance.

• Provide a handler to catch the SIGTERM signal.

In addition to the preceding list, the following is a list of things it is recommended you avoid in your code:

• Do not set the user or group ID for your daemon. Include the UserName, UID, GroupName, or GID keys in your daemon’s configuration property list instead.

• Do not set the working directory. Include the WorkingDirectory key in your daemon’s configuration property list instead.

• Do not call chroot to change the root directory. Include the RootDirectory key in your daemon’s configuration property list instead.

• Do not call setsid to create a new session.

• Do not close any stray file descriptors.

• Do not change stdio to point to /dev/null. Include the StandardOutPath or StandardErrorPath keys in your daemon’s configuration property list file instead.

• Do not set up resource limits with setrusage.

• Do not set the daemon priority with setpriority

Although many of the preceding behaviors may be standard tasks for daemons to perform, they are not recommended when running under launchd. The reason is that launchd configures the operating environment for the daemons that it manages. Changing this environment could interfere with the normal operation of your daemon.

Network Availability

If your daemon depends on the network being available, this cannot be handled with dependencies because network interfaces can come and go at any time in OS X. To solve this problem, you should use the network reachability functionality or the dynamic store functionality in the System Configuration framework. This is documented in System Configuration Programming Guidelines and System Configuration Framework Reference. For more information about network reachability, see Determining Reachability and Getting Connected in System Configuration Programming Guidelines.

Disk or Server Availability

If your daemon depends on the availability of a mounted volume (whether local or remote), you can determine the status of that volume using the Disk Arbitration framework. This is documented in Disk Arbitration Framework Reference.

Non-launchd Daemons

If your daemon has a dependency on a non-launchd daemon, you must take additional care to ensure that your daemon works correctly if that non-launchd daemon has not started when your daemon is started. The best way to do this is to include a loop at start time that checks to see if the non-launchd daemon is running, and if not, sleeps for several seconds before checking again.

Be sure to set up handlers for SIGTERM prior to this loop to ensure that you are able to properly shut down if the daemon you rely on never becomes available.

User Logins

In general, a daemon should not care whether a user is logged in, and user agents should be used to provide per-user functionality. However, in some cases, this may be useful.

To determine what user is logged in at the console, you can use the System Configuration framework, as described in Technical Q&A QA1133.

Kernel Extensions

If your daemon requires that a certain kernel extension be loaded prior to executing, you have two options: load it yourself, or wait for it to be loaded.

The daemon may manually request that an extension be loaded. To do this, run kextload with the appropriate arguments using exec or variants thereof. I/O Kit kernel extensions should not be loaded with kextload; the I/O Kit will load them automatically when they are needed.

Alternatively, our daemon may wait for a kernel service to be available. To do this, you should first register for service change notification. This is further documented in I/O Kit Framework Reference.

After registering for these notifications, you should check to see if the service is already available. By doing this after registering for notifications, you avoid waiting forever if the service becomes available between checking for availability and registering for the notification.

For more information about I/O Kit services and matching, see IOKit Fundamentals, I/O Kit Framework Reference (user space reference), and Kernel Framework Reference (kernel space reference).