Launchd is rather simple actually. Far simpler than you might think.
+ +Launchd, in an effort to be consistent with other Apple software, uses the +Property List file format for storing configuration information. Apple's +Property List APIs provide for three different file formats for storing a +property list to disk. A plain text option, a binary option, and an XML text +option. For the remainder of this HOWTO, we will use the XML varient to show +what a configuration file looks like.
+ +For the simplest of scenarios, launchd just keeps a process alive. A simple "hello +world" example of that would be:
+ ++ ++<?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.example.sleep</string> + <key>ProgramArguments</key> + <array> + <string>sleep</string> + <string>100</string> + </array> + <key>OnDemand</key> + <false/> +</dict> +</plist> +
In the above example, we have three keys to our top level dictionary. The first
+is the Label which is what is used to uniquely identify jobs when interacting
+with launchd. The second is ProgramArguments which for its value, we have an
+array of strings which represent the tokenized arguments and the program to
+run. The third and final key is OnDemand which overrides the default value of
+true with false thereby instructing launchd to always try and keep this job
+running. That's it! A Label, some ProgramArguments and OnDemand set to false is all
+you need to keep a daemon alive with launchd!
Now if you've ever written a daemon before, you've either called the
+daemon() function or written one yourself. With launchd, that is
+not only unnecessary, but unsupported. If you try and run a daemon you didn't
+write under launchd, you must, at the very least, find a configuration option to
+keep the daemon from daemonizing itself so that launchd can monitor it.
There are many optional keys available and documented in the launchd.plist +man page, so we'll only give a few optional, but common examples:
+ ++ ++<?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.example.sleep</string> + <key>ProgramArguments</key> + <array> + <string>sleep</string> + <string>100</string> + </array> + <key>OnDemand</key> + <false/> + <key>UserName</key> + <string>daemon</string> + <key>GroupName</key> + <string>daemon</string> + <key>EnvironmentVariables</key> + <dict> + <key>FOO</key> + <string>bar</string> + </dict> +</dict> +</plist> +
In the above example, we see that the job is run as a certain user and group, and additionally has an extra environment variable set.
+ +The following example will enable core dumps, set standard out and error to +go to a log file and to instruct launchd to temporarily bump up the debug level +of launchd's loggging while acting on behave of your job (remember to adjust +your syslog.conf accordingly):
+ ++ ++<?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.example.sleep</string> + <key>ProgramArguments</key> + <array> + <string>sleep</string> + <string>100</string> + </array> + <key>OnDemand</key> + <false/> + <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> +
Launchd provides a multitude of different criteria that can be used to specify +when a job should be started. It is important to note that launchd will only +run one instance of your job though. Therefore, if your on demand job +malfunctions, you are guaranteed that launchd will not spawn additional copies +when your criteria is satisfied once more in the future.
+ +Here is an example on how to have a job start every five minutes (300 seconds):
+ ++ ++<?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.example.touchsomefile</string> + <key>ProgramArguments</key> + <array> + <string>touch</string> + <string>/tmp/helloworld</string> + </array> + <key>StartInterval</key> + <integer>300</integer> +</dict> +</plist> +
Sometimes you want a job started on a calendar based interval. The following example will start the job on the 11th minute of the 11th hour every day (using a 24 hour clock system) on the 11th day of the month. Like the Unix cron subsystem, any missing key of the StartCalendarInterval dictionary is treated as a wildcard:
+ ++<?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.example.touchsomefile</string> + <key>ProgramArguments</key> + <array> + <string>touch</string> + <string>/tmp/helloworld</string> + </array> + <key>StartCalendarInterval</key> + <dict> + <key>Minute</key> + <integer>11</integer> + <key>Hour</key> + <integer>11</integer> + <key>Day</key> + <integer>11</integer> + </dict> +</dict> +
The following example will start the job whenever any of the paths being watched change for whatever reason:
+ ++ ++<?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.example.watchetchostconfig</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> +
An additional file system trigger is the notion of a queue directory. Launchd will star your job whenever +the given directories are non-empty and will keep your job running as long as those directories are not empty:
+ ++ ++<?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.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> +
Launchd will happily emulate inetd style daemon semantics:
+ ++ ++<?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.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> +