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 script 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.

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	Description
SERVER	DNS-name or IP-address of your NFS-server.
SERVER_PATH	The remote directory to mount onto your MiSTer.
SERVER_TIMEOUT	Number of seconds to wait for the NFS-server to become reachable.
MOUNT_AT_BOOT	Set to "yes" if you want this script to run at every startup of your MiSTer.
MOUNT_OPTIONS	Client-side mount options for your NFS-mount.
WOL	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).

Concerning NFS

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.

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.

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. A reasonable habit to keep this to a minimum would be to wait up to 30 seconds from inside the Menu core or any other core that doesn't write to the disk before shutting down the device. Any pending writes will have been flushed to the server by then and you'll be safe-ish.. no guarantees though!

The MOUNT_AT_BOOT flag installs a script that cleanly unmounts your NFS share at system shutdown.

A script that can trigger this same action from the OSD is on the to-do list.