Merge pull request #29 from basvandewiel/23-documentation
Update Readme
This commit is contained in:
commit
2217c322ba
138
README.md
138
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.
|
||||
|
|
Loading…
Reference in New Issue