Run Lasso9 Using Launchd On Mac OS X

A tutorial to use launchd in Mac OS X to control how lasso9 runs

Motivation: When following the instructions for a multi-site setup with Lasso 9, whenever I restarted Apache, I would get errors about servers already using the ports the shell scripts wanted to use to start up Lasso. Essentially, when you stick a shell script in between the actual lassoserver executable and Apache, when Apache stops, it doesn't stop lassoserver, so a conflict ensues when Apache starts back up and tries to use the shell script to start a process that is still running.

Solution: Instead of using Apache to control the startup of Lasso 9, use Mac OS X's launchd utility. If you've never used launchd, I highly suggest reading the man pages for it and finding some tutorials on it as it is extremely vital to know if you run any Mac servers.

Keep Apache From Starting Lasso

In your Apache configuration files, make sure there are no directives that begin with "FastCGIServer" followed by a path to either the lassoserver executable or a shell script that calls it. These are the directives that tell Apache to start lassoserver, and this is something we no longer want.

Example Launchd Scripts For Two Sites

Below are to separate launchd scripts to demonstrate a multi-site setup. If you have a multi-site setup, then the launchd scripts obviate the need for the shell scripts as well as the "FastCGIServer" Apache directive we deleted above. If you have a single-site setup, then your launchd script just takes the place of the "FastCGIServer" directive above.

Site1 Launchd Script
 

<?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.lasso.site1</string>
    <key>UserName</key>
        <string>lasso</string>
    <key>EnvironmentVariables</key>
        <dict>
            <key>LASSOSERVER_FASTCGIPORT</key>
                <string>8999</string>
            <key>LASSO9_HOME</key>
                <string>/path/to/site1/home/</string>
        </dict>
    <key>ProgramArguments</key>
        <array>
             <string>/usr/local/bin/lassoserver</string>
        </array>
    <key>StandardOutPath</key>
        <string>/path/to/site1/home/lassoserver.log</string>
    <key>StandardErrorPath</key>
        <string>/path/to/site1/home/lassoserver.log</string>
    <key>RunAtLoad</key>
        <true/>
    <key>KeepAlive</key>
        <true/>
</dict>
</plist>

 

Site2 Launchd Script

<?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.lasso.site2</string>
    <key>UserName</key>
        <string>lasso</string>
    <key>EnvironmentVariables</key>
        <dict>
            <key>LASSOSERVER_FASTCGIPORT</key>
                <string>9000</string>
            <key>LASSO9_HOME</key>
                <string>/path/to/site2/home/</string>
        </dict>
    <key>ProgramArguments</key>
        <array>
             <string>/usr/local/bin/lassoserver</string>
        </array>
    <key>StandardOutPath</key>
        <string>/path/to/site2/home/lassoserver.log</string>
    <key>StandardErrorPath</key>
        <string>/path/to/site2/home/lassoserver.log</string>
    <key>RunAtLoad</key>
        <true/>
    <key>KeepAlive</key>
        <true/>
</dict>
</plist>

You'll need to place the launchd scripts in /Library/LaunchDaemons/ folder with a name that ends in .plist. (I usually just use the same name I gave in the label section, so, for this example, the files would be named com.lasso.site1.plist and com.lasso.site2.plist)

The launchd scripts also need to have the correct permissions which you can set using the following commands on each one:

$> sudo chmod 644 /Library/LaunchDaemons/script_name.plist
$> sudo chown root:wheel /Library/LaunchDaemons/script_name.plist

After verifying that Lasso 9 is not running and connected to these ports, you can now start the sites using the following command on each:

$> sudo launchctl load /Library/LaunchDaemons/script_name.plist

From now on, because of how the scripts are setup, they should automatically run when you restart your machine. If you want to stop the a Lasso site, you can use the following command:

$> sudo launchctl unload /Library/LaunchDaemons/script_name.plist

Unfortunately, to restart the sites there is no restart command. You have to stop it using the command above and then start it using the command above.

Launchd Script Explained

Here is an outline of the keys I've used in the launchd scripts and what they do.

Label

Label is followed by a string that gives a unique name for launchd to use. The standard convention is to use the reverse URL scheme you see in the example. Remember, each one needs to be unique.

UserName

UserName is followed by a string that specifies which user to run the process as. I have specified lasso for both, but you might want to create different users for each site, depending on your needs.

EnvironmentVariables

EnvironmentVariables is followed by a dictionary with pairs that create Unix environmental variables that should be in play when the command is run. In this case, I've setup LASSO9_HOME with the path to each sites Lasso 9 home directory and LASSOSERVER_FASTCGIPORT with the unique port number the site should bind to. You can put other variables in here as well, for example LASSO9_PRINT_FAILURES1 for deep debugging information.

ProgramArguments

ProgramArguments is followed by an array of strings. The first is the path to the program launchd should launch lassoserver in this case. Additional strings are for the arguments you want to pass to the program, of which we don't have any.

StandardOutPath

StandardOutPath is followed by a string that tells launchd where the stdout should be redirected to for this program. I combine this with StandardErrorPath to have everything logged to one place.

StandardErrorPath

StandardErrorPath is followed by a string that tells launchd where the stderr should be redirected to for this program. I combine this with StandardOutPath to have everything logged to one place.

RunAtLoad

RunAtLoad is followed by a self-closed boolean tag that tells launchd whether or not to start this program when the machine starts up. As this is the handiest thing for most servers, I've set it to so that it will start at startup.

KeepAlive

KeepAlive is followed by a self-closed boolean tag that tells launchd whether or not to restart this program if the process unexpectedly quits. I've set it to to tell launchd to keep restarting it if it unexpectedly quits. (You can also follow this with a dictionary with more granular options see the man page for launchd.plist for further information.)

Author: Brad Lindsay
Created: 18 Mar 2010
Last Modified: 16 Mar 2011