Use autofs on Mac OS X to mount network shares automatically during access

autofs.md

Autofs on Mac OS X

With autofs you can easily mount network volumes upon first access to the folder where you want to mount the volume. Autofs is available for many OS and is preinstalled on Mac OS X so I show you how I mounted my iTunes library folder using this method.

Prepare autofs to use a separate configuration file

autofs needs to be configured so that it knows where to gets its configuration. Edit the file /etc/auto_master and add the last line:

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

This will tell autofs to look for a file in the '/etc' folder with name 'auto_smb'. In this case I want to create a configuration for automatically mount SMB volumes. You are free to choose a different name and can also use afp/cifs/nfs etc.

Be aware that macOS updates can overwrite this file! Make sure you'll check the content of this file after you've updated. I've encountered this behaviour with the latest macOS Catalina 10.15.7 supplemental update.

Content of the configuration file

Normally Mac OS X tries to mount network shares into the '/Volumes' folder. This is the default folder for all mounted shares on a mac. However, if you try to directly mount into this folder, autofs will fail. You just add a '/../' in front of your desired mount path and Mac OS X will even accept the Volumes folder. However, some Mac OS Version doesn't like this so I switched over to use my own folder named '/mount'.

If you want to configure AFP, do it like this:

So add this line to /etc/auto_afp:

/../Volumes/music	-fstype=afp,rw afp://ip-address:/music

Mac OS X is clever enough to lookup the username and password from the Mac keychain so there's no need to add the username and password in clear text to the configuration file.

If you want to configure SMB, do it like this:

Add this line to /etc/auto_smb:

/mount/music    -fstype=smbfs,soft,noowners,nosuid,rw ://username:password@ip-address:/music

Unfortunately you will need to add the user and password to the resource :( You can try to lock it down further using the Mac OS permissions but that won't help when the attackers user got admin rights as well.

If you're using macOS Catalina 10.15 and macOS Big Sur 11

You’ll just have to prepend your existing automount paths with /System/Volumes/Data. This is because macOS creates a second APFS volume for your user data, whereby the existing system installation is moved to a read-only APFS volume.

This is the version of /etc/auto_smb in Catalina:

/System/Volumes/Data/mount/music    -fstype=smbfs,soft,noowners,nosuid,rw ://username:password@ip-address:/music

Modern way using synthetic.conf

Thanks to rjc I now know about synthetic.conf. From the man page:

synthetic.conf describes virtual symbolic links and empty directories to be
created at the root mount point.  Because the root mount point is read-only
as of macOS 10.15, physical files may not be created at this location.  All
writeable paths must reside on the data volume, which is mounted at
/System/Volumes/Data.

synthetic.conf provides a mechanism for some limited, user-controlled file-
creation at /.  The synthetic entities described in this file are
synthesized by the kernel during early system boot.  They are not
physically present on the disk, but when the system is booted, they behave
as if they were within certain parameters.

which sounds exactly what we want. Create a new file /etc/synthetic.conf. If it does not exist, create the file with this content:

# create a symbolic link named "music" at / which points to
# "System/Volumes/Data/mount/music", a writeable location at the root of the data volume
music   System/Volumes/Data/mount/music

The first column describes the symbolic link at /. The next column is separated with a tab and describes the location under / which should be linked to the first column. You can also leave the second column empty. This would create an empty folder in which we could automount again. If you want the minumum amount of changes, use example from above. After a reboot the folder should be available at the root of your macOS installation.

Restoring autofs after macOS updates

The recent macOS updates seem to overwrite the /etc/auto_master file. You can try to set the file to read-only using the extended attributes of macOS. For more details see this blog post. Please add the entry for your autofs file again to the auto_master file and save the file. We'll try to set the auto_master file to read-only, in hope it won't be overwritten again.

~ ❯ ls -lO /etc/auto_master                                         at 20:55:44
-rw-r--r--  1 root  wheel  - 226 May  6 20:49 /etc/auto_master
~ ❯ sudo chflags schg /etc/auto_master                        ✘ INT at 21:01:04
~ ❯ ls -lO /etc/auto_master                                         at 21:01:10
-rw-r--r--  1 root  wheel  schg 226 May  6 20:49 /etc/auto_master

The file is now write protected. You can try to edit it again with sudo and it will be read only. Its the same as when you set the file write protected in the finder.

if you use

sudo chflags noschg /etc/auto_master 

it will be writeable again.

Access the folder and see autofs in action

You now need to restart the autofs service with the command 'sudo automount -cv'. If you now type mount, you'll see a listing of currently mounted volumes. Your desired volume shouldn't be mounted, so unmount it with 'sudo umount /Volumes/volumename' or 'sudo umount /mount/music' before we continue.

You can now switch to '/Volumes/music' or '/mount/music' folder or let it list on the terminal. If you're using macOS Catalina you can open /System/Volumes/Data/mount/music. Once you do that autofs will automatically try to mount the desired volume into this folder.

See an example and explanation in action

Visit my blog post where I explain this gist a little bit more in detail. A complete list of blog posts with autofs can be found here.

automount and indeed, NFS, still have their place and use. Almost 40 years ago when I worked for Sun, we pushed the message that the network is the computer, but there was no implication that people should pretend network or the computer were unimportant and only the UX mattered. I will not enable SMB on my NAS because I have Windoze on my network and you cannot in any reasonable way really secure that as long as people are allowed access to those Windoze machines. AFP? Never worked well. I gave up fighting AFP long ago. NFS is the only one that has been around and stable long enough to be considered. But Apple doesn't want to do NFS for whatever reason that only benefits Apple. As a result, their implementation is functional, but has unnecessary unpredictability, as opposed to SMB's unpredictability which appears to be organic. User credentials for file access is good. User credentials for share access was always A Bad Idea, IMNSHO. Automount is good, and Finder not knowing about it is just an intentional shortcoming on Apple's part. Finder does show NFS mounts like any other. It is only the automount ones that aren't usually set up for browsing with Finder before mounting. Apple's paranoid whacking of auto_master has been part of Apple's updates for years and years now. I still wish there was a configuration location for automount that survived updates, but the only answer I have found is to put my maps in one or more files, and always manually add back the line(s) that includes those maps after updates. I have resigned myself to the fact that it is simply a manual step in the update process, because Apple wants it that way.

I recently ditched iCloud for a NAS. What I miss was the feature that automatically mounts the ~/Documents and ~/Desktop directory to iCloud Drive. Would this configuration allow me to replicate this for a NAS?

feel free to credit ;) https://gist.github.com/L422Y/8697518

I tried a number of variations. I can get synthentic.conf to work as its intended but I can't get automouters to work. AFP or SMB. The issue is around credentials. I can play games with root and sudo and get the mounts to mount but it is unreliable and mostly I get permissions errors

I was in the process of abandoning my kluge and attempting to get something better, did some googs, and arrived here. Perhaps I'll keep my horrid hacks a bit more. FWIW, here is my kluge.

1. Arrange things so that there is a /nas/ mount point. (see above for details)
2. Create /nas/* as needed.
3. Install passwords into keychain
4. manually (too lazy to figure out how to auto run it) run a mounter script.
   % smb-mount mount --keep all >/dev/null 2>&1 &

The script below has to be edited to describe the assets one wants to mount. Too lazy to put it into separate config file.
The script also can be used to manage the keychain password entries.

I found that the --keep option was needed, or else the mounts would go stale over time.

I suppose I should put it in github or something, butI can never figure out how to appropriately package python projects.

I hereby release it free to whoever stumbles onto this gist.
Here is smb-mount:

#!/usr/bin/env python3
#
# Copyright (c) 2021 Damon Anton Permezel, all bugs revered.
#
# TODO:
#	add a `remount` option which will, if required, force unmount and re-mount.
#	-- `diskutil unmount force /nas/whatever`
#
import keyring
import click
import sys
import os
import subprocess
import threading
import pexpect
import logging
import time
import shutil

_pass_cmd = shutil.which('pass')
_user = os.getenv('USER')

# NAS resources
#   'example':		[ 'server',   'user',   'volume',  'mount-point', 'options' ],
_nas = {
    # for error testing
    'err':		[ 'nas.local', 'dap',   '/missing','/nas/err',	'-o nosuid,nodev,noatime,soft,-s' ],

    'dap':		[ 'nas.local', 'dap',   '/home',   '/nas/dap',   '-o nosuid,nodev,noatime,soft,-s' ],
    'nimda':		[ 'nas.local', 'nimda', '/home',   '/nas/nimda', '-o nosuid,nodev,noatime,soft,-s' ],

    'shared':		[ 'nas.local', 'dap', '/shared', '/nas/shared', '-o nosuid,nodev,noatime,soft,-s' ],
    'tax':		[ 'nas.local', 'dap', '/tax',	   '/nas/tax',	'-o nosuid,nodev,noatime,soft,-s' ],
    'music':		[ 'nas.local', 'dap', '/music', '/nas/music',	'-o nosuid,nodev,noatime,soft,-s' ],
    'video':		[ 'nas.local', 'dap', '/video', '/nas/video',	'-o nosuid,nodev,noatime,soft,-s' ],
    'nihongo-ro':	[ 'nas.local', 'dap', '/nihongo', '/nas/nihongo',	'-o rdonly,nosuid,nodev,noatime,soft,-s' ],
    'nihongo':		[ 'nas.local', 'dap', '/nihongo', '/nas/nihongo',	'-o nosuid,nodev,noatime,soft,-s' ],
}

_all = [ 'dap', 'nimda', 'shared', 'tax', 'music', 'video', 'nihongo' ]


@click.group()
def cli():
    pass

@cli.command()
@click.option('--server', prompt='Enter SMB server address', help='SMB server address', default='nas.local')
@click.option('--user', prompt='Enter SMB username', help='SMB user name', default=_user)
def auth_pass(server, user):
    """Establish authentication, password from `pass`.
    Create an authentication record in the keychain, per the `auth` subcommand.
    Pull the password from `pass show Auth/SMB/${server}/Users/${user}`.
    Will require (in my case) YubiKey interaction."""

    path = 'Auth/SMB/{}/Users/{}'.format(server, user)

    try:
        pwd = subprocess.run([_pass_cmd, 'show', path], capture_output=True)
    except:
        sys.exit(-1)
        pass

    if pwd.returncode != 0:
        print('Failed to find password entry for '+path)
        print(pwd.stderr.decode('UTF-8'), end='')
        sys.exit(pwd.returncode)
        pass

    pwd = pwd.stdout.decode('UTF-8')
    pwd = pwd.strip('\n')

    acnt = 'Auth/SMB/{}/{}'.format(server, user)
    serv = 'smb-pass'

    try:
        keyring.set_password(serv, acnt, pwd)
    except keyring.errors.PasswordSetError:
        print('Cannot set', serv, acnt)
        sys.exit(2)
        pass

    try:
        if keyring.get_password(serv, acnt) != pwd:
            print('keyring password mismatch')
            sys.exit(3)
            pass
    except keyring.errors.KeyringError as e:
        print('***keyring error:', e)
        sys.exit(4)
        pass

    sys.exit(0)
    pass

@cli.command()
@click.option('--server', prompt='Enter SMB server address', help='SMB server address', default='nas.local')
@click.option('--user', prompt='Enter SMB username', help='SMB user name', default=_user)
@click.password_option(help='SMB password')
def auth(server, user, password):
    """Establish the authentication.
    I keep the user passwords in `pass -c Auth/SMB/${server}/${user}`.
    However, this requires interaction with the YubiKey for each access.
    Accordingly, I cache them in the system keychain, presumably protected by
    the keychain unlock password (ie: login password)."""

    acnt = 'Auth/SMB/{}/{}'.format(server, user)
    serv = 'smb-pass'

    try:
        keyring.set_password(serv, acnt, password)
    except keyring.errors.PasswordSetError:
        print('Cannot set', serv, acnt)
        sys.exit(2)
        pass

    try:
        if keyring.get_password(serv, acnt) != password:
            print('keyring password mismatch')
            sys.exit(3)
            pass
    except keyring.errors.KeyringError as e:
        print('***keyring error:', e)
        sys.exit(4)
        pass

    sys.exit(0)
    pass

def get_pass(server, user):
    """Lookup password in keyring."""

    acnt = 'Auth/SMB/{}/{}'.format(server, user)
    serv = 'smb-pass'

    try:
        password = keyring.get_password(serv, acnt)
        if password is None:
            print('***no password entry for {}:{}'.format(serv, acnt))
            sys.exit(1)
            pass

        return password
        pass
    except keyring.errors.KeyringError as e:
        print('Looking up password for server:', server, 'user:', user)
        print('***keyring error:', e)
        sys.exit(1)
        pass

@cli.command()
@click.option('--server', prompt='Enter SMB server address', help='SMB server address', default='nas.local')
@click.option('--user', prompt='Enter SMB username', help='SMB user name', default=_user)
def check(server, user):
    """Verify authentication."""

    password = get_pass(server, user)

    # all I can do right now is just check the password entry exists
    sys.exit(0)
    pass

def is_mounted(path):
    """Check to see if `path` is a mount point for a remote volume."""

    try:
        if not os.path.isdir(path):
            os.makedirs(path)
            pass
    except Exception as e:
        print('*** Invalid path for os.makedirs(): ', path)
        sys.exit(1)
        pass
    pass

    try:
        s0 = os.lstat(path)
        s1 = os.lstat(path + '/..')
        return s0.st_dev != s1.st_dev
    except Exception as e:
        print('*** Invalid path for is_mounted(): ', path)
        sys.exit(1)
        pass
    pass


def try_mount(fs, keep=False):
    fmt = '%(asctime)s: %(message)s'
    logging.basicConfig(format=fmt, level=logging.INFO, datefmt='%H:%M:%S')

    if fs == 'all':
        threads = list()
        for fs in _all:
            t = threading.Thread(target=try_mount_one, args=(fs, keep,), daemon=True)
            t.start()
            threads.append(t)
            pass

        for i, t in enumerate(threads):
            t.join()
            pass

        sys.exit(0)
        pass
    else:
        t = threading.Thread(target=try_mount_one, args=(fs, keep,), daemon=True)
        t.start()
        t.join()
        sys.exit(0)
        pass
    pass

def try_mount_one(fs, keep=False):
    try:
        _try_mount_one(fs, keep)
    except Exception as e:
        name = threading.current_thread().name
        logging.info('%s: ****: fs:%s %r', name, fs, e)
        pass
    pass

def _try_mount_one(fs, keep):
    fs = str(fs)
    res = _nas[fs]
    usr = res[1]
    srv = res[0]
    vol = res[2]
    mnt = res[3]
    opt = res[4]
    # update = 'update' in opt
    update = '-u' in opt

    path = '//'+usr+'@'+srv+vol
    name = threading.current_thread().name

    # logging.info('%s: fs: %s', name, fs)

    while True:
        if not update and is_mounted(mnt):
            logging.info('%s: was mounted', fs)
            if keep != True:
                return
            time.sleep(60)
            continue

        # mount -t smbfs //username:userpass@myserver/PUBLIC /smb/public
        # print('/sbin/mount_smbfs '+opt+' '+path+' '+mnt)
        logging.info('/sbin/mount -t smbfs '+opt+' '+path+' '+mnt)
        child = pexpect.spawn('/sbin/mount -t smbfs '+opt+' '+path+' '+mnt, encoding='utf-8')
        # child = pexpect.spawn('/sbin/mount_smbfs '+opt+' '+path+' '+mnt, encoding='utf-8')
        try:
            child.expect('Password for .*:', timeout=120)
            # logging.info('Got password prompt')
            # print(child)
        except pexpect.exceptions.EOF as e:
            # logging.info('Got EOF')
            if 'error' in child.before:
                logging.error(child.before.strip('\n'))
                sys.exit(1)
            else:
                logging.info(child.before)
                time.sleep(60)
                continue
            pass
        except Exception as e:
            logging.info('%s: ***Did not get a password prompt from mount.', name)
            logging.info('%s: %r', name, e)
            continue

        pwd = get_pass(srv, usr)
        child.sendline(pwd)
        del pwd


        child.logfile_read = sys.stdout

        child.expect(pexpect.EOF, timeout=None)

        try:
            child.close()
        except Exception as e:
            loging.info('%s: ***close: %r', e)
            pass

        # poor attempt at purging the password info
        stat = child.exitstatus
        del child

        if keep != True:
            return stat

        if is_mounted(mnt) != True:
            logging.info('%s: ****: not mounted: ', name, mnt)
            return

        # clear update flag for loop
        update = False
        pass
    pass

@cli.command()
@click.argument('vol')
@click.option('--keep', is_flag=True, help='Keep monitoring / re-trying')
def mount(vol, keep):
    """Mount volume."""

    if vol == '?':
        # '?' will list the available volumes
        for m in _nas:
            click.echo(m)
            pass
        pass
    else:
        sys.exit(try_mount(vol, keep))
        pass

    sys.exit(0)
    pass

def try_unmount(fs):
    fmt = '%(asctime)s: %(message)s'
    logging.basicConfig(format=fmt, level=logging.INFO, datefmt='%H:%M:%S')

    if fs == 'all':
        for fs in _all:
            fs = str(fs)
            mnt = _nas[fs][3]
            res = subprocess.run(['/sbin/umount', mnt], capture_output=True)
            logging.info(res)
        pass
    elif fs in _all:
        fs = str(fs)
        mnt = _nas[fs][3]
        res = subprocess.run(['/sbin/umount', mnt], capture_output=True)
        logging.info(res)
        pass

    sys.exit(0)
    pass

@cli.command()
@click.argument('vol')
def unmount(vol):
    """Unmount volume."""

    if vol == '?':
        # '?' will list the available volumes
        for m in _nas:
            click.echo(m)
            pass
        pass
    else:
        sys.exit(try_unmount(vol))
        pass

    sys.exit(0)
    pass

if __name__ == '__main__':
    cli()
    sys.exit(0)
    pass

I should add some more/better usage.

┌──(dap  hubris)-[~]
└─% smb-mount --help 
Usage: smb-mount [OPTIONS] COMMAND [ARGS]...

Options:
  --help  Show this message and exit.

Commands:
  auth       Establish the authentication.
  auth-pass  Establish authentication, password from `pass`.
  check      Verify authentication.
  mount      Mount volume.
  unmount    Unmount volume.

The auth-pass may only be useful if you use pass and adopt the same scheme as I do.
Alternately, there is the pass sub-command.

┌──(dap  hubris)-[~]
└─% smb-mount auth --help
Usage: smb-mount auth [OPTIONS]

  Establish the authentication. I keep the user passwords in `pass -c
  Auth/SMB/${server}/${user}`. However, this requires interaction with the
  YubiKey for each access. Accordingly, I cache them in the system keychain,
  presumably protected by the keychain unlock password (ie: login password).

Options:
  --server TEXT    SMB server address
  --user TEXT      SMB user name
  --password TEXT  SMB password
  --help           Show this message and exit.

To add a new key-chain entry:

┌──(dap  hubris)-[~]
└─% smb-mount auth       
Enter SMB server address [nas.local]: my-local-nas.local
Enter SMB username [dap]: some-other-user
Password: 
Repeat for confirmation: 
┌──(dap  hubris)-[~]
└─%

Subsequently, you have to edit the python script and add in the desired mounts, using my-local-nas.local in the server column and some-other-user in the user column of the table.

It would be possible to adjust things so that /nas/${user} was owned by ${user} and each user had their own copy of the smb-mount script and then /nas/${user}/home would possibly be only accessible to that user (controled by the permissions on /nas/${user}/..

So I get mounts maintained as:

└─% df -h
Filesystem                                                     Size    Used   Avail Capacity iused ifree %iused  Mounted on
/dev/disk3s1s1                                                1.8Ti   9.2Gi   1.2Ti     1%    390k  4.3G    0%   /
...
//[email protected]/video                                          28Ti    13Ti    15Ti    47%     14G   16G   46%   /System/Volumes/Data/nas/video
//[email protected]/shared                                        100Gi   1.3Gi    99Gi     2%    1.4M  103M    1%   /System/Volumes/Data/nas/shared
//[email protected]/home                                         28Ti    13Ti    15Ti    47%     14G   16G   46%   /System/Volumes/Data/nas/nimda
//[email protected]/nihongo                                       128Gi    87Gi    41Gi    68%     91M   43M   68%   /System/Volumes/Data/nas/nihongo
//[email protected]/tax                                            28Ti    13Ti    15Ti    47%     14G   16G   46%   /System/Volumes/Data/nas/tax
//[email protected]/music                                         4.0Ti   892Gi   3.1Ti    22%    935M  3.4G   22%   /System/Volumes/Data/nas/music
//[email protected]/home                                           28Ti    13Ti    15Ti    47%     14G   16G   46%   /System/Volumes/Data/nas/dap

This works better than for @unspecified-cohabitating-individual who, on a separate machine, where @insert-anonymising-pronoun is always complaining to me that the NAS shares keep disappearing and forces Finder.app to restart to recover.

instructions say to create files in /etc not /private/etc.

instructions say to create files in /etc not /private/etc.

Not sure where you had seen /private/etc above - I can't find it.

That is, however, beside the point because it is the same location:

 $ file -h /etc
 /etc: symbolic link to private/etc

Does this work if the share you need can only be accessed via vpn? Say for example I'm working on on project, then switch to another project that requires a share that can only be accessed via vpn, when I connect to said vpn, will the share be available automatically? or will I have to restart to autofs service with sudo automount -cv?

Not to discourage your use of NFS mounts, but if you are using NFS mounts that may not have a target server, this can cause issues. i recommend the use of a program like ConnectMeNow or a tunneling solution that will ensure the target is always up. The reason is that with NFS, once an NFS mount is established, if you try to access the mount while the server is not available will cause the call to block indefinitely (well, until the remote host is available again). NFS is not intended for remote shares. This is more likely to be addressed more efficiently with other services. NFS mounts are more like OS level, multi-user mounts. you can do it with NFS but I don't think you will be happy with the results.

Does this work if the share you need can only be accessed via vpn? Say for example I'm working on on project, then switch to another project that requires a share that can only be accessed via vpn, when I connect to said vpn, will the share be available automatically? or will I have to restart to autofs service with sudo automount -cv?

Depending on the VPN, I would probably recommend using some sort of pre/post connect commands instead of this

Depending on the VPN, I would probably recommend using some sort of pre/post connect commands instead of this

Can you provide an example of a pre/post connection command(s)?

[...] will the share be available automatically?

The whole point of autofs is to only mount required filesystem upon request, i.e. access so, if you aren't connected to the VPN, don't try to access the NFS share. Access it once you connect to the VPN and either, let it time out and autofs deal with it, i.e. unmount it automatically after a set time, or you can do so manually - both after you aren't accessing the share any more, and before you disconnect from the VPN.