From f148b5bd3a0e5c6bc73831863351d5388e94755a Mon Sep 17 00:00:00 2001
From: Bas Nijholt <bas@nijho.lt>
Date: Sun, 14 Dec 2025 17:24:46 -0800
Subject: [PATCH] docs: Add TrueNAS NFS root squash configuration guide

Explains how to set maproot_user/maproot_group to root/wheel
in TrueNAS to disable root squash, allowing Docker containers
running as root to write to NFS-mounted volumes.
---
 docs/truenas-nfs-root-squash.md | 65 +++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 docs/truenas-nfs-root-squash.md

diff --git a/docs/truenas-nfs-root-squash.md b/docs/truenas-nfs-root-squash.md
new file mode 100644
index 0000000..46b6635
--- /dev/null
+++ b/docs/truenas-nfs-root-squash.md
@@ -0,0 +1,65 @@
+# TrueNAS NFS: Disabling Root Squash
+
+When running Docker containers on NFS-mounted storage, containers that run as root will fail to write files unless root squash is disabled. This document explains the problem and solution.
+
+## The Problem
+
+By default, NFS uses "root squash" which maps the root user (UID 0) on clients to `nobody` on the server. This is a security feature to prevent remote root users from having root access to the NFS server's files.
+
+However, many Docker containers run as root internally. When these containers try to write to NFS-mounted volumes, the writes fail with "Permission denied" because the NFS server sees them as `nobody`, not `root`.
+
+Example error in container logs:
+```
+System.UnauthorizedAccessException: Access to the path '/data' is denied.
+Error: EACCES: permission denied, mkdir '/app/data'
+```
+
+## The Solution
+
+In TrueNAS, configure the NFS share to map remote root to local root:
+
+### TrueNAS SCALE UI
+
+1. Go to **Shares → NFS**
+2. Edit your share
+3. Under **Advanced Options**:
+   - **Maproot User**: `root`
+   - **Maproot Group**: `wheel`
+4. Save
+
+### Result in /etc/exports
+
+```
+"/mnt/pool/data"\
+    192.168.1.25(sec=sys,rw,no_root_squash,no_subtree_check)\
+    192.168.1.26(sec=sys,rw,no_root_squash,no_subtree_check)
+```
+
+The `no_root_squash` option means remote root is treated as root on the server.
+
+## Why `wheel`?
+
+On FreeBSD/TrueNAS, the root user's primary group is `wheel` (GID 0), not `root` like on Linux. So `root:wheel` = `0:0`.
+
+## Security Considerations
+
+Disabling root squash means any machine that can mount the NFS share has full root access to those files. This is acceptable when:
+
+- The NFS clients are on a trusted private network
+- Only known hosts (by IP) are allowed to mount the share
+- The data isn't security-critical
+
+For home lab setups with Docker containers, this is typically fine.
+
+## Alternative: Run Containers as Non-Root
+
+If you prefer to keep root squash enabled, you can run containers as a non-root user:
+
+1. **LinuxServer.io images**: Set `PUID=1000` and `PGID=1000` environment variables
+2. **Other images**: Add `user: "1000:1000"` to the compose service
+
+However, not all containers support running as non-root (they may need to bind to privileged ports, create system directories, etc.).
+
+## Tested On
+
+- TrueNAS SCALE 24.10