autofs

autofs Setup and Configuration Guide

autofs mounts filesystems on-demand when accessed and unmounts them after a configurable idle timeout. This makes it significantly more robust than static /etc/fstab mounts for network shares — a missing or offline host won't hang your boot, and stale mounts are cleaned up automatically.

1. Install

sudo apt update && sudo apt install autofs sshfs -y

For NFS shares also install:

sudo apt install nfs-common -y

2. How autofs Works

autofs has two config layers:

File	Purpose
`/etc/auto.master`	Master map — defines mount point directories and which map file handles them
`/etc/auto.<name>`	Detail map — defines individual mounts under that directory

When you access /mnt/remote/myshare, autofs intercepts it, reads the map, and mounts the share on the fly. After the timeout with no activity, it unmounts automatically.

3. Master Map — `/etc/auto.master`

Each line in auto.master follows this format:

<base_mount_dir>  <map_file>  [options]

Example:

/mnt/remote  /etc/auto.sshfs  --timeout=60,--ghost
/mnt/nfs     /etc/auto.nfs    --timeout=120,--ghost

Key options:

Option	Effect
`--timeout=N`	Unmount after N seconds of inactivity
`--ghost`	Creates empty placeholder directories so the mount point is visible even when unmounted. Without this, `ls /mnt/remote` shows nothing until a mount is active
`--verbose`	Useful during setup/debugging

4. Detail Map Files

SSHFS (SSH/SFTP)

Create /etc/auto.sshfs:

<mount_name>  -fstype=fuse,rw,allow_other,IdentityFile=/home/conor/.ssh/id_ed25519,uid=1000,gid=1000,ServerAliveInterval=15,ServerAliveCountMax=3,reconnect  :sshfs#conor@100.x.x.x:/home/conor

Breakdown:

Part	Meaning
`<mount_name>`	The subdirectory created under the base — e.g. `farmdesktop` becomes `/mnt/remote/farmdesktop`
`-fstype=fuse`	Tells autofs this is a FUSE mount
`rw`	Read/write
`allow_other`	Allows users other than root to access the mount
`IdentityFile=`	Path to SSH private key — must use key auth, not password
`uid=1000,gid=1000`	Map remote files to your local user. Check yours with `id conor`
`ServerAliveInterval=15`	Send keepalive every 15s to prevent silent disconnects
`ServerAliveCountMax=3`	Drop connection after 3 missed keepalives
`reconnect`	Auto-reconnect on drop
`:sshfs#user@host:/path`	The remote — note the leading colon and `sshfs#` prefix

Full working example:

farmdesktop  -fstype=fuse,rw,allow_other,IdentityFile=/home/conor/.ssh/id_ed25519,uid=1000,gid=1000,ServerAliveInterval=15,ServerAliveCountMax=3,reconnect  :sshfs#conor@100.64.0.5:/home/conor

Access via: /mnt/remote/farmdesktop

NFS

Create /etc/auto.nfs:

nas  -fstype=nfs4,rw,soft,intr  100.64.0.10:/exports/data

Option	Meaning
`nfs4`	Use NFSv4 (preferred)
`soft`	Return error on timeout instead of hanging indefinitely
`intr`	Allow interrupting a hung NFS call with Ctrl+C

Samba / CIFS

Create /etc/auto.smb:

wiki  -fstype=cifs,rw,credentials=/home/conor/.smbcredentials,uid=1000,gid=1000,iocharset=utf8  ://100.64.0.10/wiki

/home/conor/.smbcredentials:

username=conor
password=yourpassword

chmod 600 /home/conor/.smbcredentials

5. FUSE Prerequisite for SSHFS

allow_other requires this line to be uncommented in /etc/fuse.conf:

sudo nano /etc/fuse.conf

Uncomment:

user_allow_other

Without this, SSHFS mounts via autofs (which runs as root) will be inaccessible to your user account.

6. SSH Key Setup

autofs runs as root, so the key must be readable by root, or you must specify a key that root can read. The safest approach:

Option A — use your existing user key and specify the full path (works if root can read /home/conor/.ssh/):

IdentityFile=/home/conor/.ssh/id_ed25519

Option B — create a dedicated key for autofs mounts:

sudo ssh-keygen -t ed25519 -f /root/.ssh/autofs_id_ed25519 -N ""
sudo ssh-copy-id -i /root/.ssh/autofs_id_ed25519.pub conor@100.x.x.x

Then use IdentityFile=/root/.ssh/autofs_id_ed25519 in the map file.

Option B is cleaner — keeps autofs auth separate from your interactive SSH key.

7. Enable and Start autofs

sudo systemctl enable autofs --now

Reload after any config changes (no restart needed):

sudo systemctl reload autofs

Or force a full restart:

sudo systemctl restart autofs

8. Testing

Trigger a mount by accessing the path:

ls /mnt/remote/farmdesktop

Check what's currently mounted:

mount | grep autofs

Check autofs status and recent activity:

sudo systemctl status autofs
sudo journalctl -u autofs -f

Force unmount a specific share manually:

sudo umount /mnt/remote/farmdesktop

9. Troubleshooting

Symptom	Likely cause	Fix
`ls` on mount point returns empty	`--ghost` not set or autofs not running	Add `--ghost` to auto.master, restart autofs
"Permission denied" accessing mounted path	`allow_other` not set or `user_allow_other` not in fuse.conf	Check `/etc/fuse.conf`
Mount works as root but not as user	`uid=` / `gid=` not set in map file	Add `uid=1000,gid=1000` (check with `id username`)
SSH auth fails in autofs but works manually	autofs runs as root, key path wrong	Use absolute path to key, or create a root-owned autofs key
Mount hangs on access	Remote host unreachable, no timeout set	Add `--timeout=30` and `soft` option; check host reachability via Tailscale
Changes to map file have no effect	autofs cached old config	`sudo systemctl reload autofs`
"bad option" error on SSHFS mount	Missing `fuse` package or wrong fstype string	Confirm `sshfs` is installed; check `fstype=fuse` not `fstype=sshfs`

10. Full Example: Tailscale Homelab

/etc/auto.master:

/mnt/remote  /etc/auto.sshfs  --timeout=60,--ghost

/etc/auto.sshfs:

farmpi       -fstype=fuse,rw,allow_other,IdentityFile=/root/.ssh/autofs_id_ed25519,uid=1000,gid=1000,ServerAliveInterval=15,ServerAliveCountMax=3,reconnect  :sshfs#conor@100.64.0.2:/home/conor
farmdesktop  -fstype=fuse,rw,allow_other,IdentityFile=/root/.ssh/autofs_id_ed25519,uid=1000,gid=1000,ServerAliveInterval=15,ServerAliveCountMax=3,reconnect  :sshfs#conor@100.64.0.3:/home/conor
homeserver   -fstype=fuse,rw,allow_other,IdentityFile=/root/.ssh/autofs_id_ed25519,uid=1000,gid=1000,ServerAliveInterval=15,ServerAliveCountMax=3,reconnect  :sshfs#conor@100.64.0.4:/home/conor

Access:

/mnt/remote/farmpi/
/mnt/remote/farmdesktop/
/mnt/remote/homeserver/

All mount on first access, unmount after 60 seconds idle. If a farm machine is offline, accessing its path returns an error immediately rather than hanging the system.

Notes

autofs mounts do not appear in df or mount output unless currently active — this is normal.
/etc/auto.master changes require a full systemctl restart autofs; map file changes only need systemctl reload autofs.
For Ansible management across your fleet, the map files and master config are straightforward to template — a single playbook can deploy consistent autofs config to all five machines.