Functional Automount of Network Shares in macOS

This post covers a functional automount configuration in macOS to automatically map network shares using the NFS version 4.0 protocol.

On my home network, I prefer a seamless solution for automatically mounting network shares on macOS. Unfortunately, Apple does not document this very well and the configuration must happen from a command line. This post is my attempt to document an automount setup that currently works for me, based on years of experimentation (and building upon a few of my previous troubleshooting posts).

What does my home setup currently look like?

• NAS server (TrueNAS Scale), serving NFS shares
• MacBook Pro 14-inch (M2), running macOS Sonoma
• Router and a mix of wired (1 GigE) and wireless (Wi-Fi 6) clients

Configure the auto_master Map File

In macOS, the default automounter master map file (/etc/auto_master) looks like this:

#
# Automounter master map
#
+auto_master            # Use directory service
#/net                   -hosts          -nobrowse,hidefromfinder,nosuid
/home                   auto_home       -nobrowse,hidefromfinder
/Network/Servers        -fstab
/-                      -static

In my case, I append one line which references a separate /etc/auto_nas map file. (You can use more than one, depending on the complexity of your setup.)

/-                      auto_nas

Configure the auto_nas Map File

In the /etc/auto_nas map file referenced from /etc/auto_master above, I define each mount point and corresponding remote NAS share, along with any mount options. Here is a sample of my current working auto_nas file:

/System/Volumes/Data/Nas/media           -nfsvers=4,async,noowners,noresvport,noatime,hard,bg,intr,rw,tcp,rdirplus,readahead=128,wsize=65536 nfs://my-nas:/mnt/Data1/media
/System/Volumes/Data/Nas/storage       -nfsvers=4,async,noowners,noresvport,noatime,hard,bg,intr,rw,tcp,rdirplus,readahead=128,wsize=65536 nfs://my-nas:/mnt/Data1/storage
/System/Volumes/Data/Nas/archives        -nfsvers=4,async,noowners,noresvport,noatime,hard,bg,intr,rw,tcp,rdirplus,readahead=128,wsize=65536 nfs://my-nas:/mnt/Data1/archives

Mount option notes:

• nfsvers=4 explicitly sets the nfs version to 4.0 (macOS frustratingly does not support any version higher than 4.0)
• async improves overall performance, at least for my network
• wsize=65536 increases the write size from the macOS default value of 32768.
• I no longer increase rsize, based on recommendations from a few Reddit threads. The default rsize in macOS is 32768; increasing it may adversely impact directory listing speeds (especially in large directories).

Force macOS to use NFS 4.0

By default, macOS will attempt to use NFS version 3 when mounting NFS shares. Annoyingly, macOS still only supports the 4.0 version level (attempts to use 4.1+ will fail). To change the default protocol version to 4.0, add the following line to the /etc/nfs.conf file:

nfs.client.mount.options = vers=4.0

Enable / Reload the Automounts

Now that you have your map files configured, execute the automount command in a terminal. This will flush the cache (important when re-loading the files after making changes) and reload /etc/auto_master:

sudo automount -vc

Look for confirmation that each share mounted successfully. If you have any syntax errors in your map files, or if a share path is not valid, look instead for any error messages.

automount: /System/Volumes/Data/Nas/media mounted
automount: /System/Volumes/Data/Nas/storage mounted
automount: /System/Volumes/Data/Nas/archives mounted

Automount in Action

Now switch to a Finder window (or continue in a Terminal, if that’s more your speed) to see your automounts in action. In the examples from above, browse to /System/Volumes/Data/Nas and you should see three subfolders for media, storage, and archives. Autofs will now automatically mount each share, if not already mounted, as you access the folders.

Happy automounting!

Appendix: Troubleshooting

Test mount NFS share from command line:

sudo mount -t nfs -o nfsvers=4,async,noowners,noresvport,noatime,hard,bg,intr,rw,tcp,rdirplus,readahead=128,wsize=65536 my-nas:/storage /System/Volumes/Data/Nas/storage

Determine version of currently mounted NFS share:

nfsstat -m

Example output:

/System/Volumes/Data/Nas/storage from my-nas:/mnt/Data1/storage
  -- Original mount options:
     General mount flags: 0x10700058 async,nodev,nosuid,automounted,noowners,noatime,nobrowse
     NFS parameters: vers=4,tcp,hard,intr,noresvport,wsize=65536,readahead=128,rdirplus,nfc
     File system locations:
       /mnt/Data1/storage @ my-nas (XXX.XXX.X.XX)
  -- Current mount parameters:
     General mount flags: 0x14700058 async,nodev,nosuid,automounted,noowners,noatime,nobrowse,multilabel
     NFS parameters: vers=4.0,tcp,port=2049,hard,intr,noresvport,callback,negnamecache,nonamedattr,noacl,noaclonly,locks,noquota,rsize=32768,wsize=65536,readahead=128,dsize=32768,rdirplus,nodumbtimer,timeo=10,maxgroups=16,acregmin=5,acregmax=60,acdirmin=5,acdirmax=60,nomutejukebox,noephemeral,nfc,sec=sys
     File system locations:
       /mnt/Data1/storage @ my-nas (XXX.XXX.X.XX)
     Status flags: 0x0

Display all currently mounted shares and their sizes:

df -h

Example output:

Filesystem                 Size   Used  Avail Capacity iused       ifree %iused  Mounted on
my-nas:/mnt/Data1/storage   19Ti  7.4Ti   12Ti    40%  296146 24802272422    0%   /System/Volumes/Data/Nas/storage

References:

• https://github.com/apple-oss-distributions/autofs/blob/main/files/auto_master
• https://care.qumulo.com/hc/en-us/articles/115008111268-Recommended-NFS-Mount-Options
• https://www.reddit.com/r/freenas/comments/l9dc12/tuning_nfs_performance_on_macos/
• https://jswheeler.medium.com/nfs-automount-macos-montery-1a8bef92d994
• https://www.cyberciti.biz/faq/apple-mac-osx-nfs-mount-command-tutorial/
• https://dl.acronis.com/u/vstorage/docs/html/AcronisSoftwareDefinedInfrastructure_2_users_guide_en-US/accessing-networkfs/mounting-nfs-exports-on-macos.html