OneLinersCommand workbench
Guides
Security / Services & Applications

Configure Postfix TLS and authenticated submission on port 587

Add a dedicated submission service, require STARTTLS and SASL, integrate Dovecot authentication, constrain relaying and abuse, and test safe failure modes.

90 min8 stepsChanges system stateRevision 2
Save or explore
#postfix#submission#tls#sasl#dovecot#port-587
Save to collectionCreate a collection in the sidebar first.
0 of 8 steps completed
Goal

Provide secure client submission without advertising plaintext authentication or weakening public SMTP.

Supported environments
  • Postfix 3.8+
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 Postfix implementation of “Configure Postfix TLS and authenticated submission on port 587” 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
  • Provide secure client submission without advertising plaintext authentication or weakening public SMTP. 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

A dedicated submission listener on port 587 requires STARTTLS and SASL authentication before accepting client mail. It overrides client-controlled sender and relay policy with authenticated identity rules, while public port 25 remains unauthenticated server-to-server SMTP. Certificates bind the advertised mail hostname, secrets remain in the authentication backend, and a controlled SMTP transcript proves encryption, authentication, sender policy and final queue acceptance.

Port 587 listenerSeparates authenticated clients from public server-to-server SMTP.
TLS identityAuthenticates the advertised hostname and protects credentials/message transit.
SASL backendValidates individual users without exposing reusable secrets to the MTA config.
Sender/relay policyBinds authenticated identity to permitted envelope/header senders.
  1. Inventory hostname/DNS, listeners, certificates, identities, recipient/relay maps, queue/mailbox state, logs and a recoverable configuration/data baseline.
  2. Prepare the submission candidate with official Postfix syntax, protected secrets and one explicit service/data boundary at a time.
  3. Run native configuration validation and immediate read-only checkpoint before reload or acceptance of new messages.
  4. 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

{{certFile}}

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

Example: /etc/letsencrypt/live/mail.example.com/fullchain.pem
{{keyFile}}

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

Example: /etc/letsencrypt/live/mail.example.com/privkey.pem
{{mailHost}}

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

Example: mail.example.com
{{protectedSecret}}

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

Example: secret-manager-reference
{{recipient}}

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

Example: owned-test@example.net
{{sender}}

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

Example: operator@example.com
{{user}}

Operator-reviewed value used by this tutorial for user; 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.
01

instruction

Verify the SMTP certificate and key

read-only

Use a SAN for the submission hostname, complete chain, protected key, renewal hook, and documented owner.

Why this step matters

Verify the SMTP certificate and key is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Use a SAN for the submission hostname, complete chain, protected key, renewal hook, and documented owner. 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 “Verify the SMTP certificate and key”. The scope must remain limited to the selected application and supported host.

Syntax explained

openssl
Invokes the principal tool or configuration operation for “Verify the SMTP certificate and key”; 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.

openssl x509 -in {{certFile}} -noout -subject -issuer -dates -ext subjectAltName; sudo stat -c '%a %U:%G %n' {{keyFile}}
Example output / evidence
The identity validates and private key permissions are restrictive.

Checkpoint: Checkpoint: Verify the SMTP certificate and key

Continue whenThe identity validates and private key permissions are restrictive. 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 openssl 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 “Verify the SMTP certificate and key” 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 openssl 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.
02

config

Configure Postfix server TLS

caution

Set certificate, key, CA, security level may for port 25, and current protocol/cipher exclusions; submission overrides security level to encrypt.

Why this step matters

Configure Postfix server TLS is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Set certificate, key, CA, security level may for port 25, and current protocol/cipher exclusions; submission overrides security level to encrypt. 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 “Configure Postfix server TLS”. The scope must remain limited to the selected application and supported host.

Syntax explained

postconf
Invokes the principal tool or configuration operation for “Configure Postfix server TLS”; 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.
configuration file
Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.
Configuration
Fill variables0/2 ready

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

sudo postconf -e 'smtpd_tls_cert_file={{certFile}}' 'smtpd_tls_key_file={{keyFile}}' 'smtpd_tls_security_level=may'; postconf -n | grep smtpd_tls
Example output / evidence
Public SMTP offers STARTTLS with the intended certificate.

Checkpoint: Checkpoint: Configure Postfix server TLS

Continue whenPublic SMTP offers STARTTLS with the intended certificate. 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 postconf 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 “Configure Postfix server TLS” 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 postconf 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.
03

config

Expose a Postfix-only Dovecot auth socket

caution

Configure Dovecot service auth unix_listener below /var/spool/postfix/private with postfix ownership and 0660 permissions.

Why this step matters

Expose a Postfix-only Dovecot auth socket is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Configure Dovecot service auth unix_listener below /var/spool/postfix/private with postfix ownership and 0660 permissions. 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 “Expose a Postfix-only Dovecot auth socket”. The scope must remain limited to the selected application and supported host.

Syntax explained

sudoedit
Invokes the principal tool or configuration operation for “Expose a Postfix-only Dovecot auth socket”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
|
Passes standard output to the next read-only inspection stage; review each stage separately if the combined result is surprising.
/etc/dovecot/conf.d/10-master.conf
Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.
File /etc/dovecot/conf.d/10-master.conf
Configuration
sudoedit /etc/dovecot/conf.d/10-master.conf; sudo doveconf -n | grep -A8 'service auth'
Example output / evidence
The private auth socket is accessible to Postfix only.

Checkpoint: Checkpoint: Expose a Postfix-only Dovecot auth socket

Continue whenThe private auth socket is accessible to Postfix only. 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 sudoedit 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 “Expose a Postfix-only Dovecot auth socket” 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 sudoedit 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.
04

config

Connect Postfix to Dovecot SASL

caution

Set smtpd_sasl_type=dovecot, private/auth path, enable authentication, and reject anonymous mechanisms.

Why this step matters

Connect Postfix to Dovecot SASL is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Set smtpd_sasl_type=dovecot, private/auth path, enable authentication, and reject anonymous mechanisms. 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 “Connect Postfix to Dovecot SASL”. The scope must remain limited to the selected application and supported host.

Syntax explained

postconf
Invokes the principal tool or configuration operation for “Connect Postfix to Dovecot SASL”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
configuration file
Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.
Configuration
sudo postconf -e 'smtpd_sasl_type=dovecot' 'smtpd_sasl_path=private/auth' 'smtpd_sasl_auth_enable=yes' 'smtpd_sasl_security_options=noanonymous'; postconf smtpd_sasl_type smtpd_sasl_path smtpd_sasl_auth_enable
Example output / evidence
Postfix uses the private Dovecot auth socket.

Checkpoint: Checkpoint: Connect Postfix to Dovecot SASL

Continue whenPostfix uses the private Dovecot auth socket. 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 postconf 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 “Connect Postfix to Dovecot SASL” 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 postconf 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.
05

config

Define a submission-only policy in master.cf

caution

Enable submission on 587 with TLS required, SASL enabled, client restrictions permit_sasl_authenticated,reject, and a distinct syslog name.

Why this step matters

Define a submission-only policy in master.cf is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Enable submission on 587 with TLS required, SASL enabled, client restrictions permit_sasl_authenticated,reject, and a distinct syslog name. 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 “Define a submission-only policy in master.cf”. The scope must remain limited to the selected application and supported host.

Syntax explained

sudoedit
Invokes the principal tool or configuration operation for “Define a submission-only policy in master.cf”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
/etc/postfix/master.cf
Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.
File /etc/postfix/master.cf
Configuration
sudoedit /etc/postfix/master.cf; sudo postfix check; postconf -Mf submission/inet
Example output / evidence
The submission service has explicit overrides and does not alter smtp/inet.

Checkpoint: Checkpoint: Define a submission-only policy in master.cf

Continue whenThe submission service has explicit overrides and does not alter smtp/inet. 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 sudoedit 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 submission-only policy in master.cf” 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 sudoedit 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.
06

config

Apply message, recipient, and connection limits

caution

Set submission-specific recipient and rate policy, integrate abuse monitoring, and avoid logging credentials.

Why this step matters

Apply message, recipient, and connection limits is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Set submission-specific recipient and rate policy, integrate abuse monitoring, and avoid logging credentials. 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 “Apply message, recipient, and connection limits”. The scope must remain limited to the selected application and supported host.

Syntax explained

postconf
Invokes the principal tool or configuration operation for “Apply message, recipient, and connection limits”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
configuration file
Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.
Configuration
postconf -P submission/inet/syslog_name; postconf -P submission/inet/smtpd_client_restrictions; postconf -P submission/inet/smtpd_tls_security_level
Example output / evidence
Submission limits and log identity are explicit.

Checkpoint: Checkpoint: Apply message, recipient, and connection limits

Continue whenSubmission limits and log identity are explicit. 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 postconf 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 “Apply message, recipient, and connection limits” 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 postconf 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.
07

verification

Validate, restart, and compare EHLO

caution

Run doveconf and postfix checks, restart both services, then compare port 25 and 587 capabilities before and after STARTTLS.

Why this step matters

Validate, restart, and compare EHLO is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Run doveconf and postfix checks, restart both services, then compare port 25 and 587 capabilities before and after STARTTLS. 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 “Validate, restart, and compare EHLO”. The scope must remain limited to the selected application and supported host.

Syntax explained

doveconf
Invokes the principal tool or configuration operation for “Validate, restart, and compare EHLO”; 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.

sudo doveconf -n >/dev/null; sudo postfix check; sudo systemctl restart dovecot postfix; swaks --server {{mailHost}} --port 587 --quit-after EHLO; swaks --server {{mailHost}} --port 587 --tls --quit-after EHLO
Example output / evidence
Port 587 requires TLS and advertises AUTH only after encryption.

Checkpoint: Checkpoint: Validate, restart, and compare EHLO

Continue whenPort 587 requires TLS and advertises AUTH only after encryption. 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 “Validate, restart, and compare EHLO” 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.
08

verification

Test valid and invalid submission paths

read-only

Verify authenticated TLS relay, invalid credential rejection, plaintext denial, unauthenticated relay denial, and certificate hostname validation.

Why this step matters

Test valid and invalid submission paths is a separate checkpoint because it establishes one auditable part of provide secure client submission without advertising plaintext authentication or weakening public smtp. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Verify authenticated TLS relay, invalid credential rejection, plaintext denial, unauthenticated relay denial, and certificate hostname validation. 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 “Test valid and invalid submission paths”. The scope must remain limited to the selected application and supported host.

Syntax explained

swaks
Invokes the principal tool or configuration operation for “Test valid and invalid submission paths”; 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/5 ready

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

swaks --server {{mailHost}} --port 587 --tls --tls-verify --auth --auth-user {{user}} --auth-password '{{protectedSecret}}' --from {{sender}} --to {{recipient}}
Example output / evidence
Valid submission queues once; invalid or unsafe attempts fail.

Checkpoint: Checkpoint: Test valid and invalid submission paths

Continue whenValid submission queues once; invalid or unsafe attempts fail. 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 swaks 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 “Test valid and invalid submission paths” 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 swaks 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.

Finish line

Verification checklist

Certificate verificationopenssl s_client -starttls smtp -connect {{mailHost}}:587 -servername {{mailHost}} -verify_return_error </dev/nullChain and hostname validate.
Plaintext authentication disabledswaks --server {{mailHost}} --port 587 --quit-after EHLOAUTH is absent before STARTTLS.

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 submission service and SASL integration without interrupting public port 25.

  1. Restore prior master.cf/main.cf, run postfix check, and reload.
  2. Remove the Dovecot auth socket only after Postfix no longer references it.
  3. Revoke test credentials and close firewall port 587 if submission is abandoned.

Evidence

Sources and review

Verified 2026-07-25Review due 2026-10-23
Postfix TLS supportofficialPostfix SASL supportofficialDovecot SASL authentication for Postfixofficial