launchd.plist

System wide and per-user daemon/agent configuration files

EXPECTATIONS

XML Property List Keys

Label string required key uniquely identifies the job to launchd.
Program string Used as the first argument of execvp. Default: ProgramArguments[0] .
Required in the absence of the ProgramArguments key.
ProgramArguments array_of_strings Used as the second argument of execvp.
Required in the absence of the Program key. Read execvp(3) carefully
EnableGlobbing bool use the glob(3) mechanism to update the program arguments before invocation.
Disabled boolsee /private/var/db/launchd/com.apple.xpc.launchd/disabled.plist deprecated: a hint to launchctl(1) that it should not submit this job to launchd when loading a job or jobs.
Does NOT reflect the current state of the job on the running system.
Query launchd for the presence of the job using the launchctl(1) list subcommand or use the ServiceManagement framework's SMJobCopyDictionary() method.

Conveys a default value, which maybe changed with -w of launchctl load and unload subcommands which do not modify the configuration file,
only use this key if the provided on-demand and KeepAlive criteria are insufficient to describe the conditions under which job needs to run. The cost to have a job loaded in launchd is negligible, so there is no harm in loading a job which only runs once or rarely.

UserName string  
GroupName string If UserName is set and GroupName is not, the the group will be set to the default group of the user.
inetdCompatibility dictionary expect to run as if it were launched from inetd.
Wait bool corresponds to the "wait" or "nowait" option of inetd.
true: the listening socket is passed via the standard in/out/error file descriptors.
false: accept(2) is called on behalf of the job, and the result is passed via the standard in/out/error descriptors.
LimitLoadToHardware
LimitLoadFromHardware
LimitLoadToHosts array of strings applies to the hosts listed with this key. set kern.hostname in sysctl.conf(5)
LimitLoadFromHosts array of strings applies to hosts NOT listed with this key. set kern.hostname in sysctl.conf(5)
LimitLoadToSessionType string applies to sessions of the type specified (ex:
<key>LimitLoadToSessionType</key>
     <array>
     <string>Aqua</string>      <string>Background</string>      <string>LoginWindow</string>
     </array>

Used with -S to launchctl.
EnableTransactions bool uses vproc_transaction_begin(3) and vproc_transaction_end(3) to track outstanding transactions that need to be reconciled before the process can safely terminate.
If there are outstanding transactions launchd should avoid sending kill
OnDemand bool was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was true. been deprecated and replaced in 10.5 KeepAlive .
KeepAlive bool or
 dictionary of stuff
true:   unconditionally keep the job alive.
false: only demand will start the job.
Default : false

Dictionary of conditions to selectively control wether the job is keep alive(restarted) or not.
If multiple keys are provided, launchd ORs them, thus providing maximum flexibility to the job to refine the logic and stall if necessary.
If launchd finds no reason to restart the job, it falls back on demand based invocation.
Jobs that exit quickly and frequently when configured to be kept alive will be throttled to converve system resources.

SuccessfulExit bool true:  job will be restarted if program exits with a status of zero.
     i.e. job succeded last time, run it again, if failed don't start it again

false: job will be restarted … not zero.
     i.e. job failed; run it again maybe inputs or conditions have changed and it will work this time.
      job was sucessful(finally(?)) don't start it again.

Implies RunAtLoad since the job needs to run at least once to can get an exit status.

NetworkState bool true:  will be kept alive as long as the network is up,
i.e. at least one non-loopback interface being up and having IPv4 or IPv6 addresses .
false: will be kept alive as long as the network is down.

PathState dictionary of bool keep alive if: keys are file-system paths.
true:  job will be kept alive as long as the path exists.
false: job will be kept alive if the path does NOT exist.
The intent is that jobs may create semaphores in the file-system .
OtherJobEnabled dictionary of bools keys are the label of another job.
true:  job is kept alive as long as that other job is enabled.
false: job is kept alive as long as the other job is disabled.
Not to be used instead of IPC.
CrashedJob will be restarted if exited due to sigILL, sigSEGV *… +CAUTION+
RunAtLoad bool job is launched once at the time the job is loaded. default false.
RootDirectory string a directory to chroot(2) to before running
WorkingDirectory string chdir(2) to before running .
EnvironmentVariables
  dictionary of strings
additional environmental variables set before running .
UserEnvironmentVariables
  dictionary of strings
additional environmental variables set before running .
Umask decimalInteger hugh? ed passed to umask(2) before running .
TimeOut seconds idle time out. default will be supplied by launchd for use by the job at check in time. (deprecated)
ExitTimeOut seconds time launchd waits before sending sigKILL. Default: 20 seconds, zero is (poorly) interpreted as infinity.
ThrottleInterval integer seconds minimun before respawn. Default: 10 seconds.
The principle behind this is that jobs should linger around in memory in case they are needed in the near future. reduces the latency of responses, encourages developers to amortize the cost of program invocation.
InitGroups bool whether initgroups(3) should be called before running . Default: true . UserName must be set.
WatchPaths array of strings started if any one of the listed paths are modified.
QueueDirectories array of strings like WatchPaths watchs for modifications, if the path is a directory and not empty.
StartOnMount bool start when a filesystem is mounted.
StartInterval seconds started every N seconds.
If the system is asleep, the job will be started the next time the computer wakes up.
Job will be started only once if system was sleeping when interval elapsed.
StartCalendarInterval dictionary of integers or array of dictionary of integers started every calendar interval . Missing arguments are considered to be wildcard.
The semantics are much like crontab(5). Unlike cron which skips job invocations when the computer is asleep, launchd will start the job the next ?? Job will be started only once if syhstem was sleeping when scheduled.
<key>Minute</key><integer>mm</integer> … Hour integer Day integer Month integer Weekday integer 0 and 7 are Sunday
StandardInPath string stdin
StandardOutPath string <key>StandardOutPath</key>  <string>/var/log/label.out</string>
StandardErrorPath string <key>StandardErrorPath</key><string>/var/log/label.err</string>
Debug bool launchd adjust log mask temporarily to LOG_DEBUG
WaitForDebugger bool launchd instructs kernel to have the job wait for a debugger to attach before any code in the job is executed.
SoftResourceLimits dictionary of integers
HardResourceLimits dictionary of integers Resource limits. These adjust variables set with setrlimit(2).
  • Core bytes largest core file that may be created.
  • CPU seconds maximum cpu time
  • Data bytes maximum size of the data segment, defines how far a program may extend its break with sbrk(2)
  • FileSize bytes largest size file created.
  • MemoryLock bytes maximum lock into memory using mlock(2)
  • NumberOfFiles integer maximum number of open files .
    Setting this value in a system wide daemon will set the sysctl(3) kern.maxfiles (SoftResourceLimits) or kern.maxfilesperproc (HardResourceLimits) value in addition to the setrlimit(2) values.
  • NumberOfProcesses integer maximum simultaneous processes for this user id. Setting this value in a system wide daemon will set the sysctl(3) kern.maxproc (SoftResourceLimits) or kern.maxprocperuid (HardResourceLimits) value in addition to the setrlimit(2) values.
  • ResidentSetSize bytes maximum a process's resident set size may grow. This imposes a limit on the amount of physical memory to be given to a process; if memory is tight, the system will prefer to take memory from processes that are exceeding their declared resident set size.
  • Stack bytes maximum of stack segment ; this defines how far a program's stack segment may be extended. Stack extension is performed automatically by the system.
ProcessType string describes, at a high level, the intended purpose of the job.
The system will apply resource limits based on what kind of job it is.
Default: system will apply light resource limits to the job, throttling its CPU usage and I/O bandwidth.
  • Background generally processes that do work that was not directly requested by the user. The resource limits applied are intended to prevent them from disrupting the user experience.
  • Standard equivalent to no ProcessType being set.
  • Adaptive move between the Background and Interactive classifications based on activity over XPC connections. See xpc_transaction_begin(3)
  • Interactive Critical to maintaining a responsive user experience, run with the same resource limitations as apps, i.e. none.
    should only be used if an app's ability to be responsive depends on it, and cannot be made Adaptive.
LegacyTimers bool Default: timers created by launchd jobs are coalesced. Batching the firing of timers with similar deadlines improves the overall energy efficiency of the system.
If this key is set to true, timers created by the job will opt into less efficient but more precise behavior and not be coalesced with other timers.
AbandonProcessGroup bool true: do NOT kill processes with the same process group if this job dies.
Default: when a job dies, launchd kills any remaining processes with the same process group ID as the job.
Nice integer value should be applied to the daemon.
<key>Nice</key> <integer>10</integer> <!-- slow down -->
LowPriorityIO bool <key>LowPriorityIO</key> <true/> <!-- slow down -->
LaunchOnlyOnce bool Job can only be run once, i.e. the job cannot be safely respawned without a reboot.
MachServices dictionary of bools or a dictionary of dictionaries to be registered with the Mach bootstrap sub-system.
Each key in this dictionary should be the name of service to be advertised.
The value of the key must be a bool and set to true.
A dictionary can be used instead of a simple true value.
MachServiceLookupPolicies
  • ResetAtClose bool If false, the port is recycled, thus leaving clients to remain oblivious to the demand nature of job.
    If true, clients receive port death notifications when the job lets go of the receive right.
    Not all clients may be able to handle this behavior.

    The port will be recreated atomically with respect to bootstrap_look_up() calls, so that clients can trust that after receiving a port death notification, the new port will have already been recreated.
    default: false.
  • HideUntilCheckIn bool Reserve the name in the namespace, but cause bootstrap_look_up() to fail until the job has checked in with launchd.
    Finally, for the job itself, the values will be replaced with Mach ports at the time of check-in with launchd.
Sockets dictionary of dictionaries... OR dictionary of array of dictionaries... demand sockets that can be used to let launchd know when to run the job.
The job must check-in to get a copy of the file descriptors using APIs outlined in launch(3).
The keys of the top level Sockets dictionary can be anything. for the application developer to use to differentiate which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS...). At check-in time, the value of each Sockets dictionary key will be an array of descriptors.
Daemon/Agent writers should consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents a different networking protocol which conforms to the criteria specified in the job configuration file.
    inputs to call getaddrinfo(3).
  • SockType string default stream other valid values: dgram and seqpacket .
  • SockPassive bool whether listen(2) or connect(2) should be called on the created file descriptor.
    Default: true ("to listen").
  • SockNodeName string node to connect(2) or bind(2) to.
  • SockServiceName string service on the node to connect(2) or bind(2) to.
  • SockFamily string request that "IPv4" or "IPv6" socket(s) be created.
  • SockProtocol string protocol to be passed to socket(2). TCP
  • SockPathName string set to "Unix". It specifies the path to connect(2) or bind(2) to.
  • SecureSocketWithKey string variant of SockPathName.
    Instead of binding to a known path, a securely generated socket is created and the path is assigned to the environment variable that is inherited by all jobs spawned by launchd.
  • SockPathMode DECIMALinteger mode of the socket.
  • Bonjour bool or string or array of strings request the service be registered with mDNSResponder(8).
    If the value is bool, the service name is inferred from SockServiceName.
  • MulticastGroup string request that the datagram socket join a multicast group.
    If hostname, getaddrinfo(3) will be used to join the correct multicast address for a given socket family.
    If an explicit IPv4 or IPv6 address is given,
    SockFamily family must be set

Dependencies

No explicit dependency model. Interdependencies are expected to be solved through the use of IPC. It is therefore in the best interest of a job developer who expects dependents to define all of the sockets in the configuration file. Making it possible to start the job based on demand instead.

Example XML property lists

The following XML Property List simply keeps "exampled" running continuously:
      <?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">
           <var>dict>
                <key>Label</key> <var>string</var>com.example.exampled</string>
                <key>ProgramArguments</key>
                <array>
                     <var>string</var>exampled</string>
                </array>
                <key>KeepAlive</key> <true/>
           </dict>
           </plist>

FILES

~/Library/LaunchAgents Per-user agents provided by the user.
/Library/LaunchAgents Per-user agents provided by the administrator.
/Library/LaunchDaemons System-wide daemons provided by the administrator.
/System/Library/LaunchAgents Per-user agents provided by Mac OS X.
/System/Library/LaunchDaemons System-wide daemons provided by Mac OS X.
git hub looks authoritatice.