[Enterprise][Data protection] Native account backups omit mail and user_dir storage is internally broken

[Stonemage]

Category: Bug — OpenCLI/OS, Enterprise email storage and native backups

OpenPanel version affected

OpenPanel Enterprise 1.7.66

OpenCLI upstream commit installed:

55b335bed876350302f693219002618d303365bd

Operating system

Rocky Linux 9.7, kernel 5.14.0-611.24.1.el9_7.x86_64, Docker 29.2.1.

Severity

High — data protection and restore integrity.

This is not a duplicate of #249. That 2024 issue predates the current native
backup, restore and user_dir implementation and requested email backup as a
new feature. This report documents defects in functionality that is now present
and exposed to Enterprise administrators.

We are a paying OpenPanel Enterprise customer. The current implementation can
give administrators the appearance that account mail is included in native
account backups because every backup archive has a /backup/mail source, while
the live OpenMail service is writing somewhere else and the account mail_data
volumes are empty.

Our production audit found approximately 125 GiB and 1.55 million live Maildir
files outside the native account-backup scope. All 38 instantiated account
mail_data volumes contained zero files. No customer domains, addresses,
credentials or message data are included in this report.

We are not asking the community to design a new backup system. OpenPanel already
exposes per-user email storage, creates per-account mail_data volumes, mounts
those volumes into the native backup service and restores native mail archives
back into them. The existing feature needs to be made internally consistent and
supported end-to-end.

Current architecture observed

With the documented default:

email_storage_location=/var/mail/

OpenMail mounts the host's shared mail path at /var/mail, and Dovecot uses:

/var/mail/<domain>/<mailbox>

Every account's native backup service separately mounts:

mail_data:/backup/mail:ro

Those are different storage objects. Nothing writes or synchronizes live mail
into the account mail_data volumes, so native backups contain an empty mail
section.

OpenAdmin also offers email_storage_location=user_dir, labelled “docker volume
(legacy)”. That is the mode that should align live mail with the account
mail_data volume. However, current upstream components disagree about its path
and contain implementation errors that prevent it being relied upon.

Public source evidence

1. The native account backup expects mail_data

The account Compose template archives the account named volume:

https://github.com/stefanpejcic/openpanel-configuration/blob/717e519674c9b2580204e87abcef3d258dfc50cd/docker/compose/1.0/docker-compose.yml#L805-L824

The same template defines it as storage for /var/mail:

https://github.com/stefanpejcic/openpanel-configuration/blob/717e519674c9b2580204e87abcef3d258dfc50cd/docker/compose/1.0/docker-compose.yml#L859-L879

2. OpenAdmin documentation says user_dir means the account Docker volume

The current administrator documentation says per-user mail is stored below:

/home/<username>/docker-data/volumes/<username>_mail_data/_data/

OpenPanel/website/docs/admin/emails/settings.md

Lines 39 to 48 in bc78a36

	## Storage
	Configure where email data (mailboxes) is stored on disk.
	- **Email storage location** – Choose between:
	- **docker volume (legacy)** – emails are stored in each user's home directory, e.g. `/home/<username>/docket-data/volumes/<username>_mail_data/_data/<domain>/<email>/`. This is **not recommended**, since adding or removing a domain will require the mail server to restart.
	- **custom path** – store all mailboxes under a single custom path on the host, e.g. `/var/mail/`.
	- **Custom path** – Only shown when *custom path* is selected. Example values: `/var/mail/`, `/email`, `/storage`.
	The storage location is locked (cannot be changed) once email accounts already exist. Click **Save Storage** to apply the change.

3. admin.ini documents a different user_dir path

The shipped configuration instead documents:

/home/USERNAME/mail/DOMAIN/

https://github.com/stefanpejcic/openpanel-configuration/blob/717e519674c9b2580204e87abcef3d258dfc50cd/openadmin/config/admin.ini#L23-L28

4. Mailserver mount generation skips valid owners

In email/server.sh, a non-empty owner enters the branch that reports “No user”
and skips the domain. The alternate branch then uses an empty owner. It also
targets /home/$USERNAME/mail/$DOMAIN, not the mail_data volume used by native
backup and restore.

https://github.com/stefanpejcic/opencli/blob/55b335bed876350302f693219002618d303365bd/email/server.sh#L348-L396

5. email/quotas.sh cannot correctly enumerate or repair user_dir

The current script:

• assigns /home/*/mail/ to a scalar and later quotes it;
• derives DOMAIN as basename(dirname(path)), which produces mail for a
  /home/<account>/mail/<domain> path;
• parses owner output after passing it through the timestamping logger;
• uses USER_ID=(id -u $CONTEXT) rather than command substitution;
• leaves the only mail_data path rewrite commented out;
• recursively changes ownership without a check/dry-run mode.

https://github.com/stefanpejcic/opencli/blob/55b335bed876350302f693219002618d303365bd/email/quotas.sh#L52-L93

This script is named “quotas” but its active behavior is recursive ownership
repair. It needs a safe, deterministic account/domain resolver and a report-only
mode.

6. Mailbox setup calculates one UID and uses different undefined variables

email/setup.sh calculates OP_UID, then the asynchronous chown references
UID_OVERRIDE, DOMAIN and USER, none of which are set by that function.

https://github.com/stefanpejcic/opencli/blob/55b335bed876350302f693219002618d303365bd/email/setup.sh#L62-L105

7. Domain add uses a third path interpretation

Domain creation mounts /home/$context/mail/$domain_name rather than the
account mail_data volume documented by OpenAdmin and consumed by native
backup/restore.

OpenPanel/opencli/domains/add.sh

Lines 837 to 870 in 220cdb7

	create_mail_mountpoint() {
	[[ -n "$ENTERPRISE" ]] || return
	local compose_file="/usr/local/mail/openmail/compose.yml"
	[[ -f "$compose_file" ]] || return
	local store_in
	store_in=$(grep -E '^email_storage_location=' /etc/openpanel/openadmin/config/admin.ini 2>/dev/null | cut -d'=' -f2- | xargs)
	local volume_to_add
	if [[ "$store_in" == /* ]]; then
	log "Using $store_in for email storage"
	mkdir -p "$store_in"
	volume_to_add=" - $store_in:/var/mail/"
	else
	local domain_dir="/home/$context/mail/$domain_name/"
	log "Creating $domain_dir for emails"
	mkdir -p "$domain_dir"
	volume_to_add=" - $domain_dir:/var/mail/$domain_name/"
	fi
	if grep -qF "$volume_to_add" "$compose_file"; then
	return
	fi
	sed -i "/^ mailserver:/,/^ roundcube:/ {
	/^ volumes:/a\\
	$volume_to_add
	}" "$compose_file"
	log "Reconfiguring mailserver in background"
	nohup sh -c "cd /usr/local/mail/openmail/ && docker-compose up -d --force-recreate mailserver" </dev/null >nohup.out 2>nohup.err &
	disown
	}

8. Domain delete assumes the /home/$user/mail model

The delete path independently constructs and removes a
/home/$user/mail/$domain_name mount. It does not first establish the canonical
storage resolver used when the mount was created.

OpenPanel/opencli/domains/delete.sh

Lines 322 to 349 in 220cdb7

	# add mountpoint and reload mailserver
	# todo: need better solution!
	delete_mail_mountpoint(){
	if [ -n "$key_value" ]; then
	DOMAIN_DIR="/home/$user/mail/$domain_name/"
	COMPOSE_FILE="/usr/local/mail/openmail/compose.yml"
	mount_path="/var/mail/$domain_name/"
	volume_to_remove="$DOMAIN_DIR:$mount_path"
	if [ -f "$COMPOSE_FILE" ]; then
	log "Removign volume: $volume_to_remove from mailserver"
	# Escape slashes for sed
	escaped_volume=$(printf '%s\n' " - $volume_to_remove" | sed 's/[\/&]/\\&/g')
	# Remove the exact volume line if it exists in the mailserver service block
	sed -i "/^ mailserver:/,/^[^[:space:]]/ {
	/^ volumes:/,/^[^[:space:]]/ {
	/^\s*- $escaped_volume/d
	}
	}" "$COMPOSE_FILE"
	log "Reloading mailserver to apply changes"
	(cd /usr/local/mail/openmail/ && docker-compose up -d --force-recreate mailserver) > /dev/null 2>&1 & disown
	fi
	fi
	}

9. Storage changes are locked after mailboxes exist

OpenAdmin correctly prevents changing storage mode once accounts exist:

https://github.com/stefanpejcic/openadmin/blob/04fd0f2c815f6d67a635505bd41bdd1132db50de/internal/handlers/emails.go#L267-L296

That protects data, but it means an existing paid customer has no supported path
from the default shared store into repaired per-account storage. Fixing new
installs alone will not resolve existing estates.

Installed Enterprise user-interface findings

These components are in the licensed OpenPanel user image rather than the public
repository. We are describing the observed implementation and required behavior,
not redistributing source.

Sieve/filter path

The OpenPanel 1.7.66 image initializes its base mail path directly from
email_storage_location. The filter resolver appends
<domain>/<mailbox>/home/.dovecot.sieve to that value. When the configured value
is the token user_dir, the application treats user_dir as a literal relative
filesystem directory instead of resolving the current account's mail volume.

Consequently, even if OpenMail mount generation were fixed, the user-facing
Emails → Filters page would not automatically read and write the Maildir used by
Dovecot.

Native restore metadata

The installed native restore maps backup/mail back into:

/home/<context>/docker-data/volumes/<context>_mail_data/_data

This confirms the intended relationship between user_dir, mail_data and
native backups. However, the extraction path writes regular-file contents and
does not preserve complete Maildir directory metadata, numeric UID/GID, ACLs or
xattrs. A successful extraction is not sufficient unless the restored mailbox
is immediately usable by Dovecot without manual ownership repair.

Required use cases

UC1 — New account using per-user mail storage

Given email_storage_location=user_dir is selected before any mailbox exists,
when an administrator creates two independent OpenPanel accounts and assigns a
mail domain to each, then OpenMail must mount each domain from that owning
account's mail_data volume.

No domain may be skipped when domains-whoowns returns a valid owner/context.

UC2 — Mail delivery and IMAP

When a message is delivered through Postfix/LMTP, its Maildir files must be
created in the owning account's volume and be immediately readable through IMAP
and webmail after OpenMail restart and host reboot.

UC3 — Account isolation

An account's mail volume, native archive, restore operation and filter UI must
never expose another account's domain or messages.

Test with at least two accounts, multiple domains on one account, and distinct
numeric UIDs.

UC4 — Native account backup

When native backup runs for an account with active mailboxes, /backup/mail
must contain that account's domains and messages. The backup must fail or warn
prominently if the account owns mailboxes but the mail source is empty or not
mounted.

UC5 — Native account restore

Restoring the archive into a clean account must preserve or deliberately and
correctly normalize Maildir ownership, group, modes and required metadata.

After restore, the following must work without manual chown:

• Dovecot authentication;
• IMAP folder/message enumeration;
• LMTP delivery of a new message;
• Sieve execution;
• subsequent native backup.

UC6 — Quota and ownership reconciliation

opencli email-quotas must enumerate exact accounts, contexts, domains and
mailboxes without wildcard ambiguity. It must provide a non-mutating check mode
that reports proposed UID/GID and path changes before recursive repair.

Unresolved owners or missing volumes must produce a non-zero result and must not
fall back to modifying an unintended path.

UC7 — OpenPanel Sieve filters

Emails → Filters must resolve the current account's actual Maildir for both
storage modes:

• absolute shared/custom path;
• user_dir/account mail_data volume.

The same .dovecot.sieve file must be visible to OpenPanel and active in
Dovecot.

UC8 — Domain lifecycle

Adding, deleting, transferring or renaming a domain must update only its exact
OpenMail mount. Re-running reconciliation must be idempotent and must not create
duplicate Compose entries.

OpenMail must refuse to start if a configured domain source is unexpectedly
missing, rather than silently writing into an empty or incorrect path.

UC9 — Account lifecycle

Account suspend, rename, transfer, backup, restore and delete must consistently
use the same context/volume resolver. Display username and operating-system
context must not be assumed to be interchangeable.

UC10 — Existing /var/mail customers

Provide a supported migration workflow for installations that already have
mailboxes and are therefore locked to /var/mail.

The workflow must include:

• preflight ownership/domain manifest;
• required free-space calculation;
• dry run;
• initial live copy plus quiesced final delta;
• mount/config validation before OpenMail restarts;
• per-domain/account progress and restartability;
• source retention and rollback;
• verification that the first native account backup contains restorable mail.

Changing the setting alone must remain prohibited; data must never be moved
implicitly by a UI toggle.

UC11 — Shared/custom-path behavior remains honest

If an administrator deliberately retains /var/mail or another absolute shared
path, native account backup must not silently present an empty mail section as
mail protection. OpenPanel must either:

1. support ownership-scoped mail inclusion from the shared path; or
2. clearly state that native account backup excludes mail in this mode and
   provide a supported mail backup/restore mechanism.

Sanitized reproduction on a fresh Enterprise test VM

1. Install OpenPanel Enterprise 1.7.66 on a supported OS.
2. Before creating mailboxes, select docker volume (legacy) / user_dir in
   OpenAdmin → Emails → Settings.
3. Create accounts alpha and beta with different OS contexts.
4. Add alpha.example and beta.example.
5. Add two mailboxes to each account and one Sieve filter.
6. Start or reconcile OpenMail.
7. Inspect the generated mailserver Compose mounts.
8. Deliver one message to each mailbox and verify with IMAP.
9. Inspect both account mail_data volumes.
10. Run opencli email-quotas first in the requested check mode, then repair.
11. Run native backup for both accounts and inspect /backup/mail members.
12. Restore alpha into a fresh account and repeat IMAP, Sieve and delivery
    checks.
13. Add/delete a second domain, restart OpenMail and reboot the host.
14. Confirm no alpha operation reads, changes, archives or restores beta
    data.

Expected result

• user_dir has one documented and implemented storage contract.
• Live mail is physically stored in the owning account's mail_data volume.
• Native account backup contains only that account's mail.
• Native restore produces a working mailbox with correct ownership/metadata.
• Quota repair is deterministic, inspectable and safe.
• Filters resolve the same Maildir as Dovecot.
• Domain/account lifecycle operations are idempotent and isolated.
• Existing absolute-path installations are not changed or misrepresented.
• A supported migration path exists for locked existing estates.

Actual result

• OpenMail, OpenAdmin documentation, admin.ini, domain lifecycle scripts,
  quota repair, native backup and native restore disagree about the storage
  location.
• Valid owners are skipped by mailserver mount generation.
• Quota/ownership repair cannot reliably enumerate user_dir domains and
  constructs the UID incorrectly.
• Mailbox setup uses undefined variables for ownership repair.
• OpenPanel's filter resolver treats user_dir as a literal path.
• Native backup archives an account mail_data volume that the default live
  mailserver never writes to.
• Existing customers cannot change storage mode because the UI correctly locks
  it after mailbox creation, but no supported migration workflow exists.

Acceptance criteria for vendor resolution

• OpenPanel documents one exact user_dir host path and container path.
• All affected components use one canonical owner/context/storage resolver.
• Valid owners are not skipped during OpenMail mount generation.
• Missing owners or volumes fail closed with actionable errors.
• email-quotas has a non-mutating check mode and correct UID handling.
• Mailbox add/update uses the resolved account UID and mailbox path.
• Domain add/delete/rename/transfer are idempotent.
• OpenPanel Filters operates against the active Dovecot Maildir.
• Native backup detects active mailboxes with an empty/unmounted mail source.
• Native restore preserves or correctly normalizes Maildir metadata.
• Two-account isolation test passes.
• Delivery, IMAP, Sieve, backup and isolated restore tests pass.
• Restart, host reboot and OpenPanel/OpenCLI update tests pass.
• Absolute custom-path behavior has regression coverage.
• Existing customers receive a documented, reversible migration procedure.

Requested vendor response

Please confirm:

1. Whether user_dir is currently considered a supported Enterprise feature.
2. Whether its canonical target is the account mail_data volume, as indicated
   by the backup, restore and administrator UI.
3. Which supported release will repair the cross-component implementation.
4. What supported migration path will be provided for existing locked
   /var/mail estates.
5. How administrators should protect and restore mail in the meantime without
   receiving a false impression from the empty native /backup/mail source.

We can provide additional sanitized command output from the affected paid
installation if required, but we will not publish customer identifiers,
credentials, password hashes or message content.

[stefanpejcic]

from what I can see, you are reporting 2 issues:

• that mail_data volume has no data per user when user_data configuration is set for storage
• that by default /var/mail/ is used which results in those per-user backups not contain emails

For the first one, you can just symlink /home/$USERNAME/mail/ to /home/$USERNAME/docker-data/volumes/${USERNAME}_mail_data/_data/ so that data is present in mail volume.

For the existing setting, s GUI and docs state, this can not be changed after creating email accounts. But you can still manually copy the emails in per-user folder, then change the configuration to use it and just restart mailservice.

To answer the questions:

Whether user_dir is currently considered a supported Enterprise feature.

Yes, you can switch to user_data on Enterprise.

Whether its canonical target is the account mail_data volume, as indicated by the backup, restore and administrator UI.

No, its using /home/$USERNAME/mail/`

Which supported release will repair the cross-component implementation.

What do you mean exactly? To symlink /home/$USERNAME/mail/ to /home/$USERNAME/docker-data/volumes/${USERNAME}_mail_data/_data/ for each user? if so, that is a 1-min bash script, I can add that right away in 1.7.67

What supported migration path will be provided for existing locked /var/mail estates.

No migration plan - this is documented that should be set when you setup the mailserver - we can't enforce a location for existing installations. If you do want to move to per-user home dir, its as easy as just

But you can still manually copy the emails in per-user folder, then change the configuration to use it and just restart mailservice.

If you are an Enterprise user, message support and we are happy to plan this.

How administrators should protect and restore mail in the meantime without receiving a false impression from the empty native /backup/mail source.

Currently only from terminal by backing up the fodler and restoring.

[stefanpejcic]

this is now added tho the upcoming update:

• for existing domains it will create symlinks so mailboxes can be perserved in the mail volume backup: https://github.com/stefanpejcic/OpenPanel/blob/main/version/1.7.67/UPDATE.sh
• for new domains it's handled on domain add/delete:
• • stefanpejcic/opencli@62c984f
• • stefanpejcic/opencli@d742640

---

you dont need ot wait for the update, you can patch immediately with:

bash <(curl -sSL https://raw.githubusercontent.com/stefanpejcic/OpenPanel/refs/heads/main/version/1.7.67/UPDATE.sh) && opencli update --cli

hope that resolves everything listed in this discussion - if not, feel free to re-open it