[apple/launchd.git] / launchd / src / launchd.plist.5

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