feat: add pos system nfs-server and nfs-client (systemd persistent mounts)

2026-08-06 03:19:42 -04:00
parent aac3c5266a
commit 03e9d4c8e6
8 changed files with 390 additions and 14 deletions
@@ -8,6 +8,8 @@ Host care: encrypted backups, firewall, and the health dashboard. Tools:
 | `pos system health` | Host health dashboard (disk, RAM, services, backup age, fail2ban, docker) |
 | `pos system backup` | gpg-encrypted (AES-256) folder snapshots |
 | `pos system firewall` | Interactive UFW ("UFW POWER") management |
+| `pos system nfs-server` | Manage the NFS kernel server (exports, enable/disable) |
+| `pos system nfs-client` | Mount NFS shares (ephemeral or persistent systemd units) |

 ---

@@ -143,6 +145,90 @@ not).

 ---

+## `pos system nfs-server` — NFS kernel server
+
+Requires `nfs-kernel-server` (in `preinstall.sh` PACKAGES). Writes to
+`/etc/exports` and reloads via `exportfs -ra`; mutating commands announce via
+`notify_send`.
+
+```bash
+pos system nfs-server status                    # server active? + current exports
+pos system nfs-server share /mnt/hdd            # export (generic, warns)
+pos system nfs-server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'
+pos system nfs-server list                      # exportfs -v
+pos system nfs-server unshare /mnt/hdd          # remove the export
+pos system nfs-server reload                    # re-apply /etc/exports after hand edits
+pos system nfs-server enable                    # start + boot-persist the server
+pos system nfs-server disable
+```
+
+`share <path> [client]` is idempotent: an existing line for the same path is
+replaced. With no client it uses `*(rw,sync,no_subtree_check)` and **warns you
+to restrict it** — print the restricted form:
+
+- Tailscale (CGNAT): `pos system nfs-server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'`
+- WireGuard: `pos system nfs-server share /mnt/hdd '10.10.0.0/24(rw,sync,no_subtree_check)'`
+- LAN: `pos system nfs-server share /mnt/backups '192.168.1.0/24(ro,sync,no_subtree_check)'`
+
+**Recipes:**
+- **Share the media drive to the tailnet:**
+  ```bash
+  pos system nfs-server share /mnt/hdd '100.64.0.0/10(rw,sync,no_subtree_check)'
+  pos system nfs-server enable
+  ```
+- **Read-only backups to a LAN host:** use `(ro,sync,no_subtree_check)` and only
+  `enable` the server where it's needed.
+
+**Troubleshooting:**
+- "exportfs not found" → `nfs-kernel-server` isn't installed; `sudo apt install nfs-kernel-server`
+- Client sees "mount.nfs: Permission denied" → your `/etc/exports` client rule
+  doesn't cover the client's IP (check with `pos system nfs-server list`); use
+  `showmount -e <server>` on the client to see what's exported
+- After editing `/etc/exports` by hand, run `pos system nfs-server reload`
+- NFS is blocked → allow the ports in `pos system firewall` (or `ufw`)
+- Changes to `/etc/exports` are root-required → the tool uses `sudo`
+
+---
+
+## `pos system nfs-client` — mount NFS shares
+
+Requires `nfs-common` (in `preinstall.sh` PACKAGES).
+
+```bash
+pos system nfs-client mount <server:export> <local-dir>   # one-shot (mkdir -p first)
+pos system nfs-client persist <server:export> <local-dir> # persistent systemd mount
+pos system nfs-client list                                # active NFS mounts
+pos system nfs-client unmount <local-dir>
+pos system nfs-client unpersist <local-dir>               # remove the systemd unit
+```
+
+**Persistent mounts use systemd, not fstab.** `persist` writes a
+`/etc/systemd/system/<mnt-nfs-name>.mount` unit ordered after
+`network-online.target`, so the share is mounted only once all interfaces are
+up — a down/unreachable NFS server can't break boot (with fstab it could).
+`enable --now` mounts it immediately too.
+
+**Recipes:**
+- **Mount the server's media share and keep it across reboots:**
+  ```bash
+  pos system nfs-client persist 100.100.100.1:/mnt/hdd /mnt/nfs/media
+  pos system nfs-client list
+  ```
+- **One-off mount (no persistence):**
+  `pos system nfs-client mount 10.0.0.5:/srv/data /mnt/data`
+
+**Troubleshooting:**
+- "mount.nfs not found" → `nfs-common` isn't installed; `sudo apt install nfs-common`
+- Mount hangs → check the server export (`pos system nfs-server list` on the
+  server) and that the client IP is allowed; `showmount -e <server>` lists
+  exports; NFS timeouts take ~2min by default, add `timeo=50,retrans=2` via the
+  unit if needed
+- Persistent mount fails at boot when the server is off → intended: the unit
+  waits for network-online and fails cleanly, and boot continues (unlike fstab);
+  `pos system nfs-client unpersist` removes it
+
+---
+
 ## Related

 - Reference: [DOC/POS.md → system](../POS.md)