Synopsis #
NFS (Network File System) is a distributed file system protocol supported in the OpenBSD base system. It allows one system to share directories with others across a network. Clients can mount these shared directories and use them as if they were part of the local filesystem.
Set up an NFS server or client on OpenBSD, manage its daemons, and choose the access and mount options the network needs.
Server Configuration #
An OpenBSD system acting as an NFS server must run portmap(8) , mountd(8) , and nfsd(8) .
Create the shared directory and apply appropriate permissions:
doas mkdir -p /export/projects
doas chown root:users /export/projects
doas chmod 775 /export/projects
Shared directories must be declared in exports(5)
. For example, to share /export/projects with a local network, add this line to /etc/exports:
/export/projects -maproot=root: -network 192.168.1.0 -mask 255.255.255.0
The -maproot=root: directive preserves root access for trusted clients. The -network and -mask options limit access to a specific subnet. Use -alldirs only when exporting the root of a mounted filesystem; it permits mounts throughout that filesystem, rather than restricting access to one subdirectory.
The server daemons can be enabled and started as follows:
doas rcctl enable portmap mountd nfsd
doas rcctl start portmap mountd nfsd
After later changes to /etc/exports, reload the running mountd daemon and check /var/log/daemon for parsing errors:
doas rcctl reload mountd
To accept network lock requests from clients that support the NFS locking protocol, also enable rpc.lockd(8)
and rpc.statd(8)
. Their service names in rcctl(8)
are lockd and statd; the executable and manual page names retain the rpc. prefix:
doas rcctl enable lockd statd
doas rcctl start statd lockd
OpenBSD implements only the server side of this locking protocol. Starting these daemons does not enable an OpenBSD NFS client to acquire network locks.
If pf(4)
is enabled, permit the required RPC traffic from authorized clients. Allowing only sunrpc (port 111) and NFS (port 2049) is insufficient: mountd, and the locking daemons when enabled, also register ports with portmap. Inspect the registrations with rpcinfo -p server. OpenBSD’s mountd and nfsd do not provide options to select arbitrary listening ports.
Client Configuration #
The NFS client does not require additional packages. To mount a remote export manually:
doas mount -t nfs 192.168.1.10:/export/projects /mnt
To make the mount persistent, add it to /etc/fstab:
192.168.1.10:/export/projects /mnt nfs rw 0 0
The bg option retries an unsuccessful initial mount in the background. The soft option allows file operations to fail after a timeout; applications must be able to handle these failures. For example:
192.168.1.10:/export/projects /mnt nfs rw,bg,soft 0 0
A system used only as an NFS client does not need a local portmap daemon for mounting and accessing exports. The client contacts the server’s portmap daemon. OpenBSD’s mount_nfs(8)
has no nolock option; network locking is not implemented for OpenBSD NFS clients.
To unmount a filesystem:
doas umount /mnt
Service Behavior and Options #
NFS requests may use TCP or UDP. OpenBSD’s mount_nfs uses UDP by default; use mount_nfs -T or the tcp mount option to select TCP. The nfsd service started through rcctl serves both protocols by default, using -tun 4. When nfsd is invoked directly without flags, it serves UDP only.
By default, NFS file operations retry indefinitely when the server does not respond. The soft option allows calls to fail after a timeout. Using bg causes failed initial mount attempts to retry in the background. These settings should be chosen based on application tolerance for delay or failure.
Access Control #
The maproot and mapall options in /etc/exports control how client user IDs map to local users. Mapping root to nobody is a common security measure to prevent remote root access:
/export/projects -maproot=nobody -network 192.168.1.0 -mask 255.255.255.0
Use care when exporting writable directories to untrusted clients. It is advisable to restrict access by network, use read-only exports, and assign minimal privileges when root mapping is not required.
Monitoring and Debugging #
To confirm exports:
doas showmount -e localhost
To verify service status:
doas rcctl check mountd
doas rcctl check nfsd
Use tail -f /var/log/messages or dmesg to observe errors or mount failures. On the client, mounting with -v may provide additional output:
doas mount -v -t nfs server:/path /mnt
Compatibility Notes #
The OpenBSD implementation of NFS is compatible with other Unix systems using NFSv2 or NFSv3. NFSv4 is not supported. Certain Linux clients may default to NFSv4 and must be configured to use an earlier version explicitly when interoperating with OpenBSD:
doas mount -t nfs -o vers=3 openbsd:/export /mnt
The nfsd and mountd daemons do not use inetd, and must be run via rcctl or managed using local rc hooks.