FreeBSD autofs Operations: On-Demand Mounts, Maps, and Recovery

FreeBSD’s autofs facility mounts local or remote filesystems when a process first accesses a configured path. It can keep rarely used NFS exports out of the boot-critical path, expose removable media when it is accessed, and unmount idle filesystems later. It also introduces a less obvious failure mode: the first pathname access can block while the kernel waits for the automounter to resolve a map and complete a mount.

The facility is a coordinated system, not a single daemon. A kernel filesystem intercepts accesses; automount(8) reads the master map and installs automount points; automountd(8) parses maps and performs requested mounts; autounmountd(8) attempts to detach idle automounted filesystems. A correct map with a stopped daemon is not operational, and a running daemon cannot repair an unreachable server or an invalid mount path.

Understand master maps and trigger paths

The primary configuration file is /etc/auto_master. Each ordinary line has a mount point, a map name, and optional mount options. When the mount point is a full path, the map is indirect: keys in that map are path components below the mount point. A /- mount point instead selects a direct map whose keys are full paths. Map files are found under /etc when a relative map name is used.

The /net map is a common built-in special map. It uses host exports so that accessing a path such as /net/fileserver.example.test/export can trigger a mount of that server’s export. DNS, NFS export policy, server version, and network reachability still have to work. /net is not a promise that every advertised server or directory will be accessible.

For an explicit NFS map, first select a dedicated mount root and a server-side export whose access policy is already configured. An indirect map can look like this:

Create the mountpoint as an empty directory before enabling the master-map entry. The automounter attaches its control filesystem there, so pre-existing files under that directory will be hidden while it is mounted. If the directory already exists, inspect its contents and ownership rather than replacing or repurposing it blindly.

mkdir -p /srv/automounted

# /etc/auto_master
/srv/automounted auto_projects

# /etc/auto_projects
engineering -ro nas.example.test:/exports/engineering

With the master entry active, access below /srv/automounted/engineering triggers the map entry and attempts to mount the remote export there. The -ro option is an example of a read-only client mount policy; use options supported by the installed FreeBSD mount_nfs(8) manual and agreed with the server owner. Replace the hostname and path with real values. Do not use a map key that conflicts with an existing directory or mount point, and avoid editing a live master map without recording its previous contents.

The format is specific: in a map line, the key is followed by optional per-entry options, an optional mountpoint, and the location. The simpler key options location form is used above. Direct and indirect map keys are not interchangeable; a full path in an indirect map or a relative component in a direct map can lead to a map that parses but does not resolve the request as intended.

Enable the service lifecycle

On a current FreeBSD system, autofs_enable="YES" instructs rc to start automount, automountd, and autounmountd during boot. devd is enabled by default; the Handbook’s removable-media integration uses it to react to device changes. For removable media, the Handbook documents an additional devd notification rule that calls automount -c when GEOM reports a device change; that is a separate integration from the basic NFS map above.

sysrc autofs_enable="YES"
service automount start
service automountd start
service autounmountd start

Review the installed rc and manual pages before applying startup changes to a host with existing automount entries. The exact daemon arguments can be set through the automount_flags, automountd_flags, and autounmountd_flags variables documented by rc.conf(5). Keep diagnostic flags in a deliberate maintenance window rather than leaving verbose foreground debugging as production service policy.

Use automount -L -L to ask the utility to parse and display maps, including indirect maps, without mounting or unmounting anything. This is a useful syntax and map-discovery check before testing a real trigger. After changing directory-service-backed maps or encountering cached stale information, automount -c flushes automounter caches. A cache flush is not a substitute for confirming that the map source returned the intended entry.

Test the trigger and idle-unmount behavior

Test a map first with a disposable client path and a noncritical file. A stat, ls, cd, or open beneath the automount point can trigger the mount; even a monitoring check can therefore block if the server is slow. In production, route health checks away from mount triggers unless checking the mount is their explicit purpose and they have a bounded timeout.

automount -L -L
mount -t autofs
ls -ld /srv/automounted /srv/automounted/engineering
mount -t nfs

The first path listing confirms directory visibility, but may itself trigger automount behavior depending on the exact path. Use a test namespace and take care not to run broad recursive tools across the mount root. Then access a known file on the share, confirm its contents, and inspect the actual mount and NFS options. Compare what mount reports with the policy in the map rather than relying on the map text alone.

autounmountd tracks filesystems mounted by the automounter and periodically attempts to unmount expired ones. An open file, current working directory, or other active reference can make an unmount fail as busy; the daemon retries after its configured interval. Do not interpret a still-visible mount immediately after closing a file as a failed map. Conversely, a successful unmount does not guarantee that the next access can reach the server.

Avoid invoking forced unmount as routine cleanup. automount -u attempts to unmount filesystems mounted by automountd; automount -f -u requests forced unmounting and can disrupt users or leave applications with I/O errors. The automounter’s autofs control mounts are different from filesystems mounted by automountd, so follow the automount(8) manual when clearing them. First stop consumers, identify the exact mount, and determine why it remains busy.

Diagnose a blocked first access

When an access stalls, find the exact path and the process that triggered it. Avoid launching more find, du, backup, or monitoring walks against the same automount tree. The waiting process may be blocked while automountd is resolving DNS, reading a map, contacting the NFS server, or executing a mount operation. Check the service state and system logs, then verify the hostname, export path, NFS version, route, firewall path, and server response using tools that do not touch the automount point.

Use a layered investigation:

Parse the full map with automount -L -L; verify the path-to-key mapping and the exact location string.
Check that the automountd and autounmountd services are running and that rc configuration enables the expected lifecycle.
Resolve the server name independently and inspect the route to its address.
Test the NFS endpoint and export with a separate, temporary mount point, using a bounded procedure appropriate to the server’s NFS version.
Compare the resulting mounted filesystem’s effective options with the intended map policy.

A failed direct NFS test indicates the problem is below the automounter map layer. A direct mount that succeeds while the trigger fails points back toward master-map syntax, daemon state, cache contents, or the chosen mountpoint. Preserve timestamps and logs for each attempt so DNS delays, server timeouts, and automounter child-process limits can be distinguished.

Production controls and acceptance criteria

An automounted path is not equivalent to local storage. Application startup may reach the path before the mount completes; shutdown can wait for blocked I/O; a server outage can stall new pathname operations; and idle-unmount can disconnect a filesystem between workloads. Document which services depend on each map, whether they may start before the server, what happens when the share is unavailable, and who owns recovery.

Use explicit mount options that match the workload and server, keep maps in version control or another reviewed configuration source, and deploy changes through a staged host. Test both first access and access after idle unmount. Include a failure test with DNS unavailable, the server unreachable, invalid export, and a busy mount. Define how operators identify and recover each state without repeatedly triggering more stuck processes.

For removable media, keep device discovery and map cleanup separate from network-share behavior. The Handbook’s devd integration reloads automount maps on a GEOM device event; it does not make every filesystem safe to mount read-write or resolve filesystem-specific corruption. Confirm the media label, filesystem type, and mount policy before depending on automatic attachment.

The best autofs deployment has observable maps, clear path ownership, bounded application checks, and a tested response for unavailable backends. On-demand mounting saves resources and decouples some mounts from boot, but it moves work into the first access. Treat that access as a real dependency boundary, not as a transparent guarantee of availability.

Related:

Sources:

Understand master maps and trigger paths

Enable the service lifecycle

Test the trigger and idle-unmount behavior

Diagnose a blocked first access

Production controls and acceptance criteria

Comments