Linux NFS Server Exports: Namespace, Sync Semantics, and Safe Reloads

An NFS server export is a protocol boundary over a local filesystem tree. Its behavior depends on export options, filesystem identity, NFS version, server state, client identity, and storage durability. A path in /etc/exports can look correct while clients see a different namespace, a child filesystem is unexpectedly exposed, or a write acknowledgment does not meet the application’s durability requirement.

Exports should be designed from the server’s namespace outward. Identify the backing filesystem and mount topology, define which clients can reach each path, and decide how NFSv3 or NFSv4 presents the tree. Apply changes through the server’s export management tooling and verify the active export table afterward.

Establish the local filesystem and export graph

Inspect the backing mount and current export state before editing configuration:

findmnt -T /srv/data
exportfs -v
cat /proc/fs/nfsd/exports
journalctl -u nfs-server -b --no-pager

Service names vary by distribution, and the proc file may be unavailable if nfsd is not configured. These commands are read-only. Confirm that the path is the intended local filesystem, not an unexpectedly mounted temporary or removable volume. NFS clients can continue using an export path while the server’s mount underneath changes.

NFSv4 presents a pseudo-root namespace and can mount a path relative to that root. The fsid=0 or fsid=root export identifies that root in common Linux configurations. NFSv3 and NFSv4 namespace behavior differ; do not copy an NFSv3 path directly into a v4 client mount command without checking the server’s export tree.

Submounts require explicit consideration. The crossmnt option can make child filesystems reachable through a parent export with inherited behavior. Exporting a parent that contains separately mounted filesystems without planning can expose more data or create confusing client paths. Verify each child mount and export independently.

Use options as a documented access contract

An exports entry can scope a path to a host or network and attach options. For example, a lab-only read-only export can be written as:

/srv/archive 192.0.2.0/24(ro,sync,root_squash,no_subtree_check)

This is an illustrative configuration line, not a command to append to a production file. Replace the documentation-only address range with an approved client scope. Review the exports manual for option defaults and interactions on the target nfs-utils version.

The sync option controls when the server replies relative to stable storage behavior; async can acknowledge writes before they are committed, improving performance while risking loss after a server crash. Do not choose async solely from a benchmark. Confirm the storage stack’s flush semantics and the application’s durability expectations.

root_squash maps remote root requests to an anonymous identity in common Linux exports. It is a useful default boundary but does not replace filesystem permissions, authentication policy, or network restrictions. no_subtree_check changes how subdirectory export verification is handled and has trade-offs if files are renamed or export topology changes. Treat every option as a contract and document why it is present.

NFSv4 identity and server state

NFSv4 adds stateful operations such as open, lock, and delegation behavior. Server restarts, client recovery, leases, and grace periods can affect whether old state is reclaimed. A successful TCP connection does not prove that the client has reclaimed opens or locks. Monitor server logs and client recovery status during planned maintenance.

User and group identity must be consistent across the server and clients or mapped through a deliberate identity service. Numeric UID/GID presentation and NFSv4 id mapping can differ. A file that appears owned by an unexpected user may be a mapping issue rather than a permissions defect. Validate with a test account and compare both client and server views.

Authentication flavor and transport encryption are part of deployment policy. Do not assume a network-restricted export is equivalent to strong user authentication. If Kerberos or another security flavor is required, validate principal naming, time synchronization, keytab rotation, and server support through the organization’s approved procedures.

Apply and reload changes safely

The export table is runtime state. Editing /etc/exports does not always change active exports until the export manager reloads them. Conversely, a reload can remove or alter an export while clients have open files. Use a maintenance window for namespace or identity changes and notify clients of possible state recovery.

Validate syntax and intended paths before applying. Use the distribution’s documented exportfs or systemd procedure; do not rely on a service restart when the export manager supports an in-place refresh. After applying, inspect exportfs -v and test from a dedicated client using the intended NFS version. Confirm that the client sees only the expected namespace and that the server logs no state-recovery errors.

Avoid wildcard client scopes and broad exports unless specifically justified. A typo in a client specification can expose a path to more hosts than intended. Keep configuration in version control with review, and compare the active export table to the approved source after every change.

Durability and operational monitoring

NFS server write acknowledgments interact with the local filesystem, block layer, controller cache, and device. A sync export does not compensate for a storage device that lies about flush completion. Test application-level fsync and server crash recovery on a staging system if durability is critical.

Monitor NFS server threads, network errors, filesystem latency, disk flushes, retransmissions, and client state-recovery messages. A saturated server thread pool can look like a network timeout; a local disk stall can look like an NFS hang. Correlate timestamps across the server, client, and storage systems.

Before unmounting or replacing an exported filesystem, identify clients, open files, and dependent services. Stop new operations, allow clients to drain, preserve the export state, and follow the server’s recovery procedure. Forcing an unmount or deleting a mount underneath an export can leave clients with stale handles.

Acceptance tests

Test read-only and read-write behavior from each intended client, verify the NFSv4 namespace, check UID/GID presentation, exercise a client restart, and confirm export reload does not unexpectedly remove active state. For data services, test write and fsync recovery on staging storage and verify the server’s documented sync policy.

An export record should include local filesystem and mount path, NFS version, client scope, options, backing storage durability, identity mapping, active export output, reload procedure, and rollback. Recheck the active table after reboot because service ordering and mount availability can affect whether the path was exported correctly.

An NFS export is both a namespace and a durability boundary. Correct operation comes from explicit client scope, planned filesystem topology, understood NFS version semantics, and verification of the live export table after every change.

Related:

Sources: