Improve NFS documentation and install script, especially for Windows (#…

…1442)

docs/users/performance.md

@@ -6,45 +6,64 @@ Every developer wants both quick starts of the environment and quick response to
 
 NFS (Network File System) is a classic, mature Unix technique to mount a filesystem from one device to another. It's provided as an experimental technique for improving webserving performance. DDEV-Local supports this technique, but it **does requires a small amount of configuration on your host computer.**
 
+__Before starting with NFS mounting, please make sure your project runs successfully without NFS mounting (without `nfs_mount_enabled: true` in your project's `.ddev/config.yaml` file.)__
+
 To enable NFS mounting, use `nfs_mount_enabled: true` in your .ddev/config.yaml, or `ddev config --nfs-mount-enabled=true`. This won't work until you have done the one-time configuration for your system described below.
 
 Note that you can use the NFS setup described here (and the scripts provided) or you can set up NFS any way that works for you. For example, if you're already using NFS with vagrant on macOS,and you already have a number of exports, the default export here (/Users) won't work, because you'll have mount overlaps. Or on Windows, you may want to use an NFS server other than Winnfsd, for example the [Allegrao NFS Server](https://nfsforwindows.com). The setups provided below and the scripts provided below are just intended to get you started if you don't already use NFS.
 
 ### macOS NFS Setup
 
-__macOS Mojave (and later) warning:__ You'll need to give your terminal "Full disk access" before you (or the script provided) can edit /etc/exports. If you're using iterm2, here are [full instructions for iterm2](https://gitlab.com/gnachman/iterm2/wikis/fulldiskaccess). The basic idea is that in the Mac preferences -> Security and Privacy -> Privacy you need to give "Full Aisk Access" permissions to your terminal app.
+__macOS Mojave (and later) warning:__ You'll need to give your terminal "Full disk access" before you (or the script provided) can edit /etc/exports. If you're using iterm2, here are [full instructions for iterm2](https://gitlab.com/gnachman/iterm2/wikis/fulldiskaccess). The basic idea is that in the Mac preferences -> Security and Privacy -> Privacy you need to give "Full Disk Access" permissions to your terminal app.
 
 Download, inspect, and run the macos_ddev_nfs_setup.sh script  from [macos_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/macos_ddev_nfs_setup.sh)). This stops running ddev projects, adds the /Users directory to the /etc/exports config file that nfsd uses, and enabled nfsd to run on your computer. This is one-time setup. Note that this shares the /Users directory via NFS to any client, so it's critical to consider security issues and verify that your firewall is enabled and configured. If your DDEV-Local projects are set up outside /Users, you'll need to edit /etc/exports for the correct values.
 
 ### Windows NFS Setup
 
 The executable components required for Windows NFS (winnfsd and nssm) are packaged with the ddev_windows_installer in each release, so if you've used the windows installer, they're available already. To enable winnfsd as a service, please download, inspect and run the script "windows_ddev_nfs_setup.sh" installed by the installer (or download from [windows_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/windows_ddev_nfs_setup.sh)) in a git-bash session on windows. This is one-time setup. Note that this shares the C:\ directory via NFS to any local client, so it's critical to consider security issues and verify that your firewall is enabled and configured. If your DDEV-Local projects are set up outside C:\, you'll need to edit the ~/.ddev/nfs_exports.sh created by the script and then restart the service with `sudo nssm restart nfsd`.
 
-**Firewall issues**: On Windows 10 you may run afoul of the Windows Defender Firewall, and it may be necessary to allow winnfsd to bypass it. If you're getting a timeout with no information after `ddev start`, try going to "Windows Defender Firewall" -> "Allow an app or feature through Windows Defender Firewall", "Change Settings", "Allow another app". Then choose C:\Program Files\ddev\winnfsd.exe, assuming that's where you installed winnfsd.
+**Firewall issues**: On Windows 10 you will likely run afoul of the Windows Defender Firewall, and it will be necessary to allow winnfsd to bypass it. If you're getting a timeout with no information after `ddev start`, try going to "Windows Defender Firewall" -> "Allow an app or feature through Windows Defender Firewall", "Change Settings", "Allow another app". Then choose C:\Program Files\ddev\winnfsd.exe, assuming that's where you installed winnfsd.
+
+Also see the debugging section below, and the special WIndows debugging section.
 
-### Debian/Ubuntu NFS Setup
+### Debian/Ubuntu Linux NFS Setup
 
-Note that for all Linux systems, you can and should install and configure the NFS daemon and configure /etc/exports as you see fit and share the directories that you choose to share. The debian/ubuntu script is just one way of accomplishing it. 
+Note that for all Linux systems, you can and should install and configure the NFS daemon and configure /etc/exports as you see fit and share the directories that you choose to share. The Debian/Ubuntu Linux script is just one way of accomplishing it. 
 
-Download, inspect, and run the [debian_ubuntu_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/debian_ubuntu_ddev_nfs_setup.sh)). This stops running ddev projects, adds the /home directory to the /etc/exports config file that nfs uses, and installs nfs-kernel-server  on your computer. This is one-time setup. Note that this shares the /home directory via NFS to all non-routeable ("public") IP addresses in your network, so it's critical to consider security issues and verify that your firewall is enabled and configured. If your DDEV-Local projects are set up outside /home, you'll need to edit /etc/exports for the correct values and restart nfs-kernel-server.
+Download, inspect, and run the [debian_ubuntu_linux_ddev_nfs_setup.sh](https://raw.githubusercontent.com/drud/ddev/master/scripts/debian_ubuntu_linux_ddev_nfs_setup.sh)). This stops running ddev projects, adds the /home directory to the /etc/exports config file that nfs uses, and installs nfs-kernel-server  on your computer. This is one-time setup. Note that this shares the /home directory via NFS to all non-routeable ("public") IP addresses in your network, so it's critical to consider security issues and verify that your firewall is enabled and configured. If your DDEV-Local projects are set up outside /home, you'll need to edit /etc/exports for the correct values and restart nfs-kernel-server.
 
 ### Debugging `ddev start` failures with `nfs_mount_enabled: true`
 
 There are a number of reasons that the NFS mount can fail on `ddev start`:
 
 * NFS Server not running
+* Trying to start more than one NFS server. (This is typically only an issue on Windows)
+* NFS exports overlap. This is typically an issue if you've had another NFS setup (like vagrant). You'll need to reconfigure your exports paths so they don't overlap.
 * Path of project not shared in `/etc/exports` (or `~/.ddev/nfs_exports.txt` on WIndows)
 * Docker container IP not listed in /etc/exports (Linux)
 
 Tools to debug and solve permission problems:
 
 * Try `ddev debug nfsmount` to see if basic NFS mounting is working. If that works, it's likely that everything else will.
 * When debugging, please do `ddev rm; ddev start` in between each change. Otherwise, you can have stale mounts inside the container and you'll miss any benefit you may find in the debugging process.
-* Inspect the /etc/exports (or `~/.ddev/nfs_mounts.txt` on Windows).
+* Inspect the /etc/exports (or `~/.ddev/nfs_exports.txt` on Windows).
 * Restart the server (`sudo nfsd restart` on macOS, `sudo nssm restart nfsd` on Windows, `sudo systemctl restart nfs-kernel-server` on Debian/Ubuntu, other commaonds for other Unices).
 * `showmount -e` on macOS or Linux will show the shared mounts.
 * On Linux, you may have to experiment with the client IP addresses in the /etc/exports. Temporarily set the share in /etc/exports to `/home *`, which shares /home with any client, and `sudo systemctl restart nfs-kernel-server`. Then start a ddev project doing an nfs mount, and `showmount -a` and you'll find out what the assigned IP address of the docker client is. You can add that address range to /etc/exports.
 
+### Windows-specific NFS debugging
+
+* You can only have one NFS daemon running, so if another application has installed one, you'll want to use that NFS daemon and reconfigure it to allow NFS mounts of your projects. 
+
+1. Stop the running winnfsd service: `sudo nssm stop nfsd`
+2. Run winnfsd manually in the foreground: `winnfsd "C:\\"`. If it returns to the shell prompt immediately there's likely another nfsd service running. 
+3. In another windows, in a ddev project directory, `ddev debug nfsmount` to see if it can mount successfully. (The project need not be started.). `ddev debug nfsmount` is successful, then everything is probably going to work.
+4. After verifying that ~/.ddev/nfs_exports.txt has a line that includes your project directories, `sudo nssm start nfsd` and `nssm status nfsd`. The status command should show SERVICE_RUNNING.
+5. These [nssm](https://nssm.cc/) commands may be useful: `nssm help`, `sudo nssm start nfsd`, `sudo nssm stop nfsd`, `nssm status nfsd`, `sudo nssm edit nfsd` (pops up a window that may be hidden), and `sudo nssm remove nfsd` (also pops up a window, doesn't work predictably if you haven't already stopped the service). 
+6. nssm logs failures and what it's doing to the system event log. Run "Event Viewer" and filter events as in the image below: ![Windows Event Viewer](images/windows_event_viewer.png).
+7. Please make sure you have excluded winnfsd from the Windows Defender Firewall, as described in the installation instructions above.
+8. On Windows 10 Pro you can "Turn Windows features on or off" and enable "Services for NFS"-> "Client for NFS". The `showmount -e` command will then show available exports on the current machine. This can help find out if a conflicting server is running or exactly what the problem with exports may be.
+
 ## Using webcache_enabled to Cache the Project Directory
 
 A separate webcache container is also provided as a separate experimental performance technique. It does not rely on any host configuration, but in some cases when large changes are made in the filesystem it can stop syncing and be unstable.

scripts/windows_ddev_nfs_setup.sh

@@ -32,19 +32,22 @@ if ! command -v winnfsd.exe >/dev/null; then
 fi
 winnfsd=$(command -v winnfsd.exe)
 
-if [ -f ~/.ddev/nfs_mounts.txt ]; then
-    echo "~/.ddev/nfs_mounts.txt already exists, not overwriting it"
+if [ -f ~/.ddev/nfs_exports.txt ]; then
+    echo "~/.ddev/nfs_exports.txt already exists, not overwriting it"
 else
     echo "
-# Exports for winnfsd
+# Exports for winnfsd for ddev
 # You can edit these yourself to match your workflow
 # But nfs must share your project directory
-C:\ > /C" >~/.ddev/nfs_mounts.txt
+# Additional lines can be added for additional directories or drives.
+C:\ > /C" >~/.ddev/nfs_exports.txt
 fi
-sudo nssm install nfsd "${winnfsd}" -id ${DDEV_WINDOWS_UID} ${DDEV_WINDOWS_GID} -log off -pathFile "$HOME/.ddev/nfs_mounts.txt"
-sudo nssm start nfsd
+sudo nssm install nfsd "${winnfsd}" -id ${DDEV_WINDOWS_UID} ${DDEV_WINDOWS_GID} -log off -pathFile "$HOME/.ddev/nfs_exports.txt"
+sudo nssm start nfsd || true
+sleep 2
+nssm status nfsd
 
-echo "winnfsd has been installed as service nfsd serving the mounts in ~/.ddev/nfs_mounts.txt"
+echo "winnfsd has been installed as service nfsd serving the mounts in ~/.ddev/nfs_exports.txt"
 echo "You can edit that file and restart the nfsd service"
 echo "with 'sudo nssm restart nfsd'"
 echo "Or you can edit its behavior with 'sudo nssm edit nfsd'"