User Interface Overview
Note: LaunchControl will present alerts before most actions to avoid accidental modifications. All of these alerts may be disabled. To re-enable all of them select .
Note: LaunchControl will present alerts before most actions to avoid accidental modifications. All of these alerts may be disabled. To re-enable all of them select .
LaunchControl supports five different categories of jobs:
| Name | Location | Run on behalf of |
|---|---|---|
| User Agents | ~/Library/LaunchAgents | Currently logged in user |
| Global Agents | /Library/LaunchAgents | Currently logged in user |
| Global Daemons | /Library/LaunchDaemons | root or the user specified with the key 'User' |
| System Agents | /System/Library/LaunchAgents | Currently logged in user |
| System Daemons | /System/Library/LaunchDaemons | root or the user specified with the key 'User' |
Select the desired category from the category popup.
Some categories hold a large number of jobs. You may filter the list using the Job Name Filter or the Job Attribute Filter (Cmd-Opt F). Note: On a fresh install of OSX the category User Agents is empty.
The first column the names of the job definition files. The extension (.plist) is omitted. The color the file name is displayed in represents its validation status.
| Color | Validation status | Description |
|---|---|---|
| Black | Ok | Every aspect of the jpb definition is ok. The job should run just fine. |
| Yellow | Warning | There are one or more minor problems with this job definition. A warning will not keep the job from running. It just might not behave as expected. |
| Red | Error | There is a severe problem with the job definition. launchd(8) will not be able to start this job. |
Note: The colors in this column do not reflect the run-time status of a job.
The checkboxes in the second column indicate if a job is enabled or not. An enabled job will be loaded automatically on system boot (daemons) or login (agents). The check mark indicates if the Disabled key of the job definition has been set to true (not checked) or false (checked). The background color indicates if this setting has been overridden with true (red) or false (green).
If a checkbox is grey, the status of the checkbox will tell you if the job is enabled or not. If a checkbox is green, the job is enabled no matter what the checkbox status indicates. If a checkbox is red, the job is disabled no matter what the checkbox indicates.
| Checked | Color | Description |
|---|---|---|
| No | Grey | The jobs Disabled key is not set or false. The job is effectively disabled and will not be automatically loaded by launchd(8). |
| Yes | Grey | The jobs Disabled key is set to true. The job is effectively enabled and will be automatically loaded by launchd(8). |
| No | Green | The jobs Disabled key is not set or false, but this value is ignored as it has been overridden. The job is effectively enabled and will be automatically loaded by launchd(8). |
| Yes | Green | The jobs Disabled key is set to true, but this value is ignored as it has been overridden. The job is effectively enabled and will be automatically loaded by launchd(8). |
| No | Red | The jobs Disabled key is not set or false, but this value is ignored as it has been overridden. The job is effectively disabled and will not be automatically loaded by launchd(8). |
| Yes | Red | The jobs Disabled key is set to true, but this value is ignored as it has been overridden. The job is effectively disabled and will not be automatically loaded by launchd(8). |
Clicking on a check box will set the jobs Disabled key. Use the to change the override.
Note: Don't confuse this with the job state. Just because a job is enabled does not mean that the job is loaded or even running and vice versa.
The third column displays the job state. A job is either loaded or unloaded. Loaded jobs may have the following sub-states:
| State | Description |
|---|---|
| Ok | In case it has been already executed, is has returned successfully. |
| Running | It is currently being executed. |
| Error <CODE> | It has been executed and it returned an error. The return code is provided in the status column. |
| SIG<NAME> | It has been executed and it terminated with the signal given in the status column. |
A job may also be in state 'Unknown'. In this case LaunchControl was either unable to parse the job definition file or it could not find the job label. Possible reasons for the first case might be that LaunchControl was unable to read the file due to insufficient permissions or due to a malformed job definition.
Double-click on the name in the list. You can edit the name inline. The extension (.plist) is appended automatically.
Note: Job definition files cannot be renamed while there are unsaved modifications.
Clicking the '+' button in the lower right of the job list section will create an empty job skeleton of the currently selected job category. Clicking the '-' button next to it will move the currently selected job definition to the trash. You may recover accidentally removed job definitions as usual.
LaunchControl provides two edit modes. The default mode provides custom controls for every documented key supported by launchd(8). Using this mode will guaranty that the resulting job definition is valid. The default mode also validates the configuration options you provide. It discovers problems immediately, even before you run the job. If, for example, you provide the key Program, LaunchControl will check if the program exists and if it is executable. If Program is a relative path, LaunchControl will check for the key WorkingDirectory. If this key is set, LaunchControl will assume the program is in this directory. It also considers the keys User and Group when evaluating the permissions. It performs as many checks as possible to ensure that the job definition is valid before you load it into launchd(8).
The expert mode does not restrict you in any way. It allows you to use any key of any type you want. You should rarely need this mode, but it might be useful when using some of the undocumented features of launchd(8).
You can switch between these two modes by selecting (Cmd-Opt X). Default and expert mode are synchronized. A change made in one editor will immediately be visible in the other one.
Note: Modifications won't affect the running instance until you load your changes into launchd(8) by selecting (Cmd-Shift L) or by clicking the 'Load' button in the upper right corner of the editor panel.
Make sure the Palette panel is visible (Cmd-Opt P). Drag & Drop the desired key from the palette on the editor.
In default mode, select the small cross symbol in the upper right corner of the configuration section. In expert mode, move the mouse pointer to the key you'd like to remove. One or more symbols will appear next to the key name: Add child, Add sibling and Remove. Click the last one.
Depending of the state of the currently selected job, the button in the upper right corner of the editor panel will either load or unload the job. Alternatively you may select the appropriate action from the menu.
Note: Loading a job does not necessarily start it. How/when a job is started is determined by the keys you provided for launchd(8). If you want to start a job immediately, load it and select (Cmd-Shift S) from the menu.
In this panel you'll find any key officially supported by launchd(8). To make it easier for you to find the right key, LaunchControl has grouped keys into sections. Selecting a section using the popup button in the upper part of the palette panel will limit the number of displayed keys. You may also use the key filter below the section popup button to search for keys by name or description.
The palette panel may be switched on or off by selecting (Cmd-Opt P).
LaunchControl does its best to verify every job-setting you provide. But certain things cannot be checked. You need to run the job and verify that it works as expected. Usually this involves opening Console.app and creating a filter for your specific job, a tail/grep on /var/log/system.log or another means of searching logs. LaunchControl lets you query launchd(8) log files without the hassle. Select the job and click the 'Play' button in the upper left corder of the log panel. Please note that querying the log subsystem can be an expensive operation. Pause the query operation if you don't need it anymore.
The log panel may be switched on or off by selecting (Cmd-Opt L).
Currently you need to run LaunchControl as a privileged user to use the log view for daemons. Unprivileged users may use the log feature only for agents.
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 (Cmd-Shift S) from the menu. When a change is detected, a request panel will appear: click the button.
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 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.
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 (Cmd-Opt L) from the menu. Click the trace-button in the upper left corner of the log panel and start the job by selecting (Cmd-Shift S) 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:
| Log text | meaning |
|---|---|
| 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.s |
| 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. |
We are currently not aware of a way to differentiate between these two possibilities.
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.