Container User and Group Mapping Checklist for NAS Shares
The safe approach is to treat a numeric-identity mapping check from NAS export through host mount to the running container process as a sequence of observable gates, not a single command.
On a Linux container host using SMB or NFS-backed NAS shares, the practical risk is a container can see a NAS-mounted path but reads or writes fail with permission errors. Record the current identity and recovery point, start with the least invasive discriminator, interpret pass and fail results before changing another variable, and stop when storage becomes unstable or the only recoverable copy would be exposed. The workflow below ends only after the original workload succeeds or the evidence reaches an escalation boundary.
Identify the actual container process identity
Inspect the image documentation, Compose user setting, environment variables, entrypoint behavior, and the UID, GID, and supplemental groups of the running application process. Variables named PUID and PGID are image conventions, not universal Docker features, so confirm that this image supports them.
A LinuxServer community case about container PUID and PGID permission case demonstrates that apparently correct PUID and PGID values can still leave a bind mount inaccessible. Use the case as a reminder to inspect the running process and mount, not as evidence that every image implements the same initialization logic.
Record numeric values with id inside the container and on the host. Stop if the application runs as root only because permissions previously failed; root access hides the mapping defect and increases the impact of a compromised service.
Trace ownership from the NAS to the host mount
On the NAS, inspect numeric owner, group, mode, ACL, and default ACL for the target directory. On the container host, inspect the same mounted objects and compare numeric values. If names differ but numbers match, the labels are cosmetic; if numbers differ, the authorization path is genuinely different.
For NFS, include export options, NFS version, id mapping, root squashing, and client mount identity. For SMB, include the mount credential, server-side mapped identity, uid or gid presentation options, and whether Unix extensions or ACL translation are in use.
Do not change both server ACLs and client mount options together. The stage passes when one test file has a known numeric owner and the host sees a stable mapping after unmount, remount, and reboot.
Test the bind mount and supplemental groups
Confirm the container source path is the expected host mount rather than an empty local directory created before the network share mounted. Inspect the runtime mount, then test list, read, create, rename, and delete as the application user in a disposable subdirectory.
A Server Fault case documents NFS ACL permission mismatch even when owner and ACL entries appear aligned, illustrating why the ACL mask, server mapping, and effective identity all need inspection. Capture getfacl on both the directory and the created file.
If group access is intended, add the supported supplemental numeric group and recreate the container because process groups are fixed at start. Use the ZimaSpace guide on container empty path diagnosis when the application starts against an empty path; that is a mount-order problem, not an ACL problem.
Apply the narrowest identity fix and retest
Prefer aligning the applicationโs supported UID, GID, or supplemental group with the NAS policy. Use a shared group and inherited ACL where multiple services collaborate. Avoid world-writable permissions, recursive ownership changes across unrelated datasets, and privileged containers as shortcuts.
Recreate the container, remount the share if mapping options changed, and repeat the same operations. Restart the host once to verify mount ordering and numeric identity survive boot. Confirm that newly created files remain writable to intended human clients without giving the container unnecessary rights.
Close the checklist when the app passes its original workload, denied operations remain denied, and ownership stays stable across restart. Escalate if user namespaces, rootless mappings, or NAS identity services rewrite IDs in a way the chosen image cannot support.
Recommended products
Support & Tips
More to Read
NFS Migration Checklist for Renamed Datasets and Stable File Handles
Assume file handles may change when storage identity changes. Quiesce clients, cut over the export deliberately, remount, and verify open and new files.
SMB Client Troubleshooting Guide for Windows, macOS, and Linux
Use the same server, account, share, and file operation on each client so discovery, credentials, policy, and storage faults do not get mixed together.
Home Server Secret Rotation Checklist for Apps, Databases, and Backups
Treat rotation as a dependency migration: map every consumer, overlap credentials where possible, verify the new value, then revoke and test recovery.
