Update Readme

README.md

@@ -8,3 +8,141 @@ 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.