nfs/docs/CLI.md

Command line

The reference below is taken from the programs' own help output. If the two disagree, the programs are right and this file is a defect. Both commands carry a manpage: man/nfsd.1 and man/nfs.1.

Synopsis

nfsd [-addr addr] [-export dir] [-version]
nfs [-addr host:port] [-concurrency 1-8] version | ls [path] | cat path | put local remote | get remote local | rm path | mkdir path | stat path | selftest

nfsd

The server exports one local directory tree over NFSv4.2 on a single TCP port and serves it read and write. It exits cleanly on SIGINT and SIGTERM.

Flag	Default	Effect
-addr	:2049	the TCP address to listen on
-export		the directory to serve; required, and the path must be an existing directory
-ro	false	serve the export read only: every mutation answers NFS4ERR_ROFS, the reads of every half work unchanged
-root-squash	false	map a client claiming uid 0 onto nobody (65534): no superuser grant, and objects root creates carry nobody
-tls-cert		the certificate chain in PEM for RPC-with-TLS (RFC 9289); requires -tls-key
-tls-key		the private key in PEM for RPC-with-TLS; requires -tls-cert
-log-ops	false	log every operation to stderr as nfs: OP status N duration
-max-connections	0	cap on live connections; a connection above the cap closes at once; 0 means no cap
-state-dir		directory for persisted client state: file handles and opens are written there as they change, a restart loads them back and serves a grace window, so a client reclaims its open with CLAIM_PREVIOUS; without it nothing persists
-config		configuration file in TOML, see CONFIGURATION.md; never read unless named, the flags override it
-version		print the version and exit

$ ./bin/nfsd -export /srv/demo -addr 127.0.0.1:2049
nfsd: serving /srv/demo on 127.0.0.1:2049

nfs

The client runs one operation against an NFSv4.2 server and works against any server that speaks the minor version, nfsd included. Paths address the server's namespace from its root.

Command	Purpose
version	print the version
ls [path]	list a directory, the root by default; one line per entry: name, size, octal mode
cat path	stream a file to standard output
put local remote	write a local file to the server; creates with mode 0644 and truncates first, so a shorter file leaves no tail
get remote local	copy a remote file into a local file; the local file is truncated first, so a shorter remote leaves no tail
rm path	remove one object from the server
mkdir path	make one directory on the server
stat path	print the type, size, octal mode and modification time of an object
selftest	run the whole operation matrix against the server: mkdir, touch, write and compare 64 KiB, list, rename, symlink, a nested directory, ownership of files created as another uid, setattr, and the removals; one line per check plus a summary, exit 1 when any check fails. The work directory is removed on success and left in place on failure

Flag	Default	Effect
-addr	127.0.0.1:2049	the server address
-concurrency	1	compounds in flight for get and put, 1 to 8; more slots move several chunks at once over the one connection

$ ./bin/nfs -addr 127.0.0.1:2049 ls
hello.txt	5	644
$ ./bin/nfs -addr 127.0.0.1:2049 cat /hello.txt
ahoj

Exit codes

Code	nfsd	nfs
0	clean shutdown on SIGINT or SIGTERM, or the version print	the operation completed
1	no export, a bad export path, a listen failure or a listener failure	the dial, the session or the operation failed
2		wrong arguments: no, unknown or starved subcommand

Examples

Serve a tree and read it from another terminal:

mkdir -p /srv/demo && echo "ahoj" > /srv/demo/hello.txt
./bin/nfsd -export /srv/demo -addr 127.0.0.1:2049

./bin/nfs -addr 127.0.0.1:2049 ls
./bin/nfs -addr 127.0.0.1:2049 cat /hello.txt
./bin/nfs -addr 127.0.0.1:2049 put README.md /readme.md
./bin/nfs -addr 127.0.0.1:2049 stat /readme.md