launchd.plist(5) BSD File Formats Manual launchd.plist(5)
NAME
launchd.plist -- System wide and per-user daemon/agent configuration files
DESCRIPTION
This document details the parameters that can be given to an XML property list that can be loaded into
launchd with launchctl.
EXPECTATIONS
Daemons or agents managed by launchd are expected to behave certain ways.
A daemon or agent launched by launchd MUST NOT do the following in the process directly launched by
launchd:
oo Call daemon(3).
oo Do the moral equivalent of daemon(3) by calling fork(2) and have the parent process exit(3)
or _exit(2).
A daemon or agent launched by launchd SHOULD NOT do the following as a part of their startup initial-ization: initialization:
ization:
oo Setup the user ID or group ID.
oo Setup the working directory.
oo chroot(2)
oo setsid(2)
oo Close "stray" file descriptors.
oo Change stdio(3) to /dev/null.
oo Setup resource limits with setrusage(2).
oo Setup priority with setpriority(2).
oo Ignore the SIGTERM signal.
A daemon or agent launched by launchd SHOULD:
oo Launch on demand given criteria specified in the XML property list. More information can be
found later in this man page.
oo Catch the SIGTERM signal.
XML PROPERTY LIST KEYS
The follow keys can be used to describe the configuration details of your daemon or agent. Property
lists are Apple's standard configuration file format. Please see plist(5) for more information. Please
note. Property list files are expected to have their name end in ".plist".
Label <string>
This required key uniquely identifies the job to launchd.
Disabled <boolean>
This optional key is used to disable your job. The default is false.
UserName <string>
This optional key specifies the user to run the job as. This key is only applicable when launchd is
running as root.
GroupName <string>
This optional key specifies the group to run the job as. This key is only applicable when launchd is
running as root. If UserName is set and GroupName is not, the the group will be set to the default
group of the user.
inetdCompatibility <dictionary>
The presence of this key specifies that the daemon expects to be run as if it were launched from inetd.
Wait <boolean>
This flag corresponds to the "wait" or "nowait" option of inetd. If true, then the listening
socket is passed via the standard in/out/error file descriptors. If false, then accept(2) is
called on behalf of the job, and the result is passed via the standard in/out/error descriptors.
LimitLoadToHosts <array of strings>
This configuration file only applies to the hosts listed with this key.
LimitLoadFromHosts <array of strings>
This configuration file only applies to hosts NOT listed with this key.
LimitLoadToSessionType <string>
This configuration file only applies to sessions of the type specified. This key is used in concert
with the -S flag to launchctl.
Program <string>
This key maps to the first argument of execvp(3). If this key is missing, then the first element of
the array of strings provided to the ProgramArguments will be used instead. This key is required in
the absence of the ProgramArguments key.
ProgramArguments <array of strings>
This key maps to the second argument of execvp(3). This key is required in the absence of the Program
key. Please note! Many people are confused by this key. Please read execvp(3) very carefully!
EnableGlobbing <boolean>
This flag causes launchd to use the glob(3) mechanism to update the program arguments before invoca-tion. invocation.
tion.
OnDemand <boolean>
This key was used in Mac OS X 10.4 to control whether a job was kept alive or not. The default was
true. This key has been deprecated and replaced in Mac OS X 10.5 with the more powerful KeepAlive
option.
KeepAlive <boolean or dictionary of stuff>
This optional key is used to control whether your job is to be kept continuously running or to let
demand and conditions control the invocation. The default is false and therefore only demand will start
the job. The value may be set to true to unconditionally keep the job alive. Alternatively, a dictio-nary dictionary
nary of conditions may be specified to selectively control whether launchd keeps a job alive 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 <boolean>
If true, the job will be restarted as long as the program exits and with an exit status of zero.
If false, the job will be restarted in the inverse condition. This key implies that "RunAtLoad"
is set to true, since the job needs to run at least once before we can get an exit status.
NetworkState <boolean>
If true, the job will be kept alive as long as the network is up, where up is defined as at least
one non-loopback interface being up and having IPv4 or IPv6 addresses assigned to them. If
false, the job will be kept alive in the inverse condition.
PathState <dictionary of booleans>
Each key in this dictionary is a file-system path. If the value of the key is true, then the job
will be kept alive as long as the path exists. If false, the job will be kept alive in the
inverse condition. The intent of this feature is that two or more jobs may create semaphores in
the file-system namespace.
OtherJobEnabled <dictionary of booleans>
Each key in this dictionary is the label of another job. If the value of the key is true, then
this job is kept alive as long as that other job is enabled. Otherwise, if the value is false,
then this job is kept alive as long as the other job is disabled. This feature should not be
considered a substitute for the use of IPC.
RunAtLoad <boolean>
This optional key is used to control whether your job is launched once at the time the job is loaded.
The default is false.
RootDirectory <string>
This optional key is used to specify a directory to chroot(2) to before running the job.
WorkingDirectory <string>
This optional key is used to specify a directory to chdir(2) to before running the job.
EnvironmentVariables <dictionary of strings>
This optional key is used to specify additional environmental variables to be setup before running the
job.
Umask <integer>
This optional key specifies what value should be passed to umask(2) before running the job. Known bug:
Property lists don't support octal, so please convert the value to decimal.
TimeOut <integer>
The recommended idle time out (in seconds) to pass to the job. If no value is specified, a default time
out will be supplied by launchd for use by the job at check in time.
ExitTimeOut <integer>
The amount of time launchd waits before sending a SIGKILL signal. The default value is 20 seconds. The
value zero is interpreted as infinity.
ThrottleInterval <integer>
This key lets one override the default throttling policy imposed on jobs by launchd. The value is in
seconds, and by default, jobs will not be spawned more than once every 10 seconds. The principle
behind this is that jobs should linger around just in case they are needed again in the near future.
This not only reduces the latency of responses, but it encourages developers to amortize the cost of
program invocation.
InitGroups <boolean>
This optional key specifies whether the job should have initgroups(3) be called before running the job.
The default is true in 10.5 and false in 10.4. This key will be ignored if the UserName key is not set.
WatchPaths <array of strings>
This optional key causes the job to be started if any one of the listed paths are modified.
QueueDirectories <array of strings>
Much like the WatchPaths option, this key will watch the paths for modifications. The difference being
that the job will only be started if the path is a directory and the directory is not empty.
StartOnMount <boolean>
This optional key causes the job to be started every time a filesystem is mounted.
StartInterval <integer>
This optional key causes the job to be started every N seconds. If the system is asleep, the job will
be started the next time the computer wakes up. If multiple intervals transpire before the computer is
woken, those events will be coalesced into one event upon wake from sleep.
StartCalendarInterval <dictionary of integers or array of dictionary of integers>
This optional key causes the job to be started every calendar interval as specified. 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 time the computer wakes
up. If multiple intervals transpire before the computer is woken, those events will be coalesced into
one event upon wake from sleep.
Minute <integer>
The minute on which this job will be run.
Hour <integer>
The hour on which this job will be run.
Day <integer>
The day on which this job will be run.
Weekday <integer>
The weekday on which this job will be run (0 and 7 are Sunday).
Month <integer>
The month on which this job will be run.
StandardOutPath <string>
This optional key specifies what file should be used for data being sent to stdout when using stdio(3).
StandardErrorPath <string>
This optional key specifies what file should be used for data being sent to stderr when using stdio(3).
Debug <boolean>
This optional key specifies that launchd should adjust its log mask temporarily to LOG_DEBUG while
dealing with this job.
WaitForDebugger <boolean>
This optional key specifies that launchd should instruct the 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 to be imposed on the job. These adjust variables set with setrlimit(2). The following
keys apply:
Core <integer>
The largest size (in bytes) core file that may be created.
CPU <integer>
The maximum amount of cpu time (in seconds) to be used by each process.
Data <integer>
The maximum size (in bytes) of the data segment for a process; this defines how far a program may
extend its break with the sbrk(2) system call.
FileSize <integer>
The largest size (in bytes) file that may be created.
MemoryLock <integer>
The maximum size (in bytes) which a process may lock into memory using the mlock(2) function.
NumberOfFiles <integer>
The maximum number of open files for this process.
NumberOfProcesses <integer>
The maximum number of simultaneous processes for this user id.
ResidentSetSize <integer>
The maximum size (in bytes) to which 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 <integer>
The maximum size (in bytes) of the stack segment for a process; this defines how far a program's
stack segment may be extended. Stack extension is performed automatically by the system.
Nice <integer>
This optional key specifies what nice(3) value should be applied to the daemon.
AbandonProcessGroup <boolean>
When a job dies, launchd kills any remaining processes with the same process group ID as the job. Set-ting Setting
ting this key to true disables that behavior.
HopefullyExitsFirst <boolean>
This optional key causes programs to exit earlier during system shutdown. This key exists because some
jobs do more than flush buffers and exit like they're supposed to. The use of this key should be con-sidered considered
sidered a temporary solution until the software can be changed to only flush dirty buffers and then
exit.
HopefullyExitsLast <boolean>
This optional key causes programs to exit later during system shutdown. This key exists because some
jobs don't reference count their clients, and therefore do not know when it is safe to exit. The use of
this key should be considered a temporary solution until the software can be changed to properly refer-ence reference
ence count clients.
LowPriorityIO <boolean>
This optional key specifies whether the kernel should consider this daemon to be low priority when
doing file system I/O.
LaunchOnlyOnce <boolean>
This optional key specifies whether the job can only be run once and only once. In other words, if the
job cannot be safely respawned without a full machine reboot, then set this key to be true.
MachServices <dictionary of booleans or a dictionary of dictionaries>
This optional key is used to specify Mach services 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 boolean and set to true. Alternatively, a dictionary can be used instead of a simple true value.
ResetAtClose <boolean>
If this boolean is false, the port is recycled, thus leaving clients to remain oblivious to the
demand nature of job. If the value is set to true, clients receive port death notifications when
the job lets go of the receive right. The port will be recreated atomically with respect to boot-strap_look_up() bootstrap_look_up()
strap_look_up() calls, so that clients can trust that after receiving a port death notification,
the new port will have already been recreated. Setting the value to true should be done with
care. Not all clients may be able to handle this behavior. The default value is false.
HideUntilCheckIn <boolean>
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...>
This optional key is used to specify launch on 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. They are meant for the appli-cation application
cation developer to use to associate descriptors with their corresponding 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 associated with a given key
to be to be effectively equivalent, even though each file descriptor likely represents a different net-working networking
working protocol which conforms to the criteria specified in the job configuration file.
The parameters below are used as inputs to call getaddrinfo(3).
SockType <string>
This optional key tells launchctl what type of socket to create. The default is "stream" and
other valid values for this key are "dgram" and "seqpacket" respectively.
SockPassive <boolean>
This optional key specifies whether listen(2) or connect(2) should be called on the created file
descriptor. The default is true ("to listen").
SockNodeName <string>
This optional key specifies the node to connect(2) or bind(2) to.
SockServiceName <string>
This optional key specifies the service on the node to connect(2) or bind(2) to.
SockFamily <string>
This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.
SockProtocol <string>
This optional key specifies the protocol to be passed to socket(2). The only value understood by
this key at the moment is "TCP".
SockPathName <string>
This optional key implies SockFamily is set to "Unix". It specifies the path to connect(2) or
bind(2) to.
SecureSocketWithKey <string>
This optional key is a 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 inher-ited inherited
ited by all jobs spawned by launchd.
SockPathMode <integer>
This optional key specifies the mode of the socket. Known bug: Property lists don't support
octal, so please convert the value to decimal.
Bonjour <boolean or string or array of strings>
This optional key can be used to request that the service be registered with the
mDNSResponder(8). If the value is boolean, the service name is inferred from the SockService-Name. SockServiceName.
Name.
MulticastGroup <string>
This optional key can be used to request that the datagram socket join a multicast group. If the
value is a hostname, then 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, it is required that the Sock-Family SockFamily
Family family also be set, otherwise the results are undefined.
DEPENDENCIES
Unlike many bootstrapping daemons, launchd has 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. This has the added bene-fit benefit
fit of making it possible to start the job based on demand instead of immediately.
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">
<dict>
<key>Label</key>
<string>com.example.exampled</string>
<key>ProgramArguments</key>
<array>
<string>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 Mac OS X Per-user agents.
/System/Library/LaunchDaemons Mac OS X System wide daemons.
SEE ALSO
launchctl(1), launch(3), launchd(8), plist(5)
Darwin September 30, 2004 Darwin
|