SERVER DOCUMENTATION
nfsdiag v0.22.0 — the server namespace.
Runs on the NFS server itself and audits its configuration.
This page covers nfsdiag server. To test a server from a
client machine (network, RPC, mounts, permissions, performance), see
the client documentation. Project-wide
sections — output formats, packaging, security, changelog — also live
there.
CONTENTS
# CLI reference
nfsdiag server [OPTIONS]
At least one check must be selected; running
nfsdiag server with no check prints the
usage and exits 2. Checks report through the same engine as the
client namespace, so severity levels and exit codes behave the same
way.
| flag | arg | default | description |
|---|---|---|---|
| --all | — | — | Run every server check. |
| --daemons | — | — | Check the kernel nfsd, rpcbind, rpc.mountd, rpc.statd, rpc.idmapd and gssproxy/rpc.svcgssd, plus the program registrations in the local rpcbind. |
| --exports-audit | — | — | Audit the exports file: flag syntax errors, exports without a client list, and risky options such as no_root_squash, insecure, and read-write exports to any host. |
| --ports-firewall | — | — | Check TCP listeners on 2049/111, report the dynamic mountd/statd/lockd ports, and run a best-effort firewalld/nftables rule check. |
| --storage-health | — | — | For each export: directory exists, space and inode usage (warning above 90%), and the filesystem type, warning about types that break NFS (tmpfs, overlayfs, NFS re-export). |
| --version-matrix | — | — | Report the NFS versions enabled in /proc/fs/nfsd/versions, the NFSv4 lease and grace times, and the maximum block size. |
| --sysctl-advisor | — | — | Detect nfsd thread starvation from the th histogram in /proc/net/rpc/nfsd and check network buffer tunables, with recommendations. |
| --security-audit | — | — | Deep exports analysis beyond syntax: subtree_check, insecure_locks, all_squash without anonuid, sec=sys, duplicate paths, nested exports without crossmnt. |
| --idmap-check | — | — | Validate idmapd.conf: NFSv4 domain vs the host's DNS domain (mismatches map users to nobody) and the Nobody-User mapping. |
| --krb5-server | — | — | Server-side Kerberos: keytab presence and permissions, nfs/ principal, default realm, gss daemons, NTP synchronization. |
| --acl-check | — | — | Verify POSIX ACL support on the filesystem under each export with a non-destructive xattr probe. |
| --squash-check | — | — | Mount each export from localhost, create a file as root and report the effective identity mapping. Intrusive (mounts and writes); not part of --all; requires root. |
| --audit-trail | — | — | With --output-dir, capture copies of the exports file, nfs.conf, idmapd.conf and krb5.conf plus CONFIG.SHA256SUMS for incident evidence. |
| --rpc-stats | — | — | Analyze /proc/net/rpc/nfsd: reply-cache hit rate, bad RPC calls (auth failures or malformed requests) and packet/byte traffic. |
| --locks | — | — | Summarize held locks by type from /proc/locks, the NFSv4 lease and grace times, and NLM/NSM (NFSv3 locking) registration. |
| --clients | — | — | Inventory connected NFSv4 clients from /proc/fs/nfsd/clients/ — minor version and callback state — plus established TCP connections on 2049. |
| --client-states | — | — | Count NFSv4 opens, locks, delegations and layouts held per client, flagging clients that leak file handles or hoard delegations. |
| --latency-profile | — | — | eBPF latency histogram of nfsd read/write/commit (needs an --enable-ebpf build and root). Samples for --duration seconds. Not part of --all. |
| --per-client-trace | — | — | eBPF per-client nfsd ops and average latency, to find the client degrading the server for everyone. |
| --backend-bench | — | — | Write/read benchmark of the storage under each export — the raw disk ceiling — to separate a storage bottleneck from an NFS/network one. |
| --capture | — | — | Capture NFS traffic on port 2049 with tcpdump (needs root); if tshark is present, summarize it. |
| --duration | SEC | 10 | Sampling window for --latency-profile, --per-client-trace and --capture. |
| --ha-check | — | — | High-availability validation: exports without an explicit fsid=, whether /var/lib/nfs is on shared storage, and pacemaker NFS resources. Not part of --all. |
| --ganesha-check | — | — | Detect nfs-ganesha (userland) vs kernel nfsd, parse ganesha.conf (EXPORT blocks and FSALs), and detect a container/Kubernetes environment. |
| --log-intel | — | — | Scan the journal (or /var/log/messages under --root) for known nfsd/mountd/statd problem signatures and report each with a suggested fix. |
| --rmtab-audit | — | — | Detect stale /var/lib/nfs/rmtab entries (count 0) and orphaned NSM (sm/) monitors that trigger sm-notify storms at boot. |
| --memory-pressure | — | — | Assess memory pressure relevant to NFS: MemAvailable against the reply cache and dentry/inode caches, plus vm.* tunables. |
| --exports-file | FILE | /etc/exports | Exports file to audit instead of /etc/exports. |
| --root | DIR | / | Read /proc and /etc under DIR instead of the live system — an extracted sosreport, for example. Checks that need the live system are skipped with an explanation. |
| --json | [PATH] | — | Emit a structured JSON report to PATH. Use - or omit for stdout. |
| --html | [PATH] | — | Emit a self-contained HTML report to PATH. Use - or omit for stdout. |
| --output-format | FMT | text | Terminal output format: text, table, ndjson, prometheus, junit. |
| --output-dir | DIR | — | Write a bundle containing JSON, HTML, evidence text, and SHA256 checksums. |
| --watch | SEC | — | Re-run the selected checks every SEC seconds until interrupted. |
| --listen | [ADDR:]PORT | 127.0.0.1 | Serve Prometheus server metrics (nfsd threads, DRC, RPC, clients, locks) over HTTP, refreshing every --watch seconds. --output-format prometheus prints the same gauges once. |
| -v, --verbose | — | — | Show all diagnostic steps, including INFO-level events. |
| -q, --quiet | — | — | Suppress human stdout. |
| -V, --version | — | — | Print nfsdiag <version> and exit 0. |
| -h, --help | — | — | Print the help text and exit 0. |
# exports audit
--exports-audit parses the exports file
line by line and reports:
| syntax | unparseable lines with the line number · relative export paths · unterminated quoted paths · exports with no client list (exported to the world) |
|---|---|
| security |
no_root_squash (remote root acts as
local root) · insecure (accepts
requests from unprivileged source ports) · read-write exports
to *
|
Syntax problems are reported as fail,
risky options as warn. A clean file
produces a single ok line with the entry
count.
nfsdiag server — exports audit
$ sudo nfsdiag server --exports-audit nfsdiag 0.22.0: exports audit of /etc/exports [WARN] exports /srv/data: '*(rw,no_root_squash)': no_root_squash lets remote root act as local root [FAIL] exports: line 7: export path must be absolute summary: ok=0 warn=1 fail=1 $
Use --exports-file to audit a staged copy
before applying it:
nfsdiag server --exports-audit --exports-file /tmp/exports.new# exit codes
| 0 | no warnings or failures were recorded |
|---|---|
| 1 | at least one warning or failure was recorded |
| 2 | usage error or runtime failure (no check selected, unknown flag, unreadable exports file) |
Same semantics as the client namespace, so the same CI gates and alert rules work for both.
# server checks
The nfsdiag server namespace groups its checks by theme.
The CLI reference above lists every flag.
| foundation | --daemons · --version-matrix · --ports-firewall · --storage-health · --sysctl-advisor · --exports-audit |
|---|---|
| security | --security-audit · --squash-check · --krb5-server · --idmap-check · --acl-check · --audit-trail |
| live state | --clients · --client-states · --locks · --rpc-stats · --log-intel · --rmtab-audit · --memory-pressure |
| metrics | --output-format prometheus · --listen (HTTP exporter) · --watch |
| performance | --latency-profile (eBPF) · --per-client-trace (eBPF) · --backend-bench · --capture |
| HA / ecosystem | --ha-check · --ganesha-check (nfs-ganesha and Kubernetes awareness) |
| paired mode | the client's --peer correlates a client run with the server's --listen metrics to say, with evidence, which side of the wire the problem is on |
The eBPF checks need a build configured with
./configure --enable-ebpf (clang, bpftool and libbpf).
# see also
- client documentation — testing a server from a client machine, output formats, packaging, security, architecture
- changelog
man 8 nfsdiag— installed bymake installexportfs(8),exports(5)