Clarify Permissions for Custom Volumes on TrueNAS SCALE

[shaddowlink]

Hi, thanks for the great work on docker-mailserver!

I'm running docker-mailserver as a custom app on TrueNAS SCALE, using two separate ZFS datasets, permissions managed by ACL:

1. /mnt/Wonderpool/mail → mounted as /var/mail
2. /mnt/Wonderpool/appData/docker-mailserver → mounted as /tmp/docker-mailserver (for config, logs, mail-state)

During setup, I didn't pay attention to permissions and gave broad access to all users and just ran with it. Afterward I wanted to clean up and set the Owner and Group to vmail (UID 5000) for both mounts and only gave my TrueNAS admin user (not root) access via ACL aswell. This was based on the assumption that:

• All mail files are owned by vmail after being processed.
• The documentation references vmail as the user running most services in the container.

For other Containers this strategy worked for me. When I usually struggle with permission problems the container wont even execute properly and throw alot of errors. Here everything seems fine, and the docker mailserver starts without error, The logs show it’s reading my config properly and processing mail normally, but no mail ends up in /var/mail unless I allow everyone write access. It took me quite a while to find these errors in my log, so I assume they are related to Postfix when everyone is not allowed write access. Once I allow everyone write access, the errors disappear, and I find new mail in /var/mail.

The error I’m seeing in the logs is:

fatal: scan_dir_push: open directory defer: Permission denied
fatal: Postfix integrity check failed!

Questions:

• Which users, besides vmail, and what permissions do I need to set for /var/mail, /tmp/docker-mailserver, /var/log/mail, and /var/mail-state? It seems to break when I only give vmail (5000) these permissions.
• Does Postfix possibly run as a different user, requiring specific permissions for certain directories?

I'm still learning and might be overlooking something obvious, but I'm really enjoying experimenting with my Homelab and learning from it.

Thanks!
shaddowlink

[polarathene]

For the /var/mail-state volume we try to ensure correct permissions are handled here:

docker-mailserver/target/scripts/startup/setup.d/mail_state.sh

Lines 93 to 138 in 2079841

	# These corrections are to fix changes to UID/GID values between upgrades,
	# or when ownership/permissions were altered externally on the host (eg: migration or system scripts)
	function _setup_adjust_state_permissions() {
	[[ ! -d ${DMS_STATE_DIR} ]] && return 0
	# Parent directories must have executable bit set to descend the file tree for access,
	# as each service running as a non-root user requires this to access their state directory,
	# `/var/mail-state` must allow all users `+x`:
	chmod +x "${DMS_STATE_DIR}"
	# This ensures the user and group of the files from the external mount have their
	# numeric ID values in sync. New releases where the installed packages order changes
	# can change the values in the Docker image, causing an ownership mismatch.
	# NOTE: More details about users and groups added during image builds are documented here:
	# https://github.com/docker-mailserver/docker-mailserver/pull/3011#issuecomment-1399120252
	_log 'trace' "Ensuring correct ownership + permissions for DMS state dir: '${DMS_STATE_DIR}'"
	[[ ${ENABLE_AMAVIS} -eq 1 ]] && chown -R amavis:amavis "${DMS_STATE_DIR}/lib-amavis"
	[[ ${ENABLE_CLAMAV} -eq 1 ]] && chown -R clamav:clamav "${DMS_STATE_DIR}/lib-clamav"
	[[ ${ENABLE_FETCHMAIL} -eq 1 ]] && chown -R fetchmail:nogroup "${DMS_STATE_DIR}/lib-fetchmail"
	[[ ${ENABLE_MTA_STS} -eq 1 ]] && chown -R _mta-sts:_mta-sts "${DMS_STATE_DIR}/lib-mta-sts"
	[[ ${ENABLE_POSTGREY} -eq 1 ]] && chown -R postgrey:postgrey "${DMS_STATE_DIR}/lib-postgrey"
	[[ ${ENABLE_RSPAMD} -eq 1 ]] && chown -R _rspamd:_rspamd "${DMS_STATE_DIR}/lib-rspamd"
	[[ ${ENABLE_RSPAMD_REDIS} -eq 1 ]] && chown -R redis:redis "${DMS_STATE_DIR}/lib-redis"
	[[ ${ENABLE_SPAMASSASSIN} -eq 1 ]] && chown -R debian-spamd:debian-spamd "${DMS_STATE_DIR}/lib-spamassassin"
	chown -R root:root "${DMS_STATE_DIR}/lib-logrotate"
	chown -R postfix:postfix "${DMS_STATE_DIR}/lib-postfix"
	# NOTE: The Postfix spool location has mixed owner/groups to take into account:
	# UID = postfix(101): active, bounce, corrupt, defer, deferred, flush, hold, incoming, maildrop, private, public, saved, trace
	# UID = root(0): dev, etc, lib, pid, usr
	# GID = postdrop(103): maildrop, public
	# GID for all other directories is root(0)
	# NOTE: `spool-postfix/private/` will be set to `postfix:postfix` when Postfix starts / restarts
	# Set most common ownership:
	chown -R postfix:root "${DMS_STATE_DIR}/spool-postfix"
	chown root:root "${DMS_STATE_DIR}/spool-postfix"
	# These two require the postdrop(103) group:
	chgrp -R postdrop "${DMS_STATE_DIR}"/spool-postfix/{maildrop,public}
	# These permissions rely on the `postdrop` binary having the SGID bit set.
	# Ref: https://github.com/docker-mailserver/docker-mailserver/pull/3625
	chmod 730 "${DMS_STATE_DIR}/spool-postfix/maildrop"
	chmod 710 "${DMS_STATE_DIR}/spool-postfix/public"
	}

There's various other changes throughout where you'll probably have to search the project source for chmod/chown and similar commands, but another common location is here:

docker-mailserver/target/scripts/startup/setup-stack.sh

Lines 85 to 114 in 2079841

	# Misc checks and fixes migrated here until next refactor:
	# NOTE: `start-mailserver.sh` runs this along with `mail-state.sh` during container restarts
	function _setup_directory_and_file_permissions() {
	_log 'trace' 'Removing leftover PID files from a stop/start'
	find /var/run/ -not -name 'supervisord.pid' -name '*.pid' -delete
	touch /dev/shm/supervisor.sock
	_log 'debug' 'Checking /var/mail permissions'
	if ! _chown_var_mail_if_necessary; then
	_dms_panic__general 'Failed to fix /var/mail permissions'
	fi
	_log 'debug' 'Removing files and directories from older versions'
	rm -rf /var/mail-state/spool-postfix/{dev,etc,lib,pid,usr,private/auth}
	_rspamd_get_envs
	# /tmp/docker-mailserver/rspamd/dkim
	if [[ -d ${RSPAMD_DMS_DKIM_D} ]]; then
	_log 'debug' "Ensuring '${RSPAMD_DMS_DKIM_D}' is owned by '_rspamd:_rspamd'"
	chown -R _rspamd:_rspamd "${RSPAMD_DMS_DKIM_D}"
	fi
	# Parent directories must have the executable bit set to descend the file tree for access,
	# as each service in the container running as a non-root user requires this to access any subpath,
	# `/tmp/docker-mailserver` must allow all users `+x` (notably required for `_rspamd` user read access):
	local DMS_CONFIG_DIR=/tmp/docker-mailserver
	chmod +x "${DMS_CONFIG_DIR}"
	__log_fixes
	}

One of the function calls there is for /var/mail, and is located here:

docker-mailserver/target/scripts/helpers/utils.sh

Lines 69 to 81 in 2079841

	# TODO: `chown -R 5000:5000 /var/mail` has existed since the projects first commit.
	# It later received a depth guard to apply the fix only when it's relevant for a dir.
	# Assess if this still appropriate, it appears to be problematic for some LDAP users.
	#
	# `helpers/accounts.sh:_create_accounts` (mkdir, cp) appears to be the only writer to
	# /var/mail folders (used during startup and change detection handling).
	function _chown_var_mail_if_necessary() {
	# fix permissions, but skip this if 3 levels deep the user id is already set
	if find /var/mail -maxdepth 3 -a \( \! -user "${DMS_VMAIL_UID}" -o \! -group "${DMS_VMAIL_GID}" \) | read -r; then
	_log 'trace' 'Fixing /var/mail permissions'
	chown -R "${DMS_VMAIL_UID}:${DMS_VMAIL_GID}" /var/mail || return 1
	fi
	}

Similar for /var/log:

docker-mailserver/target/scripts/startup/setup-stack.sh

Lines 127 to 154 in 2079841

	function __log_fixes() {
	_log 'debug' 'Ensuring /var/log/mail ownership + permissions are correct'
	# File/folder permissions are fine when using docker volumes, but may be wrong
	# when file system folders are mounted into the container.
	# Set the expected values and create missing folders/files just in case.
	mkdir -p /var/log/{mail,supervisor}
	# TODO: Remove these lines in a future release once concerns are resolved:
	# https://github.com/docker-mailserver/docker-mailserver/pull/4370#issuecomment-2661762043
	chown syslog:root /var/log/mail
	if [[ ${ENABLE_CLAMAV} -eq 1 ]]; then
	# TODO: Consider assigning /var/log/mail a writable non-root group for other processes like ClamAV?
	# - Check if ClamAV is capable of creating files itself when they're missing?
	# - Alternatively a symlink to /var/log/mail from the original intended location would allow write access
	# as a user to the symlink location, while keeping ownership as root at /var/log/mail
	# - `LogSyslog false` for clamd.conf + freshclam.conf could possibly be enabled instead of log files?
	# However without better filtering in place (once Vector is adopted), this should be avoided.
	touch /var/log/mail/{clamav,freshclam}.log
	chown clamav:adm /var/log/mail/{clamav,freshclam}.log
	fi
	# Volume permissions should be corrected:
	# https://github.com/docker-mailserver/docker-mailserver-helm/issues/137
	chmod 755 /var/log/mail/
	find /var/log/mail/ -type f -exec chmod 640 {} +
	}

---

It's not quite the straight-forward answer you'd like, but I don't have a convenient answer to offer beyond the above references 😓

We have had a variety of issues / discussions opened where there have been problems that are difficult for us to reproduce and turned out to be due to remote storage use or NAS users (especially those with outdated or heavily patched kernels).

Generally the container operates as the root user and assumes it has the authority to make whatever changes/corrections are needed. Some users with NFS/SMB mounts I think ran into issues as the container root user lacked the permission to do certain operations IIRC. One of the recent ones for example worked around an issue by keeping /var/mail-state local/internal instead.

Beyond this information not much is documented as our affected users tend to take whatever solutions work at the time and not contribute back for other users in the same boat 😅

[shaddowlink]

Thanks a lot for your detailed reply and for taking the time!

I spent weeks of my free time roleplaying as sysadmin@home, messing around with this stuff, and honestly, I just couldn’t get it to work right. I took all the info you shared and what I found online(which helped me learn a ton), but every time it seemed to work, random permission issues would pop up and I’d have to start over.
Don’t even ask about all the things I tried…

So in the end, I made an Ubuntu LXC inside TrueNAS, mounted my appdata dataset as shared storage, stripped off all the ACLs, and set it back to basic Linux (POSIX) permissions. Then I moved my whole Docker stack over to the LXC—and now it finally works. What a ride, haha.

It’s a bit of a compromise for now. I gave up on the “perfect” setup and just wanted something stable that I can rely on day-to-day. The cool thing is, I can still do snapshot backups in TrueNAS, and power/resource usage is still super efficient with good performance—honestly, little to no difference. Not perfect, but it works!

Still need to do some fine-tuning (filters and all that), but for now I’m honestly really happy. And I’m definitely gonna keep experimenting in the future.