misternfs

NFS support for MiSTer. This repository contains supporting scripts for use once the MiSTer's Linux kernel gets NFS client support compiled in.

The script is based off the CIFS scripts already present in the project and modifications as made by misterfpga.org user RealLarry.

The purpose of this repository is to eventually disappear so that the script can be adopted into the mainline MiSTer project and live on there.

Installing the script

Place the nfs_mount.sh and nfs_unmount.sh scripts inside your MiSTer's /media/fat/Scripts directory. You can run it from there through the OSD or from a (remote) Linux shell as you see fit.

What it does: ..here be dragons

These two scripts do what they say on the box: mount and unmount your NFS-provided network storage. When the sanity checks work out, the actual mount works as follows.

1. The script mounts your SERVER_PATH onto /tmp/nfs_mount on your MiSTer.
2. It then looks for directories inside your /tmp/nfs_mount and compares them to the directories you have in /media/fat.
3. If it finds directories that appear in both location, the NFS-version gets mounted on top of the existing directory in /media/fat.

Wait.. what!?

Let's say you have a directory on your NAS named /storage/MiSTer that you export over NFS, then that will end up mounted at /tmp/nfs_mount on your MiSTer and that will be that if it's empty.

If you have a games directory inside your /storage/MiSTer on the NAS, then the script will pick up on that. If and only if you also have an pre-existing /media/fat/games directory, the remote version will be mounted on top of your existing /media/fat/games.

This goes for any and all directories that appear in both places at the time time script runs, which is once at system boot and/or on demand when you run it from a shell or the MiSTer's OSD.

This trick permits you to keep your cores on the SD-card by not having /media/fat/_Arcade etc. on your NAS. If it's not found on your NAS, then the directory won't be overlaid with anything and just left alone as-is on your SD-card.

You can use this to keep a small-ish /media/fat/games directory on your SD-card for portable gaming fun, while having the entire history of retrogaming and a plethora of Windows 95 installations on your NAS at home by overlaying /media/fat/games via NFS.

Configuration

The preferred method for configuring the script is through an INI file that sits in the same directory as the main script itself and is named nfs_mount.ini. In this file you can define a number of variables of which SERVER and SERVER_PATH are mandatory.

Variable name	Default	Description
SERVER	Undefined	DNS-name or IP-address of your NFS-server.
SERVER_PATH	Undefined	The remote directory to mount onto your MiSTer.
SERVER_TIMEOUT	60	Number of seconds to wait for both IP-connectivity and the NFS-server to become reachable.
MOUNT_AT_BOOT	yes	Set to "yes" if you want this script to run at every startup of your MiSTer.
MOUNT_OPTIONS	"noatime"	Client-side mount options for your NFS-mount.
WOL	"no	WakeOnLAN: set to "yes" to send a wake-up packet to your NFS-server to wake it up.

An example for the contents of a valid INI file would be:

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

This example would try to mount the /storage/mister path from a server that lives at IP-address 192.168.0.4. It'd install scripts to run at every boot and the MOUNT_OPTIONS mount the directory as read-only (see below).

You can also modify the script itself, but that'll get clobbered when you update the script. Using an INI file keeps the script and its configuration separate, which is good practice.

Just to be 100% clear here: you must define SERVER and SERVER_PATH yourself. The other variables all have sensible defaults set.

Troubleshooting

This script is entirely silent on the MiSTer's console. For troubleshooting, have a look at the syslog file in /var/log/messages. The script logs status messages there.

Concerning NFS: more dragons

The NFS protocol is ancient and it was conceived in the days of big-iron UNIX machines in well-tended datacenters where grey-haired veteran geeks would carefully nurture, cultivate and sacrifice the occasional goat to them. This is quite a different backdrop from a retro computing appliance that simulates consumer devices which would habitually be turned off and on again as legitimate troubleshooting steps without batting an eyelash.

When to use NFS

Using the NFS protocol on your MiSTer allows you to use files that sit on your NAS or another Linux/UNIX compatible device like a Raspberry Pi. The main advantage of NFS over all other options is that it comes included with most Linux and other UNIX-like operating systems, unlike Samba for example. NFS is also arguably more light-weight than Samba, which matters in case you're using an old Raspberry Pi or similar board as a server. If you know and love UNIX, you'll feel more at home with NFS than you do with Samba/CIFS.

When not to use NFS

Don't use NFS if you don't already know what it is and have it running in your network. Really, it's hardly worth the trouble and CIFS will service you just fine for your MiSTer needs. NFS should be treated as an option for those who already know why they want to use it, which obviously includes curious tinkerers. This is not a threat by any means, but do consider yourself warned.

Potential issues

By virtue of being an old UNIX file-sharing protocol, you're exposing your MiSTer to the old world that began with teletypes and punch cards. You'll need to be more careful with it than you'd be when using just the plain local SD card or you'll run into issues that may seem hard to debug at first. Here's a few pointers.

Case sensitivity

MiSTer runs Linux, which is generally case-sensitive but not in the MiSTer's default case using just the SD-card for storage. The SD-card is formatted using exFAT, which is case-insensitive. NFS, on the other hand, generally has a Linux/UNIX backing store which does care about case. This means that on your SD-card NeoGeo and NEOGEO are the same thing, while they're quite distinct via NFS.

Ensure that you test your update scripts etc. carefully before moving your stuff over to an NFS-based network share.

Mounting NFS may take a while

The SERVER_TIMEOUT value is used in two places, accumulating to a total timeout value of twice the number of seconds you define for it. By default this means it can take up to two minutes for your MiSTer to have NFS mounted and ready to go. These timeouts are not blocking to the rest of the system's startup process, so you may get some glitchy behavior there if you have overlapping directories with differing contents. The contents of the /media/fat hierarchy may suddenly appear different from how it after NFS gets mounted.

The mount should take hardly any time at all if your NFS-server is already up before you start your MiSTer, but you could be in for a surprise if you're using the WOL flag for instance and your NFS-server needs to boot up while your MiSTer proceeds to load from its SD-card. This is an advanced use case, so don't try this if you're not comfortable with it.. or open a thread on the MiSTerFPGA.org forum and aks for guidance.

Can't write to my network share

The MiSTer device runs everything as the root user. This is perfectly valid for an appliance that has no concept of security contexts within its own operating system. For all intents and purposes, the MiSTer doesn't concern itself with permissions: root can always do everything it wants, which is the user-friendly option for a device like this.

NFS, by default, is not that forgiving because it was born in big datacenters where the resident greybeards did care passionately about who could do what to their precious files. By virtue of this, the default for NFS servers is to tell the MiSTer's root user to go play a fiddle in a field somewhere instead of trying to write to the server's files as root no less.

MiSTer's root user will be mapped to the server's nobody user by default, which will most likely mean a world of pain for MiSTer users: you can hardly access anything, let alone write to any files from your MiSTer.

In order to change this, you can do one of generally two things:

• Adjust the /etc/exports file on your server so that root on a client gets mapped to root on the server as well. All NFS-servers are different so there's no one-size-fits-all recipe to give for this. Consult the manual for your specific NFS-server of NAS device. Look for terms like 'maproot' or 'root squash'.
• Look up the specific user and group that root gets mapped to and change the permissions on your server's file system so that this mapped user, usually nobody, is allowed the proper access to both files and directories.

Still can't write to my network share

Your server may have exported the directory itself as read-only. In that case the NFS-server will go full-on Gandalf at your MiSTer: you shall not pass, not even if you are root. Have a good look at your /etc/exports file on the server, look for ro in the export definiton of the path you are trying to mount and get rid of it.

Can't write to this particular file

What if all files are fine except this one file or directory? That's almost always a permissions issue combined with the root user being mapped to something else on the server. The files that refuse to play ball are generally owned by the wrong user on the server's side, or they have the wrong permissions set on them.

You're dealing with the dark underbelly of the 1970's world of UNIX here. Learn it, it's fun! Or use something like a USB-drive or a bigger SD-card instead.

Combinations with USB and CIFS storage

MiSTer provides alternative options for storage next to NFS. At the time of this writing, these options have not been unified into any kind of Grand Unifying Storage Architecture for the MiSTer so this is the observed behavior from initial testing.

USB trumps everything. When you attach USB-storage, its contents get overlaid onto everything else including CIFS and NFS storage options.

CIFS and NFS do coexist fairly peacefully since they both have different mechanics of exposing their contents to the user. The NFS-script overlays the NFS mounts onto the existing structures on the SD-card, while CIFS exposes its own cifs directory which the cores prefer when they detect it, giving you the option of navigating to the SD-card directory structures that sit alongside it.

At this point in time, these items are simply facts of life. If/when NFS sees any significat uptake it'd probably be a good idea to unify alternative storage options into a predictable mechanism. For now the user should note that these differences exist.

General wonkiness after turning my MiSTer off

As mentioned before, NFS comes from datacenters where one does not simply power off a machine. NFS was designed against a background of sysadmins knowing what they're doing and performing a clean shutdown at the end of their session.

MiSTer, on the other hand, is an appliance. The computers it simulates have no notion of a clean shutdown procedure. Back in the 1980's we just flipped the switch and that was it.

While the NFS-server will survive if you do this, chances are that some wonky behaviour ensues if you turn it back on again very quickly. NFS simply wasn't made with this usage pattern in mind and any problems have to do with files being "open" from the server's perspective and remaining that way in the face of the client simply falling off the face of the planet.

These dangling references don't happen very often, but they do happen and they can corrupt any files that the NFS-server thinks you were still writing to when you turned your MiSTer off.

You can prevent this whole issue from occurring by only using read-only mounts, which is perfectly fine for immutable things like arcade ROM's and the like. It won't go over very well for hard disk images for cores like PCXT/AO486 or Amiga. Those simulated machines expect their drives to be writable at all times and things get hairy if they're not.

This is a fact of life when using a datacenter protocol with an appliance and will also happen if you rudely hang up a CIFS server, so there's no real recourse against this. You really should always call the nfs_unmount.sh script from the Scripts folder before shutting down your MiSTer. The MOUNT_AT_BOOT flag installs a script that cleanly unmounts your NFS share upon clean system shutdown. The main problem with that is that clean system shutdowns are so rare on MiSTer.