LaunchControl
Frequently Asked Questions

Miscellaneous

How do I enable/disable a job?
The main window is divided in three parts. The left-most section shows a list of all jobs of the currently selected type. This list has three columns, the name of the configuration file (without the .plist extension), a checkbox and a status description. Use the check box to enable/disable a service. Note: This operation instantly modifies the job configuration.
How do I add a new job?
The main window is divided in three parts. The left-most section shows a list of all jobs of the currently selected type. Below this list you find a little button with a '+' label. Click it to add a new job.
How do I remove an existing job?
The main window is divided in three parts. The left-most section shows a list of all jobs of the currently selected type. Below this list you find a little button with a '-' label. Click it to remove an existing job. The .plist file will not be deleted. It will be moved to the Trash instead.
How do I rename an existing job?
The main window is divided in three parts. The left-most section shows a list of all jobs of the currently selected type. This list has three columns, the name of the configuration file (without the .plist extension), a checkbox and a status description. Select the name, wait half a second and click on the name again to rename this file. The .plist file extension is appended automatically.
How do I add a new configuration key to a job?
The main window is divided in three parts. The left-most section shows a list of all jobs of the currently selected type, the center represents the configuration section and the table to the right is the palette of available configuration keys. Just drag a key from the palette to configuration section. Make sure you don't drop the key on an input element. Should the key already be defined it will be highlighted.
What is the recommended way to debug a job?
While debugging a job it is not necessary to load/unload it manually every time a change to the configuration is made. Event triggered jobs might not be executed at all when loading. The preferred method is to start the job unconditionally by selecting Job>Start (⌘⇧T) from the menu. When a change is detected, a request panel will appear: click the Save, Reload and Start button.
  • Check for warnings and errors

    This is the obvious first step. Make sure you understand every warning and error that LaunchControl reports. Hovering over a warning or error sign in a config sections header will provide details about the error/warning.

  • Check the error code

    Check for the exit code of the job in the status column of the job list. Move your mouse over the error code to bring up a tool tip with a likely error reason. See bullet "Check the launchd(8) log" to find out if this error reason applies.

  • Check the launchd(8) log

    It is a good idea to have a look at what launchd(8) has to say about the job while trying run it. Open the log panel by selecting View>Toggle Log (⌘⌥L) from the menu. Click the trace-button in the upper left corner of the log panel and start the job by selecting Job>Start (⌘⇧T) from the menu.

    To find out whether a jobs exit code comes from launchd(8) or the program to be executed watch out for these lines:

    Job failed to exec(3) for weird reason: <code>

    This error code was generated by launchd(8) itself. The program specified could not be run. The error details provided in the tool tip of the job list status column are definitely correct

    Exited with code: <code>

    This error code was generated by the program/script. launchd(8) was able to execute the program but the program did return a non-zero exit code. By convention this is to be interpreted as an error, but actually the author of the script/program is free to return any exit code he/she wishes. In this case the error details provided in the tool tip of the job list status column may or may not be correct. If the author of the program adhered to the standard exit codes they are correct. Otherwise they are completely misleading.

    Check the jobs standard error/output

    Make sure you configure the keys StandardErrorPath and StandardOutPath. The job might write relevant information to either of these. After running the job click on the trace button in the standard out/error config section. This will open the corresponding file in Console.app.

Uninstall

How do I uninstall LaunchControl?
This is not exactly a frequently asked question, but It might be of interest to some.

To completely remove LaunchControl from your computer, disable QuickLaunch from the LaunchControl preferences panel and quit the application. Now unload the helper tool. Open Terminal.app (in your Utilities folder) and enter:

sudo launchctl unload /Library/LaunchDaemons/com.soma-zone.LaunchControl.Helper.plist

This command will ask for your admin password. After the helper tool has been unloaded you can safely remove LaunchControl.app and these files/folders:

  • /Library/PrivilegedHelperTools/com.soma-zone.LaunchControl.Helper
  • ~/Library/Preferences/com.soma-zone.LaunchControl.plist
  • ~/Library/Preferences/com.soma-zone.LaunchControl.shared.plist
  • ~/Library/Caches/com.soma-zone.LaunchControl/
  • ~/Library/Application Support/LaunchControl/