# 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
```