====== launchd ======

===== Background =====
Mac OS X provides two methods for launching daemons: [[creating startup items|startup items]] and launchd(8) daemons. Which one you use depends largely on the versions of Mac OS X that the daemon must support.
  * Mac OS X v10.3 and earlier: You must use startup items. The launchd service is not supported prior to v10.4.
  * Mac OS X v10.4 and later: You can either use startup items or launchd daemons. Using launchd daemons is preferred unless you also require backwards compatibility with versions of Mac OS X prior to v10.4.

===== Creating a launchd job =====
  - review the [[#External Links]] below to get a better understanding of how launchd and launchctl work
  - open Property List Editor (included in Developer Tools) or use a text editor to create files like the examples below
  - save the file with a namespaced filename, such as com.example.MyApp.plist
    * if you edit the file in a text editor and launchctl complains later, you can check the file for errors with<code>
plutil -lint <path to your plist file>
</code>
  - decide how you want the job to run
    * ~/Library/LaunchAgents/ - will run when user logs in, as that user (UserName key is ignored in plist file)
    * /Library/LaunchAgents/ - will run when any user logs in, as that user (UserName key is ignored in plist file)
    * /Library/LaunchDaemons/ - will run when system starts, as root; file permissions need to be 644, owned as root
  - the job will start when your computer is restarted or if you log out and back in, depending on where you placed the file.  To start the job now, run this:<code>
launchctl load <path to your plist file>
</code>
    * if you get a "nothing found to load" message, use the -w parameter:<code>
launchctl load -w <path to your plist file>
</code>
  - to stop the job, run this:<code>
launchctl unload <path to your plist file>
</code>
  - if the job needs to run as root, use sudo before the commands
  - you can start an interactive session by running launchctl.  If you do this with sudo, it will be the root launchd session; otherwise it will only be for your user

===== Example: Apache2 =====
Since the apachectl program spawns a daemon and doesn't stay open, we need launchd to work with a script that will monitor the Apache server and kickstart it appropriately when necessary.

**/usr/local/apache2/bin/launchd_apache.sh**
<code sh>
#!/bin/sh
/usr/local/apache2/bin/apachectl graceful

sleeptime=40

httpdArray=(`ps -U www | grep httpd | awk '{print $1}'`);
let httpdCount=${#httpdArray[*]};
    
while (($httpdCount > 0))
do  
    sleep $sleeptime;
    hpptdArray=(`ps -U www | grep httpd | awk '{print $1}'`);
    let httpdCount=${#httpdArray[*]};
done
    
echo "Apache Stopped, restarting..."
</code>

**/Library/LaunchDaemons/local.apache2.plist**
<code xml>
<?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>GroupName</key>
    <string>admin</string>
    <key>Label</key>
    <string>Apache2</string>
    <key>KeepAlive</key>
    <false/>
    <key>Program</key>
    <string>/usr/local/apache2/bin/launchd_apache.sh</string>
    <key>RunAtLoad</key>
    <true/>
    <key>ServiceDescription</key>
    <string>Launches the Apache2 httpd web server</string>
    <key>UserName</key>
    <string>root</string>
</dict>
</plist>
</code>

===== Example: MySQL =====
**/Library/LaunchDaemons/local.mysql.plist**

<code xml>
<?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>MySQL</string>
    <key>UserName</key>
    <string>root</string>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/mysql/bin/mysqld_safe</string>
      <string>--user=mysql</string>
    </array>
    <key>WorkingDirectory</key>
    <string>/usr/local/mysql</string>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
</code>

===== Example: Postgres =====
**/Library/LaunchDaemons/local.postgres.plist**

  * note - the below script causes console to log this:<code>
  * 7/1/12 2:24:05.272 PM com.apple.launchd: (Postgres[20215]) Suspicious setup: User "postgres" maps to user: _postgres
</code>
    * however, if you try changing the users to _postgres, the launch fails (doesn't have permission to read conf file)

<code xml>
<!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>Postgres</string>
    <key>Disabled</key>
    <false/>
    <key>UserName</key>
    <string>postgres</string>
    <key>GroupName</key>
    <string>postgres</string>
    <key>Program</key>
    <string>/usr/local/pgsql/bin/postgres</string>
    <key>StandardOutPath</key>
    <string>/usr/local/pgsql/log/postgres.log</string>
    <key>StandardErrorPath</key>
    <string>/usr/local/pgsql/log/postgres.log</string>
    <key>EnvironmentVariables</key>
    <dict>
    <key>PGDATA</key>
    <string>/usr/local/pgsql/data/</string>
    </dict>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
</code>

===== External Links =====
  * http://developer.apple.com/library/mac/#documentation/Darwin/Reference/ManPages/man5/launchd.plist.5.html
  * [[http://www.macgeekery.com/tips/all_about_launchd_items_and_how_to_make_one_yourself|all about launchd items and how to make one yourself]]
  * [[http://diymacserver.com/forum/topic/using-launchd-instead-of-startupitems|using launchd instead of startupitems]]
  * [[http://www.afp548.com/article.php?story=20050620071558293|launchd in Depth]]
  * http://en.wikipedia.org/wiki/Launchd
  * http://hints.macworld.com/article.php?story=20080128103022907

==== GUI's ====
  * [[http://www.codepoetry.net/products/launchdeditor|Launchd Editor]]
  * [[http://www.peterborgapps.com/lingon/|Lingon]]