]> git.saurik.com Git - apple/launchd.git/blame - launchd/src/launchd.plist.5
launchd-106.14.tar.gz
[apple/launchd.git] / launchd / src / launchd.plist.5
CommitLineData
e91b9f68
A
1.Dd September 30, 2004
2.Dt launchd.plist 5
3.Os Darwin
4.Sh NAME
5.Nm launchd.plist
6.Nd System wide and per-user daemon/agent configuration files
7.Sh DESCRIPTION
8This document details the parameters that can be given to an XML property list that can be loaded into
9.Nm launchd
10with
11.Nm launchctl .
12.Sh EXPECTATIONS
13Daemons or agents managed by
14.Nm launchd
15are expected to behave certain ways.
16.Pp
17A daemon or agent launched by
18.Nm launchd
19MUST NOT do the following in the process directly launched by
20.Nm launchd :
21.Pp
22.Bl -bullet -offset indent -compact
23.It
24.Xr fork 2
25and have the parent process
26.Xr exit 3
27or
28.Xr _exit 2 .
29.It
30Call
31.Xr daemon 3
32.El
33.Pp
34A daemon or agent launched by
35.Nm launchd
36SHOULD NOT do the following as a part of their startup initialization:
37.Pp
38.Bl -bullet -offset indent -compact
39.It
40Setup the user ID or group ID.
41.It
42Setup the working directory.
43.It
44.Xr chroot 2
45.It
46.Xr setsid 2
47.It
48Close "stray" file descriptors.
49.It
50Change
51.Xr stdio 3
52to /dev/null.
53.It
54Setup resource limits with
55.Xr setrusage 2 .
56.It
57Setup priority with
58.Xr setpriority 2 .
59.It
60Ignore the SIGTERM signal.
61.El
62.Pp
63A daemon or agent launched by
64.Nm launchd
65SHOULD:
66.Pp
67.Bl -bullet -offset indent -compact
68.It
69Launch on demand given criteria specified in the XML property list.
70More information can be found in
71.Xr launch 3 .
72.It
73Catch the SIGTERM signal.
74.El
75.Sh XML PROPERTY LIST KEYS
76The follow keys can be used to describe the configuration details of your daemon or agent.
77Property lists files are expected to have their name end in ".plist" but that is not strictly required.
78.Pp
79.Bl -ohang
80.It Sy Label <string>
81This required key uniquely identifies the job to
82.Nm launchd .
83.It Sy Disabled <boolean>
84This optional key is used to disable your job. The default is false.
85.It Sy UserName <string>
86This optional key specifies the user to run the job as. The default is the user who submitted the job to
87.Nm launchd .
88.It Sy GroupName <string>
89This optional key specifies the user to run the job as. The default is the group of the user who submitted the job to
90.Nm launchd .
91.It Sy inetdCompatibility <dictionary>
92The presence of this key specifies that the daemon expects to be run as if it were launched from
93.Xr inetd 8 .
ab36757d 94This flag is incompatible with the ServiceIPC key.
e91b9f68
A
95.Bl -ohang -offset indent
96.It Sy Wait <boolean>
97This flag corresponds to the "wait" or "nowait" option of
98.Xr inetd 8 .
99.El
100.It Sy ProgramArguments <array of strings>
101This required key maps to the second argument of
102.Xr execvp 3 .
103.It Sy Program <string>
104This optional key maps to the first argument of
105.Xr execvp 3 .
106If this key is missing, then the first element of the array of strings provided to the ProgramArguments will be used instead.
107.It Sy OnDemand <boolean>
108This optional key is used to control whether your job is launched based on demand or to be kept continuously running. The default is true.
109.It Sy RunAtLoad <boolean>
110This optional key is used to control whether your job is launched once at the time the job is loaded. The default is false.
111.It Sy RootDirectory <string>
112This optional key is used to specific a directory to
113.Xr chroot 2
114to before running the job.
115.It Sy WorkingDirectory <string>
116This optional key is used to specific a directory to
117.Xr chdir 2
118to before running the job.
119.It Sy ServiceDescription <string>
120This optional key is used to specify a human readable description of the purpose of the job.
121.It Sy EnvironmentVariables <dictionary of strings>
122This optional key is used to specify additional environmental variables to be setup before running the job.
123.It Sy Umask <integer>
124This optional key specifies what value should be passed to
125.Xr umask 2
126before running the job.
127.It Sy ServiceIPC <boolean>
128This optional key specifies whether the job participates in advanced communication with
129.Nm launchd .
ab36757d 130The default is false. This flag is incompatible with the inetdCompatibility key.
e91b9f68
A
131.It Sy TimeOut <integer>
132The recommended time out to pass to the job. If no value is specified, a default time out will be supplied by
133.Nm launchd
134for use by the job at check in time.
135.It Sy InitGroups <boolean>
136This optional key specifies whether the job should have
137.Xr initgroups 3
ab36757d 138be called before running the job.
e91b9f68
A
139The default is false.
140.It Sy WatchPaths <array of strings>
141This optional key causes the job to be started if any one of the listed paths are modified.
142.It Sy QueueDirectories <array of strings>
143Much 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.
144.It Sy StartInterval <integer>
145This optional key causes the job to be started every N seconds.
ab36757d
A
146If the system is asleep, the job will be started the next time the computer
147wakes up. If multiple intervals transpire before the computer is woken, those
148events will be coalesced into one event upon wake from sleep.
e91b9f68
A
149.It Sy StartCalendarInterval <dictionary of integers>
150This 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
ab36757d
A
151.Xr crontab 5 .
152Unlike cron which skips job invocations when the computer is asleep, launchd
153will start the job the next time the computer wakes up. If multiple intervals
154transpire before the computer is woken, those events will be coalesced into one
155event upon wake from sleep.
e91b9f68
A
156.Bl -ohang -offset indent
157.It Sy Minute <integer>
158The minute on which this job will be run.
159.It Sy Hour <integer>
160The hour on which this job will be run.
161.It Sy Day <integer>
162The day on which this job will be run.
163.It Sy Weekday <integer>
164The weekday on which this job will be run (0 and 7 are Sunday).
165.It Sy Month <integer>
166The month on which this job will be run.
167.El
168.It Sy StandardOutPath <string>
169This optional key specifies what file should be used for data being sent to stdout when using
170.Xr stdio 3 .
171.It Sy StandardErrorPath <string>
172This optional key specifies what file should be used for data being sent to stderr when using
173.Xr stdio 3 .
174.It Sy Debug <boolean>
175This optional key specifies that
176.Nm launchd
177should adjust its log mask temporarily to LOG_DEBUG while dealing with this job.
e91b9f68
A
178.It Sy SoftResourceLimits <dictionary of integers>
179.It Sy HardResourceLimits <dictionary of integers>
180Resource limits to be imposed on the job. These adjust variables set with
181.Xr setrlimit 2 .
182The following keys apply:
183.Bl -ohang -offset indent
184.It Sy Core <integer>
185The largest size (in bytes) core file that may be created.
186.It Sy CPU <integer>
187The maximum amount of cpu time (in seconds) to be used by each process.
188.It Sy Data <integer>
189The maximum size (in bytes) of the data segment for a process; this defines how far a program may extend its break with the
190.Xr sbrk 2
191system call.
192.It Sy FileSize <integer>
193The largest size (in bytes) file that may be created.
194.It Sy MemoryLock <integer>
195The maximum size (in bytes) which a process may lock into memory using the
196.Xr mlock 2
197function.
198.It Sy NumberOfFiles <integer>
199The maximum number of open files for this process.
200.It Sy NumberOfProcesses <integer>
201The maximum number of simultaneous processes for this user id.
202.It Sy ResidentSetSize <integer>
203The maximum size (in bytes) to which a process's resident set size may grow.
204This imposes a limit on the amount of physical memory to be given to a process;
205if memory is tight, the system will prefer to take memory from processes that
206are exceeding their declared resident set size.
207.It Sy Stack <integer>
208The maximum size (in bytes) of the stack segment for a process; this defines
209how far a program's stack segment may be extended. Stack extension is
210performed automatically by the system.
211.El
212.It Sy Nice <integer>
213This optional key specifies what
214.Xr nice 3
215value should be applied to the daemon.
216.It Sy LowPriorityIO <boolean>
217This optional key specifies whether the kernel should consider this daemon to be low priority when doing file system I/O.
ab36757d 218.It Sy Sockets <dictionary of dictionaries... OR dictionary of array of dictionaries...>
e91b9f68
A
219This optional key is used to specify launch on demand sockets that can be used to let
220.Nm launchd
221know when to run the job. The job can check-in and get a copy of the file descriptors using APIs outlined in
222.Xr launch 3 .
ab36757d
A
223The keys of the top level Sockets dictionary can be anything. They are meant for the application developer to use to
224differentiate different which descriptors correspond to which application level protocols (e.g. http vs. ftp vs. DNS...).
225At check in time, the value of each Sockets dictionary key will be an array of descriptors. Daemon/Agent writers should
226consider all descriptors of a given key to be to be effectively equivalent, even though each file descriptor likely represents
227a different networking protocol which conforms to the criteria specified in the job configuration file.
228.Pp
e91b9f68
A
229The paramters below are used as inputs to call
230.Xr getaddrinfo 3 .
231.Bl -ohang -offset indent
232.It Sy SockType <string>
233This optional key tells
234.Nm launchctl
235what type of socket to create. The default is "stream" and other valid values for this key
236are "dgram" and "seqpacket" respectively.
237.It Sy SockPassive <boolean>
238This optional key specifies whether
239.Xr listen 2
240or
241.Xr connect 2
242should be called on the created file descriptor. The default is true ("to listen").
243.It Sy SockNodeName <string>
244This optional key specifies the node to
245.Xr connect 2
246or
247.Xr bind 2
248to.
249.It Sy SockServiceName <string>
250This optional key specifies the service on the node to
251.Xr connect 2
252or
253.Xr bind 2
254to.
255.It Sy SockFamily <string>
256This optional key can be used to specifically request that "IPv4" or "IPv6" socket(s) be created.
257.It Sy SockProtocol <string>
258This optional key specifies the protocol to be passed to
259.Xr socket 2 .
260The only value understood by this key at the moment is "TCP".
261.It Sy SockPathName <string>
262This optional key implies SockFamily is set to "Unix". It specifies the path to
263.Xr connect 2
264or
265.Xr bind 2
266to.
aa59983a
A
267.It Sy SockPathMode <integer>
268This optional key specifies the mode of the socket. Known bug: Property lists don't support octal, so please convert the value to decimal.
e91b9f68
A
269.It Sy Bonjour <boolean or string or array of strings>
270This optional key can be used to request that the service be registered with the
271.Xr mDNSResponder 8 .
272If the value is boolean, the service name is inferred from the SockServiceName.
ab36757d
A
273.It Sy MulticastGroup <string>
274This optional key can be used to request that the datagram socket join a multicast group.
275If the value is a hostname, then
276.Xr getaddrinfo 3
277will be used to join the correct multicast address for a given socket family.
278If an explicit IPv4 or IPv6 address is given, it is required that the SockFamily family also be set, otherwise the results are undefined.
e91b9f68
A
279.El
280.El
281.Pp
282.Sh EXAMPLE XML PROPERTY LISTS
283.Pp
284The following XML Property List simply keeps "exampled" running continuously:
285.Pp
286.Dl <?xml version="1.0" encoding="UTF-8"?>
287.Dl <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
288.Dl <plist version="1.0">
289.Dl <dict>
290.Dl <key>Label</key>
291.Dl <string>com.example.exampled</string>
292.Dl <key>ProgramArguments</key>
293.Dl <array>
294.Dl <string>exampled</string>
295.Dl </array>
296.Dl <key>OnDemand</key>
297.Dl <false/>
298.Dl </dict>
299.Dl </plist>
300.Pp
301.Sh FILES
302.Bl -tag -width "/System/Library/LaunchDaemons" -compact
303.It Pa ~/Library/LaunchAgents
304Per-user agents provided by the user.
305.It Pa /Library/LaunchAgents
306Per-user agents provided by the administrator.
307.It Pa /Library/LaunchDaemons
308System wide daemons provided by the administrator.
309.It Pa /System/Library/LaunchAgents
310Mac OS X Per-user agents.
311.It Pa /System/Library/LaunchDaemons
312Mac OS X System wide daemons.
313.El
314.Sh SEE ALSO
315.Xr launchctl 1 ,
316.Xr launch 3 ,
317.Xr launchd 8