NFS Shares with ZFS

FreeBSD provides a built-in NFS server and client which understand the NFSv3 and NFSv4 protocols. If you’re new to NFS, this section of the FreeBSD Handbook provides a good overview of NFS and its components.

If you’ve configured NFS on FreeBSD before, you’ve used this configuration workflow:

1. Add the services NFS uses to /etc/rc.conf.
2. Control the permissions systems have to shared directories by adding entries to the /etc/exports configuration file.
3. Verify that clients can access the NFS shares as defined in your configuration.

You may have heard that OpenZFS provides its own sharenfs property. How does this property change the NFS configuration workflow and why would you use it? In a nutshell, it changes step #2 as you specify your configuration options using zfs set sharenfs instead of by editing /etc/exports directly.

Today’s article answers some common questions about why you would use the sharenfs property for NFS configuration and how to do so.

Why Use sharenfs Instead of exports?

To understand why, consider what sharenfs and exports actually are:

• exports is the configuration file used by mountd, the service that listens for NFS mount requests from NFS clients. Since mountd only reads its configuration file when it starts, you have to remember to service mountd reload whenever you edit /etc/exports in order to let the service know that there are changes to its configuration.
• sharenfs is a ZFS property that indicates whether the share is available (on/off) and the configuration details for that share. Since the configuration details are not tied to mountd’s configuration file, any changes to this property are available immediately without needing to first reload mountd.

While it is convenient to not have to remember to reload mountd, there are other benefits that come from sharenfs being a ZFS property:

• You can specify the sharenfs property to the zfs get command to determine which filesystems are currently sharing via NFS and to view per-filesystem NFS sharing details.
• You can enable/disable the property on a per-filesystem basis by setting sharenfs to on or off with zfs set.
• Child datasets automatically inherit the sharenfs property from their parent. As a ZFS property, you can override the inherited defaults using zfs set on the child dataset to specify what you want for that dataset.

How do I Recreate Existing exports Entries Using sharenfs?

If you already have a working NFS configuration on a FreeBSD system with OpenZFS filesystems, it is easy to recreate your configuration using zfs set. For example, this line from /etc/exports:

/usr/ports -maproot=root    192.168.15.0/24

is equivalent to this command:

zfs set sharenfs=’on,-maproot=root,192.168.15.0/24’ mypool/usr/ports

This means you can simply run the equivalent zfs set sharenfs=’on,REPLACE_WITH_YOUR_OPTIONS’ poolname/filesystem command for each line in your /etc/exports file.

   | If you're new to NFS or want to understand its fundamentals, including the role of /etc/exports in traditional configurations, read our guide on configuring NFS on FreeBSD.

Things to Keep in Mind:

• You can use any option listed in exports(5). Basically, if you’re using it now in /etc/exports, you can specify it withzfs set.
• Don’t forget to prepend your options with on to enable NFS sharing on the specified dataset.
• Note that zfs sharenfs options are separated with commas instead of the spaces the exports file uses. Using commas gives the bonus of not having to quote each option when using the command in a script.
• ZFS will update its /etc/zfs/exports file automatically. Never edit this file directly! You should always use zfs set to change sharenfs options.
• Whenever you make a change, take the time to verify from an NFS client that the share is behaving as expected. Also, double-check /var/log/messages to determine if there are any NFS-related errors that need to be resolved.

You probably don’t want to run zfs set sharenfs=on on a dataset without including some restrictions, since the unspecified default is to allow rw access to any client on any network. In this example, /usr/ports is restricted to the specified network but /usr/home is wide open to anyone on any network:

zfs get sharenfs | grep on
mypool/usr/home	sharenfs on local
mypool/usr/ports sharenfs on,maproot=root,192.168.15.0/24	local

If you see entries with no maproot setting in your own configuration, you should evaluate if you need to add restrictions to that filesystem’s sharenfs property.

How do I enable/disable NFS Sharing?

The  zfs share and zfs unshare commands can be used to enable or disable NFS sharing. Some points to keep in mind:

• To globally start or stop all sharing, use -a (all filesystems) with either zfs share or zfs unshare.
• Alternately, specify the filesystem to share/unshare.
• Running zfs share only affects the filesystems where you have defined (and set to on) the sharenfs property. For example, you could run zfs share on a parent filesystem but only the child datasets that have been defined as onwill start sharing.
• zfs share/unshare only concerns itself with the sharenfs property. This assumes that you will manage the underlying services and will start/stop them as needed.

Putting it All Together

FreeBSD’s built-in integration of OpenZFS and NFS makes it easy for an administrator to configure and manage NFS shares. By using OpenZFS’ sharenfs property, managing NFS shares can be added to your arsenal of scripts and procedures for monitoring and maintaining the data stored on OpenZFS filesystems. For an advanced look at scaling NFS with distributed file systems, explore how FreeBSD supports pNFS.