misternfs

NFSv4 storage support for MiSTer.

This repository contains scripts for mounting NFSv4 storage on MiSTer systems whose Linux kernel includes NFS client support.

The original scripts were based on the CIFS support already present in MiSTer and on modifications by MiSTerFPGA.org user RealLarry. The current version keeps the same basic idea while making mounting and unmounting safer, repeatable, and better integrated with current MiSTer startup mechanisms.

The long-term goal of this repository remains the same: ideally, it becomes unnecessary because NFS support is eventually adopted into the main MiSTer project.

Installing

Copy these files to your MiSTer's Scripts directory:

/media/fat/Scripts/nfs_mount.sh
/media/fat/Scripts/nfs_unmount.sh

You can then run them from the MiSTer OSD or from a Linux shell.

The two scripts should remain in the same directory. nfs_unmount.sh is a compatibility wrapper around:

nfs_mount.sh --unmount

The actual mount and unmount logic therefore lives in one place.

How it works

The scripts use a simple overlay mechanism.

When nfs_mount.sh runs successfully:

1. Your configured NFSv4 export is mounted at:

   /tmp/nfs_mount
   

2. The script looks at the top-level directories inside that NFS mount.

3. For each directory, it checks whether a directory with the same name already exists under:

   /media/fat
   

4. If both exist, the NFS directory is bind-mounted on top of the corresponding /media/fat directory.

For example, suppose your NAS exports:

/storage/MiSTer

and it contains:

/storage/MiSTer/games
/storage/MiSTer/Saves

After the initial NFS mount, these appear as:

/tmp/nfs_mount/games
/tmp/nfs_mount/Saves

If your MiSTer already contains:

/media/fat/games
/media/fat/Saves

the script bind-mounts the NFS versions over those directories:

/tmp/nfs_mount/games  -> /media/fat/games
/tmp/nfs_mount/Saves  -> /media/fat/Saves

Anything that does not exist in both locations is left alone.

Why do this?

It lets you decide which parts of the MiSTer filesystem live on the SD card and which are supplied by your NAS.

For example, you could keep:

/media/fat/_Arcade
/media/fat/_Console
/media/fat/_Computer

entirely on the SD card while placing only:

games
Saves

on your NFS server.

Or you can keep a small local games directory for portable use and overlay it with a much larger collection when your MiSTer is connected to your home network.

The directory on /media/fat must already exist before the script will overlay it.

Safe repeated execution

The current script is designed to be idempotent.

Running nfs_mount.sh more than once should not create duplicate mounts. If the configured NFS export is already mounted in the expected location, the script reuses it. Existing mountpoints under /media/fat are left untouched rather than blindly mounted over again.

A lock also prevents multiple copies of the script from performing the mount operation simultaneously.

This is particularly useful during startup, where multiple pieces of the system may become active at roughly the same time.

Unmounting

To unmount the NFS storage manually, run:

/media/fat/Scripts/nfs_unmount.sh

or equivalently:

/media/fat/Scripts/nfs_mount.sh --unmount

Unlike the old implementation, this does not run:

umount -a -t nfs4

and therefore does not indiscriminately unmount every NFSv4 filesystem on the MiSTer.

The mount script records the mount IDs of the NFS and bind mounts it creates. The unmount operation uses that information to remove only mounts belonging to this script.

If another filesystem has subsequently replaced one of those mounts, the script leaves it alone rather than risking unmounting something it does not own.

Configuration

The preferred configuration method is a file named:

nfs_mount.ini

in the same directory as nfs_mount.sh.

For the usual installation this means:

/media/fat/Scripts/nfs_mount.ini

The configuration parser accepts a fixed set of known options. The file is not executed as arbitrary shell code.

SERVER and SERVER_PATH are mandatory.

Variable	Default	Description
SERVER	unset	DNS name or IP address of the NFS server.
SERVER_PATH	unset	NFSv4 path to mount. Must begin with /.
SERVER_TIMEOUT	60	Seconds to wait for TCP port 2049 on the NFS server.
NETWORK_TIMEOUT	45	Seconds to wait for the MiSTer to obtain a usable IPv4 address.
BOOT_START_DELAY	8	Extra delay, in seconds, before a boot-started mount attempt.
MOUNT_AT_BOOT	yes	Enable automatic mounting during MiSTer startup.
MOUNT_OPTIONS	noatime	Additional client-side NFS mount options.
WOL	no	Send a Wake-on-LAN packet before waiting for the NFS server.
SERVER_MAC	00:11:22:33:44:55	MAC address used when WOL="yes".

An example configuration:

SERVER="192.168.0.4"
SERVER_PATH="/storage/mister"
MOUNT_AT_BOOT="yes"
MOUNT_OPTIONS="noatime,ro"

This mounts:

192.168.0.4:/storage/mister

as an NFSv4 filesystem and makes the resulting matching directories available under /media/fat.

Because ro is included in MOUNT_OPTIONS, the NFS filesystem is mounted read-only.

A writable example would simply use:

MOUNT_OPTIONS="noatime"

Using a hostname

You may use a DNS hostname instead of an IP address:

SERVER="nas.example.lan"
SERVER_PATH="/storage/mister"

Make sure name resolution is working on the MiSTer before relying on this during startup.

Automatic mounting at boot

With:

MOUNT_AT_BOOT="yes"

the script configures itself to run automatically during MiSTer startup.

Current versions prefer MiSTer's persistent:

/media/fat/linux/user-startup.sh

mechanism.

If that mechanism is unavailable, the script can fall back to creating an init script under:

/etc/init.d

The boot-time invocation runs in the background so it does not block the remainder of the MiSTer startup process.

Old if-up.d and if-down.d hooks created by earlier versions of the script are removed when the new script runs.

To disable automatic mounting, set:

MOUNT_AT_BOOT="no"

and run nfs_mount.sh once manually so it can remove its startup configuration.

Network startup timing

There are now two separate timeout settings.

NETWORK_TIMEOUT controls how long the script waits for the MiSTer itself to obtain a usable IPv4 address:

NETWORK_TIMEOUT="45"

SERVER_TIMEOUT controls how long it waits for the NFSv4 service on the server:

SERVER_TIMEOUT="60"

For NFSv4, the script checks TCP port:

2049

It does not treat rpcbind on port 111 as proof that the NFSv4 service itself is available.

During boot, BOOT_START_DELAY adds a small initial delay before network checking begins:

BOOT_START_DELAY="8"

This helps avoid racing the MiSTer's network initialization.

If your NAS is already running and your network is available, mounting should normally happen almost immediately.

If Wake-on-LAN is being used and the NAS takes a minute to boot, the NFS overlay may appear some time after the rest of the MiSTer interface has already started.

That can temporarily make the contents of /media/fat look different from what they become after the NFS mounts are installed.

Wake-on-LAN

Set:

WOL="yes"
SERVER_MAC="00:11:22:33:44:55"

to send a standard Wake-on-LAN magic packet before waiting for the NFS server.

Both colon-separated and hyphen-separated MAC addresses are accepted.

For example:

SERVER_MAC="00:11:22:33:44:55"

The script validates the address before attempting to send the packet.

Wake-on-LAN support requires the relevant xxd and socat utilities to be available on the MiSTer system.

Logging and troubleshooting

Normal status messages are sent to the system logger, so check:

/var/log/messages

when troubleshooting.

For boot-started runs, output is also written to:

/tmp/nfs_mount.log

Useful checks from a shell include:

mount

and:

cat /proc/self/mountinfo

To verify the NFS server itself is reachable:

nc -z SERVER 2049

replacing SERVER with the address configured in nfs_mount.ini.

NFSv4 only

This script currently supports NFSv4.

The mount itself is performed using:

-t nfs4

and server readiness is determined using the standard NFSv4 TCP port 2049.

NFSv2 and NFSv3 are not supported by this script.

When to use NFS

NFS is a good fit when you already operate Linux, BSD, another UNIX-like system, or a NAS with good NFS support.

Advantages include:

• native support on most UNIX-like systems;
• relatively low protocol and server overhead;
• no need to operate Samba solely for the MiSTer;
• familiar UNIX ownership and permission semantics;
• convenient access to large game, disk-image, and save collections.

If you already run NFS elsewhere on your network, using the same infrastructure for MiSTer can be very convenient.

When not to use NFS

If you have never used NFS before and simply want network storage for MiSTer, CIFS/Samba will often be easier.

NFS assumes more familiarity with:

• UNIX permissions;
• UID/GID ownership;
• root squashing;
• server export configuration;
• client/server failure behavior;
• case-sensitive filesystems.

That does not make NFS inherently unsuitable for MiSTer, but it does mean that the failure modes can be less obvious if you are unfamiliar with traditional UNIX filesystem semantics.

Curious tinkerers are, of course, encouraged to ignore this warning responsibly.

Potential issues

Case sensitivity

MiSTer runs Linux, but the normal SD-card filesystem is usually exFAT and therefore case-insensitive.

NFS exports, on the other hand, are commonly backed by Linux, BSD, ZFS, ext4, XFS, or another case-sensitive filesystem.

On the SD card:

NeoGeo
NEOGEO

may effectively refer to the same name.

On a typical NFS server they are two different names.

Be particularly careful with update scripts, ROM directories, configuration files, and software that assumes case-insensitive storage.

Root permissions and root squashing

MiSter normally performs these operations as:

root

A typical NFS server deliberately does not allow a client's root account to automatically become root on the server.

This security feature is commonly called:

root squash

As a result, MiSTer's root user may be mapped to an unprivileged account such as:

nobody

on the NFS server.

This can result in files being readable but not writable, or directories being inaccessible altogether.

There are generally two approaches.

Allow client root appropriate server-side access

Configure your NFS server so that root from the MiSTer is mapped appropriately.

The exact terminology depends on the server or NAS implementation. Look for settings involving:

root squash
no_root_squash
maproot
mapall

Do not blindly disable root squashing across an untrusted network. Restrict exports to the MiSTer or to an appropriate trusted network.

Give the mapped account appropriate permissions

Alternatively, determine which UID/GID or account your NFS server maps the MiSTer's root user to and give that identity the necessary permissions on the exported files.

This is often preferable when you do not want remote root users to have root-equivalent access on the server.

The share is read-only

Even perfect UNIX permissions cannot make a server-side read-only NFS export writable.

If the NFS server exports the filesystem as read-only, the client cannot override that decision.

Check your NFS server configuration for options such as:

ro

and change the server configuration if write access is required.

Also check the client configuration. This:

MOUNT_OPTIONS="noatime,ro"

explicitly requests a read-only mount.

For writable storage use, for example:

MOUNT_OPTIONS="noatime"

Only one file or directory is unwritable

If most of the share works but one particular file or directory cannot be modified, the problem is usually server-side ownership or permissions.

Check:

• the file owner;
• the file group;
• directory permissions;
• the UID/GID presented by the NFS client;
• root-squash or maproot behavior;
• ACLs, if your server uses them.

The issue is normally not MiSTer-specific at that point; it is ordinary UNIX filesystem permission behavior.

Sudden power-off and writable disk images

NFS comes from an environment where clients were traditionally expected to perform orderly shutdowns.

MiSTer behaves much more like the consumer computers it recreates: turning the power off is perfectly normal.

The NFS server will generally survive an abruptly disappearing client, but applications may still have writes in progress when power is removed.

This is particularly important for writable disk images used by cores such as:

ao486
Amiga
Atari ST
Macintosh
PC/XT

A disk image being modified at exactly the wrong moment can be left in an inconsistent state.

This is not unique to NFS. The same fundamental risk exists with other network filesystems and with local writable storage if power disappears during an important write.

For immutable content such as ROM collections, a read-only NFS mount is the safest arrangement:

MOUNT_OPTIONS="noatime,ro"

For writable disk images and saves, make sure your server and storage are reliable and understand that abrupt power removal always carries some risk.

When practical, run:

/media/fat/Scripts/nfs_unmount.sh

before deliberately disconnecting the MiSTer from the network or shutting down the NFS server.

The script does not claim to make arbitrary hard power-offs safe, and automatic mounting at boot does not imply that a clean unmount can occur when power is simply removed.

NFS and Wake-on-LAN

Wake-on-LAN can make startup timing less predictable.

The sequence becomes approximately:

MiSTer boots
    |
    +--> sends Wake-on-LAN packet
    |
    +--> MiSTer continues starting
    |
NAS boots
    |
TCP/2049 becomes available
    |
NFS mount is created
    |
matching /media/fat directories are overlaid

During that interval, software may initially see the local SD-card contents and later see the NFS-backed contents.

If that distinction matters for your setup, leave the NAS running continuously or avoid launching affected cores until the NFS mount is available.

NFS, CIFS and USB storage

MiSTer supports several approaches to external and network storage.

This NFS script deliberately uses bind mounts over existing /media/fat directories, while other MiSTer storage mechanisms may use different integration methods.

As a result, NFS, CIFS, USB storage and the SD card can coexist, but the effective precedence depends on how each mechanism is mounted and on the MiSTer software version in use.

If you combine multiple storage mechanisms, verify the resulting mount layout with:

mount

rather than assuming that one particular source will always take precedence.

The NFS script itself follows one simple rule:

It only overlays an existing /media/fat/<name> directory when a top-level directory with the same name exists in the configured NFS export.

Everything else is left untouched.

Safety improvements over the original scripts

The current implementation deliberately avoids several behaviors from the older NFS scripts.

It no longer:

• aborts merely because some unrelated NFS filesystem is mounted;
• treats rpcbind on port 111 as proof that NFSv4 is available;
• globally unmounts every NFSv4 filesystem;
• blindly creates duplicate bind mounts;
• runs multiple concurrent mount operations without locking;
• uses eval to execute the contents of nfs_mount.ini;
• relies on network if-up.d and if-down.d hooks;
• assumes that a mount at a familiar path necessarily belongs to this script.

Instead it tracks the mounts it creates and tries to leave unrelated filesystems alone.

That is particularly important on MiSTer systems doing more than one interesting thing with Linux networking.

Example configuration

A fairly typical writable configuration:

SERVER="192.168.1.20"
SERVER_PATH="/storage/MiSTer"

SERVER_TIMEOUT="60"
NETWORK_TIMEOUT="45"
BOOT_START_DELAY="8"

MOUNT_AT_BOOT="yes"
MOUNT_OPTIONS="noatime"

WOL="no"

A read-only ROM-library setup using Wake-on-LAN:

SERVER="nas.home.arpa"
SERVER_PATH="/tank/roms/MiSTer"

SERVER_TIMEOUT="120"
NETWORK_TIMEOUT="45"
BOOT_START_DELAY="8"

MOUNT_AT_BOOT="yes"
MOUNT_OPTIONS="noatime,ro"

WOL="yes"
SERVER_MAC="00:11:22:33:44:55"

Final warning from the greybeards

NFS is old, powerful, simple, and surprisingly difficult to fool.

Most problems ultimately come down to one of four things:

networking
permissions
server exports
filesystem semantics

If those concepts already make sense to you, NFS on MiSTer is a very useful option.

If they don't, CIFS may be the easier road.

Or learn NFS.

It's fun.