feat: full NFSv4.2 server and client in pure Go

Assisted-by: GLM 5.3 Flash
2026-09-21 18:51:17 +02:00
commit a9b8039ef7
153 changed files with 34403 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 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](../man/nfsd.1) and [man/nfs.1](../man/nfs.1).
+
+## Synopsis
+
+```sh
+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](CONFIGURATION.md); never read unless named, the flags override it |
+| `-version` | | print the version and exit |
+
+```sh
+$ ./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 |
+
+```sh
+$ ./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:
+
+```sh
+mkdir -p /srv/demo && echo "ahoj" > /srv/demo/hello.txt
+./bin/nfsd -export /srv/demo -addr 127.0.0.1:2049
+```
+
+```sh
+./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
+```