.TH NFSD 1 2026-09-21 nfs "User Commands"
.SH NAME
nfsd \- serve a local directory tree over NFSv4.2
.SH SYNOPSIS
.B nfsd
.RB [ \-addr
.IR addr ]
.RB [ \-export
.IR dir ]
.RB [ \-ro ]
.RB [ \-tls-cert
.IR file ]
.RB [ \-tls-key
.IR file ]
.RB [ \-log-ops ]
.RB [ \-max-connections
.IR n ]
.RB [ \-state-dir
.IR dir ]
.RB [ \-config
.IR file ]
.RB [ \-version ]
.SH DESCRIPTION
.B nfsd
exports one local directory tree over NFSv4.2 on a single TCP port, as
RFC 8881 and RFC 7862 describe and RFC 8276, RFC 7861 and RFC 9289
extend. NFSv4 carries everything on the one port: there is no
portmapper, no mountd and no separate locking protocol.
.PP
The tree is served read and write. Every request is evaluated against
the identity the client presents, so the permission bits of the served
files decide what each caller may do, and the objects a client creates
carry the identity it presented. The server keeps its open, lock and
delegation state across the connections of a client and drops it when
the client reboots or its lease lapses.
.PP
On
.B SIGINT
or
.B SIGTERM
the listener closes and the process exits cleanly; clients recover
through their session replay caches, so a stopped server costs no
state.
.SH OPTIONS
.TP
.BI \-addr " addr"
The TCP address to listen on. Defaults to
.IR :2049 .
.TP
.BI \-export " dir"
The directory to serve, relative or absolute. The directory must exist;
a missing or non directory path ends the start up. Required: without it
the server prints a reminder and exits.
.TP
.B \-ro
Serve the export read only. Every operation that would change the tree
answers NFS4ERR_ROFS; the reads of every half, the attributes, the
extended attributes and the hole seeking included, work unchanged.
.TP
.B \-root-squash
Map a client claiming uid 0 onto nobody: the credential acts as uid
65534 with group 65534, the superuser grant is gone, and the objects
root creates carry nobody. The default keeps the trust AUTH_SYS hands
to the claim; an operator serving untrusted clients turns this on.
.TP
.BI \-tls-cert " file"
The certificate chain in PEM that enables RPC-with-TLS of RFC 9289.
A client probes with AUTH_TLS, the connection upgrades in place, and a
client that skips the upgrade is refused with auth too weak for every
procedure but the NULL of the probe. Goes together with
.BR \-tls-key ;
either alone ends the start up.
.TP
.BI \-tls-key " file"
The private key in PEM for RPC-with-TLS, matching
.BR \-tls-cert .
.TP
.B \-log-ops
Log one line per operation to standard error: the operation, the status
it answered and the time it took, as
.BR "nfs: LOOKUP status 0 84\es" .
Off by default: a quiet server answers nothing on the log.
.HP
.B \-config
.I file
The configuration file in TOML, described under
.B CONFIGURATION
below. Never read unless the flag names it; the flags override the
file. A file that fails the read, the schema or the validation ends
the start up with the file and the line named.
.TP
.BI \-max-connections " n"
The cap on connections served at once. A connection offered above the
cap closes at once and the client sees an immediate end of file; the
server answers nothing on it. Zero, the default, means no cap.
.TP
.BI \-state-dir " dir"
The directory for the persisted client state. The file handle map and
the open state are written there as they change, a restart loads them
back, and the grace window after a start lets a client reclaim its
opens with CLAIM_PREVIOUS. The directory is created with owner only
permissions when it is missing. Without the flag nothing persists and
a restart starts from an empty state, as before.
.TP
.B \-version
Print the version and exit. A build made at a tag reports the tag, a
build outside version control reports
.IR devel .
.SH CONFIGURATION
The server reads a TOML configuration file when
.B \-config
names one, and never otherwise. The file carries
.BR listen ,
.BR log-ops ,
.BR state-dir ,
.BR max-connections ,
a
.B [tls]
table with
.B cert
and
.BR key ,
and one
.B [[export]]
table with
.BR path ,
.B read-only
and
.BR root-squash .
The flags override the file; every key, type, default and effect is
described in docs/CONFIGURATION.md of the repository. A file that
breaks the schema or the syntax ends the start up with the file and
the line of the fault.
.SH EXIT STATUS
.TP
.B 0
The version was printed, or the server shut down cleanly on
.B SIGINT
or
.BR SIGTERM .
.TP
.B 1
The start up or the service failed: no export was given, the export
path is missing or is not a directory, the listen address could not be
bound, or the listener failed.
.SH EXAMPLES
Serve
.I /srv/demo
on the default port:
.PP
.RS
.nf
nfsd \-export /srv/demo
.RE
.PP
Serve on a loopback address and print the version first:
.PP
.RS
.nf
nfsd \-version
nfsd \-export /srv/demo \-addr 127.0.0.1:2049
.RE
.PP
Read the tree with
.BR nfs (1):
.PP
.RS
.nf
nfs \-addr 127.0.0.1:2049 ls
.RE
.SH AUTHOR
Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
.SH LICENCE
MIT. See the LICENSE file in the repository.
.SH SEE ALSO
.BR nfs (1),
https://sourcedock.dev/petrbalvin/nfs