@claude-code-commands/code-network-mounts-setup-nfs-mounts

# NFS Mount Setup Assistant

You are helping the user set up NFS (Network File System) mounts to remote systems.

## Your tasks:

1. **Check NFS client prerequisites:**
   - Check if NFS client utilities are installed: `dpkg -l | grep nfs-common`
   - If not installed:
     ```bash
     sudo apt update
     sudo apt install nfs-common
     ```

2. **Gather mount information from the user:**
   Ask the user for:
   - Remote NFS server IP or hostname (e.g., `10.0.0.100`)
   - Remote export path (e.g., `/srv/nfs/share`)
   - Local mount point (e.g., `/mnt/nfs/remote-share`)
   - Mount options preferences (default is usually fine, but ask if they need specific options)

3. **Test NFS server accessibility:**
   - Check if remote server is reachable: `ping -c 3 <remote-ip>`
   - List available NFS exports from the remote server:
     ```bash
     showmount -e <remote-ip>
     ```
   - If this fails, troubleshoot:
     - Check if NFS ports are open (2049, 111)
     - Verify firewall settings

4. **Create local mount point:**
   ```bash
   sudo mkdir -p <local-mount-point>
   ```

5. **Test mount temporarily:**
   Before making it permanent, test the mount:
   ```bash
   sudo mount -t nfs <remote-ip>:<remote-path> <local-mount-point>
   ```

   Verify the mount:
   ```bash
   df -h | grep <local-mount-point>
   ls -la <local-mount-point>
   ```

6. **Configure mount options:**
   Discuss common NFS mount options with the user:
   - `rw` / `ro` - Read-write or read-only
   - `hard` / `soft` - Hard mount (recommended) or soft mount
   - `intr` - Allow interruption of NFS requests
   - `noatime` - Don't update access times (performance)
   - `vers=4` - Force NFSv4 (recommended)
   - `timeo=14` - Timeout value
   - `retrans=3` - Number of retransmits
   - `_netdev` - Required for network filesystems
   - `nofail` - Don't fail boot if mount unavailable

   Recommended default options:
   ```
   rw,hard,intr,vers=4,_netdev,nofail
   ```

7. **Make mount permanent via /etc/fstab:**
   - Backup current fstab:
     ```bash
     sudo cp /etc/fstab /etc/fstab.backup.$(date +%Y%m%d_%H%M%S)
     ```

   - Add entry to /etc/fstab:
     ```
     <remote-ip>:<remote-path> <local-mount-point> nfs <options> 0 0
     ```

   - Test fstab entry without rebooting:
     ```bash
     sudo umount <local-mount-point>
     sudo mount -a
     df -h | grep <local-mount-point>
     ```

8. **Set up automount with systemd (alternative to fstab):**
   If the user prefers automount, create systemd mount units:

   Create `/etc/systemd/system/mnt-nfs-remote\x2dshare.mount`:
   ```
   [Unit]
   Description=NFS Mount for remote-share
   After=network-online.target
   Wants=network-online.target

   [Mount]
   What=<remote-ip>:<remote-path>
   Where=<local-mount-point>
   Type=nfs
   Options=<options>

   [Install]
   WantedBy=multi-user.target
   ```

   Enable and start:
   ```bash
   sudo systemctl daemon-reload
   sudo systemctl enable mnt-nfs-remote\\x2dshare.mount
   sudo systemctl start mnt-nfs-remote\\x2dshare.mount
   sudo systemctl status mnt-nfs-remote\\x2dshare.mount
   ```

9. **Configure permissions:**
   Check and configure local mount point permissions:
   ```bash
   ls -la <local-mount-point>
   ```

   If needed, adjust ownership:
   ```bash
   sudo chown <user>:<group> <local-mount-point>
   ```

10. **Test and verify:**
    - Create a test file:
      ```bash
      touch <local-mount-point>/test-file
      ls -la <local-mount-point>/test-file
      ```
    - Check from remote server if possible
    - Verify mount survives reboot (ask user to test)

11. **Troubleshooting guidance:**
    If issues occur, check:
    - Network connectivity: `ping <remote-ip>`
    - NFS service on remote: `showmount -e <remote-ip>`
    - Firewall rules on both client and server
    - SELinux/AppArmor policies (if applicable)
    - NFS server exports configuration (`/etc/exports` on server)
    - Mount logs: `sudo journalctl -u <mount-unit>` or `dmesg | grep nfs`

12. **Provide best practices:**
    - Use NFSv4 when possible (better performance and security)
    - Use `_netdev` option for network mounts
    - Use `nofail` to prevent boot issues if NFS server is down
    - Consider using autofs for on-demand mounting
    - Document all NFS mounts (keep a list of what's mounted where)
    - Regular monitoring of NFS mount health

## Important notes:
- Always backup /etc/fstab before editing
- Test mounts before making them permanent
- Use `_netdev` and `nofail` options to prevent boot issues
- Systemd mount units need escaped names (replace / with \x2d)
- Ensure NFS server has proper export permissions configured