Debian and Ubuntu Linux NFS Server Configuration and Management
General Description of an NFS Server
Network File System (NFS) is a distributed file-system protocol that allows a Linux server to export directories to remote clients. A client mounts an exported path into its own directory tree and applications normally use the files through ordinary POSIX file operations. The server remains responsible for the underlying storage, export policy, identity interpretation, locking, state recovery, write stability, and service availability.
An NFS server is not only a process listening on TCP port 2049. It is a coordinated stack consisting of the Linux kernel NFS server, user-space helper daemons, the export table, local file-system permissions and ACLs, name and identity services, firewall policy, optional Kerberos or TLS components, and the storage beneath the export. A successful TCP connection proves only that one part of the stack is reachable.
This guide is a companion to the Debian and Ubuntu networking guide. It starts with a safe single-server NFSv4 configuration, then expands into pseudo-filesystems, NFSv3 compatibility, export administration, identity and permission design, Kerberos, RPC-with-TLS where supported, quotas, monitoring, performance, high availability, and structured troubleshooting.
Typical server tasks include:
- Installing and managing the nfs-kernel-server and supporting packages.
- Preparing dedicated export storage with predictable ownership, group membership, ACLs, and mount ordering.
- Defining client allow-lists and export options in /etc/exports or /etc/exports.d/*.exports.
- Choosing NFSv4-only operation or deliberately supporting NFSv3 and its auxiliary RPC services.
- Applying export changes without unnecessarily interrupting active clients.
- Restricting network exposure with UFW or native nftables rules.
- Securing user identity with consistent UID/GID data or Kerberos security flavours.
- Monitoring nfsd, clients, RPC operations, storage latency, network traffic, and logs.
- Diagnosing permission errors, stale file handles, lock recovery failures, timeouts, and poor performance.
Safety, Scope, Conventions, and Example Values
Scope: The examples target current Debian and Ubuntu releases using systemd and Linux nfs-utils. Ubuntu 22.04 LTS and later use /etc/nfs.conf and /etc/nfs.conf.d/*.conf as the normal unified daemon configuration. Older releases can still contain converted settings under /etc/nfs.conf.d or historical /etc/default/nfs-* files, so always inspect the effective configuration before assuming a default.
Warning: Changing export permissions, security flavours, protocol versions, file-system mounts, or firewall rules can immediately affect running applications. Keep console access, a tested rollback, and a current backup of both configuration and data. Coordinate maintenance with client owners before restarting the service or removing an export.
Command prompts used in this guide:
|
$ command # Run as an ordinary user |
Documentation-only example values:
|
Purpose |
Example |
|
NFS server |
nfs01.example.com / 192.0.2.10 |
|
Authorised IPv4 client network |
192.0.2.0/24 |
|
Authorised IPv6 client network |
2001:db8:100::/64 |
|
Single client |
client01.example.com / 192.0.2.21 |
|
NFSv4 namespace root |
/srv/nfs |
|
Projects export |
/srv/nfs/projects |
|
Underlying storage |
/data/projects |
|
Shared writer group |
nfswriters, GID 2000 |
|
Kerberos realm |
EXAMPLE.COM |
Before editing, capture the current state and create dated backups:
|
# stamp=$(date +%F-%H%M%S) |
Use a staged change: edit one file, validate or display the resulting configuration, apply the export table, test from a non-privileged client account, and only then remove the rollback copy.
Contents
- NFS architecture, protocol versions, and service components
- Planning storage, identity, permissions, availability, and security
- Installation and service management
- Configuration files and runtime state
- Preparing export directories, bind mounts, groups, and ACLs
- /etc/exports syntax, client selectors, and export options
- Basic NFSv4 export and NFSv4 pseudo-filesystem examples
- Adding, changing, deleting, and reloading exports
- NFSv4-only and NFSv3-compatible server configuration
- UFW and nftables firewall configuration
- UID/GID mapping, root squashing, and application access
- Kerberos-secured NFS and RPC-with-TLS
- Quotas, ACLs, extended attributes, and snapshots
- Performance tuning, monitoring, metrics, and packet capture
- Backups, maintenance, high availability, and disaster recovery
- Troubleshooting workflows and common errors
- Security hardening checklist and command reference
NFS Architecture, Protocol Versions, and Service Components
The Linux NFS server is implemented primarily in the kernel. User-space programs prepare policy and state, then the kernel nfsd threads perform file operations on behalf of clients. NFSv4 integrates more functions into the main protocol, whereas NFSv3 depends on additional RPC programs for mounting, locking, status notification, and optional quota reporting.
|
Version |
Network and state model |
Administrative implications |
|
NFSv4.2 |
Stateful; normally TCP 2049; integrated locking; NFSv4 namespace; supports modern features such as server-side copy when the client, server, and storage support them. |
Preferred starting point for current Linux clients. Simplifies firewalls and supports krb5, krb5i, krb5p, and newer RPC-with-TLS implementations. |
|
NFSv4.1 |
Stateful sessions and improved connection handling; TCP 2049. |
Useful when clients do not support 4.2 or when testing identifies an interoperability issue. |
|
NFSv4.0 |
Stateful; TCP 2049; older recovery and callback behaviour. |
Retain only for clients that require it. Verify DNS and identity mapping carefully. |
|
NFSv3 |
Core protocol is largely stateless, but mountd, rpcbind, lockd, statd, and sometimes rquotad add state and dynamic RPC services. |
Requires a wider firewall policy and explicit recovery testing. Use only when a client or application requires it. |
Important Server Components
|
Component |
Role |
Useful checks |
|
nfsd / rpc.nfsd |
Kernel NFS service and its user-space launcher. Handles NFS protocol requests and server threads. |
cat /proc/fs/nfsd/versions; ps -eLf | grep nfsd; nfsstat -s |
|
exportfs |
Builds and displays the effective export table from /etc/exports and /etc/exports.d/*.exports. |
exportfs -rav; exportfs -v; exportfs -s |
|
rpc.mountd / nfs-mountd |
Authorises NFSv3 MOUNT requests and supplies export information to the kernel. |
systemctl status nfs-mountd; rpcinfo -p |
|
rpcbind |
Maps RPC program numbers to ports. Normally required by NFSv3-era services. |
systemctl status rpcbind; rpcinfo -p localhost |
|
rpc.statd / lockd |
NFSv3 lock and reboot notification support. |
systemctl status rpc-statd; journalctl -u rpc-statd |
|
nfs-idmapd |
Assists NFSv4 name-to-ID mapping when that mapping path is used. |
systemctl status nfs-idmapd; grep -v “^#” /etc/idmapd.conf |
|
rpc-svcgssd |
Server-side RPCSEC_GSS helper for Kerberos-secured NFS. |
systemctl status rpc-svcgssd; klist -k /etc/krb5.keytab |
|
nfsdcld / nfsdclnts |
Maintains or inspects NFSv4 client recovery state and active client information. |
nfsdclnts –clientinfo; journalctl -u nfsdcld |
|
rpc.rquotad |
Provides remote quota information when configured. |
systemctl status rpc-rquotad; rpcinfo -p | grep rquota |
Choose the Protocol Deliberately
For a new deployment with current Linux clients, begin with NFSv4.2 and keep NFSv4.1 available unless a compatibility or policy requirement says otherwise. Disable NFSv3 only after inventorying every operating system, appliance, hypervisor, backup product, and embedded client. A device can silently negotiate an older version even when an administrator expects NFSv4.
Check the versions enabled by the running kernel server:
|
$ cat /proc/fs/nfsd/versions |
A plus sign means enabled and a minus sign means disabled. The exact line depends on the kernel, nfs-utils release, and configuration. Test the version actually negotiated from the client with nfsstat -m or findmnt -o TARGET,FSTYPE,OPTIONS.
Planning the NFS Server
A stable NFS service starts with storage and identity design, not with /etc/exports. Decide what is shared, who is trusted, which protocol and security flavour are required, how data is backed up, and what applications should do during an outage.
Planning Checklist
- Use a dedicated file system or clearly defined subtree for each data class. Avoid exporting /, /etc, /var, or a broad parent that unintentionally exposes future mount points.
- Confirm the underlying file system supports the required ownership, POSIX ACLs, extended attributes, quotas, snapshots, and application locking semantics.
- Choose a stable server FQDN and address. Kerberos and TLS certificates depend on correct names, and clients should not be tied to an address that will change unexpectedly.
- Define authorised clients with single hosts, explicit CIDR networks, or managed netgroups. Avoid a writable export to * in production.
- Document numeric UID/GID ownership. sec=sys carries numeric credentials supplied by the client; it does not authenticate a human user.
- Use root_squash unless a narrowly defined boot, provisioning, or appliance workflow demonstrably requires no_root_squash.
- Choose sync for normal data integrity. Treat async as a measured exception because acknowledged writes can be lost after a crash or power failure.
- Plan firewall rules from the client subnets only. NFSv4 is simpler because it normally needs TCP 2049; NFSv3 requires auxiliary RPC services.
- Plan backup consistency. A snapshot, application quiesce, database-native backup, or cluster-aware procedure is often required; copying live files is not automatically application-consistent.
- For high availability, design shared storage, fencing, a stable service address/name, NFSv4 recovery state, and export ownership as one system. DNS round-robin alone is not NFS failover.
Permission Layers
|
Layer |
Question to answer |
|
Export allow-list |
Is this client host or network permitted to mount this path with the requested security flavour? |
|
Firewall |
Can the required protocol reach the server from this source address? |
|
NFS credential |
Which numeric UID/GID or Kerberos principal is presented for this operation? |
|
Squashing |
Is root, or every user, mapped to the anonymous UID/GID? |
|
POSIX mode and ACL |
Does the resulting local identity have search, read, write, create, delete, and rename permission? |
|
Underlying file system |
Is it mounted read-write, healthy, in space and inodes, and free of quota or I/O errors? |
|
Application policy |
Does the application use the expected account, umask, locking method, and file-creation pattern? |
Install NFS Server Packages and Manage Services
Install and Verify Packages
|
# apt update |
The nfs-kernel-server package supplies the kernel-server service and server helpers. nfs-common supplies shared utilities used by both client and server components. Install quota, acl, krb5-user, tcpdump, sysstat, or nftables only when the corresponding functions are needed.
Enable, Start, Stop, Reload, and Restart
|
# systemctl enable –now nfs-server.service |
Use exportfs -rav for an export-table-only change whenever possible. A full restart interrupts service processing and forces clients through recovery behaviour. Changes to protocol versions, listener ports, server thread settings, Kerberos helpers, or TLS helpers normally require a service restart.
Initial Health Checks
|
$ cat /proc/fs/nfsd/versions |
On an NFSv4-only server, showmount -e can be empty or unavailable because showmount queries the older MOUNT protocol. Treat exportfs -v on the server and a direct NFSv4 client mount as authoritative tests.
Configuration Files and Runtime State
|
Path |
Purpose |
|
/etc/exports |
Primary persistent export definitions. |
|
/etc/exports.d/*.exports |
Modular export snippets. Only files ending in .exports are read by exportfs. |
|
/etc/nfs.conf |
Unified INI-style configuration for nfsd, mountd, statd, lockd, gssd, svcgssd, and related programs. |
|
/etc/nfs.conf.d/*.conf |
Local configuration snippets read with /etc/nfs.conf. Later settings can override earlier settings. |
|
/etc/idmapd.conf |
NFSv4 ID-mapping domain and related settings when name mapping is used. |
|
/etc/krb5.conf |
Kerberos realms, KDC discovery, and client library settings. |
|
/etc/krb5.keytab |
Host and nfs service keys. Protect this file as a root-only secret. |
|
/var/lib/nfs/etab |
Runtime master export table maintained by exportfs; do not edit directly. |
|
/var/lib/nfs/rmtab |
Historical mount information used by mountd; it is not a complete NFSv4 active-client inventory. |
|
/proc/fs/nfsd |
Kernel nfsd control and status pseudo-filesystem. |
|
/proc/net/rpc/nfsd |
Raw server RPC counters used by tools such as nfsstat. |
|
systemd journal |
Service and kernel events; query with journalctl rather than expecting a dedicated NFS log file. |
Inspect the Effective Daemon Configuration
|
$ nfsconf –dump |
Do not assume /etc/nfs.conf is the whole configuration. Package upgrades and migration tools can create local snippets. nfsconf –dump merges the relevant files and is the fastest way to reveal an override.
Prepare Export Storage, Ownership, Groups, and ACLs
Create a Dedicated Group-Writable Export
This example creates a shared projects area where members of a consistent nfswriters group can create files. The setgid bit keeps new entries in the shared group.
|
# groupadd –gid 2000 nfswriters |
Create the same numeric GID and appropriate user memberships in the authoritative identity source used by every client. A group name that looks identical but has a different numeric GID is a different identity to NFS.
Use Default ACLs for Collaborative Directories
|
# apt install -y acl |
Default ACLs control permissions inherited by new children. Application umasks and explicit chmod operations can still change results, so test file creation using the real service account rather than only root.
Bind Mount Storage into an NFSv4 Namespace
A bind mount separates the client-visible NFS namespace from the physical storage layout. This is useful when data lives under /data but clients should mount paths under a clean /srv/nfs tree.
|
# mkdir -p /srv/nfs/projects |
Persistent /etc/fstab entry:
|
/data/projects /srv/nfs/projects none bind,x-systemd.requires-mounts-for=/data/projects 0 0 |
Use the mountpoint export option for a path that must be a mounted file system. It prevents an accidental export of the empty underlying directory if storage fails to mount:
|
/srv/nfs/projects 192.0.2.0/24(rw,sync,no_subtree_check,root_squash,mountpoint) |
Warning: Never use chmod 777 as a substitute for identity and ACL design. It makes every local and remote identity able to modify the directory and often hides the real UID/GID problem until a security incident occurs.
/etc/exports Syntax and Client Selectors
Each export line starts with a local path, followed by one or more client selectors. An option list immediately follows each selector in parentheses. There must be whitespace between the path and the selector, but no whitespace between a selector and its opening parenthesis.
|
/srv/nfs/projects 192.0.2.0/24(rw,sync,no_subtree_check,root_squash) |
Critical whitespace example: client01.example.com(rw) and client01.example.com (rw) do not mean the same thing. The second form separates the client from the option block and can create an unintended default export. Always review exportfs -v after a change.
Client Selector Examples
|
Selector type |
Example |
Notes |
|
Single FQDN |
client01.example.com |
Requires reliable forward and reverse resolution. A DNS change can alter which system matches. |
|
Single IPv4 address |
192.0.2.21 |
Unambiguous but tied to the address. |
|
IPv4 CIDR network |
192.0.2.0/24 |
Common for a managed client subnet. |
|
Single IPv6 address |
2001:db8:100::21 |
Do not put square brackets around IPv6 addresses inside /etc/exports. |
|
IPv6 prefix |
2001:db8:100::/64 |
Authorises the whole prefix. |
|
Wildcard domain |
*.example.com |
Matches dots as well as labels; broader than many administrators expect. |
|
Netgroup |
@engineering |
Centralised host grouping through NSS; verify getent netgroup engineering. |
|
Everyone |
* |
Avoid for writable production exports. It is not user authentication. |
Multiple Clients with Different Options
|
/srv/nfs/projects 192.0.2.0/24(rw,sync,root_squash) \ |
A continuation backslash must be the final character on the line. Keep entries short enough to review, and prefer one clear export definition per data set.
Important Export Options
|
Option |
Meaning and guidance |
|
ro / rw |
Read-only or read-write. ro is the default. File-system permissions can still deny a write on an rw export. |
|
sync / async |
sync replies after changes reach stable storage and is the normal integrity choice. async can improve throughput but acknowledged data can be lost or corrupted after an unclean restart. |
|
root_squash |
Maps client UID 0 to the anonymous identity. This is the normal safe default. |
|
no_root_squash |
Preserves remote root authority. Use only for a tightly restricted, documented workflow; a compromised client root can then create or alter server-owned files. |
|
all_squash |
Maps every remote identity to the anonymous account. Useful for drop boxes or service shares with one controlled server-side identity. |
|
anonuid / anongid |
Sets the numeric anonymous UID and GID. Create and protect a dedicated local account when all_squash is used. |
|
subtree_check |
Checks whether each requested file remains under the exported subtree. Can add overhead and cause problems with frequent renames. |
|
no_subtree_check |
Disables subtree verification. Common for dedicated export roots and frequently changing data. |
|
secure / insecure |
secure normally requires non-GSS requests to originate from a reserved client port. insecure permits high source ports and should be used only for a client that requires it. |
|
fsid=0 |
Marks the root of an NFSv4 pseudo-filesystem. Use only one root per server namespace. |
|
fsid=N |
Provides a stable file-system identifier where needed. Keep values unique and stable. |
|
crossmnt |
Lets a parent export cross into mounted child file systems and can implicitly export children with inherited options. Audit carefully. |
|
nohide |
Makes a mounted child visible through a parent for certain NFSv2/v3 cases. Client behaviour varies; prefer explicit exports or the NFSv4 namespace. |
|
mountpoint / mp |
Exports the path only when it is a mount point, preventing accidental exposure of an empty backing directory. |
|
wdelay / no_wdelay |
Controls a small write delay used to combine related synchronous writes. no_wdelay has no effect with async. |
|
sec=sys |
Uses client-supplied UNIX-style numeric credentials. It provides no cryptographic user authentication. |
|
sec=krb5 |
Kerberos authentication without integrity protection for ordinary NFS payload data. |
|
sec=krb5i |
Kerberos authentication plus integrity protection. |
|
sec=krb5p |
Kerberos authentication, integrity, and privacy encryption. Strongest Kerberos flavour, with additional CPU cost. |
|
xprtsec=tls / mtls |
On supported current nfs-utils and kernel stacks, requires RPC-with-TLS confidentiality or mutual TLS for the export. Confirm release support before relying on it. |
Explicitly state the important options instead of relying on defaults. The common default set includes ro, sync, root_squash, and wdelay, but readable configuration is safer than hidden assumptions.
Basic NFSv4 Server Configuration
Create and Export a Single Path
|
# mkdir -p /srv/nfs/projects |
Add to /etc/exports or to /etc/exports.d/projects.exports:
|
/srv/nfs/projects 192.0.2.0/24(rw,sync,no_subtree_check,root_squash) |
Validate and activate:
|
# exportfs -rav |
Permit NFSv4 Through UFW
|
# ufw allow from 192.0.2.0/24 to any port 2049 proto tcp comment “NFSv4 clients” |
Test from an Authorised Client
|
# apt install -y nfs-common |
Test with the actual non-root account that will run the workload. A root-only test can be misleading because root_squash intentionally changes root into an anonymous identity.
Build an NFSv4 Pseudo-Filesystem Namespace
An NFSv4 pseudo-filesystem presents a stable client-visible tree even when the server stores data on several local file systems. The namespace root is exported with fsid=0, and child paths are exported separately. Clients then mount paths such as nfs01.example.com:/projects rather than the server-local /srv/nfs/projects path.
Prepare the Namespace
|
# mkdir -p /srv/nfs/projects /srv/nfs/reference |
Example /etc/fstab entries:
|
/data/projects /srv/nfs/projects none bind 0 0 |
Define the Exports
|
/srv/nfs 192.0.2.0/24(ro,fsid=0,crossmnt,sync,no_subtree_check,root_squash) |
Client Mounts
|
# mount -t nfs4 nfs01.example.com:/projects /mnt/projects |
Use exactly one fsid=0 root for the intended NFSv4 namespace. Do not casually add crossmnt to a broad directory because newly mounted child file systems can become reachable with inherited export options.
Add, Change, Delete, and Reload Exports
Display Current Exports
|
$ exportfs |
exportfs -v is for human review. exportfs -s prints a form suitable for configuration comparison. /var/lib/nfs/etab is runtime state and must not be edited directly.
Apply Additions and Changes
|
# editor /etc/exports.d/projects.exports |
The -r option synchronises runtime exports with persistent files, removing entries deleted from configuration. The -a option applies all entries and -v shows each action.
Temporarily Add an Export
|
# exportfs -o ro,sync,root_squash client01.example.com:/srv/nfs/reference |
A command-line-only export is useful for a controlled test but is not persistent. Record it and remove it after the test so runtime state does not diverge from configuration.
Remove One Export
|
# exportfs -u client01.example.com:/srv/nfs/reference |
Remove an Export Persistently
|
# editor /etc/exports.d/projects.exports |
Warning: exportfs -ua unexports everything and can disrupt every client. Use it only during a planned shutdown or a deliberately isolated test.
Safe Change Sequence
- Confirm which clients are using the export and whether open files or locks are present.
- Back up the export files and capture exportfs -v.
- Change one entry and run exportfs -rav.
- Review exportfs -v for unexpected clients or options.
- Remount or retest from an authorised client and a deliberately unauthorised client.
- Monitor logs and application behaviour before deleting the rollback copy.
Configure an NFSv4-Only Server
NFSv4-only operation reduces open ports and removes dependencies on the NFSv3 MOUNT, lock, and status-notification path. Use it only after confirming that all clients support the required NFSv4 minor versions.
Create /etc/nfs.conf.d/server.conf:
|
[nfsd] |
To allow only NFSv4.1 and NFSv4.2, make the minor-version choices explicit:
|
[nfsd] |
Do not mask rpcbind or rpc-statd merely because one NFS service no longer needs them; another installed application can depend on RPC. First inventory rpcinfo -p, systemctl list-dependencies, package dependencies, and monitoring requirements. The firewall should expose only the services actually required by clients.
Bind NFS to Selected Server Addresses
On a multi-homed server, the [nfsd] host setting can restrict listeners to selected addresses or names. Confirm syntax and support with man nfs.conf and rpc.nfsd on the installed release, then test both IPv4 and IPv6.
|
[nfsd] |
Binding a listener does not replace firewall policy or the export client allow-list. It only controls where the service listens.
Support NFSv3 with Fixed Ports
NFSv3 needs rpcbind and auxiliary RPC programs. Dynamic ports make firewall rules difficult, so pin the relevant daemons to documented unused ports. Check for conflicts before activation and test TCP and UDP behaviour required by the actual clients.
Example /etc/nfs.conf.d/nfsv3.conf:
|
[nfsd] [mountd] [statd] [lockd] |
The example disables NFS UDP while retaining TCP. Some legacy clients require UDP; enable it only when required and include equivalent firewall rules. Verify actual daemon ports with rpcinfo -p rather than assuming that a configuration file was honoured.
UFW Rules for the Example NFSv3 Port Set
|
# ufw allow from 192.0.2.0/24 to any port 111 proto tcp comment “RPC bind TCP” |
The outgoing statd port controls notifications sent by the server and may need an egress or peer rule depending on network policy. Confirm packet flow with tcpdump during a planned lock-recovery test.
Native nftables Firewall Examples
Use either UFW as the policy manager or a directly managed nftables ruleset. Do not maintain two independent rule managers that overwrite or contradict each other.
NFSv4-Only Input Rule
|
table inet filter { chain input { |
Merge this concept into the host’s existing ruleset rather than replacing a production firewall. Preserve management, monitoring, DNS, time, and other required traffic.
Trace a Firewall Decision
|
# nft list ruleset |
A SYN arriving at the interface but no SYN-ACK leaving suggests a local listener or firewall problem. No arriving SYN suggests routing, upstream ACL, address, DNS, or client-side problems.
Identity, UID/GID Mapping, and Squashing
Understand sec=sys
With sec=sys, the client kernel sends UNIX-style numeric credentials. The server generally trusts those numbers as supplied by an authorised client. Matching usernames are not sufficient; the numeric UID and GID must represent the same person or service on every system. A client administrator can normally create a local account with an arbitrary UID, so sec=sys should be used only on trusted, managed clients and protected networks.
|
$ id projectuser |
Demonstrate Root Squashing
Server export:
|
/srv/nfs/projects 192.0.2.0/24(rw,sync,no_subtree_check,root_squash) |
Client test:
|
# touch /mnt/projects/created-by-client-root |
The resulting owner can be the anonymous UID rather than 0. That is expected. Grant normal users or a service group the required permission instead of disabling root squashing.
Map All Users to a Dedicated Anonymous Account
|
# groupadd –system –gid 2001 nfsdrop |
This pattern deliberately removes individual ownership. It can be useful for a controlled ingest area, but it is unsuitable where per-user accountability is required.
NFSv4 ID Mapping Domain
Current Linux NFSv4 deployments often use numeric IDs directly for ordinary sec=sys operation, but idmapd can still be involved in particular paths and legacy combinations. If names appear as nobody or ownership looks inconsistent, inspect /etc/idmapd.conf, DNS domain assumptions, daemon state, and actual numeric values before changing permissions.
|
$ grep -Ev “^[[:space:]]*(#|$)” /etc/idmapd.conf |
Clear ID-mapping caches only during troubleshooting and after correcting the underlying domain or identity source. Cache clearing is not a substitute for consistent directory data.
Kerberos-Secured NFS Server
Kerberos RPCSEC_GSS security flavours authenticate principals instead of trusting only client-supplied numeric IDs. krb5 authenticates, krb5i also protects integrity, and krb5p also encrypts NFS payload traffic. Correct DNS, synchronized time, a functioning KDC, and protected keytabs are prerequisites.
Prepare DNS, Time, and Packages
|
$ hostname –fqdn |
Create the NFS Service Principal and Keytab
Run the principal-management commands according to the Kerberos platform. A typical MIT Kerberos example is:
|
$ kadmin -p admin/admin -q “addprinc -randkey nfs/nfs01.example.com” |
Security note: /etc/krb5.keytab is a long-lived machine secret. Keep it owned by root, mode 0600, backed up only through an approved secret-handling process, and remove obsolete keys after a controlled rollover.
Require Kerberos on an Export
|
/srv/nfs/secure 192.0.2.0/24(rw,sync,no_subtree_check,root_squash,sec=krb5p) |
Offer Different Access by Security Flavour
Only ro/rw and squash behaviour can vary after a sec= group in the supported export syntax. One example is read-only legacy access and read-write Kerberos privacy access:
|
/srv/nfs/reference 192.0.2.0/24(sec=sys,ro,root_squash,sec=krb5p,rw,root_squash,sync,no_subtree_check) |
Keep such entries simple and verify exportfs -v. Complex security-flavour ordering is easy to misread.
Client Verification
|
$ kinit projectuser@EXAMPLE.COM |
Kerberos Troubleshooting
|
$ getent hosts nfs01.example.com |
A mount that works with sec=sys but fails with sec=krb5p normally points to DNS canonicalisation, time skew, missing or mismatched service keys, principal naming, ticket acquisition, or the GSS helper rather than basic IP reachability.
RPC-with-TLS on Supported Debian and Ubuntu Releases
Recent Linux NFS server and nfs-utils releases can use RPC-with-TLS as defined by RFC 9289. Availability depends on the installed kernel, nfs-utils, ktls-utils or tlshd packaging, and distribution release. Check the release documentation and man exports for xprtsec support before making it a requirement. A VPN remains a valid alternative when the platform does not provide server-side RPC-with-TLS.
Check Capability
|
$ man exports | col -b | grep -A12 -i “Transport layer security” |
Typical Server Components
|
# apt install -y ktls-utils # Package name and availability vary by release |
When the installed exports(5) supports policy enforcement, an export can require transport security:
|
/srv/nfs/private 192.0.2.0/24(rw,sync,root_squash,xprtsec=tls) |
Use xprtsec=mtls only after provisioning and validating client certificates and trust. TLS protects transport confidentiality; it does not replace export permissions, local ownership, or application authorisation. Combine it with an appropriate security flavour and client allow-list.
Quotas, ACLs, Extended Attributes, and Snapshots
Enable File-System Quotas First
NFS cannot enforce a useful remote quota if the underlying file system has no local quota configuration. Enable user, group, or project quotas according to the file system, remount requirements, and storage policy, then verify locally before exposing quota information remotely.
|
$ findmnt -no SOURCE,FSTYPE,OPTIONS /srv/nfs/projects |
Provide Remote Quota Information
|
# apt install -y quota |
If the quota daemon uses a fixed port, allow that TCP/UDP port only from client networks and document it with the NFSv3 RPC port plan. Service names and default options can differ by release, so confirm systemctl cat rpc-rquotad and rpc.rquotad –help before changing the port.
ACL and Extended Attribute Tests
|
$ getfacl -p /srv/nfs/projects |
Test the real client and application. Support for a local feature does not automatically prove that every NFS version, client kernel, mount option, and application will use it as expected.
Snapshots and Backups
Take snapshots on the server storage layer, not from a client that sees only the network view. Before a snapshot intended for application recovery, quiesce or coordinate the workload. For databases and virtual-machine images, use application-aware or hypervisor-aware backup methods rather than assuming a crash-consistent file copy is sufficient.
Performance Tuning and Capacity Planning
Measure before tuning. NFS throughput can be limited by storage latency, queue depth, network loss, link speed, CPU, server thread availability, synchronous-write behaviour, client mount choices, file-size distribution, or application locking. Changing rsize, wsize, thread counts, or async without identifying the bottleneck can make reliability worse.
Establish a Baseline
|
$ uptime |
NFS Server Thread Count
The [nfsd] threads setting controls the number of server worker threads. Too few can limit concurrency; excessively many consume memory and do not repair slow storage. Increase in measured steps while observing RPC backlog, CPU, and storage latency.
|
[nfsd] |
Interpret sync and async Carefully
sync protects the NFS protocol guarantee that a completed stable write survives a server crash, subject to honest storage hardware. async can produce attractive benchmark results by acknowledging before stable storage, but a sudden reset can lose acknowledged data or leave application structures inconsistent. Prefer better storage, write-back cache with power-loss protection, batching, and application tuning before changing to async.
Network and Storage Tests
|
# iperf3 -s |
Run destructive benchmarks only in an isolated test directory with an approved data set. A local storage benchmark and a network iperf3 test help separate the two paths, but the final test must use the real NFS client, mount options, file sizes, concurrency, and application I/O pattern.
Common Performance Indicators
|
Observation |
Likely direction |
|
High disk await and utilisation; network below capacity |
Underlying storage or synchronous commit latency. |
|
Interface drops, CRC errors, retransmissions, or duplex mismatch |
Physical or data-link problem before NFS tuning. |
|
Many retransmissions with normal server storage |
Loss, congestion, MTU, firewall state, or overloaded network path. |
|
One client slow, others normal |
Client route, NIC, mount options, DNS, credentials, or local workload. |
|
Small-file metadata workload slow |
Directory contention, storage metadata latency, lookup/cache behaviour, or application serialization. |
|
All nfsd threads busy and RPC backlog grows |
Consider more threads only after confirming CPU and storage headroom. |
|
Write benchmark fast with async but unsafe for workload |
Do not treat unsafe acknowledgement semantics as a storage upgrade. |
Monitor the NFS Server
Exports, Clients, and Operations
|
$ exportfs -v |
showmount reflects the older mount protocol and is not a complete list of NFSv4 clients. Use nfsdclnts where available, connection state, NFSv4 recovery data, application inventory, and central monitoring together.
Sockets and Connection State
|
$ ss -lntup | grep -E “:2049\b|rpc” |
Interface and Packet Monitoring
|
$ ip -s -s link show dev enp1s0 |
Logs
|
# journalctl -u nfs-server -b |
Increase daemon debug logging only for a bounded troubleshooting window. Verbose RPC and authentication logs can be noisy and can expose client names or operational details. Record the prior setting and revert it after collecting evidence.
Maintenance, Backups, and High Availability
Planned Maintenance Sequence
- Identify active clients, open files, lock-sensitive applications, and the expected outage behaviour.
- Stop or quiesce applications that cannot safely tolerate a pause.
- Confirm backups or storage snapshots and preserve /etc/exports, /etc/nfs.conf.d, keytabs, certificates, and service metadata according to policy.
- Apply storage or operating-system maintenance through console access.
- Verify mounts, file-system health, exportfs -v, protocol versions, firewall state, and service listeners before reopening applications.
- Test create, read, rename, lock, and delete operations using an ordinary client account.
Configuration Backup Set
|
# tar –xattrs –acls -czf /root/nfs-config-$stamp.tar.gz \ |
Handle /etc/krb5.keytab and TLS private keys separately as secrets. A normal configuration archive can have a broader readership than a key archive.
High Availability Design Principles
- Use storage that can be activated safely on only the intended server, or a supported clustered file system and NFS stack.
- Use fencing to prevent two nodes from exporting the same non-cluster-safe writable file system simultaneously.
- Move a stable service IP and DNS identity with the NFS service, not independently.
- Preserve or coordinate NFSv4 recovery state and grace periods so locks and opens recover correctly after failover.
- Keep export definitions, UID/GID sources, Kerberos keys, TLS trust, and firewall rules consistent on every eligible node.
- Test abrupt failure, planned migration, lock recovery, long-running I/O, and client retry behaviour before declaring the service highly available.
Pacemaker and resource-agent design is environment-specific and should follow the storage vendor and cluster distribution documentation. Do not build NFS failover by merely copying /etc/exports and floating an address between two independently writable local disks.
Troubleshooting Workflow
Troubleshoot from the lowest failing layer upward. Capture evidence before restarting services, because a restart can remove the state needed to identify the original fault.
1. Confirm Server Storage
|
$ findmnt -R /srv/nfs |
2. Confirm Service and Protocol
|
$ systemctl status nfs-server –no-pager |
3. Confirm the Effective Export
|
$ exportfs -v |
4. Confirm Network and Firewall
|
$ ip route get 192.0.2.21 |
5. Confirm Identity and Permissions
|
$ id projectuser |
6. Reproduce from the Client
|
$ getent hosts nfs01.example.com |
Common Errors and Interpretations
|
Symptom |
Likely causes |
Checks and corrective direction |
|
access denied by server while mounting |
Wrong path, client not in allow-list, wrong security flavour, DNS selector mismatch, stale export table. |
Compare requested path with exportfs -v; use an IP/CIDR test; run exportfs -rav; inspect mountd/GSS logs. |
|
Permission denied after a successful mount |
POSIX mode/ACL, UID/GID mismatch, root_squash, read-only export or file system, quota, application identity. |
Use id, ls -ln, getfacl -n, namei -om, findmnt, quota tools, and a non-root create test. |
|
read-only file system |
Export is ro, client mounted ro, underlying file system is ro, or file-system error forced read-only mode. |
Check exportfs -v, nfsstat -m, findmnt on server, and kernel I/O logs. |
|
stale file handle |
Exported object was replaced, file system was remounted with changed identity, snapshot/restore changed handles, or a subtree moved. |
Correct server storage/export identity first; then unmount/remount affected clients. Avoid hiding the root cause with repeated remounts. |
|
server not responding |
Service down, firewall, route, packet loss, overloaded storage, hung kernel I/O, or address failover problem. |
Check TCP 2049, tcpdump both ends, ss, nfsstat, iostat, interface errors, and server console. |
|
NFSv4 works but showmount fails |
Pure NFSv4 service does not expose the older MOUNT protocol. |
Use exportfs -v and a direct NFSv4 mount; do not open NFSv3 ports only to satisfy showmount. |
|
NFSv3 mount works but locks fail |
lockd/statd port blocked, reboot notification failure, or mixed TCP/UDP policy. |
Check rpcinfo -p, fixed ports, rpc-statd logs, packet capture, and a controlled lock test. |
|
nobody / nogroup ownership |
Squashing, missing identity, ID-mapping domain mismatch, or unknown numeric IDs. |
Inspect export options, ls -ln, getent, idmapd settings, and client/server identity sources. |
|
Kerberos permission or mount failure |
No ticket, wrong principal, DNS mismatch, clock skew, keytab problem, GSS helper stopped, sec mismatch. |
Use klist, kvno, klist -k, chronyc, forward/reverse DNS, rpc-svcgssd journal, and sec= mount options. |
|
Slow writes |
sync commit latency, storage saturation, small random I/O, network loss, too few threads, application fsync pattern. |
Correlate nfsstat, iostat, sar, ss -ti, packet loss, and client workload before tuning. |
|
Cannot unexport or unmount cleanly |
Active processes, current working directory, open files, locks, or application retry loop. |
Use fuser -vm, lsof +D carefully, client inventory, application shutdown, and planned maintenance. |
Diagnostic Snapshot Collection
Collect a bounded state package before making disruptive changes. Review it for secrets before sending it outside the organisation.
|
# stamp=$(date +%F-%H%M%S) |
Do not include /etc/krb5.keytab, TLS private keys, or confidential file names in a support archive unless the recipient and transfer method are explicitly approved.
Security Hardening Checklist
- Prefer NFSv4 and disable NFSv3 when the complete client inventory permits it.
- Restrict exports and firewall rules to explicit hosts or CIDR networks; do not rely on a writable * export.
- Keep root_squash enabled and document every exception to it.
- Use sync unless a formal risk decision accepts possible acknowledged-data loss with async.
- Keep UID/GID data centrally managed and test an ordinary account, not only root.
- Use sec=krb5i or sec=krb5p for stronger user authentication and protection where Kerberos is available.
- Use RPC-with-TLS or a VPN for transport encryption on platforms that support it, and require it explicitly when policy demands it.
- Protect keytabs and private keys as secrets; rotate and remove obsolete material.
- Keep the server, kernel, nfs-utils, and storage firmware patched through the distribution support channel.
- Monitor export changes, service restarts, authentication failures, file-system errors, capacity, and network drops.
- Back up configuration and data, and test restoration to a clean system.
- For HA, use fencing and a supported storage/cluster design; never permit split-brain writers.
Command Reference Summary
|
Task |
Command |
|
Install server |
apt install -y nfs-kernel-server nfs-common |
|
Start at boot |
systemctl enable –now nfs-server |
|
Show exports |
exportfs -v |
|
Apply persistent exports |
exportfs -rav |
|
Show normalised exports |
exportfs -s |
|
Unexport one client/path |
exportfs -u client:/path |
|
Dump daemon configuration |
nfsconf –dump |
|
Show enabled NFS versions |
cat /proc/fs/nfsd/versions |
|
Show RPC programs |
rpcinfo -p localhost |
|
Show listeners |
ss -lntup |
|
Server RPC statistics |
nfsstat -s |
|
Watch server RPC statistics |
nfsstat -s 1 |
|
Inspect NFSv4 clients |
nfsdclnts –clientinfo |
|
Service logs |
journalctl -u nfs-server -b |
|
Kernel NFS logs |
journalctl -k -b | grep -Ei “nfs|rpc|lockd” |
|
Check path permissions |
namei -om /srv/nfs/projects; getfacl -pn /srv/nfs/projects |
|
Capture NFSv4 traffic |
tcpdump -ni any tcp port 2049 -w nfs.pcap |
|
UFW NFSv4 allow |
ufw allow from 192.0.2.0/24 to any port 2049 proto tcp |
Authoritative References
Use the manual pages installed on the exact server because option availability follows the installed kernel and nfs-utils version:
- man 5 exports
- man 8 exportfs
- man 5 nfs.conf
- man 8 rpc.nfsd
- man 8 rpc.mountd
- man 7 nfs.systemd
- man 8 nfsdclnts
- man 8 rpc.svcgssd
- Ubuntu Server documentation – Network File System (NFS) – installation, unified configuration, service restarts, and Kerberos examples
- Debian manpages – exports(5) – export syntax, client selectors, security, and option semantics
- Debian manpages – exportfs(8) – runtime export administration
- Debian manpages – nfs.conf(5) – daemon configuration sections and settings
Validate every example against the release documentation, local man pages, security policy, storage design, and a non-production test client before applying it to a live service.
Check out our other Cheat Sheets and Blogs and if you would like us to write a cheat sheet for you, for FREE, (and we find it suitable) Contact Us.