macOS daemons and agents: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(macOS only)
2	2
3	3		## Overview
4	4
5	5		UNIX-based operating systems have daemons or programs that run as background processes in the system context (eg named - the Internet Domain Name Server which is a daemon responsible for resolving domain name queries). Daemons are therefore better described as system background processes and should not have a graphical user interface. They are system-wide background processes of which there is only one instance for all clients.
6	6
7	7		Agents are very similar to daemons in that they are both programs that run as background processes, but in the case of agents they are not running in the system context but in the context of an interactive user's session. Agents are therefore better described as user background processes and may have a graphical user interface or communicate with the user through the macOS system menu bar (eg temperature monitors generally display the status in the system menu bar). They are per-user background processes.
8	8
9	9		Daemons and agents are each useful in their own right, but each has its own specific use cases. jobs that rely on system-level access should be run as daemons in the system context and jobs that do not require system-level access should be run as agents in the user's context.
10	10
11	11		Note: in the rest of this article the generic term daemon will be used to refer to both daemons and agents unless required otherwise by the context.
12	12
13	13		launchd is the macOS system-wide and per-user daemon manager which is started by the kernel during the system boot process. It manages processes, both for the system as a whole and for individual users. launchd provides the following benefits to daemon developers:
14	14
15	15		- Simplifies the process of making a daemon by handling many of the standard housekeeping chores normally associated with launching a daemon.
16	16		- Provides system administrators with a central place to manage daemons on the system.
17	17		- Supports inetd-style daemons.
18	18		- Eliminates the primary reason for running daemons as root. Because launchd runs as root, it can create low-numbered TCP/IP listen sockets and hand them off to the daemon.
19	19		- Simplifies error handling and dependency management for inter-daemon communication. As daemons can be launched on demand, communication requests do not fail if the daemon is not launched. They are simply delayed until the daemon can launch and process them.
20	20
21	21		## The launchd startup process
22	22
23	23		After the system is booted and the kernel is running, launchd is run to finish the system initialization. As part of that initialization, it goes through the following steps:
24	24
25	25		- Loads the parameters for each launch-on-demand system-level daemon from the property list files found in `/System/Library/LaunchDaemons/` and `/Library/LaunchDaemons/`.
26	26		- Registers the sockets and file descriptors requested by those daemons.
27	27		- Launches any daemons that requested to be running all the time.
28	28		- As requests for a particular service arrive, it launches the corresponding daemon and passes the request to it.
29	29		- When the system shuts down, it sends a SIGTERM signal to all of the daemons that it started.
30	30
31	31		The process for per-user agents is similar. When a user logs in, a per-user launchd is started. It does the following:
32	32
33	33		- Loads the parameters for each launch-on-demand user agent from the property list files found in `/System/Library/LaunchAgents/`, `/Library/LaunchAgents/`, and the user’s individual `~/Library/LaunchAgents/` directory.
34	34		- Registers the sockets and file descriptors requested by those user agents.
35	35		- Launches any user agents that requested to be running all the time.
36	36		- As requests for a particular service arrive, it launches the corresponding user agent and passes the request to it.
37	37		- When the user logs out, it sends a SIGTERM signal to all of the user agents that it started.
38	38
39	39		As launchd registers the sockets and file descriptors used by all daemons before it launches any of them, daemons can be launched in any order. If a request comes in for a daemon that is not yet running, the requesting process is suspended until the target daemon finishes launching and responds.
40	40
41	41		If a daemon does not receive any requests over a specific period of time, it can choose to shut itself down and release the resources it holds. When this happens, launchd monitors the shutdown and makes a note to launch the daemon again when future requests arrive.
42	42
43	43		## launchctl
44	44
45	45		launchctl is the primary interface to launchd which, among other things, allows the administrator or user to load or unload daemons or agents. Where possible, it is preferred that background jobs are launched on demand, based on criteria specified in their respective [[macOS property list files\|property list files]].
46	46
47	47		Some of the useful commands available include:
48	48
49	49		\| Command \| Description \|
50	50		\|----\|----\|
51	51		\| `launchctl list` \| List loaded jobs \|
52	52		\| `launchctl list <LABEL>` \| List information about this loaded job from its .plist file. \|
53	53		\| `launchctl load /Library/LaunchDaemons/<LABEL>.plist` \| Load and start a job (system daemon) that is not disabled. \|
54	54		\| `launchctl load -w /Library/LaunchDaemons/<LABEL>.plist` \| Load, start and mark a job as not disabled (system daemon). Job restarts on next reboot. \|
55	55		\| `launchctl unload /Library/LaunchDaemons/<LABEL>.plist` \| Unload and stop a job (system daemon). Job restarts on next boot. \|
56	56		\| `launchctl unload -w /Library/LaunchDaemons/<LABEL>.plist` \| Unload, stop and disable a job (system daemon). Job does not restart on next reboot. \|
57	57		\| `launchctl start <LABEL>` \| Start a loaded job. Useful when debugging. \|
58	58		\| `launchctl stop <LABEL>` \| Stop a loaded job. Job may restart immediately if configured to keep running. \|
59	59		\| `launchctl restart <LABEL>` \| Restart a loaded job. \|
60	60
61	61		Note: The commands listed above, while documented as "legacy", are simpler to use than the more complicated replacement commands. For the full details, open an Application \> Utilities \> Terminal and type `man launchctl` at the prompt to access the UNIX manual page.
62	62
63	63		## Types of background processes
64	64
65	65		There are four types of background processes in macOS. To select the appropriate type of background process, consider the following:
66	66
67	67		- Whether it does something for the currently logged in user or for all users.
68	68		- Whether it will be used by single application or by multiple applications.
69	69		- Whether it ever needs to display a user interface or launch a GUI application.
70	70
71		-	~~<thead>~~
72		-
73		-	~~</thead>~~
74		-	~~<tbody>~~
75		-
76		-	~~(Except in a very limited way using IOSurface)</td>~~
77		-
78		-	~~</tbody>~~
	71	+	\| Type \| Managed by launchd? \| Runs in \| Can present UI? \|
	72	+	\|---\|---\|---\|---\|
	73	+	\| Login item \| No* \| Per user context \| Yes \|
	74	+	\| XPC service \| Yes \| Per user context \| No · (Except in a very limited way using IOSurface) \|
	75	+	\| Launch Daemon \| Yes \| System-wide context \| No \|
	76	+	\| Launch Agent \| Yes \| Per user context \| Best practice: Not recommended \|
79	77
80	78		* Login items are started by the per-user instance of launchd, but it does not take any actions to manage them.
81	79
82	80		## Creating a launchd property list file
83	81
84	82		To run your daemon under launchd, you must provide a configuration property list file for it. This file contains information about your daemon, including the list of sockets or file descriptors it uses to process requests. Specifying this information in a property list file lets launchd register the corresponding file descriptors and launch your daemon only after a request arrives for your daemon’s services. The required and recommended keys for all daemons are:
85	83
86	84		\| Key \| Description \|
87	85		\|----\|----\|
88	86		\| Label \| Contains a unique string that identifies your daemon to launchd. (required) \|
89	87		\| ProgramArguments \| Contains the arguments used to launch your daemon. The first argument is the absolute path to your program executable. (required) \|
90	88		\| inetdCompatibility \| Indicates that your daemon requires a separate instance per incoming connection. This causes launchd to behave like inetd, passing each daemon a single socket that is already connected to the incoming client. (required if your daemon was designed to be launched by inetd; otherwise, must not be included) \|
91	89		\| 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. \|
92	90		\| StartInterval \<integer\> \| Optional key causes the job to be started every N seconds. If the computer is asleep, the job will be started the next time it wakes up. If multiple intervals occur before the computer wakes, those events will be coalesced into one event. \|
93	91		\| KeepAlive \| This key specifies whether your daemon launches on-demand or must always be running. It is recommended that you design your daemon to be launched on-demand and for this reason this key defaults to false. \|
94	92
95	93		The full list of keys for daemon property lists may be found in the online UNIX manual page for `launchd.plist` which you can access by opening an Application \> Utilities \> Terminal window and typing `man launchd.plist` at the prompt.
96	94
97	95		The [[macOS property list files\|property list file]] is structured the same for both daemons and agents. You indicate whether it describes a daemon or agent by the directory you place it in. Property list files describing daemons are installed in `/Library/LaunchDaemons/`, and those describing agents are installed in `/Library/LaunchAgents/` or in the individual user's `~/Library/LaunchAgents/` subdirectory. The following table lists these directories and describes their correct usage:
98	96
99	97		\| Directory \| Description \|
100	98		\|----\|----\|
101	99		\| `~/Library/LaunchAgents` \| Per-user agents provided by the user. \|
102	100		\| `/Library/LaunchAgents` \| Per-user agents provided by the administrator. \|
103	101		\| `/Library/LaunchDaemons` \| System-wide daemons provided by the administrator. \|
104	102		\| `/System/Library/LaunchAgents` \| Per-user agents provided by macOS. \|
105	103		\| `/System/Library/LaunchDaemons` \| System-wide daemons provided by macOS. \|
106	104
107	105		The appropriate location for the executable program that you launch as your background process is `/usr/local/libexec/`.
108	106
109	107		## Writing daemon code
110	108
111	109		Processes that are managed by launchd must follow certain requirements so that they interact properly with it. This includes launch daemons and launch agents.
112	110
113	111		### Mandatory
114	112
115	113		- You must provide a property list file with some basic launch-on-demand criteria for your daemon. See Creating a launchd Property List File.
116	114
117	115		- You must not daemonize your process. No calling any daemon function, fork followed by exec, or fork followed by exit. If you do, launchd will consider your process has died. Depending on your property list key settings, launchd will either keep trying to relaunch your process until it gives up with a "respawning too fast" error or will be unable to restart it if it really does die.
118	116
119	117		- Daemons and agents that are installed globally must be owned by the root user. Agents installed for the current user must be owned by that user. All daemons and agents must not be group or world writable.
120	118
121	119		### Recommended
122	120
123	121		- Wait until your daemon is fully initialized before attempting to process requests. Your daemon should always provide a reasonable response (rather than an error) when processing requests.
124	122
125	123		- Register the sockets and file descriptors used by your daemon in your launchd configuration property list file. If your daemon advertises a socket, check-in with launchd as part of your daemon initialization using the launch_activate_socket() function call.
126	124
127	125		- Provide a handler to catch the SIGTERM signal sent by launchd to shut down your daemon.
128	126
129	127		### Not recommended
130	128
131	129		- Do not set the user or group ID for your daemon. Include the UserName, UID, GroupName, or GID keys in your daemon’s configuration property list file instead.
132	130
133	131		- Do not set the working directory. Include the WorkingDirectory key in your daemon’s configuration property list file instead.
134	132
135	133		- Do not call chroot to change the root directory. Include the RootDirectory key in your daemon’s configuration property list file instead.
136	134
137	135		- Do not call setsid to create a new session.
138	136
139	137		- Do not close any stray file descriptors.
140	138
141	139		- Do not change stdio to point to /dev/null. Include the StandardOutPath or StandardErrorPath keys in your daemon’s configuration property list file instead.
142	140
143	141		- Do not set up resource limits with setrusage. Use the SoftResourceLimits and HardResourceLimit keys in your daemon’s configuration property list file instead.
144	142
145	143		- Do not set the daemon priority with setpriority. Use the nice, ProcessType, LowPriorityIO, LowPriorityBackgroundIO, nice keys in your daemon’s configuration property list file instead.
146	144
147	145		## Examples
148	146
149	147		### Launch Daemon to run a script as a user on a schedule
150	148
151	149		Here is an example of a [[macOS property list files\|property list file]] for a system-wide daemon which runs a script as a specific user at 11 o'clock every morning. It will run even when there is no user logged in to the computer provided that the computer is operating.
152	150
153	151		``` xml
154	152		<?xml version="1.0" encoding="UTF-8"?>
155	153		<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
156	154		<plist version="1.0">
157	155		<dict>
158	156		<key>Label</key>
159	157		<string>my_daemon.job</string>
160	158		<key>UserName</key>
161	159		<string>username</string>
162	160		<key>WorkingDirectory</key>
163	161		<string>/Users/username/work_dir</string>
164	162		<key>EnvironmentVariables</key>
165	163		<dict>
166	164		<key>PATH</key>
167	165		<string>/Users/username/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
168	166		<key>SHELL</key>
169	167		<string>/bin/sh</string>
170	168		</dict>
171	169		<key>LowPriorityBackgroundIO</key>
172	170		<true/>
173	171		<key>Nice</key>
174	172		<integer>10</integer>
175	173		<key>Program</key>
176	174		<string>/Users/username/bin/my_daemon.sh</string>
177	175		<key>StandardErrorPath</key>
178	176		<string>/Users/username/tmp/my_daemon.stderr</string>
179	177		<key>StandardOutPath</key>
180	178		<string>/Users/username/tmp/my_daemon.stdout</string>
181	179		<key>StartCalendarInterval</key>
182	180		<dict>
183	181		<key>Hour</key>
184	182		<integer>11</integer>
185	183		<key>Minute</key>
186	184		<integer>0</integer>
187	185		</dict>
188	186		</dict>
189	187		</plist>
190	188		```
191	189
192	190		An explanation of the above file:
193	191
194	192		Line 1: The XML prolog
195	193
196	194		Line 2: The XML DTD for property list files
197	195
198	196		Line 6: A unique name identifying this job
199	197
200	198		Line 8: The username under which to run the job
201	199
202	200		Line 10: Directory to change to before running the job
203	201
204	202		Line 14: The path environment variable to use to find commands used in the script
205	203
206	204		Line 16: The shell to use
207	205
208	206		Line 19: Tells the kernel to consider this daemon to be low priority when doing filesystem I/O when throttled with a background classification
209	207
210	208		Line 21: Sets the scheduling priority of this job to 10 (-20 = highest; 20 = lowest)
211	209
212	210		Line 23: The script to run
213	211
214	212		Line 25: The path to the file to which to map the the job's stdout (Useful for debugging; the file is created if it does not exist. If omitted, output is directed to /dev/null.)
215	213
216	214		Line 27: The path to the file to which to map the the job's stderr (Useful for debugging; the file is created if it does not exist. If omitted, output is directed to /dev/null.)
217	215
218	216		Line 31: The hour at which to start the job every day
219	217
220	218		Line 33: The minute at which to start the job every day (if omitted, the job would run every minute!)
221	219
222	220		Here is the example `my_daemon.sh` script (referenced in the property list file above) to be executed:
223	221
224	222		``` bash
225	223		#!/bin/sh
226	224		date
227	225		svn up
228	226		date
229	227		```
230	228
231	229		which just prints the date and time, updates the source code in the Subversion repository in `work_dir` and prints the date and time again. The standard output is captured in the `my_daemon.stdout` file and any error output is captured in the `my_daemon.stderr` file. On subsequent runs, these files will be appended to and not overwritten.
232	230
233	231		The property list file should be copied to the `/Library/LaunchDaemons/` directory and the file should be owned by root and not group or world writable.
234	232
235	233		To start the job:
236	234
237	235		```text
238	236		$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist
239	237		```
240	238
241	239		To stop the job from executing any more:
242	240
243	241		```text
244	242		$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist
245	243		```
246	244
247	245		## Launch daemon to run a TCP server
248	246
249	247		Here is an example of a property list file for a system-wide daemon which runs a TCP server. It will run even when there is no user logged in to the computer provided that the computer is operating.
250	248
251	249		``` xml
252	250		<?xml version="1.0" encoding="UTF-8"?>
253	251		<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
254	252		<plist version="1.0">
255	253		<dict>
256	254		<key>Label</key>
257	255		<string>my_daemon</string>
258	256		<key>ProgramArguments</key>
259	257		<array>
260	258		<string>/usr/local/bin/my_daemon.sh</string>
261	259		</array>
262	260		<key>RunAtLoad</key>
263	261		<true/>
264	262		<key>StandardErrorPath</key>
265	263		<string>/Users/username/tmp/my_daemon.stderr</string>
266	264		<key>StandardOutPath</key>
267	265		<string>/Users/username/tmp/my_daemon.stdout</string>
268	266		</dict>
269	267		</plist>
270	268		```
271	269
272	270		The property list file should be copied to the `/Library/LaunchDaemons/` directory and the file should be owned by root and not group or world writable.
273	271
274	272		This is a simple TCP server daemon which simply prints "Hello Pascal World!" when a client connects to the server's port 12345; after printing that message the server then disconnects the client. For example, with telnet on FreeBSD:
275	273
276	274		```text
277	275		$ telnet macmini8 12345
278	276		Trying 192.168.1.21...
279	277		Connected to macmini8.sentry.org.
280	278		Escape character is '^]'.
281	279		Hello Pascal World!
282	280		Connection closed by foreign host.
283	281		```
284	282
285	283		In the absence of telnet on macOS, you can use nc (netcat):
286	284
287	285		```text
288	286		$ nc localhost 12345
289	287		Hello Pascal World!
290	288		$
291	289		```
292	290
293	291		``` pascal
294	292		//
295	293		// Heavily based on forum member leledumbo's TCP server at http://pascalgeek.blogspot.com/2012/06/
296	294		//
297	295
298	296		Program my_daemon;
299	297
300	298		{$mode objfpc}{H+}
301	299
302	300		Uses
303	301		cThreads, // needed to handle each client in its own thread
304	302		Classes,
305	303		SysUtils,
306	304		Sockets,
307	305		fpSock, // see note
308	306		fpAsync,
309	307		BaseUnix;
310	308
311	309		Type
312	310
313	311		{ Client handler thread }
314	312
315	313		TClientHandlerThread = class(TThread)
316	314		private
317	315		FClientStream: TSocketStream;
318	316		public
319	317		constructor Create(AClientStream: TSocketStream);
320	318		procedure Execute; override;
321	319		end;
322	320
323	321		{ TCP server - override constructor to hook when a client connects }
324	322
325	323		TTestServer = class(TTCPServer)
326	324		private
327	325		procedure TestOnConnect(Sender: TConnectionBasedSocket; AStream: TSocketStream);
328	326		public
329	327		constructor Create(AOwner: TComponent); override;
330	328		end;
331	329
332	330		{ Helper to obtain and save IP and port as a string }
333	331
334	332		function AddrToString(Addr: TSockAddr): String;
335	333		begin
336	334		Result := NetAddrToStr(Addr.sin_addr) + ':' + IntToStr(Addr.sin_port);
337	335		end;
338	336
339	337		{ TClientHandlerThread }
340	338
341	339		constructor TClientHandlerThread.Create(AClientStream: TSocketStream);
342	340		begin
343	341		inherited Create(false);
344	342		FreeOnTerminate := true;
345	343		FClientStream := AClientStream;
346	344		end;
347	345
348	346		procedure TClientHandlerThread.Execute;
349	347		begin
350	348		try
351	349		FClientStream.WriteAnsiString('Hello Pascal World!' + LineEnding);
352	350		WriteLn(AddrToString(FClientStream.PeerAddress) + ' connected');
353	351		except
354	352		on e: EStreamError do begin
355	353		WriteLn('EStreamError');;
356	354		end;
357	355		end;
358	356
359	357		WriteLn(AddrToString(FClientStream.PeerAddress) + ' disconnected');
360	358		FClientStream.Free;
361	359		end;
362	360
363	361		{ TTestServer }
364	362
365	363		procedure TTestServer.TestOnConnect(Sender: TConnectionBasedSocket; AStream: TSocketStream);
366	364		begin
367	365		WriteLn('Incoming connection from ' + AddrToString(AStream.PeerAddress));
368	366		TClientHandlerThread.Create(AStream);
369	367		end;
370	368
371	369		constructor TTestServer.Create(AOwner: TComponent);
372	370		begin
373	371		inherited;
374	372		OnConnect := @TestOnConnect;
375	373		end;
376	374
377	375		{ main }
378	376
379	377		var
380	378		ServerEventLoop: TEventLoop;
381	379
382	380		begin
383	381		ServerEventLoop := TEventLoop.Create;
384	382		with TTestServer.Create(nil) do
385	383		begin
386	384		EventLoop := ServerEventLoop;
387	385		Port := 12345;
388	386		WriteLn('Serving...');
389	387		Active := true;
390	388		EventLoop.Run;
391	389		end;
392	390		end.
393	391		```
394	392
395	393		Note: The unit `fpSock` is currently not being compiled for macOS. You will need to copy it from `/usr/local/share/fpcsrc/3.x.x/packages/fcl-net/src/fpsock.pp` to your project directory and then substitute SO_NOSIGPIPE for MSG_NOSIGNAL in the two places where it occurs in that file. Now when you compile your project it should be found, compiled and linked.
396	394
397	395		The `my_daemon` executable file should be copied to `/usr/local/bin/` and should be owned by root and not group or world writable.
398	396
399	397		The script `/usr/local/bin/my_daemon.sh` (referenced in the property list file above) for Launchd to start the Pascal TCP server daemon executable is:
400	398
401	399		``` bash
402	400		#!/bin/sh
403	401		/usr/local/bin/my_daemon
404	402		```
405	403
406	404		To start the TCP server, execute:
407	405
408	406		```text
409	407		$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist
410	408		```
411	409
412	410		To stop the TCP server, execute:
413	411
414	412		```text
415	413		$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist
416	414		```
417	415
418	416		A confession: This is not the recommended method of launching a TCP server. In theory, the socket name (port) should be listed in the property list file and the macOS launch_activate_socket() function call should take care of setting up the socket. Unfortunately, while I have managed to get launch_activate_socket() working in C, I have so far failed to translate it successfully into Pascal. In the meantime, this somewhat inelegant workaround (using a script to launch the TCP server) works.
419	417
420	418		## See also
421	419
422	420		- [[Daemons and Services\|Cross-platform daemons and services]].
423	421
424	422		## External links
425	423
426	424		- [Apple: Technical Note: Daemons and Agents](https://developer.apple.com/library/archive/technotes/tn2083/_index.html).
427	425		- [Apple: Daemons and Services Programming Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
428	426
429	427		---
430	428		From the Free Pascal wiki, page "macOS daemons and agents", as it stood on 2021-05-04 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
431	429		Category: Code
432	430		Category: Tutorials
433	431		Category: macOS

Back to history