Repository navigation
Expand file tree
/
Copy pathfreebsd-launchd-service-ordering.html
More file actions
1632 lines (1371 loc) · 97.5 KB
/
Copy pathfreebsd-launchd-service-ordering.html
File metadata and controls
1632 lines (1371 loc) · 97.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>freebsd-launchd: solving service ordering (and the netconfigd path)</title>
<style>
:root {
--fg: #1a1a1a;
--fg-muted: #555;
--bg: #fafaf7;
--accent: #b8472a;
--accent-soft: #f3e7df;
--border: #d8d4c8;
--code-bg: #f0ece2;
--table-stripe: #f4efe5;
--warn: #8a5a00;
--good: #2d6f3b;
--bad: #a23030;
}
* { box-sizing: border-box; }
html { -webkit-text-size-adjust: 100%; }
body {
font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", Helvetica, sans-serif;
color: var(--fg);
background: var(--bg);
line-height: 1.55;
margin: 0;
padding: 0;
}
.wrap {
max-width: 880px;
margin: 0 auto;
padding: 48px 32px 96px;
}
h1 {
font-size: 2.1rem;
line-height: 1.2;
margin: 0 0 8px;
letter-spacing: -0.01em;
}
h2 {
font-size: 1.45rem;
margin: 56px 0 12px;
padding-top: 18px;
border-top: 2px solid var(--border);
letter-spacing: -0.005em;
}
h3 {
font-size: 1.15rem;
margin: 32px 0 10px;
color: var(--accent);
}
h4 {
font-size: 1rem;
margin: 24px 0 6px;
color: var(--fg);
}
p { margin: 0 0 14px; }
ul, ol { margin: 0 0 14px 22px; padding: 0; }
li { margin: 0 0 6px; }
code {
font-family: "SF Mono", Menlo, Consolas, monospace;
font-size: 0.9em;
background: var(--code-bg);
padding: 1px 5px;
border-radius: 3px;
}
pre {
font-family: "SF Mono", Menlo, Consolas, monospace;
font-size: 0.86em;
line-height: 1.5;
background: var(--code-bg);
border: 1px solid var(--border);
border-radius: 4px;
padding: 14px 16px;
overflow-x: auto;
margin: 0 0 14px;
}
pre code {
background: none;
padding: 0;
border-radius: 0;
font-size: inherit;
}
.lede {
font-size: 1rem;
color: var(--fg-muted);
margin: 0 0 28px;
}
.meta {
font-size: 0.85rem;
color: var(--fg-muted);
margin: 0 0 24px;
}
table {
border-collapse: collapse;
width: 100%;
margin: 12px 0 22px;
font-size: 0.94rem;
}
th, td {
text-align: left;
padding: 10px 12px;
border: 1px solid var(--border);
vertical-align: top;
}
th {
background: var(--accent-soft);
font-weight: 600;
}
tr:nth-child(even) td { background: var(--table-stripe); }
.callout {
border-left: 3px solid var(--accent);
background: var(--accent-soft);
padding: 14px 18px;
margin: 18px 0 22px;
border-radius: 0 4px 4px 0;
}
.callout p:last-child { margin-bottom: 0; }
.callout-warn {
border-left-color: var(--warn);
background: #fbf3df;
}
.callout-good {
border-left-color: var(--good);
background: #e8f1e3;
}
.pill {
display: inline-block;
font-size: 0.78rem;
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.04em;
padding: 2px 8px;
border-radius: 10px;
margin-right: 8px;
}
.pill-good { background: #d6ead0; color: var(--good); }
.pill-warn { background: #f4dfbf; color: var(--warn); }
.pill-bad { background: #f0c8c8; color: var(--bad); }
.pill-neutral { background: #ddd; color: #333; }
.toc {
background: white;
border: 1px solid var(--border);
border-radius: 4px;
padding: 18px 24px 14px 36px;
margin: 0 0 36px;
font-size: 0.95rem;
}
.toc h2 {
margin: 0 0 8px;
padding-top: 0;
border-top: none;
font-size: 1rem;
text-transform: uppercase;
letter-spacing: 0.04em;
color: var(--fg-muted);
margin-left: -14px;
}
.toc ol { margin: 0 0 0 6px; }
.toc li { margin-bottom: 4px; }
.toc a { color: var(--fg); text-decoration: none; }
.toc a:hover { text-decoration: underline; }
.footnote {
font-size: 0.85rem;
color: var(--fg-muted);
border-top: 1px solid var(--border);
margin-top: 48px;
padding-top: 16px;
}
.pros-cons {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 14px;
margin: 14px 0 18px;
}
.pros, .cons {
border: 1px solid var(--border);
border-radius: 4px;
padding: 12px 16px;
background: white;
}
.pros { border-left: 3px solid var(--good); }
.cons { border-left: 3px solid var(--bad); }
.pros h4, .cons h4 { margin-top: 0; }
@media (max-width: 600px) {
.pros-cons { grid-template-columns: 1fr; }
.wrap { padding: 24px 18px 64px; }
}
</style>
</head>
<body>
<div class="wrap">
<h1>freebsd-launchd: solving service ordering (and the netconfigd path)</h1>
<p class="lede">Working notes on the cross-service ordering problem on freebsd-launchd — what makes <code>varrun → cron</code>, <code>syslogd</code>-first, <code>dhcpcd</code>-after-<code>kmodloader</code> work declaratively rather than by alphabetical-filename luck. netconfigd is one downstream consumer of the same primitives; the doc walks both layers.</p>
<p class="meta">Companion document to the freebsd-launchd / configd discussion. Written 2026-05-10.</p>
<div class="toc">
<h2>Contents</h2>
<ol>
<li><a href="#background">Background — what we're trying to build, and why this is hard</a></li>
<li><a href="#primer">Primer — the IPC technologies, in plain language</a>
<ol>
<li><a href="#mach">Mach IPC</a></li>
<li><a href="#mig">MIG (Mach Interface Generator)</a></li>
<li><a href="#xpc">XPC</a></li>
<li><a href="#bootstrap">Bootstrap server & <code>MachServices</code></a></li>
<li><a href="#afunix">AF_UNIX sockets</a></li>
<li><a href="#do">GNUstep Distributed Objects</a></li>
</ol>
</li>
<li><a href="#current-state">What's actually in the Gershwin tree today</a></li>
<li><a href="#ordering">Service ordering today, and how each option changes it</a>
<ol>
<li><a href="#services-today">Every launchd plist on the live ISO today</a></li>
<li><a href="#ordering-mech">How ordering actually works today</a></li>
<li><a href="#ordering-fragile">Where the current ordering is fragile</a></li>
<li><a href="#mach-mechanism">What Mach activation actually does, step by step</a></li>
<li><a href="#varrun-cron">The "varrun starts before cron" question, walked through</a></li>
<li><a href="#apple-other">Apple's other ordering primitives (not Mach)</a></li>
<li><a href="#ordering-options">What changes under each option</a></li>
</ol>
</li>
<li><a href="#option-1">Option 1 — Reverse Mach → AF_UNIX inside configd</a></li>
<li><a href="#option-2">Option 2 — Port Mach IPC to FreeBSD</a></li>
<li><a href="#option-3">Option 3 — New Gershwin-native daemon using GNUstep DO</a></li>
<li><a href="#comparison">Side-by-side comparison</a></li>
<li><a href="#decision">Decision framework</a></li>
<li><a href="#recommendation">Recommendation</a></li>
<li><a href="#key-roadmap">The plist-key roadmap: what we have, what we need</a></li>
<li><a href="#risks">Open questions & risks</a></li>
</ol>
</div>
<h2 id="background">1. Background — the service ordering problem (and netconfigd as one consumer)</h2>
<p>The central topic of this document is <strong>cross-service ordering on freebsd-launchd</strong>. The launchd port today recognizes 6 plist keys (<code>Label</code>, <code>Program</code>, <code>ProgramArguments</code>, <code>Disabled</code>, <code>RunAtLoad</code>, <code>KeepAlive</code>) and orders services by alphabetical filename scan. That works coincidentally on the live ISO but breaks the moment any real cross-service dependency has to be expressed:</p>
<ul>
<li><code>cron</code> wants <code>/var/run</code> to exist before writing its PID file. <code>varrun</code> sorts <em>after</em> <code>cron</code> alphabetically. Saved today only by base.txz pre-populating <code>/var/run</code>.</li>
<li><code>syslogd</code> sorts after <code>cron</code> / <code>dhcpcd</code> / <code>kmodloader</code>; their early log lines go to the kernel ring buffer instead of <code>/var/log/messages</code>.</li>
<li><code>dhcpcd</code> sorts before <code>kmodloader</code>, but kmodloader is what loads the NIC drivers. dhcpcd survives only because it watches <code>PF_ROUTE</code> for late-arriving interfaces.</li>
<li>Any future service that depends on another — including a hypothetical netconfigd — has no declarative way to express it.</li>
</ul>
<p>Solving this is the <strong>foundation work</strong> covered in the recommendation (Section 10) and the plist-key roadmap (Section 11). It's mechanical engineering inside <code>core.m</code>: grow the plist key vocabulary — <code>WatchPaths</code>, <code>Sockets</code>, <code>KeepAlive</code> subkeys, <code>LaunchEvents</code> — so dependencies can be declared instead of inferred from filename order.</p>
<p><strong>netconfigd is one downstream consumer of those same primitives.</strong> It's the most-discussed consumer because the gershwin-on-freebsd variant has imported Apple's <code>configd</code> source (<code>configd/src/</code>, version 963.270.3) and a build script (<code>make-configd.sh</code>) intended to produce a daemon called <code>netconfigd</code>. Whether that import actually ships, and in what form, is a real architectural fork (Sections 5–7) — but it sits on top of the ordering work, not parallel to it.</p>
<p>The hard problem inside the netconfigd-specific question: <strong>configd is built end-to-end on Mach IPC</strong>. Every plugin talks to the core via Mach messages; every client (<code>scutil</code>, <code>SCDynamicStore</code> consumers) reaches the daemon via the bootstrap server's Mach port lookup; the modern XPC layer sits on top of Mach. <strong>FreeBSD has no Mach.</strong> So you can compile configd, but you can't run it usefully without doing real work first.</p>
<p>That framework manages, on macOS:</p>
<ul>
<li>Network interface state (which interfaces exist, their IP, link, etc.)</li>
<li>DHCP, IPv6 RA/SLAAC, link-local addressing (the <code>IPConfiguration</code> plugin)</li>
<li>The "dynamic store" — a system-wide key/value database of the current machine state, watchable by any process</li>
<li>Higher-level abstractions like network locations, VPN, proxies, AirDrop discovery</li>
</ul>
<p>This document walks through both layers: the ordering work in the launchd port (Sections 4, 10, 11) and the three netconfigd paths that consume those primitives (Sections 5–7), with cross-references between them.</p>
<h2 id="primer">2. Primer — the IPC technologies, in plain language</h2>
<p>If you're confident on what Mach and DO are, skip ahead to <a href="#current-state">section 3</a>. The other terms — MIG, XPC, bootstrap, AF_UNIX framed messages — are easier to evaluate options against if they're not abstract.</p>
<h3 id="mach">2.1 Mach IPC</h3>
<p>Mach is the kernel's <strong>inter-process communication primitive</strong> on macOS (and on Hurd, NeXTSTEP, and a few research kernels). It's not a library; it's built into the kernel, like FreeBSD's pipes or sockets. Two programs talk by sending each other <strong>messages</strong> — typed, structured data — through <strong>Mach ports</strong>, which are kernel-managed mailboxes.</p>
<p>Concretely, a Mach message exchange looks like:</p>
<pre><code>// Sender
mach_msg_header_t msg;
msg.msgh_remote_port = some_port; // who to send to
msg.msgh_local_port = reply_port; // where reply comes back
msg.msgh_id = 1234; // operation code
mach_msg(&msg, MACH_SEND_MSG, sizeof(msg), 0,
MACH_PORT_NULL, MACH_MSG_TIMEOUT_NONE, MACH_PORT_NULL);
// Receiver, on the other end of some_port:
mach_msg(&msg, MACH_RCV_MSG, 0, sizeof(msg),
my_recv_port, MACH_MSG_TIMEOUT_NONE, MACH_PORT_NULL);</code></pre>
<p>Important properties that distinguish Mach from "just sockets":</p>
<ul>
<li><strong>Ports are first-class kernel objects.</strong> You can transfer port rights — give another process the ability to send to your port — through the message itself, by reference. There's no portable equivalent on FreeBSD; passing file descriptors over Unix sockets is the closest approximation but lacks Mach's send/receive right semantics.</li>
<li><strong>The kernel mediates everything.</strong> Permissions, copy semantics for large messages (vm_copy), out-of-line memory transfer — all kernel features.</li>
<li><strong>It's the OS-wide convention.</strong> On Darwin, <em>everything</em> is built on Mach: IOKit user-client communication, the BSD signal layer, threading primitives, kqueue's <code>EVFILT_MACHPORT</code>, etc.</li>
</ul>
<p><em>Key takeaway: Mach is a kernel feature. "Porting Mach" means either implementing it as a userspace library (slow, semantics partial) or putting it in the FreeBSD kernel (large, invasive).</em></p>
<h3 id="mig">2.2 MIG (Mach Interface Generator)</h3>
<p>Writing raw <code>mach_msg</code> calls is tedious and error-prone, so Apple ships a code generator: <strong>MIG</strong>. You write an interface definition (a <code>.defs</code> file) that looks like an RPC schema:</p>
<pre><code>// SystemConfiguration's actual MIG interface (excerpt from configd):
subsystem config 20000;
routine configopen(
server : mach_port_t;
name : xmlData;
options: xmlData;
out session : mach_port_t;
out status : int);
routine configget(
server : mach_port_t;
key : xmlData;
out value : xmlDataOut;
out status : int);</code></pre>
<p>MIG generates two C files: a client stub (<code>configopen()</code> as a function the caller can use) and a server dispatcher (a switch on <code>msgh_id</code> that calls into your handler). Configd's IPC contract is defined as MIG, and configd's source includes generated stubs for <code>config.defs</code>, <code>shared_dns_info.defs</code>, <code>helper.defs</code>, and several others.</p>
<p><em>Key takeaway: MIG is just a code generator on top of Mach. If you replace Mach, you replace MIG too — every <code>config_user.c</code> / <code>configMIGServer.c</code> stub becomes hand-written transport code.</em></p>
<h3 id="xpc">2.3 XPC</h3>
<p>XPC is Apple's <strong>modern higher-level IPC API</strong>, introduced in Mac OS X 10.7 (2011). It hides Mach behind a friendlier interface:</p>
<pre><code>// XPC client (in configd's nwi/network_information.c):
xpc_connection_t conn = xpc_connection_create_mach_service(
"com.apple.SystemConfiguration.configd",
queue,
XPC_CONNECTION_MACH_SERVICE_PRIVILEGED);
xpc_object_t request = xpc_dictionary_create(NULL, NULL, 0);
xpc_dictionary_set_uint64(request, "cmd", NWI_GET_STATE);
xpc_connection_send_message_with_reply(conn, request, queue,
^(xpc_object_t reply) {
// process reply asynchronously
});</code></pre>
<p>XPC adds:</p>
<ul>
<li><strong>Dictionary-shaped messages</strong> — JSON-like, typed, versionable</li>
<li><strong>Asynchronous, block-based callbacks</strong> integrated with libdispatch</li>
<li><strong>Audit tokens</strong> so the server can identify the calling process</li>
<li><strong>Connection lifecycle</strong> — events for peer death, reconnect, etc.</li>
</ul>
<p>Crucially, XPC <strong>still uses Mach as transport</strong>. <code>xpc_connection_create_mach_service()</code> literally looks up a Mach port via the bootstrap server. Without Mach, XPC has no wire.</p>
<p><em>Key takeaway: XPC and Mach are not separable in Apple's stack. Anything that uses XPC is using Mach underneath.</em></p>
<h3 id="bootstrap">2.4 Bootstrap server & <code>MachServices</code></h3>
<p>How does a client know which Mach port to send to? It asks the <strong>bootstrap server</strong>, a registry that maps human-readable names like <code>com.apple.SystemConfiguration.configd</code> to the kernel port object.</p>
<p>On Apple, the bootstrap server is part of <strong>launchd itself</strong>. When a daemon's plist contains:</p>
<pre><code><key>MachServices</key>
<dict>
<key>com.apple.SystemConfiguration.configd</key>
<true/>
</dict></code></pre>
<p>...launchd does three things:</p>
<ol>
<li>Registers the name <code>com.apple.SystemConfiguration.configd</code> in its bootstrap registry, attaching a Mach port.</li>
<li>When any client calls <code>bootstrap_look_up()</code> with that name, launchd hands them a send right to the port.</li>
<li>If the daemon hasn't started yet, launchd <em>starts it on demand</em> — this is "launch-on-demand activation" — and queues the message until the daemon checks in.</li>
</ol>
<p>This is the dependency-resolution mechanism we don't have. <strong>"Service A depends on service B" on Apple is expressed by service A calling <code>bootstrap_look_up("B")</code></strong>, blocking until launchd has B running.</p>
<p><em>Key takeaway: <code>MachServices</code> in a plist is a request to launchd's bootstrap server. The freebsd-launchd port doesn't implement bootstrap, so the key is silently ignored.</em></p>
<h3 id="afunix">2.5 AF_UNIX sockets</h3>
<p>Unix-domain sockets are FreeBSD's native IPC. They look and act like network sockets (<code>socket()</code>, <code>bind()</code>, <code>connect()</code>, <code>read()</code>, <code>write()</code>), except the address is a filesystem path (<code>/var/run/foo.sock</code>) and the kernel keeps the bytes in memory rather than going over the wire.</p>
<pre><code>// Server
int s = socket(AF_UNIX, SOCK_STREAM, 0);
struct sockaddr_un addr = { .sun_family = AF_UNIX };
strcpy(addr.sun_path, "/var/run/configd.sock");
bind(s, (struct sockaddr*)&addr, sizeof(addr));
listen(s, 5);
int c = accept(s, NULL, NULL);
read(c, buf, sizeof(buf));
// Client
int c = socket(AF_UNIX, SOCK_STREAM, 0);
connect(c, (struct sockaddr*)&addr, sizeof(addr));
write(c, msg, len);</code></pre>
<p>What you give up versus Mach:</p>
<ul>
<li>No port-rights transfer (FD-passing via <code>SCM_RIGHTS</code> is the closest analog and is more limited)</li>
<li>No kernel-managed launch-on-demand</li>
<li>No structured message types — you define your own framing on top of the byte stream</li>
</ul>
<p>What you get in exchange: it works on every Unix, has well-understood semantics, doesn't need any kernel changes, and the file system gives you a natural namespace.</p>
<p><strong>"Framed messages"</strong>, which appears in the freebsd-launchd ipc.c, just means you put a small header (length + opcode) on top of each message so the receiver knows where one ends and the next begins. The launchd port already does this:</p>
<pre><code>// from freebsd-launchd src/src/ipc_proto.c (sketch)
struct msg_hdr {
uint32_t length;
uint32_t cmd;
} __packed;
// Client sends: write(s, &hdr, sizeof hdr); write(s, payload, hdr.length);
// Server reads: read(s, &hdr, sizeof hdr); read(s, payload, hdr.length);</code></pre>
<p>That's the pattern Option 1 would extend to configd: replace MIG-generated <code>mach_msg</code> calls with framed AF_UNIX writes, replace XPC dictionary passing with serialized blobs over the same socket.</p>
<h3 id="do">2.6 GNUstep Distributed Objects (DO)</h3>
<p>DO is a <strong>Foundation-level remote-object system</strong>. Your daemon vends an Objective-C object; another process gets a transparent proxy and calls methods on it as if it were local.</p>
<pre><code>// Server (the daemon)
@interface NCNetworkStore : NSObject
- (NSString *)valueForKey:(NSString *)key;
- (void)setValue:(NSString *)v forKey:(NSString *)k;
@end
NCNetworkStore *store = [[NCNetworkStore alloc] init];
NSConnection *conn = [NSConnection serviceConnectionWithName:@"NCNetworkStore"
rootObject:store];
// Process now serves DO requests on a runloop.
// Client (some other process)
id<NCNetworkStoreProto> proxy =
(id)[NSConnection rootProxyForConnectionWithRegisteredName:@"NCNetworkStore"
host:nil];
NSString *v = [proxy valueForKey:@"State:/Network/Interface/wlan0/IPv4"];</code></pre>
<p>Underneath, DO uses:</p>
<ul>
<li><strong>NSPort</strong> as the transport (<code>NSMessagePort</code> = AF_UNIX local sockets, <code>NSSocketPort</code> = TCP)</li>
<li><strong>NSPortCoder</strong> for serialization (an NSCoder that turns objects into bytes)</li>
<li><strong>gdomap</strong> as the name registry (the daemon already running on Gershwin via <code>org.gnustep.gdomap.plist</code>)</li>
<li><strong>NSRunLoop</strong> for callback dispatch</li>
</ul>
<p>What you get:</p>
<ul>
<li>Transparent proxying — calls look like normal Objective-C method invocations</li>
<li>A well-known Foundation API, with thirty years of GNUstep experience behind it</li>
<li>Already partly in production on Gershwin (gdomap is up, dshelper uses it)</li>
</ul>
<p>What you don't get:</p>
<ul>
<li>The async dictionary-passing semantics of XPC (DO is fundamentally synchronous proxies; you build async on top)</li>
<li>MIG-class performance (NSPortCoder is more general, slower than a generated <code>mach_msg</code> stub)</li>
<li>Source compatibility with Apple's frameworks — no Apple plugin will drop in unmodified onto DO</li>
</ul>
<p><em>Key takeaway: DO is the "Objective-C native" alternative. It pairs well with new code; pairing it with imported Apple C source is awkward.</em></p>
<h2 id="current-state">3. What's actually in the Gershwin tree today</h2>
<p>Three pieces of imported Apple source matter here:</p>
<table>
<thead><tr><th>What</th><th>Version</th><th>State</th></tr></thead>
<tbody>
<tr>
<td><code>src/</code> — launchd</td>
<td>launchd-842.1.4</td>
<td>
Daemon rewritten: Mach RPC server replaced with AF_UNIX framed messages (per <code>ipc.c:11-13</code>).
Recognizes 5 plist keys: Label, Program, ProgramArguments, RunAtLoad, KeepAlive.
No MachServices, no Sockets, no WatchPaths.
<code>liblaunch/liblaunch.c</code> (Apple client lib with Mach hooks) is preserved as source but <strong>not built or linked</strong>.
</td>
</tr>
<tr>
<td><code>configd/src/</code> — configd</td>
<td>configd-963.270.3</td>
<td>
Imported as-is. Still depends on Mach + MIG + XPC throughout. Includes plugin tree (IPMonitor, IPConfiguration, KernelEventMonitor, etc.), SC framework headers, scutil, IPMonitorControl, nwi.
Build script <code>make-configd.sh</code> exists; daemon would be installed as <code>netconfigd</code>.
<strong>Not currently shipped on the live ISO.</strong>
</td>
</tr>
<tr>
<td>GNUstep base</td>
<td>upstream</td>
<td>
In the system domain at <code>/System/Library/</code>.
<code>gdomap</code> runs as <code>org.gnustep.gdomap.plist</code> on Gershwin (per gershwin-on-freebsd repo).
DO infrastructure is operational.
</td>
</tr>
</tbody>
</table>
<p>So: a launchd that doesn't speak Mach, a configd that only speaks Mach, and a parallel DO infrastructure that's already running for other reasons.</p>
<h2 id="ordering">4. Service ordering today, and how each option changes it</h2>
<p>This section is the foundation for evaluating the three options realistically. The question "how does service A wait for service B?" is exactly the question Mach was designed to answer for Apple, and it's the question this launchd port currently handles only by luck.</p>
<h3 id="services-today">4.1 Every launchd plist on the live ISO today</h3>
<p>The complete set, in alphabetical filename order (which is the order the launchd port scans them at boot):</p>
<table>
<thead>
<tr><th>#</th><th>Plist label</th><th>What it does</th><th>Lifecycle</th></tr>
</thead>
<tbody>
<tr>
<td>1</td>
<td><code>org.freebsd.cron</code></td>
<td>Run scheduled tasks from <code>/etc/crontab</code>, <code>/var/cron/tabs/</code>. Self-daemonizes (parent forks + exits, child detaches).</td>
<td>RunAtLoad, KeepAlive=false, <code>cron -s</code></td>
</tr>
<tr>
<td>2</td>
<td><code>org.freebsd.dhcpcd</code></td>
<td>DHCP v4 + v6, RA/SLAAC processing, RTM_NEWLINK hot-plug. Master mode covers all interfaces; recognizes bridge/lagg/vlan layering. Supervises wpa_supplicant for wifi interfaces via its hook.</td>
<td>RunAtLoad, KeepAlive=true, <code>dhcpcd -B</code> (foreground)</td>
</tr>
<tr>
<td>3</td>
<td><code>org.freebsd.dmesg.boot</code></td>
<td>Save kernel ring buffer to <code>/var/log/dmesg.boot</code>. Self-mitigates by <code>mkdir -p /var/log</code> first.</td>
<td>RunAtLoad once, exits</td>
</tr>
<tr>
<td>4</td>
<td><code>org.freebsd.getty.console</code></td>
<td>Spawn getty on <code>/dev/ttyu0</code> (serial console).</td>
<td>RunAtLoad, KeepAlive=true (respawn after each session)</td>
</tr>
<tr>
<td>5</td>
<td><code>org.freebsd.getty.vty0</code></td>
<td>Spawn getty on <code>/dev/ttyv0</code> (VGA console). Wrapper sleeps 24h if device is absent (serial-only hardware).</td>
<td>RunAtLoad, KeepAlive=true</td>
</tr>
<tr>
<td>6</td>
<td><code>org.freebsd.kmodloader</code></td>
<td>Run <code>devmatch(8)</code>, kldload missing drivers for unattached devices in the live device tree. Plus PCI-vendor scan for the radeonkms-vs-amdgpu split.</td>
<td>RunAtLoad once, exits</td>
</tr>
<tr>
<td>7</td>
<td><code>org.freebsd.sysctl</code></td>
<td>Apply <code>/etc/sysctl.conf</code>. No-op on a default live ISO (file is comment-only).</td>
<td>RunAtLoad once, exits</td>
</tr>
<tr>
<td>8</td>
<td><code>org.freebsd.syslogd</code></td>
<td>Drain kernel <code>/dev/klog</code> + Unix socket <code>/var/run/log</code> to <code>/var/log/messages</code>.</td>
<td>RunAtLoad, KeepAlive=true, <code>syslogd -F -ss</code></td>
</tr>
<tr>
<td>9</td>
<td><code>org.freebsd.varrun</code></td>
<td>Defensive one-shot: <code>mkdir /var/run /var/log /var/spool /var/empty</code>, sticky <code>/tmp</code>, touch the standard log files. Replaces conventional <code>rc.d/var</code> + <code>rc.d/cleanvar</code>.</td>
<td>RunAtLoad once, exits</td>
</tr>
</tbody>
</table>
<h3 id="ordering-mech">4.2 How ordering actually works today</h3>
<p>Three mechanisms, in decreasing order of importance:</p>
<ol>
<li>
<strong>Alphabetical filename order.</strong> The launchd port scans <code>/System/Library/LaunchDaemons/</code> in <code>readdir()</code> order, which on UFS is filename-sorted. That's the only ordering primitive the daemon recognizes. <code>org.freebsd.cron.plist</code> < <code>org.freebsd.dhcpcd.plist</code> < ... < <code>org.freebsd.varrun.plist</code> in lexicographic order.
</li>
<li>
<strong>Self-defensive scripts.</strong> Some plists pre-mkdir what they need rather than relying on a previous job. <code>dmesg.boot</code>'s ProgramArguments includes <code>/bin/mkdir -p /var/log</code> exactly because <code>varrun</code> sorts after it. The plist comment notes this explicitly: <em>"Self-sufficient is safer than relying on ordering."</em>
</li>
<li>
<strong>Coincidence with base.txz.</strong> <code>/var/run</code>, <code>/var/log</code>, <code>/var/spool</code> all exist in the unionfs lower because base.txz populated them. <code>varrun</code> creating them again is a no-op on the live ISO. On a system where <code>/var</code> were a fresh tmpfs, the ordering would matter and it would be wrong.
</li>
</ol>
<p>That is the entire ordering toolkit. <code>MachServices</code>, <code>WatchPaths</code>, <code>KeepAlive</code>'s state-predicate subkeys (<code>OtherJobEnabled</code>, <code>PathState</code>, <code>SuccessfulExit</code>), <code>LaunchEvents</code> — none of those are parsed by the daemon. Plists may contain them; they're silently dropped (recall <code>core.m:258-266</code> recognizes only six keys: Label, Program, ProgramArguments, Disabled, RunAtLoad, KeepAlive — all booleans or simple strings/arrays, no nested structure).</p>
<h3 id="ordering-fragile">4.3 Where the current ordering is fragile</h3>
<table>
<thead><tr><th>Hypothetical "want"</th><th>What actually happens today</th></tr></thead>
<tbody>
<tr>
<td>cron wants <code>/var/run/cron.pid</code>; varrun should create <code>/var/run</code> first.</td>
<td>cron sorts before varrun (c < v). On the live ISO this works only because <code>/var/run</code> already exists in base.txz. On a cleaner rootfs, cron's PID-file write would fail.</td>
</tr>
<tr>
<td>syslogd wants to write <code>/var/log/messages</code>; varrun touches it.</td>
<td>varrun runs LAST. syslogd starts first and uses an existing file (saved by base.txz pre-population). On a fresh-/var system, syslogd would get a write error.</td>
</tr>
<tr>
<td>dhcpcd should run after kmodloader so NIC drivers are loaded first.</td>
<td>dhcpcd sorts before kmodloader (d < k). dhcpcd survives because it's in master mode and watches PF_ROUTE for late-arriving interfaces. If it weren't, it would miss the NICs that kmodloader brings up moments later.</td>
</tr>
<tr>
<td>kmodloader's log lines should reach syslogd.</td>
<td>syslogd sorts after kmodloader (k < s). kmodloader's early stderr/syslog calls go to the kernel ring buffer or are dropped. They eventually appear in <code>/var/log/messages</code> because syslogd drains <code>/dev/klog</code> at startup, but they aren't real-time.</td>
</tr>
<tr>
<td>Any service wants config from a hypothetical netconfigd.</td>
<td>No mechanism. Phase 2's netconfigd would have to either be RunAtLoad and assume clients sort after it alphabetically, or implement its own readiness signaling (sentinel file? socket-connect retry loop?). This is exactly what Mach activation solves on Apple.</td>
</tr>
</tbody>
</table>
<p>The current state is "works because the test environment is forgiving." It is not a robust ordering model.</p>
<h3 id="mach-mechanism">4.4 What Mach activation actually does, step by step</h3>
<p>Apple's launchd has one core ordering mechanism — <strong>launch-on-demand activation via the bootstrap server</strong> — plus a few satellite mechanisms (Section 4.6) that handle cases Mach can't.</p>
<p>Here is the complete flow for "daemon B advertises a Mach service; daemon A consumes it":</p>
<h4>Step 1: B's plist declares the service</h4>
<pre><code><key>Label</key>
<string>com.apple.configd</string>
<key>ProgramArguments</key>
<array>
<string>/usr/libexec/configd</string>
</array>
<key>MachServices</key>
<dict>
<key>com.apple.SystemConfiguration.configd</key>
<true/>
</dict>
<!-- Note: NO RunAtLoad. Launch-on-demand is the default with MachServices. --></code></pre>
<h4>Step 2: At launchd startup, launchd registers the name</h4>
<p>Launchd reads B's plist, creates a Mach receive port, and stores the mapping <code>"com.apple.SystemConfiguration.configd" → port</code> in the bootstrap namespace. <strong>Daemon B itself is not running yet.</strong> Launchd holds the receive right; nobody is listening on it.</p>
<h4>Step 3: Daemon A wants to talk to B</h4>
<pre><code>// In A's source:
mach_port_t configd_port;
kern_return_t kr = bootstrap_look_up(bootstrap_port,
"com.apple.SystemConfiguration.configd",
&configd_port);
if (kr != BOOTSTRAP_SUCCESS) { /* error */ }
// A now has a send right to B's port.</code></pre>
<p>This single call has profound consequences:</p>
<ul>
<li>The call goes via Mach to launchd. Launchd checks: is B running? If yes, hand back the existing port. <strong>If no, launchd executes B's <code>ProgramArguments</code> right now, then proceeds.</strong></li>
<li>Launchd returns the send right to A synchronously. From A's source, the dependency is invisible — A is just "looking up a name."</li>
<li>Messages A sends on <code>configd_port</code> queue in the kernel until B is ready. A doesn't have to know whether B is running yet.</li>
</ul>
<h4>Step 4: B claims the receive right</h4>
<pre><code>// In B's startup, after exec'ing /usr/libexec/configd:
mach_port_t my_recv_port;
bootstrap_check_in(bootstrap_port,
"com.apple.SystemConfiguration.configd",
&my_recv_port);
// B can now mach_msg(MACH_RCV) on my_recv_port and process A's messages.</code></pre>
<h4>Why this solves ordering</h4>
<p>The ordering between A and B is now <em>implicit in the IPC contract</em>. There is no "A starts before B" or "B starts before A" configuration anywhere. The actual rule is:</p>
<div class="callout">
<p><strong>B is started exactly when somebody first wants to talk to it. Until then, B doesn't run. Once it's running, anyone who needs to talk to it can.</strong></p>
</div>
<p>This is dependency injection at the OS level. Compared to alphabetical filename ordering: the current scheme requires every plist filename to rank correctly against every other, and breaks silently when a new service is added. Mach activation does away with the ordering question entirely — you don't order, you express what you want, and the bootstrap server resolves it.</p>
<h3 id="varrun-cron">4.5 The "varrun starts before cron" question, walked through</h3>
<p>You asked specifically: <em>"How do we say varrun starts before cron with Mach? Do we modify cron?"</em> The honest answer is: <strong>Mach activation doesn't actually solve this case directly.</strong> Walking through each plausible approach:</p>
<h4>Approach A: Express it as a Mach IPC dependency</h4>
<p>For Mach activation to apply, varrun would need to expose a Mach service. Cron would call <code>bootstrap_look_up("com.gershwin.varrun")</code>. Launchd would start varrun on demand.</p>
<p>This doesn't fit because <strong>varrun is a one-shot</strong>: it creates directories and exits. There is no daemon to register a Mach port, and no IPC for cron to do once it has a port. You'd have to redesign varrun as a long-running daemon that exposes some pointless query interface, just to give cron something to look up. <em>Wrong tool.</em></p>
<p>Cron source modification: yes, you'd have to add the <code>bootstrap_look_up</code> call. But that's an ugly way to express "wait for the filesystem to be ready."</p>
<h4>Approach B: Express it as exit-status dependency (Apple-style, not Mach)</h4>
<p>Apple's launchd has a <code>KeepAlive</code> dictionary with conditional subkeys. The relevant one here:</p>
<pre><code><!-- Cron's plist would add: -->
<key>KeepAlive</key>
<dict>
<key>OtherJobEnabled</key>
<dict>
<key>org.freebsd.varrun</key>
<true/>
</dict>
</dict></code></pre>
<p>This says: "only keep cron loaded while varrun's job has been enabled and successfully run." It's an explicit ordering at the launchd level. <strong>cron source is not modified.</strong></p>
<p>Caveat: this key is not parsed by the freebsd-launchd port today. Adding support for it is a launchd port enhancement, separate from any Mach work.</p>
<h4>Approach C: Express it as filesystem-state dependency (also Apple-style, not Mach)</h4>
<pre><code><!-- Cron's plist would add: -->
<key>WatchPaths</key>
<array>
<string>/var/run</string>
</array></code></pre>
<p>Cron is launched when <code>/var/run</code> exists. <strong>cron source is not modified.</strong> Same caveat: not parsed by this launchd port.</p>
<h4>Approach D: Pragmatic — self-mitigate in the plist</h4>
<p>Change cron's <code>ProgramArguments</code> to <code>/bin/sh -c "/bin/mkdir -p /var/run; exec /usr/sbin/cron -s"</code>. No ordering needed; cron self-mitigates the way <code>dmesg.boot</code> already does (which has the comment: <em>"Self-sufficient is safer than relying on ordering"</em>). Ugly but works today.</p>
<h4>So: do we modify cron?</h4>
<table>
<thead><tr><th>Scenario</th><th>Modify cron?</th><th>Why</th></tr></thead>
<tbody>
<tr>
<td>"varrun before cron" — filesystem-state dependency.</td>
<td><strong>No.</strong></td>
<td>Right tools are launchd-side: <code>KeepAlive { OtherJobEnabled }</code>, <code>WatchPaths</code>. Mach is wrong tool for this case. Pragmatic workaround: self-mitigate in the plist (Approach D).</td>
</tr>
<tr>
<td>"cron consults a config service" — IPC dependency.</td>
<td><strong>Yes.</strong></td>
<td>Cron source calls <code>bootstrap_look_up("com.gershwin.configservice")</code>. The lookup blocks until the service is up. This is where Mach activation shines.</td>
</tr>
</tbody>
</table>
<p>The takeaway: Mach activation is the <em>right</em> answer for IPC-shaped dependencies between long-running daemons. It is the <em>wrong</em> answer for filesystem-state, exit-status, or boot-phase dependencies. Apple's launchd has separate keys for those, all currently absent in the freebsd-launchd port.</p>
<h3 id="apple-other">4.6 Apple's other ordering primitives (the ones that aren't Mach)</h3>
<p>To complete the picture, the keys Apple's launchd recognizes for non-IPC dependencies. <strong>None of these is parsed by the freebsd-launchd port today.</strong></p>
<table>
<thead><tr><th>Key</th><th>What it does</th><th>Use case</th></tr></thead>
<tbody>
<tr>
<td><code>WatchPaths</code></td>
<td>Start the daemon when any of these paths appear or change.</td>
<td>Wait for a directory to exist; pickup of dropped-in config files.</td>
</tr>
<tr>
<td><code>QueueDirectories</code></td>
<td>Like WatchPaths, but only fires when a directory becomes non-empty.</td>
<td>Spool processors, mail queues, log shippers.</td>
</tr>
<tr>
<td><code>KeepAlive { OtherJobEnabled = { ... } }</code></td>
<td>Run only while another job is loaded.</td>
<td>"cron only after varrun"; daemon dependency chains.</td>
</tr>
<tr>
<td><code>KeepAlive { SuccessfulExit = false }</code></td>
<td>Respawn unless the previous instance exited cleanly.</td>
<td>Crash-loop recovery without infinite respawn after intentional exit.</td>
</tr>
<tr>
<td><code>KeepAlive { PathState = { ... } }</code></td>
<td>Run only while a path exists / doesn't exist.</td>
<td>Conditional services tied to filesystem state.</td>
</tr>
<tr>
<td><code>KeepAlive { NetworkState = ... }</code></td>
<td>Run only when network is up.</td>
<td>Network-dependent services (less granular than IPC dep).</td>
</tr>
<tr>
<td><code>LaunchEvents</code></td>
<td>Activate on a notify(3) event.</td>
<td>Generic event-driven activation; configd publishes events for many things.</td>
</tr>
<tr>
<td><code>Sockets</code></td>
<td>Have launchd open the socket(s); fire daemon when a connection arrives. Daemon inherits the listening fd.</td>
<td>Socket-activation pattern; xinetd-style. syslogd's <code>/var/run/log</code> would be the natural example here.</td>
</tr>
<tr>
<td><code>LimitLoadToSessionType</code></td>
<td>Only load in matching sessions (Aqua, Background, LoginWindow).</td>
<td>Distinguishing GUI-session daemons from system daemons.</td>
</tr>
</tbody>
</table>
<p>Apple's launchd has a rich vocabulary for expressing dependencies. <strong>Mach activation is just one mechanism — the most powerful for IPC — and these others fill the gaps for non-IPC cases.</strong> Phase 2 of the launchd port should plan to grow at least <code>WatchPaths</code>, <code>OtherJobEnabled</code>, and <code>Sockets</code> support, alongside whatever IPC story is chosen.</p>
<h3 id="ordering-options">4.7 What changes under each option</h3>
<h4>Option 1 — Reverse Mach → AF_UNIX in configd</h4>
<ul>
<li>The launchd port still doesn't speak Mach. <code>MachServices</code> in plists remains a no-op.</li>
<li>Clients that previously called <code>bootstrap_look_up()</code> instead call <code>connect()</code> on a known socket path (e.g. <code>/var/run/configd.sock</code>) with a retry loop. That retry loop is the AF_UNIX equivalent of waiting for the bootstrap port to be ready.</li>
<li>For ordering between netconfigd and its clients: the connect-with-retry pattern provides "client blocks until daemon ready" semantics. <strong>That is the dependency primitive for IPC.</strong></li>
<li>For ordering between unrelated services (cron, varrun, syslogd): unchanged. Still alphabetical. Fixing this requires implementing <code>WatchPaths</code> / <code>OtherJobEnabled</code> / etc. in <code>core.m</code> — a separate launchd-port enhancement, not part of the configd work.</li>
</ul>
<h4>Option 2 — Port Mach IPC to FreeBSD</h4>
<ul>
<li>You also have to port the bootstrap server (which is part of launchd on Apple). The 6-key plist parser becomes a real launchd that handles <code>MachServices</code> with launch-on-demand activation.</li>
<li>Configd, scutil, IPMonitor, every SC framework consumer just works, because the original Mach activation path is operational.</li>
<li>For non-IPC ordering (varrun before cron): <strong>still need to implement WatchPaths / OtherJobEnabled / etc.</strong> Mach doesn't address this. Option 2 unlocks the IPC half of dependency resolution but leaves the filesystem-state half unsolved. (The good news: with Mach active, the rest of the macOS ecosystem of daemon-coordination tools follows.)</li>
</ul>
<h4>Option 3 — New Gershwin-native daemon using GNUstep DO</h4>
<ul>
<li><code>[NSConnection rootProxyForConnectionWithRegisteredName:host:]</code> is the Foundation equivalent of <code>bootstrap_look_up()</code>. Calling it blocks until the name is registered in gdomap.</li>
<li>A DO daemon publishing the name (via <code>[NSConnection serviceConnectionWithName:rootObject:]</code>) is the equivalent of <code>bootstrap_check_in()</code>.</li>
<li>For IPC-shaped ordering (<code>NCDaemon</code>'s clients), DO gives you the same model Mach gives Apple, just with NSPort instead of mach_port and gdomap instead of the bootstrap server.</li>
<li>For non-IPC ordering: same story as Options 1 and 2. Filesystem-state, exit-status, and boot-phase dependencies are not Foundation things. Need launchd-side support, same as the other options.</li>
</ul>
<div class="callout callout-warn">
<strong>Common thread across all three options:</strong> Mach (and DO, and AF_UNIX socket connect-with-retry) all solve <em>IPC-shaped dependencies</em>. None of them solves filesystem-state dependencies, exit-status dependencies, or boot-phase dependencies. For those, the freebsd-launchd port needs to grow new keys in <code>core.m</code> beyond the current 6 (see <a href="#key-roadmap">section 11</a> for the full inventory). That's a separate work item from the netconfigd question — but it's adjacent, and Phase 2 should plan to tackle both. The <code>varrun</code> ↔ <code>cron</code> ordering is the canonical example of the <em>non-Mach</em> half of the problem.
</div>
<h2 id="option-1">5. Option 1 — Reverse Mach → AF_UNIX inside configd</h2>
<p><span class="pill pill-good">Recommended</span> <span class="pill pill-neutral">Effort: weeks – months</span></p>
<h3>What it actually means</h3>
<p>Apply the same surgery to <code>configd</code> that was already applied to <code>launchd</code>. Specifically:</p>
<ol>
<li><strong>Replace MIG-generated stubs</strong> (<code>config_user.c</code>, <code>configMIGServer.c</code>, <code>shared_dns_infoUser.c</code>, etc.) with hand-written client/server pairs over AF_UNIX. Same shape: a function call on the client becomes a framed write; the server dispatches by opcode.</li>
<li><strong>Replace XPC sites</strong> (<code>nwi/network_information_server.c</code>, <code>libSystemConfiguration/*</code>) with a small wrapper library that imitates the XPC API surface but transports over the same AF_UNIX socket.</li>
<li><strong>Replace <code>bootstrap_look_up()</code></strong> with <code>connect()</code> to a well-known socket path (e.g. <code>/var/run/configd.sock</code>).</li>
<li><strong>Stub or remove Mach-specific features</strong> that have no Unix equivalent: <code>vm_copy</code> for large messages, <code>send_once</code> rights, port-right transfer. Most of configd doesn't use these — they're hot paths in IOKit and the BSD kernel layer, not the SC stack.</li>
</ol>
<h3>What you keep</h3>
<ul>
<li>Configd's plugin model — <code>Plugins/IPMonitor</code>, <code>Plugins/IPConfiguration</code>, <code>Plugins/KernelEventMonitor</code>, etc. They're loaded into the daemon as bundles and talk to each other via the dynamic store, which is configd's own thing (not Mach-dependent).</li>
<li>The <code>SCDynamicStore</code> C client API. Code that uses <code>SCDynamicStoreCreate()</code>, <code>SCDynamicStoreSetValue()</code>, <code>SCDynamicStoreCopyKeyList()</code> keeps working — only the underlying transport changes.</li>
<li><code>scutil</code> as a command-line interface to the store.</li>
<li>The plist-based network configuration on disk (<code>NetworkConfiguration.plist</code>, etc.) — this is just XML.</li>
<li>Future Apple releases of configd: when configd-1000.x ships, you can import the new source and re-apply the same transport patches. There's a precedent — that's exactly the relationship the launchd port has with launchd-842.</li>
</ul>
<h3>What you change</h3>
<ul>
<li>Every <code>mach_msg(...)</code> call site, every MIG stub, every <code>xpc_*</code> call.</li>
<li>Server-side message dispatch: instead of MIG's generated switch on <code>msgh_id</code>, you write your own dispatcher reading framed messages from <code>accept()</code>'d sockets.</li>
<li>Audit tokens and credential checks: replace XPC's audit-token API with <code>SO_PEERCRED</code> / <code>getpeereid()</code> on the Unix socket.</li>
<li>Port-rights transfer: rare in configd, but where it appears (e.g. SCHelper privilege escalation), use FD-passing via <code>SCM_RIGHTS</code> or redesign.</li>
</ul>
<div class="pros-cons">
<div class="pros">
<h4>Pros</h4>
<ul>
<li>Reuses the configd source you already imported — the import wasn't wasted.</li>
<li>Keeps the SC framework's API surface, so Gershwin code that calls SC functions matches what macOS code does.</li>
<li>Mirrors the precedent set by the launchd port. Same pattern, same justification, future contributors find it consistent.</li>
<li>No new kernel work. Everything is userspace.</li>
<li>scutil, IPMonitorControl, nwi, SCMonitor — all the satellite tooling continues to work after the surgery.</li>
<li>Future configd updates can be re-merged with the same transport patches; you stay close to upstream.</li>
</ul>
</div>
<div class="cons">
<h4>Cons</h4>
<ul>
<li>Real work. Configd is ~963 versions of accumulated complexity. The plugin tree alone is dense, and every IPC site has to be touched.</li>
<li>You're essentially writing an XPC-shaped library on top of AF_UNIX. That's not nothing — XPC has connection lifecycle, audit tokens, dictionary serialization, async reply queues. A "good-enough" subset is achievable; full fidelity is a project.</li>
<li>Some Mach features have no clean Unix analog. Where they're load-bearing in configd, you end up redesigning, not just transporting differently.</li>
<li>Debugging the transport layer means understanding both Mach semantics (what configd <em>expects</em>) and AF_UNIX semantics (what you've given it). Two mental models at once.</li>
<li>Apple's plugin source is C with Apple-isms (CoreFoundation idioms, dispatch_queue patterns, reference-counting conventions). Not hard, but you'll be reading it constantly during the rewrite.</li>
</ul>
</div>
</div>
<h3>Concrete time estimate</h3>
<p>Hard to be precise without scoping each plugin individually, but the launchd port (a smaller project — one daemon, one IPC interface) was a multi-month effort. Configd has on the order of 8–12 MIG interfaces, plus XPC sites in the framework client library, plus the helper privilege-escalation bridge. Realistic estimate: <strong>2–4 months of focused work</strong> to a working <code>netconfigd</code> + IPMonitor + IPConfiguration that can DHCP a wired interface. Wireless and IPv6 add more. Polish to match dhcpcd's current behavior is more on top.</p>
<h2 id="option-2">6. Option 2 — Port Mach IPC to FreeBSD</h2>
<p><span class="pill pill-bad">Maximalist</span> <span class="pill pill-neutral">Effort: months – years</span></p>
<h3>What it actually means</h3>
<p>Make FreeBSD speak Mach. Three sub-paths exist, each with prior art:</p>
<ol>
<li>
<strong>Userspace Mach library.</strong> Implement <code>mach_msg</code>, ports, port rights, message queues entirely as a userspace library on top of (probably) AF_UNIX. The library would have to manage port-name allocation, port-right reference counting, message buffering — all the things the kernel does on Darwin. This is what <strong>Darling</strong> does (the macOS compatibility layer for Linux), via a kernel module that emulates Mach syscalls.
<ul>
<li>Reasonable for app-level use; semantics partially diverge under stress (ports outliving processes, IPC across user/kernel boundary, etc.).</li>
<li>Performance is acceptable but not native.</li>
</ul>
</li>
<li>
<strong>Kernel module.</strong> Add Mach as a FreeBSD kernel feature, accessed via a new syscall surface. Closer to native semantics; closer to "actually FreeBSD now has Mach." Far more work; touches the kernel, which means review, security audit, and ongoing maintenance against FreeBSD's release cadence.
</li>
<li>
<strong>Pull GNU Mach.</strong> The Hurd's microkernel <em>is</em> Mach, and there's a userspace Mach implementation lineage (<code>libports</code>, <code>libpager</code>, etc.). In principle reusable. In practice, Hurd Mach has its own dialect and is not a drop-in for Apple's xnu Mach.
</li>
</ol>
<p>All three approaches assume you're willing to ship something that runs <em>unmodified</em> Apple source. That's the entire point of the option.</p>
<h3>What you keep</h3>
<ul>
<li>Apple source compiles and runs unmodified, at least for the parts that don't depend on xnu-specific kernel features beyond Mach.</li>
<li>Future imports become "just a recompile" — no transport patches to maintain.</li>
<li>XPC works, which means a much wider class of Apple components (not just configd) can be ported with reduced effort. CoreServices, NetworkExtension, NSXPCConnection, all become easier targets.</li>
<li>Strategic positioning: Gershwin becomes the FreeBSD-on-which-Apple-source-runs distribution. That's a real differentiator.</li>
</ul>
<h3>What you change</h3>
<ul>
<li>You're now maintaining a Mach implementation. That's a project the size of, say, FreeBSD's CAPSICUM, with a smaller user base and harder testing surface.</li>
<li>Bootstrap server has to be implemented — either as part of the launchd port (rebuilding what was removed) or as a separate daemon.</li>
<li>Edge cases in port-rights semantics are subtle. Reference counting on ports across process exits, send-once rights, no-senders notifications — all behaviors that Apple software relies on without commenting.</li>
<li>Security review surface explodes. Mach historically has had its own class of CVEs (port-stuffing, exception-handler hijacking, etc.). Whatever you ship inherits that surface.</li>
</ul>
<div class="pros-cons">
<div class="pros">
<h4>Pros</h4>
<ul>
<li>Strategic compounding: every future Apple-source port becomes cheaper.</li>
<li>Gershwin can host code that nobody else can host on a non-Apple kernel.</li>
<li>No per-component transport patches to maintain.</li>
<li>Honest engineering: you're not papering over the dependency, you're solving it.</li>
</ul>
</div>
<div class="cons">
<h4>Cons</h4>
<ul>
<li>Massive effort for a payoff that's currently theoretical (no other Gershwin component imminently needs Mach).</li>
<li>Long time-to-first-result. configd doesn't ship until Mach works, and Mach's "works" bar is high.</li>
<li>Maintenance burden continues forever.</li>
<li>If only configd needs Mach, you've built a city to host a single building.</li>
<li>Fragile in subtle ways — port-rights semantics, exception delivery, signal/Mach interaction. Lots of places where Apple code "just works" because xnu does something specific that your reimplementation might or might not.</li>
</ul>
</div>
</div>
<h3>Concrete time estimate</h3>
<p>Userspace Mach with enough fidelity to run configd: <strong>6–12 months minimum</strong>, with a person familiar with both Mach internals and FreeBSD kernel/userspace boundaries. Kernel-module path: <strong>1–2 years</strong>, plus ongoing FreeBSD-version maintenance. Either way, configd doesn't ship for the duration of the Mach project.</p>
<h2 id="option-3">7. Option 3 — New Gershwin-native daemon using GNUstep DO</h2>
<p><span class="pill pill-warn">Smallest scope</span> <span class="pill pill-neutral">Effort: weeks</span></p>
<h3>What it actually means</h3>
<p>Don't port configd. Treat the imported configd source as a reference, and write a fresh Objective-C daemon — call it <code>NCDaemon</code> — that fulfills the same role using GNUstep idioms.</p>
<p>Sketch of the architecture:</p>
<pre><code>// NCDaemon.h
@protocol NCNetworkStoreProto
- (NSDictionary *)copyValueForKey:(NSString *)key;
- (void)setValue:(NSDictionary *)value forKey:(NSString *)key;
- (NSArray *)copyKeyList;
- (void)addObserver:(id<NCNetworkObserverProto>)observer
forKey:(NSString *)key;
@end
@interface NCNetworkStore : NSObject <NCNetworkStoreProto>
@end
// In NCDaemon's main:
NCNetworkStore *store = [[NCNetworkStore alloc] init];
NSConnection *conn = [NSConnection serviceConnectionWithName:@"NCNetworkStore"
rootObject:store];
[[NSRunLoop currentRunLoop] run];
// Plugin equivalents are NSBundle-loaded classes, e.g.:
// /System/Library/NCBundles/IPMonitor.bundle
// /System/Library/NCBundles/IPConfiguration.bundle
// Each registers with the NCNetworkStore on load and posts state changes.</code></pre>
<p>Clients (including a thin <code>SCDynamicStore</code>-shaped C wrapper, if needed for Apple-source porting) call:</p>
<pre><code>// Client side (in some other process)