Backup & Recovery / Services & Applications

Back up and restore Dovecot mailboxes and metadata

Inventory storage and identity backends, create application-consistent copies, protect indexes and Sieve data, encrypt offsite, restore one user, and verify IMAP state.

90 min8 stepsChanges system stateRevision 2

Save or explore

#dovecot #backup #restore #maildir #dsync

0 of 8 steps completed

Goal

Recover mailbox content and required metadata without assuming a filesystem copy is sufficient.

Supported environments

Dovecot CE 2.4

Prerequisites

Authoritative DNS and stable identity Control forward and reverse DNS, choose the canonical mail hostname and domains, and verify the host is not behind an outbound SMTP-blocking network.hostname -f; getent ahosts $(hostname -f); dig +short -x {{publicIp}}
Recovery and queue safety Keep console access, back up active configuration, and record queue state before changing routing, authentication, filters, or mailbox delivery.
Abuse and deliverability plan Define relay boundaries, account owners, rate limits, bounce handling, postmaster address, monitoring, and how compromised credentials will be revoked.

Operating boundary

OneLiners never runs these steps or stores secrets. Review placeholders, versions, current state, and change-control requirements before using a command.

Full guide

What you will build

System

A production Dovecot implementation of “Back up and restore Dovecot mailboxes and metadata” with explicit SMTP/IMAP boundaries, identity, durable state and observable delivery evidence.
A read-only baseline, staged candidate and end-to-end canary covering DNS, TLS, authentication, recipient or route policy, queue/mailbox state and logs.
A security and rollback procedure that avoids open relay, backscatter, plaintext credentials, world-readable keys/mail and unreviewed bulk queue actions.

Observable outcome

Recover mailbox content and required metadata without assuming a filesystem copy is sufficient. The intended success path is visible in native status, protocol transcript, headers or mailbox evidence.
Expected unauthorized relay, unknown-recipient, wrong-sender, invalid-authentication or wrong-certificate tests fail at the declared boundary without harming unrelated mail.

Architecture

How the parts fit together

Mailbox content, Dovecot indexes/metadata, user identity mappings, quotas, configuration and encryption material have different consistency and confidentiality requirements. Delivery is quiesced or captured with supported synchronization, files are archived with ownership and checksums, and sensitive artifacts are encrypted off-host. Restoration occurs under a different test identity/path first, followed by force-resync and IMAP/message checks before production data is touched.

Mailbox snapshotCaptures messages with ownership and consistency.

Identity/config metadataPreserves mappings, quotas and settings needed to interpret mailboxes.

Encryption/off-host storageProtects sensitive correspondence and survives host loss.

Isolated restore/resyncProves content, indexes, permissions and IMAP usability.

Inventory hostname/DNS, listeners, certificates, identities, recipient/relay maps, queue/mailbox state, logs and a recoverable configuration/data baseline.
Prepare the backup candidate with official Dovecot syntax, protected secrets and one explicit service/data boundary at a time.
Run native configuration validation and immediate read-only checkpoint before reload or acceptance of new messages.
Use controlled local and external canaries plus an expected-denial test, preserve message identifiers/headers, and retain the prior configuration for rollback.

Assumptions

The public mail hostname, forward/reverse DNS ownership, supported package version and responsibility for ports 25/587/993 are known.
A maintenance or canary window, console recovery and current protected backup of configuration, keys, identity mappings and relevant mailbox/queue data exist.
Test sender and recipient addresses are owned by the operator; no unsolicited or third-party traffic is generated during verification.
Secrets and private keys are delivered outside shell history and have narrowly defined service ownership and rotation plans.

Key concepts

envelope identity: SMTP sender and recipient used for routing, delivery status and SPF; it is distinct from visible message headers.
open relay: An MTA that accepts unauthorized third-party sender-to-recipient forwarding, enabling abuse and reputation damage.
backscatter: A later non-delivery report sent to a forged sender because an invalid recipient was accepted instead of rejected during SMTP.
alignment: DMARC relationship between visible From domain and authenticated SPF or DKIM domain.
Maildir: A mailbox format storing messages as individual files in cur/new/tmp directories with strict ownership.

Before you copy

Values used in this guide

{{ageRecipientsFile}}

Operator-reviewed value used by this tutorial for ageRecipientsFile; derive it from the target environment and never from untrusted request data.

Example: /etc/mail-backup/age-recipients.txt

{{archive}}

Operator-reviewed value used by this tutorial for archive; derive it from the target environment and never from untrusted request data.

Example: /var/backups/mail/mailboxes-20260725T020000Z.tar.zst.age

{{backupRoot}}

Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.

Example: /var/backups/mail

{{identitySource}}

Operator-reviewed value used by this tutorial for identitySource; derive it from the target environment and never from untrusted request data.

Example: /etc/dovecot/users

{{mailRoot}}

Operator-reviewed value used by this tutorial for mailRoot; derive it from the target environment and never from untrusted request data.

Example: /srv/vmail

{{restoreReport}}

Operator-reviewed value used by this tutorial for restoreReport; derive it from the target environment and never from untrusted request data.

Example: example-restorereport

{{restoreSource}}

Operator-reviewed value used by this tutorial for restoreSource; derive it from the target environment and never from untrusted request data.

Example: /srv/mail-restore/mailboxes

{{restoreUser}}

Operator-reviewed value used by this tutorial for restoreUser; derive it from the target environment and never from untrusted request data.

Example: restore-alice@example.com

{{stamp}}

Operator-reviewed value used by this tutorial for stamp; derive it from the target environment and never from untrusted request data.

Example: 20260725T020000Z

{{testUser}}

Operator-reviewed value used by this tutorial for testUser; derive it from the target environment and never from untrusted request data.

Example: alice@example.com

Security and production boundaries

Never weaken relay/recipient checks, publish private DKIM/TLS keys, enable plaintext authentication, or expose web/IMAP administration broadly to make a test pass.
Mail content, credentials, queues, logs and backups contain personal or confidential data; restrict, encrypt, minimize and retain them under an explicit policy.
Use dedicated service identities and root-readable credential maps; verify logs and configuration output are redacted before sharing.

Stop before continuing if

Stop if a test permits unauthorized relay, accepts unknown recipients for later bounce, sends credentials without verified TLS, or exposes private keys/mailbox files.
Do not continue when hostname/PTR ownership, package/config version, recipient map, route, queue, mailbox ownership or rollback backup is ambiguous.
Immediately quarantine the candidate when unrelated mail is rerouted, deleted, multiply delivered, signed by the wrong domain, or inaccessible after reload.

instruction

Inventory mail, indexes, Sieve, quotas, and identity data

read-only

Record mail driver/path, userdb/passdb, control/index paths, subscriptions, ACLs, Sieve scripts, quota backend, size, and recovery objectives.

Why this step matters

Inventory mail, indexes, Sieve, quotas, and identity data is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Record mail driver/path, userdb/passdb, control/index paths, subscriptions, ACLs, Sieve scripts, quota backend, size, and recovery objectives. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

Capture the before-state and the exact output in the change record. If this step modifies a file or service, validate the candidate with its native checker before any reload; a successful process exit alone does not prove that the application uses the intended value.

Use a representative staging or canary host first. Repeat the stated checkpoint immediately, because proceeding with ambiguous evidence makes the later end-to-end verification and rollback materially harder.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Inventory mail, indexes, Sieve, quotas, and identity data”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveconf: Invokes the principal tool or configuration operation for “Inventory mail, indexes, Sieve, quotas, and identity data”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Mail Root{{mailRoot}}Operator-reviewed value used by this tutorial for mailRoot; derive it from the target environment and never from untrusted request data.

sudo doveconf -n > /root/doveconf-backup-baseline.txt; sudo doveadm user '*'; sudo du -sh {{mailRoot}}; df -h {{mailRoot}}

Example output / evidence

All state required for a usable mailbox is in backup scope.

Checkpoint: Checkpoint: Inventory mail, indexes, Sieve, quotas, and identity data

Continue whenAll state required for a usable mailbox is in backup scope. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

Stop whenStop before the next step when doveconf reports an error, the output differs materially from the example, an unexpected package/service/path is affected, or the required before-state and rollback artifact are missing.

If this step fails

The command for “Inventory mail, indexes, Sieve, quotas, and identity data” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v doveconf 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

ResolutionDo not improvise a privileged workaround. Re-read the environment and variable table, inspect the official source for the installed version, restore the candidate file if necessary, and repeat only this checkpoint.

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

instruction

Define a restricted backup identity and destination

read-only

Use a local root-controlled job or a dedicated account that can read mail only through dsync/replicator as designed; define encryption, retention, and immutability.

Why this step matters

Define a restricted backup identity and destination is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Use a local root-controlled job or a dedicated account that can read mail only through dsync/replicator as designed; define encryption, retention, and immutability. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Define a restricted backup identity and destination”. The scope must remain limited to the selected application and supported host.

Syntax explained

stat: Invokes the principal tool or configuration operation for “Define a restricted backup identity and destination”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.

Command

Fill variables0/2 ready

Values stay on this page and are never sent or saved.

Mail Root{{mailRoot}}Operator-reviewed value used by this tutorial for mailRoot; derive it from the target environment and never from untrusted request data.Backup Root{{backupRoot}}Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.

sudo stat -c '%a %U:%G %n' {{mailRoot}} {{backupRoot}}

Example output / evidence

Source and destination ownership plus retention are documented.

Checkpoint: Checkpoint: Define a restricted backup identity and destination

Continue whenSource and destination ownership plus retention are documented. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

Stop whenStop before the next step when stat reports an error, the output differs materially from the example, an unexpected package/service/path is affected, or the required before-state and rollback artifact are missing.

If this step fails

The command for “Define a restricted backup identity and destination” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v stat 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

command

Back up configuration and identity sources

caution

Archive Dovecot/Postfix configuration, virtual user databases or query definitions, certificates references, Sieve, and package versions separately from mail content.

Why this step matters

Back up configuration and identity sources is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Archive Dovecot/Postfix configuration, virtual user databases or query definitions, certificates references, Sieve, and package versions separately from mail content. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Back up configuration and identity sources”. The scope must remain limited to the selected application and supported host.

Syntax explained

tar: Invokes the principal tool or configuration operation for “Back up configuration and identity sources”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.

Command

Fill variables0/3 ready

Values stay on this page and are never sent or saved.

Backup Root{{backupRoot}}Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.Stamp{{stamp}}Operator-reviewed value used by this tutorial for stamp; derive it from the target environment and never from untrusted request data.Identity Source{{identitySource}}Operator-reviewed value used by this tutorial for identitySource; derive it from the target environment and never from untrusted request data.

sudo tar -czf {{backupRoot}}/mail-config-{{stamp}}.tgz /etc/dovecot /etc/postfix {{identitySource}}; dpkg-query -W 'dovecot*' 'postfix*' > {{backupRoot}}/mail-packages-{{stamp}}.txt

Example output / evidence

Protected configuration and package manifests exist.

Checkpoint: Checkpoint: Back up configuration and identity sources

Continue whenProtected configuration and package manifests exist. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

Stop whenStop before the next step when tar reports an error, the output differs materially from the example, an unexpected package/service/path is affected, or the required before-state and rollback artifact are missing.

If this step fails

The command for “Back up configuration and identity sources” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v tar 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

command

Create an application-consistent mailbox copy

caution

Prefer doveadm backup/dsync to a compatible target for online consistency; use filesystem snapshots only with documented consistency semantics.

Why this step matters

Create an application-consistent mailbox copy is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Prefer doveadm backup/dsync to a compatible target for online consistency; use filesystem snapshots only with documented consistency semantics. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Create an application-consistent mailbox copy”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveadm: Invokes the principal tool or configuration operation for “Create an application-consistent mailbox copy”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.

Command

Fill variables0/2 ready

Values stay on this page and are never sent or saved.

Test User{{testUser}}Operator-reviewed value used by this tutorial for testUser; derive it from the target environment and never from untrusted request data.Backup Root{{backupRoot}}Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.

sudo doveadm backup -u {{testUser}} maildir:{{backupRoot}}/users/{{testUser}}/Maildir

Example output / evidence

The selected user's messages and mailbox metadata copy successfully.

Checkpoint: Checkpoint: Create an application-consistent mailbox copy

Continue whenThe selected user's messages and mailbox metadata copy successfully. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

Stop whenStop before the next step when doveadm reports an error, the output differs materially from the example, an unexpected package/service/path is affected, or the required before-state and rollback artifact are missing.

If this step fails

The command for “Create an application-consistent mailbox copy” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v doveadm 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

command

Back up all intended users with bounded parallelism

caution

Enumerate through the authoritative userdb, log per-user exit status, retry failures, and cap I/O/concurrency to protect live service.

Why this step matters

Back up all intended users with bounded parallelism is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Enumerate through the authoritative userdb, log per-user exit status, retry failures, and cap I/O/concurrency to protect live service. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Back up all intended users with bounded parallelism”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveadm: Invokes the principal tool or configuration operation for “Back up all intended users with bounded parallelism”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.
|: Passes standard output to the next read-only inspection stage; review each stage separately if the combined result is surprising.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Backup Root{{backupRoot}}Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.

sudo doveadm user '*' | while read -r user; do sudo doveadm backup -u "$user" "maildir:{{backupRoot}}/users/$user/Maildir" || printf '%s\n' "$user" >> {{backupRoot}}/failed-users.txt; done

Example output / evidence

Every user succeeds or appears in an explicit failure list.

Checkpoint: Checkpoint: Back up all intended users with bounded parallelism

Continue whenEvery user succeeds or appears in an explicit failure list. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

If this step fails

The command for “Back up all intended users with bounded parallelism” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v doveadm 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

command

Encrypt, checksum, and copy independently

caution

Archive configuration and mail copy, encrypt to recovery recipients, checksum ciphertext, transfer off host, and retain a manifest.

Why this step matters

Encrypt, checksum, and copy independently is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Archive configuration and mail copy, encrypt to recovery recipients, checksum ciphertext, transfer off host, and retain a manifest. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Encrypt, checksum, and copy independently”. The scope must remain limited to the selected application and supported host.

Syntax explained

set: Invokes the principal tool or configuration operation for “Encrypt, checksum, and copy independently”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.
|: Passes standard output to the next read-only inspection stage; review each stage separately if the combined result is surprising.

Command

Fill variables0/4 ready

Values stay on this page and are never sent or saved.

Backup Root{{backupRoot}}Operator-reviewed value used by this tutorial for backupRoot; derive it from the target environment and never from untrusted request data.Stamp{{stamp}}Operator-reviewed value used by this tutorial for stamp; derive it from the target environment and never from untrusted request data.Age Recipients File{{ageRecipientsFile}}Operator-reviewed value used by this tutorial for ageRecipientsFile; derive it from the target environment and never from untrusted request data.Archive{{archive}}Operator-reviewed value used by this tutorial for archive; derive it from the target environment and never from untrusted request data.

set -o pipefail; sudo tar -C {{backupRoot}} -cpf - users mail-config-{{stamp}}.tgz mail-packages-{{stamp}}.txt | zstd -T0 | age -R {{ageRecipientsFile}} -o {{archive}}.tar.zst.age; sha256sum {{archive}}.tar.zst.age > {{archive}}.sha256

Example output / evidence

Encrypted backup, checksum, and manifest exist.

Checkpoint: Checkpoint: Encrypt, checksum, and copy independently

Continue whenEncrypted backup, checksum, and manifest exist. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

Stop whenStop before the next step when set reports an error, the output differs materially from the example, an unexpected package/service/path is affected, or the required before-state and rollback artifact are missing.

If this step fails

The command for “Encrypt, checksum, and copy independently” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v set 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

command

Restore one mailbox into an isolated account

caution

Verify and decrypt the backup, create a disposable test identity, run doveadm backup/sync into its empty mailbox, and recalculate quota.

Why this step matters

Restore one mailbox into an isolated account is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Verify and decrypt the backup, create a disposable test identity, run doveadm backup/sync into its empty mailbox, and recalculate quota. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Restore one mailbox into an isolated account”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveadm: Invokes the principal tool or configuration operation for “Restore one mailbox into an isolated account”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.

Command

Fill variables0/2 ready

Values stay on this page and are never sent or saved.

Restore User{{restoreUser}}Operator-reviewed value used by this tutorial for restoreUser; derive it from the target environment and never from untrusted request data.Restore Source{{restoreSource}}Operator-reviewed value used by this tutorial for restoreSource; derive it from the target environment and never from untrusted request data.

sudo doveadm backup -u {{restoreUser}} maildir:{{restoreSource}}/Maildir; sudo doveadm quota recalc -u {{restoreUser}}

Example output / evidence

The restored test mailbox and quota metadata are created.

Checkpoint: Checkpoint: Restore one mailbox into an isolated account

Continue whenThe restored test mailbox and quota metadata are created. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

If this step fails

The command for “Restore one mailbox into an isolated account” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v doveadm 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

verification

Validate messages, flags, folders, subscriptions, and search

read-only

Compare mailbox list/status, selected GUIDs, message counts, flags, dates, attachments, Sieve availability, quota, and IMAP login; record RPO/RTO.

Why this step matters

Validate messages, flags, folders, subscriptions, and search is a separate checkpoint because it establishes one auditable part of recover mailbox content and required metadata without assuming a filesystem copy is sufficient. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Compare mailbox list/status, selected GUIDs, message counts, flags, dates, attachments, Sieve availability, quota, and IMAP login; record RPO/RTO. Read the complete command or configuration before execution, replace the documented placeholders, and compare the target host with the supported environments listed at the beginning of this tutorial.

System changes

This step may affect the files, packages, identities, services, or runtime policy named in “Validate messages, flags, folders, subscriptions, and search”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveadm: Invokes the principal tool or configuration operation for “Validate messages, flags, folders, subscriptions, and search”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
{{…}}: Marks an operator-supplied value. Replace every placeholder deliberately; do not paste untrusted text or leave braces in the production command.
|: Passes standard output to the next read-only inspection stage; review each stage separately if the combined result is surprising.

Command

Fill variables0/1 ready

Values stay on this page and are never sent or saved.

Restore User{{restoreUser}}Operator-reviewed value used by this tutorial for restoreUser; derive it from the target environment and never from untrusted request data.

sudo doveadm mailbox list -u {{restoreUser}}; sudo doveadm mailbox status -u {{restoreUser}} 'messages unseen uidnext guid' '*'; sudo doveadm search -u {{restoreUser}} ALL | head

Example output / evidence

Recovered mailbox structure and sampled content match the source.

Checkpoint: Checkpoint: Validate messages, flags, folders, subscriptions, and search

Continue whenRecovered mailbox structure and sampled content match the source. Treat this concrete evidence as the minimum success signal and also confirm that unrelated services and the previous healthy path remain unchanged.

If this step fails

The command for “Validate messages, flags, folders, subscriptions, and search” fails, produces no useful evidence, or the expected service/configuration state is absent.

Likely causeA placeholder targets the wrong environment, the installed version uses another path or unit name, permissions are insufficient, or an earlier prerequisite was not satisfied.

Safe checks

command -v doveadm 2>/dev/null || true
systemctl --failed --no-pager 2>/dev/null || true
journalctl -p warning -n 50 --no-pager 2>/dev/null || true

Security notes

Keep secrets out of shell history, process arguments, screenshots, logs, and tutorial placeholders. Elevate only the narrow command that requires it and preserve package signature and TLS verification.

Alternatives

When the host layout or software version differs, use the vendor-supported equivalent in a disposable staging environment and document the mapping before touching production.

Stop conditions

Stop if the action broadens network exposure, permissions, package sources, writable paths, or service privileges beyond the tutorial's declared architecture.

Finish line

Verification checklist

Artifact integritysha256sum -c {{archive}}.sha256The encrypted offsite artifact matches its checksum.

Restore reportcat {{restoreReport}}A recent isolated restore proves mailbox content and metadata within RPO/RTO.

Recovery guidance

Common problems and safe checks

A message remains queued or the remote server returns a temporary 4xx response.

Likely causeDNS/MX resolution, routing, network reachability, TLS negotiation, remote greylisting/rate limits, reputation or recipient policy prevents delivery.

Safe checks

exim -bp 2>/dev/null || postqueue -p
dig +short MX example.net
journalctl -u exim4 -u postfix --since '-30 min' --no-pager

ResolutionInspect one message's recorded diagnostic and route first, fix the evidenced dependency, then retry only that message; do not force an undiagnosed bulk queue.

SMTP accepts a recipient, but the mailbox is absent, unreadable or never visible over IMAP.

Likely causeRecipient maps, LMTP/LDA route, virtual UID/GID, Maildir path, quota, Dovecot namespace or filesystem permissions disagree.

Safe checks

doveconf -n
doveadm user user@example.com
doveadm mailbox list -u user@example.com

ResolutionTrace the exact address through recipient validation, delivery socket and resolved mailbox path; correct the narrow mapping/ownership mismatch before accepting more mail.

Authentication or TLS fails despite apparently correct credentials and certificate files.

Likely causeThe listener uses another configuration, hostname/SAN does not match, chain/key permissions are wrong, authentication is attempted without TLS, or the identity backend maps another username.

Safe checks

openssl s_client -connect mail.example.com:587 -starttls smtp -servername mail.example.com </dev/null
openssl s_client -connect mail.example.com:993 -servername mail.example.com </dev/null
journalctl -u dovecot -u postfix -u exim4 -p warning -n 100 --no-pager

ResolutionVerify the advertised hostname, chain, listener and mapped user independently; never disable certificate verification or enable plaintext authentication to bypass the failure.

After the procedure

Alternatives and next steps

Consider these alternatives

Use a reputable managed mail transport or mailbox provider when staffing, deliverability, abuse response, DNS reputation and 24/7 queue operations cannot be sustained.
Separate inbound, outbound, submission and mailbox roles across hosts only when TLS identity, routing, backups and observability remain end-to-end testable.

Operate it safely

Alert on queue age/depth, delivery deferrals, authentication failures, TLS/certificate expiry, disk/quota pressure, DKIM/DMARC failures and backup restore age.
Review relay/recipient maps, dormant users, supported versions, DNS policy and key/certificate rotation at least every 90 days.
Practice one-message queue diagnosis and an isolated mailbox/config restore so incident steps are proven before a real outage.

Reference

Frequently asked questions

Why is one successful test email insufficient?

It may bypass the actual external DNS, authentication, recipient, DKIM, queue retry or IMAP path. Test each boundary and preserve protocol/header evidence.

Can TLS be tested by checking that encryption is present?

No. Verify the chain and hostname and ensure authentication is unavailable before STARTTLS; encryption to an unverified endpoint is not server authentication.

Should a stuck queue be forced immediately?

No. Read one message's diagnostic and fix the dependency first. Bulk retries can amplify rate limits, duplicates or reputation damage.

Recovery

Rollback

Disable the new backup job and restore the prior schedule; a test restore must never overwrite a live mailbox.

Stop the new timer or scheduler and restore prior backup configuration.
Remove only the disposable restored account after evidence is captured.
Retain encrypted backup artifacts through their defined retention period.

Evidence

Sources and review

Verified 2026-07-25Review due 2026-10-23

Dovecot virtual usersofficial Dovecot quota pluginofficial Dovecot SSL configurationofficial