NFS Shares with ZFS

NFS Shares With ZFS

Leveraging the sharenfs property for NFS configuration

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

is equivalent to this command:

zfs set sharenfs=’on,-maproot=root,’ 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.

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,	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.

<strong>Meet the author:</strong> Dru Lavigne
Meet the author: Dru Lavigne

Dru Lavigne is a retired network and systems administrator, IT instructor, author, and international speaker. Dru is author of BSD Hacks, The Best of FreeBSD Basics, and The Definitive Guide to PC-BSD.

Like this article? Share it!

More on this topic

OpenZFS – OpenZFS, Your Data and the Challenge of Ransomware

As commercial storage becomes increasingly expensive, more and more of the Education vertical is looking at Open Source solutions for storage. In this article, we discuss the value of OpenZFS for Universities and how system administrators can best leverage it to their benefit.

OpenZFS – OpenZFS For HPC Clusters

Discover how OpenZFS can provide cost-effective and reliable storage for high-performance computing (HPC) workloads in this comprehensive write-up.

OpenZFS – Understanding ZFS vdev Types

The most common category of ZFS questions is “how should I set up my pool?” Sometimes the question ends “… using the drives I already have” and sometimes it ends with “and how many drives should I buy.” Either way, today’s article can help you make sense of your options.

4 Comments on “NFS Shares with ZFS

  1. Pingback: NFS Shares with ZFS - The web development company Lzo Media - Senior Backend Developer

  2. Pingback: Valuable News – 2022/02/28 | 𝚟𝚎𝚛𝚖𝚊𝚍𝚎𝚗

  3. The documentation does not work under FreeBSD 13.0

    The command

    zfs set sharenfs=’on,-maproot=root,′ tank/home


    Apr 21 09:39:43 bsdfs01 mountd[2547]: can’t get address info for host on
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad host on, skipping
    Apr 21 09:39:43 bsdfs01 mountd[2547]: can’t get address info for host
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad host, skipping
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad exports list line ‘/tank/home on -maproot’: no valid entries
    Apr 21 09:39:43 bsdfs01 mountd[2547]: can’t get address info for host on
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad host on, skipping
    Apr 21 09:39:43 bsdfs01 mountd[2547]: can’t get address info for host
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad host, skipping
    Apr 21 09:39:43 bsdfs01 mountd[2547]: bad exports list line ‘/tank/home/willi on -maproot’: no valid entries

    and showmount -e is empty

Tell us what you think!