FreeBSD NFS Server Operations: Exports, Protocols, and Observability

An NFS server makes a local filesystem part of a remote client’s namespace. That convenience can hide the fact that each operation still depends on server storage, network transport, identity mapping, and daemon state. A production export is therefore more than an /etc/exports line: it is a contract describing which filesystem is exposed, which clients may mount it, how file identities are interpreted, and what users should observe when the network or backing disk is unavailable.

This guide focuses on FreeBSD as an NFS server. It does not replace the separate client-side troubleshooting steps needed when mounts hang. The goal is to configure a small, explicit export, activate the server predictably, verify it from an independent client, and correlate NFS symptoms with the filesystem and network underneath.

Map the service before editing files

The base system’s NFS service includes nfsd, which serves NFS requests, and mountd, which processes mount-protocol requests and loads export information. rpcbind lets clients discover RPC services, particularly in common NFSv3 deployments. NFSv4 uses a different mount model; an NFSv4-only server can avoid the legacy Mount protocol and rpcbind, but that is a deliberate protocol configuration, not an assumption to make from a successful NFSv4 client mount.

Start with the local release and current service state. Confirm which filesystem backs each export, whether it is mounted where expected, which NFS versions the clients require, and whether file locking is part of the application contract. A web of daemons can be listening while the storage beneath the exported path is degraded. Conversely, a healthy filesystem does not prove that RPC registration, exports, or client identity mappings are correct.

freebsd-version -kru
sysrc rpcbind_enable nfs_server_enable mountd_enable nfsv4_server_enable
service nfsd status
mount
zpool status

The sysrc output is configuration evidence; it is not runtime proof that every daemon is healthy. zpool status is useful only when ZFS backs the path; use the filesystem’s own status tools for UFS or another backend. Do not assume that service nfsd status proves a remote client can mount an export.

Design export paths and client scope

Every export should refer to a stable server-side path with a clearly understood filesystem boundary. Avoid exporting a parent directory simply because it is convenient: a broad export can expose unrelated subdirectories, and an export whose path is not a filesystem mount point may have semantics different from the subtree an operator imagines. -alldirs permits mounting directories within the exported filesystem; it does not mean “only the one mountpoint.” Use it only when clients actually need that behavior.

FreeBSD’s /etc/exports syntax lists one or more filesystem paths, options, and permitted hosts on a line. Host names must resolve consistently from the server, and IP-based client specifications avoid accidental dependence on an inconsistent name-service view. Multiple exports can share a line only when the syntax and options intentionally apply to each one. Keep each path’s policy easy to review rather than compressing unrelated shares into a clever line.

# /etc/exports: export one dataset path read-write to a specific client
/srv/projects -maproot=root build01.example.net

# A read-only artifact tree for two known client addresses
/srv/artifacts -ro 192.0.2.41 192.0.2.42

The documentation addresses are placeholders; replace them with approved client identities. -ro makes the export read-only. -maproot=root maps a specified client’s root identity to server-side root for that export and should not be copied casually: use it only when remote root-level ownership operations are part of a documented requirement. Without an explicit client list, the server’s default exposure may be broader than intended. Review exports(5) for the exact grammar and semantics of client netgroups, network masks, and mapping options before relying on them.

If the backing path is a ZFS dataset, there are two ownership models: a traditional entry in /etc/exports, or ZFS’s sharenfs property, which generates an export entry under /etc/zfs/exports. Pick one as the authoritative source for a dataset. Duplicating policy in both locations makes zfs get sharenfs disagree with the actual export set and makes rollback harder. The NFS server service still must be enabled for ZFS-managed sharing.

Bring the server up and make configuration changes take effect

For the common server arrangement, persist the services through sysrc, then start the NFS service. The Handbook documents rpcbind_enable, nfs_server_enable, and mountd_enable for the general setup. Whether all are required depends on the selected protocol mode; an NFSv4-only configuration should follow the nfsv4(4), mountd(8), and release-specific rc.conf(5) guidance rather than retaining unneeded NFSv3 support by habit.

sysrc rpcbind_enable="YES"
sysrc nfs_server_enable="YES"
sysrc mountd_enable="YES"
service nfsd start

When nfsd starts, it also starts mountd in the documented setup. mountd reads /etc/exports at startup; after editing that file, reload the export list with the supported service action rather than restarting every network service:

service mountd reload
service nfsd status

Check syslog for parsing errors immediately after a reload. A failed or malformed export line can leave the intended path absent even while existing exports continue to work. Preserve the prior working file and apply changes in a controlled window when clients perform latency-sensitive work. If a dataset’s share property is authoritative, inspect zfs get sharenfs and the generated export source as well as the service state.

Export updates affect authorization and namespace visibility, but they do not retroactively change every client’s mount options or identity cache. Ask a client to verify the expected source and mount options with mount; use showmount -e server as a useful NFS Mount-protocol view for compatible configurations. It is not a complete inventory for NFSv4-only servers, because NFSv4 does not use the legacy Mount protocol and exports are not shown there in the same way.

Identity, file ownership, and locks

With common AUTH_SYS-style operation, NFS requests carry numeric user and group identifiers. The displayed account name is resolved separately by each host. If UID 1001 means build on the server but alice on one client, the numeric ownership is still 1001; matching names alone do not align authorization. Coordinate account IDs across the participating systems or adopt the identity design supported by the chosen NFS version and environment. For NFSv4, id mapping and the configured domain require special care; verify the installed release’s nfsuserd(8) and nfsv4(4) instructions rather than treating NFSv3 and NFSv4 identity behavior as identical.

Test ownership with a non-production file and an actual client account. Create, stat, rename, and remove a disposable file, then compare numeric IDs with ls -ln on both ends. A test as root alone can mask an identity mapping error, especially when root squashing or -maproot is configured. Similarly, an application that depends on advisory locks needs an explicit lock test; a basic read/write test does not prove lock daemons and client support are correctly configured.

The Handbook documents enabling rpc_lockd on both server and client for applications that need file locking. Confirm whether your application uses the expected locking model and whether locks recover after a client restart. Do not infer database safety from “the share mounted”: NFS, locking semantics, cache behavior, and application durability guarantees are separate design choices. Use the application’s supported storage and failure model.

Network, version, and firewall boundaries

NFSv3 commonly involves RPC service discovery and mountd, so an intervening firewall must account for the actual listening ports and version negotiated. Do not paste a generic port list from an unrelated operating system. Inspect rpcinfo -p, server sockets, the local release’s rc.conf(5), and any configured fixed service ports; then build firewall policy around the intended client network and protocol set. NFSv4 uses TCP and a single NFS service model, but related services such as rpcbind may still be enabled for other host functions.

Varying MTU, packet loss, asymmetric routing, and stateful firewalls can turn a server that responds to ping into an NFS endpoint that stalls under larger file operations. Verify the route and packet path from a real client; use a bounded packet capture if needed and avoid placing sensitive file contents in an incident capture. Confirm that hostnames resolve as intended, the client reaches the expected address family, and server replies return through the same policy boundary.

For a controlled maintenance test, check both a read-only client and a designated writer, verify a large transfer as well as metadata operations, and observe whether latency changes with concurrency. A small touch succeeds on many paths that fail during sustained I/O, directory enumeration, lock traffic, or reconnect. Measure representative workloads before deciding that more nfsd threads, a different protocol version, or a mount option will fix the issue.

Observe NFS and its storage dependencies

Use a layered evidence set. nfsstat reports NFS client/server statistics; rpcinfo shows registered RPC services where applicable; sockstat -l shows listening sockets; system logs report export reload failures and daemon errors. On the backing storage, correlate filesystem-specific health, I/O latency, capacity, and errors. A server can accept RPCs while storage is waiting on a failing device, and a client can keep retrying during a path interruption without producing an obvious server daemon crash.

nfsstat -s
rpcinfo -p localhost
sockstat -l | grep -E 'nfsd|mountd|rpcbind'
tail -n 100 /var/log/messages

Exact options and output vary by release, and nfsstat counters are cumulative snapshots rather than proof of a particular request’s cause. Capture before-and-after deltas around a test. Correlate server timestamps with client logs such as “server not responding” and “is alive again,” network packet captures, and storage metrics. If a client reports a hang, also verify the server’s backing pool or filesystem; increasing the client’s retry timeout can hide evidence without restoring service.

For production observability, define alerts for unavailable exports, increasing RPC errors or retransmissions, server thread saturation where measurable, storage latency, pool degradation, and client-visible operation latency. Retain an inventory of client scope and the chosen protocol versions, plus a known-good exports snapshot. The useful incident record is not just “NFS is up”; it includes the exact client, source path, server export, filesystem, negotiated protocol, operation, and time window.

Validate the end-to-end contract

Before calling a server ready, confirm that each declared export points at the intended mounted filesystem, reloads without an error, and is visible from an authorized test client. From that client, verify expected read/write policy, numeric ownership, rename and delete behavior, lock behavior if required, and performance under representative concurrency. Also test what an unauthorized or wrong-subnet client sees, without exposing production data. Keep this as a bounded validation test rather than a broad scan of network clients.

Document how clients mount the share, what happens during server reboot or network loss, how application writes are made durable, and how the underlying data is backed up. NFS is a remote filesystem interface, not a backup protocol or high-availability mechanism. A healthy mount cannot replace a tested restore, and a second server needs an explicit replication and failover design. The operational finish line is a reproducible client-visible read/write contract with storage, network, identity, and recovery ownership clearly assigned.

Related:

Sources: