← Back · NextBSD Research · supersedes FreeBSD DiskArbitration — porting plan (2026-05, deferred)

Mounts, fstab and DiskArbitration

Who should mount what on NextBSD, and when? This covers the root filesystem, the live union, the Linux ABI filesystems, and USB sticks going to /Volumes. It answers each by asking what Apple actually does and reading the code NextBSD ships. Three questions drove it: do we need /etc/fstab at all, how should the Linuxulator's mounts be handled, and what would a real DiskArbitration epic look like, including whether vermaden's automount fits.

2026-09-20. Research spike. Seven agents, five of them Fable, read Apple's open source (DiskArbitration-535.120.1.0.1 and -268, launchd-106 through -842.92.1, Startup-60/177, files-363 through -662, xnu, diskdev_cmds-757, Libinfo, autofs-322, apple/containerization). They also read FreeBSD releng/15.0, vermaden/automount 1.8.0, dsbmd, bsdisks, GNUstep libs-gui, the Gershwin repos, and all five NextBSD repos at main. Every load-bearing claim is cited as file:line. The latest green CI boot log (nextbsd run 35544120227) was used as runtime evidence. The epic is filed as nextbsd#471 (E15, on the roadmap), with nextbsd#467 under it. The child tickets are drafts on the E15 ticket drafts page.

1. What NextBSD does at boot today

The whole boot mount sequence, in execution order. All of it is on main and was confirmed against the CI boot log.

The shipped fstab, from nextbsd-overlays rootfs/private/etc/fstab, has a single commit. Both claims in its header are now false: root comes from the kernel's ROOTDEVNAME (#188), not loader.conf, and launchctl does run mount -a.

# The kernel mounts root directly via loader.conf's vfs.root.mountfrom
# (ufs:/dev/ufs/ROOTFS, options=rw). This entry exists for mount(8) /
# df(1) correctness; launchd is PID 1 and bypasses rc.d, so nothing
# runs `mount -a` over the rest of this file.
/dev/ufs/ROOTFS  /  ufs  rw,noatime  1  1

2. What Apple does, era by era

† The 10.0–10.3 rc scripts contain no unconditional mount -uw /. Darwin mount(8) forces MNT_UPDATE for / (diskdev_cmds mount.c:779), and later Libinfo synthesises a root fstab entry when the file is missing (Libinfo-600 file_module.c:1876-1913, 2011-2015). That is how getfsfile("/") and df stay correct on a Mac with no fstab. The exact 10.0 mechanism is unverified.

What fstab is for on modern macOS. fstab(5) describes it as an admin-maintained file, edited with vifs(8), that is read by diskarbitrationd, fsck, mount and umount. diskarbitrationd consults it “for user-defined mount points, indexed by filesystem” by UUID=/LABEL=, and automountd builds its -fstab/-static maps from it. It is a policy overlay, not a boot mount list. Apple moved the boot-critical set out of fstab and into code (mount -P never reads fstab on macOS: diskdev_cmds-757 mount.c:286-288).

The model that fits the live ISO is modern macOS, not 10.x. A read-only sealed root plus a writable volume mounted by a PID-1 boot task, with top-level mount points declared in synthetic.conf, is structurally NextBSD's read-only uzip base plus the tmpfs union assembled by /init. The Darwin lesson is to keep boot-critical mounts in boot code and never express them as fstab lines.

3. Do we need fstab? The audit

We checked every consumer of /etc/fstab that ships in the image. The base is a full buildworld minus the superseded list, and the Darwin userland was grepped for getfsent/getfsfile/_PATH_FSTAB: only launchctl.c uses them. The FreeBSD loader is the one consumer outside userland.

Options

4. What DiskArbitration actually does

Read from apple-oss-distributions/DiskArbitration at 535.120.1.0.1 (current) and 268 (10.9).

4.1 fstab is a policy overlay, never a mount list

• DiskArbitration ships its own getfsent copy (diskarbitrationd/fstab.c) and builds a mount map in __DAMountMapCreate1 (DASupport.m:1488-1634). Only three spec forms are accepted: UUID=, LABEL= (matched against the volume name) and DEVICE=<plist>. Anything else produces no entry: /dev/da0p1, tmpfs, host:/export, none, and a root line are all ignored.
• Honoured fields: mount point (none means the default), options passed through verbatim, noauto, and a type filter matched against the fs-bundle CFBundleName. freq and passno are ignored.
• The map is consulted only inside DAMountWithArguments(disk, …) (DAMount.c:1312-1430), which takes a disk DiskArbitration has already discovered. gDAMountMapList1 has exactly three references, and none of them iterates fstab to mount. Re-reading is gated on mtime at the next disk event after idle; there is no file watch.
• Consequence: a Linux-compat line in fstab means nothing to DiskArbitration. On macOS only the legacy mount -vat nonfs path would act on it.

4.2 Pipeline

IOMedia appears, then Probe, then Peek, then Mount, then Appeared (DAStage.c:139-559).

• Probe: runs every fs bundle in /System/Library/Filesystems/*.fs whose FSMediaProperties (content hint, Leaf, Whole) match, sorted by FSProbeOrder. Each bundle's <util> -p returns the name, -k the UUID, and fsck -q reports whether the volume is clean.
• Mount: runs /sbin/mount -t <kind> -k -o … as the disk's owner uid. FreeBSD mount(8) has no -k, and CFBundleName must be the FreeBSD vfs type (msdosfs, not msdos).
• Mount point: /Volumes/<name>, falling back to <name> 1 … <name> 99. It is created with mkdir 0111 and chowned (DAMount.c:725-898). At startup DiskArbitration sweeps /Volumes and removes stale directories (DAMain.c:150-246), so the OS owns /Volumes, which settles gershwin-internal#22. (Gershwin’s dscli init currently creates it 01777, dscli/main.m:1085-1092.)
• Trust defaults (DAMount.c:940-972, 1527-1543): removable and external media are untrusted and get nosuid,nodev,noowners; internal media is trusted. Media that is not writable gets rdonly. On FreeBSD, nodev no longer exists and noowners has no equivalent; ownership-less filesystems get it through the helper’s -u/-g/-m options instead.
• Defer: removable and external media are not auto-mounted until a console user exists (DAMount.c:1498-1521). They are mounted at login and unmounted at logout.
• Dirty volumes: an automatic mount of a dirty volume runs fsck -y once, then retries with force,rdonly.
• Mounts it didn't make: on kNotifyVFSMount, DiskArbitration walks getmntinfo and adopts NFS/SMB mounts as disks (DAServer.c:3362-3406). That is how Finder sees them. DiskArbitration never initiates network or pseudo-filesystem mounts.
• Unmount and eject: an approval broadcast with a 10 s timer. The first dissenter wins, Force overrides, and on EBUSY a dissenter carries the offending PID. The “volume mounted” signal clients watch for is DescriptionChanged on VolumePath.
• Launchd plist: MachServices com.apple.DiskArbitration.diskarbitrationd, KeepAlive, no RunAtLoad.

4.3 NextBSD's skeleton, against that

What ports and what doesn't. The stage machine, request and queue plumbing, DAMount.c policy, fstab/vsdb overlays, the fs-bundle model, DACommand, the MIG interface and the whole client framework are C over CF, libdispatch and Mach, all of which NextBSD has. What needs rewriting is everything IOKit-specific: IOMedia creation and description, interest notifications, DKIOCEJECT, SCDynamicStore console user, notify(3) VFS keys, sandbox_check, Authorization Services, and proc_listpidspath. APFS, CoreStorage and FSKit are deleted. The code is APSL 2.0, like launchd already in the tree.

IOMedia → GEOM mapping. Whole disk = DISK-class provider; partition = PART provider. The content hint is gpart rawtype. GPT GUIDs are the same values Apple uses, but gpart prints them lower-case (kern_uuid.c:277), so they are upper-cased before matching fs-bundle FSMediaTypes keys. MBR rawtype is the decimal partition type and needs Apple’s IOStorageFamily name table. Probing is done with fstyp(8) (-l gives the label), wrapped in a *.util -p/-k shim. Removable, vendor and model come from CAM and the newbus parent, which is where the existing ioregistry watch is still useful. Adopting mounts it didn't make uses kqueue EVFILT_FS; that it delivers VQ_MOUNT on NextBSD is unverified. There is no devd, so the arrival event is the kernel registry channel plus a libgeom walk.

5. Linux ABI filesystems — the Darwin shape

What's left of rc.d/linux's job on NextBSD. The module loads are gone: the Linuxulator, linprocfs and linsysfs are compiled into the kernel, NO_MODULES=yes is set, and kldload is stripped. fallback_brand=3 is already the kernel default (patch 0009). The only unowned piece is the five mounts:

linprocfs  $emul/proc      nocover
linsysfs   $emul/sys       nocover
devfs      $emul/dev       nocover
fdescfs    $emul/dev/fd    nocover,linrdlnk
tmpfs      $emul/dev/shm   nocover,mode=1777

These are rc.d/linux:74-80. /dev/shm needs no mkdir, because linux_dev_shm_create() puts shm/ in every devfs instance at ABI init (linux.c:699-709). #460 wants the same set on the native root for AppImages as well.

5.1 Apple precedent

Apple never uses fstab or autofs for a subsystem's pseudo filesystems:

• The kernel owns its own pseudo-filesystems with zero configuration: devfs, with fdesc folded in.
• Every other compatibility or virtualisation subsystem is provisioned by its owning daemon when it is enabled, and the same daemon registers the exec handler:
  • apple/containerization: vminitd mounts proc, sysfs, devtmpfs, /dev/shm and devpts per container (LinuxContainer.swift:445-456). The Rosetta guest agent mounts the virtiofs share and then writes the binfmt_misc registration (Vminitd+Rosetta.swift:21-34, Binfmt.swift:64-82). That registration is the exact analogue of fallback_brand.
  • xsand: ships inside its fs bundle, is Disabled until turned on, and then mounts the SAN.
  • container system start: registers its own launchd job.
• autofs is for network and home directories only. automountd has no RunAtLoad; the kernel upcalls it through HostSpecialPort 11.

5.2 Options

FUSE for AppImage (#460) needs no provisioning. fusefs is static, /dev/fuse exists from boot with mode 0666 (fuse_device.c:615-619), vfs.usermount=1 is patch 0008, and the Linuxulator itself translates Linux mount("fuse.*") into a fusefs mount (linux_file.c:1108-1132). An unprivileged mount end to end is still the untested item #460 lists.

6. USB sticks, /Volumes, vermaden and Gershwin

6.1 vermaden/automount

A 779-line sh script (v1.8.0, BSD-2 in its header) run by devd on every DEVFS CREATE/DESTROY for da|mmcsd|ugen|cd. Gershwin already installs it on its FreeBSD target (SystemPrepare.sh:584) and documents it. gershwin-desktop#60 only asks for MNT_PREFIX=/Volumes.

The alternatives are worse fits:

• dsbmd is the closest in shape (a daemon with a socket protocol, eject, and per-user mounts), but it is single-maintainer, last updated in 2023, and needs devd.
• bsdisks is actively maintained, but it is a UDisks2 clone built on Qt6, polkit and D-Bus.
• autofs -media has no events, no eject and no user ownership.

6.2 What Gershwin needs, and already has

• Discovery: A 1.5 s timer (GWDesktopManager.m:1142) diffs libs-gui’s mountedLocalVolumePaths (getmntinfo, NSWorkspace.m:2295) for mounts under the roots in +volumeMountRoots (/media, /Volumes, /run/media: Workspace.m:5493-5502). Anything DiskArbitration mounts under /Volumes appears with zero Gershwin changes.
• Notifications: NSWorkspaceDidMountNotification is observed, but nothing on FreeBSD posts it. GNUstep's _GSWorkspaceCenter rebroadcasts workspace notifications over NSDistributedNotificationCenter (NSWorkspace.m:327-457). Gershwin itself posts Will/DidUnmount on [NSNotificationCenter defaultCenter] while its observers listen on [ws notificationCenter], so today those notifications never reach them (GWUnmountHelper.m:65-66, GWDesktopManager.m:155-168). A daemon posting NSWorkspaceDidMountNotification (object GSWorkspaceNotification, NSDevicePath) reaches every app. This is the bridge proposed in gershwin-desktop/issues#26.
• The real gap is unmount and eject without root. GWUnmountHelper falls back to sudo -A -E umount -f (GWUnmountHelper.m:102), and there is no real USB eject anywhere. That is exactly DADiskUnmount/DADiskEject with dissenters.
• Other consumers waiting for a disk registry: the DiskUtility backends, ISOWrite (“wait for automount”), gershwin-desktop#64 (the installer must unmount all volumes on the target), and workspace#78 (drag-and-drop install, which needs a device, partition and volume model).

7. The epic: E15 Disks, mounts & DiskArbitration (#471)

Every ticket below is written out in full, with repo, labels, dependencies and exact Markdown body, on the E15 ticket drafts page. The drafting pass split C5 (adding C6, the fstab overlay) and D3 (into D3a–D3c), and added C7, a kernel ticket. The tables here are the summary.

Stage A — fstab and boot (no DiskArbitration code; fixes #467)

Stage B — Linux ABI mounts (E13; revisits #54 only if you choose to)

Stage C — diskarbitrationd, the daemon

Stage D — framework, policy, desktop

Relationship to E14. The swap plan's swapd is the dynamic_pager shape and is already the right activation path under no-fstab. One E14 acceptance line, “an fstab entry for /private/var/vm/swapfile0 activates via swapon -a”, should become swapon /private/var/vm/swapfile0. E14's premise “launchd never runs mount -a (#171)” is half right: mount -a does run, but swapon -a and dumpon don't.

8. Corrections to existing tickets and pages

9. Open questions

1. A or B? Ship no fstab (Apple) or a comment-only one (quieter FreeBSD tooling). Both fix #467.
2. #54: keep option H as the default, or schedule org.nextbsd.linux? And should the native /proc=linprocfs set ever be on by default, given it is a system-wide change?
3. noexec on untrusted media? Apple doesn't set it. It blocks running AppImages straight off a stick, which Gershwin users may expect.
4. Console user source: which process publishes “who is at the console” on NextBSD (loginwindow? dshelper?), so DiskArbitration can own and defer mounts?
5. EVFILT_FS: does VQ_MOUNT reach userland on NextBSD? It is untested. FreeBSD signals VQ_MOUNT and VQ_UNMOUNT only; mount -u signals nothing. C3 carries a test program.
6. Unverified on a running box: that /etc/sysctl.conf really applies, that the automount binaries ship, and that a fstab-less image boots clean. The last is covered by CI once A1 lands.

10. Methodology note

There were two fact-gathering agents (site conventions; tickets and code state) and five Fable research agents: the Darwin boot mount sequence, the DiskArbitration source, the Linux-compat mount design, the installed-system fstab audit, and USB automount with Gershwin. Where agents disagreed, the page says so. The one real disagreement was A versus B for fstab: the Darwin agent pointed out that Apple ships no file, and the audit agent pointed out FreeBSD's no-file stderr and halt edge case. The DiskArbitration agent proposed devd as the event source; that was corrected here because NextBSD removed devd. Claims marked unverified were not run on hardware.

Evidence: nextbsd@37a3b6e, nextbsd-userland@f035d62, nextbsd-overlays@c0d0d1f, nextbsd-kernel main, FreeBSD releng/15.0; apple-oss-distributions DiskArbitration-535.120.1.0.1 & -268, launchd-106/-258.1/-329.3.3/-392.39/-442.26.2/-842.92.1, Startup-60/-177.8, files-363 through -662.1.1, xnu-201/-12377.121.6, diskdev_cmds-143/-757, Libinfo-78/-600, autofs-322; apple/containerization, apple/container; vermaden/automount 1.8.0; dsbmd 1.12; bsdisks 0.41; gnustep/libs-gui f285e90; gershwin-workspace 817491d; CI run 35544120227. Related: nextbsd#467, userland#171, userland#54, #460, #461, gershwin-desktop#49, #60, swap plan (E14).