FreeBSD DiskArbitration — porting plan

A port of Apple's DiskArbitration framework + diskarbitrationd to FreeBSD: disk attach/detach events, mount/unmount/eject coordination, mount-policy approval prompts, and the same DiskArbitration.framework C API that Apple-derived applications already use. Replaces ad-hoc kqueue(EVFILT_FS) polling with a clean event API. Companion to launchd, configd, kmodloader, asl, notifyd, mDNSResponder.

1. Goal & non-goals

1.1 Goal

Provide a working diskarbitrationd + libDiskArbitration on FreeBSD so apps calling the standard DiskArbitration C API (DARegisterDiskAppearedCallback, DARegisterDiskMountApprovalCallback, DADiskUnmount, DADiskEject, DADiskClaim, etc.) work without source modification. Replace the IOKit-based disk-discovery layer with libgeom-based discovery; replace IOKit hot-plug notifications with devctl(4) events; preserve the policy framework that lets apps register mount approval / disapproval callbacks (e.g., disk-encryption tools that want a chance to unlock a disk before it's mounted).

1.2 Non-goals (this iteration)

• No IOKit port. Replace the IOKit layer entirely with FreeBSD-native equivalents (GEOM + devctl). Don't try to port IOKit-without-Mach — that's a configd-scale project on its own.
• No HFS+ / APFS support. FreeBSD doesn't natively mount these filesystems (and shouldn't). DiskArbitration's filesystem-type detection skips them.
• No FileVault / encrypted-volume integration. macOS-specific encryption metadata; FreeBSD has GELI / GBDE / ZFS-native encryption with their own tooling.
• No Spotlight integration. Apple's DiskArbitration triggers Spotlight indexing on mount; we don't ship Spotlight.
• No SetupAssistant hooks. Apple-specific OOBE flow.

2. Repository

Monorepo. Source under diskarb/:

freebsd-launchd/
├── src/                          launchd
├── configd/                      Apple configd
├── kmodloader/                   clean-room kmodloader
├── asl/                          Apple syslog
├── notifyd/                      Apple Libnotify
├── mdns/                         Apple mDNSResponder
├── diskarb/                      Apple DiskArbitration (this plan)
│   ├── scripts/import-source.sh
│   ├── Makefile
│   ├── compat/                   FreeBSD-specific shims (GEOM bridge)
│   └── src/                      forked Apple DiskArbitration-79.3
│       ├── DiskArbitration/      framework (libDiskArbitration.so)
│       ├── DiskArbitrationAgent/ per-user mount-approval prompt agent
│       ├── diskarbitrationd/     the daemon
│       ├── autodiskmount/        legacy automount shim (drop or keep small)
│       ├── datest/               test harness
│       └── Modules/              IOKit hooks (mostly dropped + replaced)
└── make-diskarb.sh               STANDALONE — builds + installs

3. Architecture

3.1 Replacing IOKit with libgeom

Apple's daemon at startup walks the IOKit I/O Registry to find every IOMedia object — that's its source of truth for "what disks exist, what their metadata is, are they whole disks vs partitions, what filesystem type per partition." On FreeBSD we use libgeom:

• geom_gettree(3) returns the live GEOM topology (providers, consumers, classes).
• Each provider (geom_provider_t) has metadata: name, sector size, mediasize, etc.
• Walk the tree at startup; one NCDisk object per provider that's a "disk-shaped" thing (DISK or PART class).
• Filesystem type detection via g_label metadata or by reading the partition table directly (libufs, ZFS pool import, etc.).

For hot-plug: subscribe to devctl(4) events as kmodloader does. New !system=DEVFS type=CREATE for a disk-shaped device → walk libgeom for the new entry → instantiate NCDisk → fire DARegisterDiskAppearedCallback subscribers.

3.2 Replacing Mach IPC with DO

Same pattern as configd / notifyd. Daemon creates an NSConnection over /var/run/DiskArbitration.sock at startup; client framework's DARegister* calls go through DO proxy invocations. Client callbacks are delivered over the same DO connection — a remote message send back to the client's stub object.

3.3 Mount-policy arbitration

One of DiskArbitration's defining features — not just events, but veto rights. When a new disk appears, before it auto-mounts, the daemon dispatches mount-approval callbacks to all registered subscribers. Each subscriber can:

• Approve — let the mount proceed.
• Veto — provide a dissent dictionary explaining why.
• Claim — tell the daemon "I'm going to mount this myself, don't auto-mount."

This is how disk-encryption tools (FileVault on macOS, geli on FreeBSD) intercept disk insertion: register an approval callback, veto the auto-mount, prompt the user for the password, then explicitly mount. Without DiskArbitration, every encryption tool has to monitor disk events independently and race the auto-mounter.

3.4 Event sources (libdispatch)

4. Install paths

5. Locked architectural decisions

6. File-by-file plan (diskarb/src/)

Imported source: Apple DiskArbitration-79.3. 71 files, ~34.5k LOC. 10 Mach-tied (the Mach IPC layer + IOKit lookup hooks).

6.1 Deleted on import

• DiskArbitration.xcodeproj/ — Xcode
• Modules/ — IOKit-based device-classification hooks; replaced by GEOM-based logic
• Mach IDL files (*.defs) wherever they exist in the repo
• autodiskmount/ — legacy pre-DiskArbitration mount mechanism; either drop entirely or keep a small shim that translates autodiskmount CLI invocations to DA calls. Decision: drop in Phase 1; add back in Phase 5 if any compat consumer turns up.

6.2 Retained — Phase 2 fate

Total post-Phase-2: roughly 22-24k LOC vs Apple's ~34k. About 30% deletion, plus ~30% of remaining code is new GEOM-bridging logic. Net: similar LOC but very different shape.

7. FreeBSD-only wins (vs Apple's Darwin-tied DiskArbitration)

8. Use cases for gershwin

8.1 Workspace File Viewer (the headline)

The "Devices" sidebar in File Viewer (Finder-equivalent) populates from DA events. When a user plugs in a USB stick:

1. Kernel attaches the device; devctl(4) fires.
2. diskarbitrationd sees the new disk via libgeom; instantiates DADisk; runs approval callbacks (none registered for USB sticks by default → approves).
3. Auto-mount fires: mount is invoked with the right filesystem type at /Volumes/<name>.
4. Mount-success callback fires; subscribers (Workspace) get notified.
5. Workspace adds the volume to the sidebar; user clicks → opens the mount point.

On eject (drag to trash, sidebar eject button): Workspace calls DADiskUnmount(disk, kDADiskUnmountOptionDefault); daemon orchestrates clean unmount; eject-success callback removes the sidebar entry.

8.2 Disk-utility-style apps

8.3 System-administration utilities

• diskarbitrationd's logs surface in asl with structured fields: which disk, which subscriber claimed, mount destination, timing. Way better than parsing dmesg for cdN: attached.
• A future diskutil(1)-equivalent CLI on FreeBSD could lean on DA events instead of direct GEOM scraping.

9. launchd integration

9.1 The plist (system daemon)

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
<dict>
    <key>Label</key>             <string>org.freebsd.diskarbitrationd</string>
    <key>ProgramArguments</key>  <array><string>/usr/libexec/diskarbitrationd</string></array>
    <key>RunAtLoad</key>         <true/>
    <key>KeepAlive</key>         <true/>
    <key>Sockets</key>           <dict>
        <key>Listeners</key>     <dict>
            <key>SockPathName</key> <string>/var/run/DiskArbitration.sock</string>
            <key>SockType</key>     <string>stream</string>
            <key>SockPathMode</key> <integer>438</integer> <!-- 0666 -->
        </dict>
    </dict>
</dict>
</plist>

9.2 Boot ordering

diskarbitrationd needs devctl(4) open + libgeom topology populated. Both available immediately after kernel boot. Order: starts in parallel with other system daemons; provides events from "now" forward (existing already-mounted root + critical filesystems aren't re-arbitrated).

10. Licensing

APSL 2.0 (same as configd / asl). Per-file headers preserved on Apple-derived files; top-level repo BSD-2-Clause.

11. Phased delivery

12. Open questions

13. References

• Apple source: github.com/apple-oss-distributions/DiskArbitration (latest tag DiskArbitration-79.3).
• Companion plans: launchd, configd, asl, notifyd, mDNSResponder.
• FreeBSD geom(8), libgeom(3), devctl(4) manpages.
• Apple's DiskArbitration framework: man 3 DiskArbitration on macOS.
• Apple Public Source License 2.0: opensource.apple.com/apsl/.