No description
Find a file
Henry Bubert d9a695dfbd
Some checks failed
Code scanning - action / CodeQL-Build (push) Has been cancelled
nfs: let the embedder authorize each call by its AUTH_UNIX credential
A Handler learned who was calling only in Mount, from the raw RPC
header. Every other procedure ran for anyone holding a file handle, and
ACCESS echoed the rights asked for. A server for one user on a shared
machine, like a loopback mount, could not keep the other local users
out.

Two additions, both opt-in:

- AuthUnixFromContext(ctx) (AuthUnix, bool) returns the parsed AUTH_UNIX
  credential (uid, gid, groups, machine name, stamp) of the call a
  context belongs to: the one Mount, FSStat and Authorize get. It reports
  false for AUTH_NULL, other flavors and a malformed AUTH_UNIX body, one
  over RFC 5531's bounds (255-byte name, 16 groups) or with trailing
  bytes.
- Server.Authorize func(ctx, prog, vers, proc uint32) error is called
  before every procedure other than NULL. An error refuses the call with
  that procedure's own failure: NFS3ERR_ACCES and its resfail body (or
  the status of an *NFSStatusError, such as NFS3ERR_PERM or ROFS),
  MNT3ERR_ACCES or MNT3ERR_PERM, NFS4ERR_ACCESS or NFS4ERR_PERM with the
  COMPOUND's tag, and AUTH_ERROR AUTH_TOOWEAK for UMNT, which has no
  status. With Authorize set, a malformed AUTH_UNIX credential is
  rejected with AUTH_BADCRED before Authorize sees it.

ACCESS asks Authorize about the procedure behind each right requested
(READ and EXECUTE: READ, LOOKUP: LOOKUP, MODIFY and EXTEND: WRITE,
DELETE: REMOVE) and leaves out the refused ones, so a client does not
offer what the server will refuse. A hook on Server rather than an
optional Handler interface, because handlers are usually wrapped in
helpers.CachingHandler, which would hide it.

Without Authorize nothing changes. MSG_DENIED replies, which nothing
sent before, needed two fixes: they wrote the accept_stat-like
ResponseCode where the reject_stat belongs, and AuthError and
RPCMismatchError encoded their bodies little-endian.

Checked on a macOS mount: the client sends AUTH_SYS whenever Mount
offers AuthFlavorUnix, with the user's uid and up to 16 groups. A
read-only policy lets cat through, makes test -w false and touch and rm
fail with EACCES; refusing the mounting user makes mount_nfs fail with
"Permission denied".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 04:49:44 -03:00
.github bump go.mod version (#56) 2022-12-07 07:23:50 +00:00
example finish move to preferred go:build formatting 2024-01-02 16:43:25 +01:00
file Updated for specific case for wasm 2024-10-24 11:55:24 +00:00
helpers helpers: take a cache limit below one as one 2026-11-11 04:49:43 -03:00
auth.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
auth_test.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
auth_unix_test.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
conn.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
conn_concurrency_test.go conn: stop handlers and close the socket when the connection ends 2026-11-09 10:05:27 -03:00
CONTRIBUTING.md Create CONTRIBUTING.md 2023-11-29 21:00:54 +00:00
drc.go conn: one duplicate request cache per server, in sequential mode too 2026-11-11 04:49:38 -03:00
drc_test.go conn: one duplicate request cache per server, in sequential mode too 2026-11-11 04:49:38 -03:00
errors.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
file.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
filesystem.go mounting, directory listing work 2020-05-16 22:45:20 -07:00
go.mod bump memphis for windows support of the osview example 2024-12-11 15:06:35 +09:00
go.sum bump memphis for windows support of the osview example 2024-12-11 15:06:35 +09:00
handler.go simplify 2023-12-31 22:28:56 +01:00
LICENSE cleanup hello world example 2020-05-23 10:31:15 -07:00
locker.go Add NFSv4.0 with byte-range locking 2026-09-22 16:52:49 -03:00
log.go log interface 2023-08-06 17:28:08 -07:00
memlocker.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
memlocker_test.go Add NFSv4.0 with byte-range locking 2026-09-22 16:52:49 -03:00
mount.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
mount_test.go mount: make a root handle only for a granted mount 2026-11-11 04:49:43 -03:00
mountinterface.go Round-trip test 2020-06-05 10:43:02 -07:00
nfs.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
nfs4_attrs.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onaccess.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onclose.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_oncommit.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_oncreate.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_ongetattr.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_ongetfh.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onlock.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onlockt.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onlocku.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onlookup.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onlookupp.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onopen.go nfs4: answer CLAIM_PREVIOUS reclaims with NFS4ERR_NO_GRACE 2026-09-26 13:32:30 -03:00
nfs4_onopenconfirm.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onopendowngrade.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onputfh.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onputrootfh.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onread.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onreaddir.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onreadlink.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onreleaselockowner.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onremove.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onrename.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onrenew.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onrestorefh.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onsavefh.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onsecinfo.go Address review: one file per NFSv4 operation, XDR structs, open stateids 2026-09-25 10:43:12 -03:00
nfs4_onsetattr.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onsetclientid.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onsetclientidconfirm.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_onwrite.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_state.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_state_test.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
nfs4_test.go nfs4: convert the SETCLIENTID result in the test client helper 2026-09-26 15:20:00 -03:00
nfs_concurrency_test.go conn: one duplicate request cache per server, in sequential mode too 2026-11-11 04:49:38 -03:00
nfs_fsinfo_test.go nfs: advertise the READ, WRITE and READDIR sizes the server handles 2026-11-11 04:49:37 -03:00
nfs_onaccess.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
nfs_oncommit.go remaining missing errors 2020-10-18 17:32:51 -07:00
nfs_oncreate.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onfsinfo.go nfs: advertise the READ, WRITE and READDIR sizes the server handles 2026-11-11 04:49:37 -03:00
nfs_onfsstat.go Properly map method errors 2020-10-18 17:27:56 -07:00
nfs_ongetattr.go replace fs.Stat with fs.Lstat 2024-02-11 23:51:11 -08:00
nfs_onlink.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onlookup.go Improve Lookup efficiency (#121) 2024-01-04 17:08:43 +00:00
nfs_onmkdir.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onmknod.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onpathconf.go Properly map method errors 2020-10-18 17:27:56 -07:00
nfs_onread.go nfs: read until the count is satisfied or EOF 2026-11-09 10:00:03 -03:00
nfs_onreaddir.go use consistent fileid for directory root 2023-12-13 08:04:23 +01:00
nfs_onreaddirplus.go Update test to validate large directories and rename 2024-01-04 10:52:57 +01:00
nfs_onreadlink.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onremove.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onrename.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onrmdir.go stricter error on rmdir 2026-07-21 10:28:31 -07:00
nfs_onsetattr.go use hash of file path for fileid when not provided. 2023-11-28 12:13:25 -08:00
nfs_onsymlink.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_onwrite.go nfs: close the file on every WRITE error path; prefer WriteAt 2026-11-09 10:00:03 -03:00
nfs_symlink_test.go nfs: act on a symlink itself, not on what it points to 2026-11-11 04:49:37 -03:00
nfs_test.go nfs_test: retry a go-nfs-client dial whose local port is taken 2026-11-11 04:49:34 -03:00
nfsinterface.go mounting, directory listing work 2020-05-16 22:45:20 -07:00
README.md nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
SECURITY.md Create SECURITY.md 2023-11-29 20:02:45 +00:00
server.go nfs: let the embedder authorize each call by its AUTH_UNIX credential 2026-11-11 04:49:44 -03:00
server_test.go NFS4 fixups: 2026-09-26 09:49:38 +02:00
time.go Fixed bug causing SETATTR to always fail when guard is supplied 2023-02-15 14:02:22 +00:00

Golang Network File Server

NFSv3 protocol implementation in pure Golang.

Current Status:

  • Minimally tested
  • Mounts, read-only and read-write support

Usage

The most interesting demo is currently in example/osview.

Start the server go run ./example/osview ..

The local folder at . will be the initial view in the mount. mutations to metadata or contents will be stored purely in memory and not written back to the OS. When run, this demo will print the port it is listening on.

The mount can be accessed using a command similar to mount -o port=<n>,mountport=<n> -t nfs localhost:/mount <mountpoint> (For Mac users)

or

mount -o port=<n>,mountport=<n>,nfsvers=3,noacl,tcp -t nfs localhost:/mount <mountpoint> (For Linux users)

API

The NFS server runs on a net.Listener to export a file system to NFS clients. Usage is structured similarly to many other golang network servers.

package main

import (
	"fmt"
	"log"
	"net"

	"github.com/go-git/go-billy/v5/memfs"
	nfs "github.com/willscott/go-nfs"
	nfshelper "github.com/willscott/go-nfs/helpers"
)

func main() {
	listener, err := net.Listen("tcp", ":0")
	panicOnErr(err, "starting TCP listener")
	fmt.Printf("Server running at %s\n", listener.Addr())
	mem := memfs.New()
	f, err := mem.Create("hello.txt")
	panicOnErr(err, "creating file")
	_, err = f.Write([]byte("hello world"))
	panicOnErr(err, "writing data")
	f.Close()
	handler := nfshelper.NewNullAuthHandler(mem)
	cacheHelper := nfshelper.NewCachingHandler(handler, 1)
	panicOnErr(nfs.Serve(listener, cacheHelper), "serving nfs")
}

func panicOnErr(err error, desc ...interface{}) {
	if err == nil {
		return
	}
	log.Println(desc...)
	log.Panicln(err)
}

Notes

  • Ports are typically determined through portmap. The need for running portmap (which is the only part that needs a privileged listening port) can be avoided through specific mount options. e.g. mount -o port=n,mountport=n -t nfs host:/mount /localmount

  • This server currently uses billy to provide a file system abstraction layer. There are some edges of the NFS protocol which do not translate to this abstraction.

    • NFS expects access to an inode or equivalent unique identifier to reference files in a file system. These are considered opaque identifiers here, which means they will not work as expected in cases of hard linking.
    • The billy abstraction layer does not extend to exposing uid and gid ownership of files. If ownership is important to your file system, you will need to ensure that the os.FileInfo meets additional constraints. In particular, the Sys() escape hatch is queried by this library, and if your file system populates a syscall.Stat_t concrete struct, the ownership specified in that object will be used. You can also return a file.FileInfo which doesn't vary between platforms so may be easier to deal with.
  • Access control: NFS clients assert who is calling, they don't prove it. With AUTH_UNIX (sec=sys) each call carries the caller's uid and gids, which nfs.AuthUnixFromContext returns. Set Server.Authorize to refuse calls by caller and procedure, for instance to serve only the user who mounted on a single-user machine; ACCESS then reports only the rights it allows. The Handler's Mount must offer nfs.AuthFlavorUnix for clients to send these credentials.

  • Relevant RFCS: 5531 - RPC protocol, 1813 - NFSv3, 1094 - NFS