macOS daemons and agents: what changed

Revision 1 to 2. 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	71		<thead>
72	72
73	73		</thead>
74	74		<tbody>
75	75
76	76		(Except in a very limited way using IOSurface)</td>
77	77
78	78		</tbody>
79	79
80	80		* Login items are started by the per-user instance of launchd, but it does not take any actions to manage them.
81	81
82	82		## Creating a launchd property list file
83	83
84	84		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	85
86	86		\| Key \| Description \|
87	87		\|----\|----\|
88	88		\| Label \| Contains a unique string that identifies your daemon to launchd. (required) \|
89	89		\| ProgramArguments \| Contains the arguments used to launch your daemon. The first argument is the absolute path to your program executable. (required) \|
90	90		\| 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	91		\| 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	92		\| 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	93		\| 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	94
95	95		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	96
97	97		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	98
99	99		\| Directory \| Description \|
100	100		\|----\|----\|
101	101		\| `~/Library/LaunchAgents` \| Per-user agents provided by the user. \|
102	102		\| `/Library/LaunchAgents` \| Per-user agents provided by the administrator. \|
103	103		\| `/Library/LaunchDaemons` \| System-wide daemons provided by the administrator. \|
104	104		\| `/System/Library/LaunchAgents` \| Per-user agents provided by macOS. \|
105	105		\| `/System/Library/LaunchDaemons` \| System-wide daemons provided by macOS. \|
106	106
107	107		The appropriate location for the executable program that you launch as your background process is `/usr/local/libexec/`.
108	108
109	109		## Writing daemon code
110	110
111	111		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	112
113	113		### Mandatory
114	114
115	115		- 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	116
117	117		- 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	118
119	119		- 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	120
121	121		### Recommended
122	122
123	123		- 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	124
125	125		- 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	126
127	127		- Provide a handler to catch the SIGTERM signal sent by launchd to shut down your daemon.
128	128
129	129		### Not recommended
130	130
131	131		- 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	132
133	133		- Do not set the working directory. Include the WorkingDirectory key in your daemon’s configuration property list file instead.
134	134
135	135		- Do not call chroot to change the root directory. Include the RootDirectory key in your daemon’s configuration property list file instead.
136	136
137	137		- Do not call setsid to create a new session.
138	138
139	139		- Do not close any stray file descriptors.
140	140
141	141		- 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	142
143	143		- Do not set up resource limits with setrusage. Use the SoftResourceLimits and HardResourceLimit keys in your daemon’s configuration property list file instead.
144	144
145	145		- 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	146
147	147		## Examples
148	148
149	149		### Launch Daemon to run a script as a user on a schedule
150	150
151	151		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	152
153	153		``` xml
154	154		<?xml version="1.0" encoding="UTF-8"?>
155	155		<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
156	156		<plist version="1.0">
157	157		<dict>
158	158		<key>Label</key>
159	159		<string>my_daemon.job</string>
160	160		<key>UserName</key>
161	161		<string>username</string>
162	162		<key>WorkingDirectory</key>
163	163		<string>/Users/username/work_dir</string>
164	164		<key>EnvironmentVariables</key>
165	165		<dict>
166	166		<key>PATH</key>
167	167		<string>/Users/username/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin</string>
168	168		<key>SHELL</key>
169	169		<string>/bin/sh</string>
170	170		</dict>
171	171		<key>LowPriorityBackgroundIO</key>
172	172		<true/>
173	173		<key>Nice</key>
174	174		<integer>10</integer>
175	175		<key>Program</key>
176	176		<string>/Users/username/bin/my_daemon.sh</string>
177	177		<key>StandardErrorPath</key>
178	178		<string>/Users/username/tmp/my_daemon.stderr</string>
179	179		<key>StandardOutPath</key>
180	180		<string>/Users/username/tmp/my_daemon.stdout</string>
181	181		<key>StartCalendarInterval</key>
182	182		<dict>
183	183		<key>Hour</key>
184	184		<integer>11</integer>
185	185		<key>Minute</key>
186	186		<integer>0</integer>
187	187		</dict>
188	188		</dict>
189	189		</plist>
190	190		```
191	191
192	192		An explanation of the above file:
193	193
194	194		Line 1: The XML prolog
195	195
196	196		Line 2: The XML DTD for property list files
197	197
198	198		Line 6: A unique name identifying this job
199	199
200	200		Line 8: The username under which to run the job
201	201
202	202		Line 10: Directory to change to before running the job
203	203
204	204		Line 14: The path environment variable to use to find commands used in the script
205	205
206	206		Line 16: The shell to use
207	207
208	208		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	209
210	210		Line 21: Sets the scheduling priority of this job to 10 (-20 = highest; 20 = lowest)
211	211
212	212		Line 23: The script to run
213	213
214	214		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	215
216	216		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	217
218	218		Line 31: The hour at which to start the job every day
219	219
220	220		Line 33: The minute at which to start the job every day (if omitted, the job would run every minute!)
221	221
222	222		Here is the example `my_daemon.sh` script (referenced in the property list file above) to be executed:
223	223
224	224		``` bash
225	225		#!/bin/sh
226	226		date
227	227		svn up
228	228		date
229	229		```
230	230
231	231		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	232
233	233		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	234
235	235		To start the job:
236	236
237		-	~~`$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist`~~
	237	+	```text
	238	+	$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist
	239	+	```
238	240
239	241		To stop the job from executing any more:
240	242
241		-	~~`$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist`~~
	243	+	```text
	244	+	$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist
	245	+	```
242	246
243	247		## Launch daemon to run a TCP server
244	248
245	249		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.
246	250
247	251		``` xml
248	252		<?xml version="1.0" encoding="UTF-8"?>
249	253		<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
250	254		<plist version="1.0">
251	255		<dict>
252	256		<key>Label</key>
253	257		<string>my_daemon</string>
254	258		<key>ProgramArguments</key>
255	259		<array>
256	260		<string>/usr/local/bin/my_daemon.sh</string>
257	261		</array>
258	262		<key>RunAtLoad</key>
259	263		<true/>
260	264		<key>StandardErrorPath</key>
261	265		<string>/Users/username/tmp/my_daemon.stderr</string>
262	266		<key>StandardOutPath</key>
263	267		<string>/Users/username/tmp/my_daemon.stdout</string>
264	268		</dict>
265	269		</plist>
266	270		```
267	271
268	272		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.
269	273
270	274		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:
271	275
272		-	~~` $ telnet macmini8 12345`\~~
273		-	~~` Trying 192.168.1.21...`\~~
274		-	~~` Connected to macmini8.sentry.org.`\~~
275		-	~~` Escape character is '^]'.`\~~
276		-	~~` Hello Pascal World!`\~~
277		-	~~` Connection closed by foreign host.`~~
	276	+	```text
	277	+	$ telnet macmini8 12345
	278	+	Trying 192.168.1.21...
	279	+	Connected to macmini8.sentry.org.
	280	+	Escape character is '^]'.
	281	+	Hello Pascal World!
	282	+	Connection closed by foreign host.
	283	+	```
278	284
279	285		In the absence of telnet on macOS, you can use nc (netcat):
280	286
281		-	~~` $ nc localhost 12345`\~~
282		-	~~` Hello Pascal World!`\~~
283		-	~~` $`~~
	287	+	```text
	288	+	$ nc localhost 12345
	289	+	Hello Pascal World!
	290	+	$
	291	+	```
284	292
285	293		``` pascal
286	294		//
287	295		// Heavily based on forum member leledumbo's TCP server at http://pascalgeek.blogspot.com/2012/06/
288	296		//
289	297
290	298		Program my_daemon;
291	299
292	300		{$mode objfpc}{H+}
293	301
294	302		Uses
295	303		cThreads, // needed to handle each client in its own thread
296	304		Classes,
297	305		SysUtils,
298	306		Sockets,
299	307		fpSock, // see note
300	308		fpAsync,
301	309		BaseUnix;
302	310
303	311		Type
304	312
305	313		{ Client handler thread }
306	314
307	315		TClientHandlerThread = class(TThread)
308	316		private
309	317		FClientStream: TSocketStream;
310	318		public
311	319		constructor Create(AClientStream: TSocketStream);
312	320		procedure Execute; override;
313	321		end;
314	322
315	323		{ TCP server - override constructor to hook when a client connects }
316	324
317	325		TTestServer = class(TTCPServer)
318	326		private
319	327		procedure TestOnConnect(Sender: TConnectionBasedSocket; AStream: TSocketStream);
320	328		public
321	329		constructor Create(AOwner: TComponent); override;
322	330		end;
323	331
324	332		{ Helper to obtain and save IP and port as a string }
325	333
326	334		function AddrToString(Addr: TSockAddr): String;
327	335		begin
328	336		Result := NetAddrToStr(Addr.sin_addr) + ':' + IntToStr(Addr.sin_port);
329	337		end;
330	338
331	339		{ TClientHandlerThread }
332	340
333	341		constructor TClientHandlerThread.Create(AClientStream: TSocketStream);
334	342		begin
335	343		inherited Create(false);
336	344		FreeOnTerminate := true;
337	345		FClientStream := AClientStream;
338	346		end;
339	347
340	348		procedure TClientHandlerThread.Execute;
341	349		begin
342	350		try
343	351		FClientStream.WriteAnsiString('Hello Pascal World!' + LineEnding);
344	352		WriteLn(AddrToString(FClientStream.PeerAddress) + ' connected');
345	353		except
346	354		on e: EStreamError do begin
347	355		WriteLn('EStreamError');;
348	356		end;
349	357		end;
350	358
351	359		WriteLn(AddrToString(FClientStream.PeerAddress) + ' disconnected');
352	360		FClientStream.Free;
353	361		end;
354	362
355	363		{ TTestServer }
356	364
357	365		procedure TTestServer.TestOnConnect(Sender: TConnectionBasedSocket; AStream: TSocketStream);
358	366		begin
359	367		WriteLn('Incoming connection from ' + AddrToString(AStream.PeerAddress));
360	368		TClientHandlerThread.Create(AStream);
361	369		end;
362	370
363	371		constructor TTestServer.Create(AOwner: TComponent);
364	372		begin
365	373		inherited;
366	374		OnConnect := @TestOnConnect;
367	375		end;
368	376
369	377		{ main }
370	378
371	379		var
372	380		ServerEventLoop: TEventLoop;
373	381
374	382		begin
375	383		ServerEventLoop := TEventLoop.Create;
376	384		with TTestServer.Create(nil) do
377	385		begin
378	386		EventLoop := ServerEventLoop;
379	387		Port := 12345;
380	388		WriteLn('Serving...');
381	389		Active := true;
382	390		EventLoop.Run;
383	391		end;
384	392		end.
385	393		```
386	394
387	395		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.
388	396
389	397		The `my_daemon` executable file should be copied to `/usr/local/bin/` and should be owned by root and not group or world writable.
390	398
391	399		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:
392	400
393	401		``` bash
394	402		#!/bin/sh
395	403		/usr/local/bin/my_daemon
396	404		```
397	405
398	406		To start the TCP server, execute:
399	407
400		-	~~`$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist`~~
	408	+	```text
	409	+	$ sudo launchctl load /Library/LaunchDaemons/my_daemon.plist
	410	+	```
401	411
402	412		To stop the TCP server, execute:
403	413
404		-	~~`$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist`~~
	414	+	```text
	415	+	$ sudo launchctl unload /Library/LaunchDaemons/my_daemon.plist
	416	+	```
405	417
406	418		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.
407	419
408	420		## See also
409	421
410	422		- [[Daemons and Services\|Cross-platform daemons and services]].
411	423
412	424		## External links
413	425
414	426		- [Apple: Technical Note: Daemons and Agents](https://developer.apple.com/library/archive/technotes/tn2083/_index.html).
415	427		- [Apple: Daemons and Services Programming Guide](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html).
416	428
417	429		---
418	430		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).
419	431		Category: Code
420	432		Category: Tutorials
421	433		Category: macOS

Back to history