Services & Applications / Networking & DNS

Configure Exim4 to relay outbound mail through a smarthost

Route non-local mail to an authenticated TLS relay, protect credentials, preserve local delivery, rewrite identities deliberately, and test failure behavior.

60 min8 stepsChanges system stateRevision 2

Save or explore

#exim #smarthost #relay #smtp-auth #tls

0 of 8 steps completed

Goal

Send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly.

Supported environments

Exim4 4.98+

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 Exim implementation of “Configure Exim4 to relay outbound mail through a smarthost” 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

Send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. 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

The local MTA accepts only approved local senders and routes non-local mail through an authenticated upstream relay endpoint. Credentials live in a root-readable map or protected configuration, TLS verifies the relay hostname and local routing remains distinct. A canary proves external delivery and headers; deliberate invalid credentials and unapproved senders prove failure boundaries. Direct-to-MX delivery is disabled only after the relay path is healthy.

Local acceptance policyLimits which local identities may submit mail.

Relay routeSends non-local recipients through one verified upstream endpoint.

Credential mapStores narrow relay credentials in a root-readable compiled or protected form.

TLS and canaryVerify upstream identity and final delivery evidence.

Inventory hostname/DNS, listeners, certificates, identities, recipient/relay maps, queue/mailbox state, logs and a recoverable configuration/data baseline.
Prepare the smarthost candidate with official Exim 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

{{canary}}

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

Example: mail-canary-20260725

{{externalRecipient}}

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

Example: owned-test@example.net

{{localRecipient}}

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

Example: root@localhost

{{localSender}}

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

Example: monitor@example.com

{{relayHost}}

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

Example: smtp.relay.example

{{relayPort}}

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

Example: 587

{{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

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

Record relay endpoint and policy

read-only

Document hostname, port, CA validation, authentication identity, approved envelope/header domains, rate limits, outage behavior, and provider ownership.

Why this step matters

Record relay endpoint and policy is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Document hostname, port, CA validation, authentication identity, approved envelope/header domains, rate limits, outage behavior, and provider ownership. 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 “Record relay endpoint and policy”. The scope must remain limited to the selected application and supported host.

Syntax explained

getent: Invokes the principal tool or configuration operation for “Record relay endpoint and policy”; 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.

Relay Host{{relayHost}}Operator-reviewed value used by this tutorial for relayHost; derive it from the target environment and never from untrusted request data.Relay Port{{relayPort}}Operator-reviewed value used by this tutorial for relayPort; derive it from the target environment and never from untrusted request data.

getent ahosts {{relayHost}}; timeout 5 openssl s_client -starttls smtp -connect {{relayHost}}:{{relayPort}} -servername {{relayHost}} -verify_return_error </dev/null

Example output / evidence

Relay DNS and TLS identity validate.

Checkpoint: Checkpoint: Record relay endpoint and policy

Continue whenRelay DNS and TLS identity validate. 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 getent 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 “Record relay endpoint and policy” 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 getent 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

Back up routing, credentials, and queue state

caution

Archive Exim configuration with protected permissions and record every queued message before changing the outbound route.

Why this step matters

Back up routing, credentials, and queue state is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Archive Exim configuration with protected permissions and record every queued message before changing the outbound route. 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 routing, credentials, and queue state”. 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 routing, credentials, and queue state”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.

Command

sudo tar -czf /root/exim-before-smarthost-$(date +%F-%H%M).tgz /etc/exim4; sudo exim -bp > /root/exim-queue-before-smarthost.txt

Example output / evidence

Configuration and queue inventory are saved.

Checkpoint: Checkpoint: Back up routing, credentials, and queue state

Continue whenConfiguration and queue inventory are saved. 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 routing, credentials, and queue state” 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.

config

Select smarthost mode

caution

Set dc_eximconfig_configtype=smarthost, canonical local identity, smarthost hostname and port, and local domains that must never be relayed outward.

Why this step matters

Select smarthost mode is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Set dc_eximconfig_configtype=smarthost, canonical local identity, smarthost hostname and port, and local domains that must never be relayed outward. 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 “Select smarthost mode”. The scope must remain limited to the selected application and supported host.

Syntax explained

dpkg-reconfigure: Invokes the principal tool or configuration operation for “Select smarthost mode”; 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.
configuration file: Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.

Configuration

sudo dpkg-reconfigure exim4-config; sudo grep -E '^(dc_eximconfig_configtype|dc_smarthost|dc_other_hostnames|dc_readhost)' /etc/exim4/update-exim4.conf.conf

Example output / evidence

Smarthost endpoint and local-domain behavior are explicit.

Checkpoint: Checkpoint: Select smarthost mode

Continue whenSmarthost endpoint and local-domain behavior 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 dpkg-reconfigure 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 “Select smarthost mode” 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 dpkg-reconfigure 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.

config

Store relay credentials with strict permissions

caution

Add a hostname-specific entry to passwd.client, avoid wildcard credentials where possible, and keep the file root-readable only.

Why this step matters

Store relay credentials with strict permissions is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Add a hostname-specific entry to passwd.client, avoid wildcard credentials where possible, and keep the file root-readable only. 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 “Store relay credentials with strict permissions”. The scope must remain limited to the selected application and supported host.

Syntax explained

sudoedit: Invokes the principal tool or configuration operation for “Store relay credentials with strict permissions”; confirm that it resolves to the expected packaged executable or file before using elevated privileges.
/etc/exim4/passwd.client: Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.

File /etc/exim4/passwd.client

Configuration

sudoedit /etc/exim4/passwd.client; sudo chown root:Debian-exim /etc/exim4/passwd.client; sudo chmod 0640 /etc/exim4/passwd.client

Example output / evidence

The exact relay hostname maps to protected credentials.

Checkpoint: Checkpoint: Store relay credentials with strict permissions

Continue whenThe exact relay hostname maps to protected credentials. 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 “Store relay credentials with strict permissions” 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

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.

config

Require and verify TLS to the smarthost

caution

Use certificate verification and fail delivery temporarily rather than downgrade to plaintext when the approved relay TLS fails.

Why this step matters

Require and verify TLS to the smarthost is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Use certificate verification and fail delivery temporarily rather than downgrade to plaintext when the approved relay TLS fails. 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 “Require and verify TLS to the smarthost”. The scope must remain limited to the selected application and supported host.

Syntax explained

grep: Invokes the principal tool or configuration operation for “Require and verify TLS to the smarthost”; 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.
configuration file: Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.

Configuration

sudo grep -R --line-number -E 'hosts_require_tls|tls_verify_certificates|smarthost' /etc/exim4; sudo exim -bP transport remote_smtp_smarthost

Example output / evidence

The smarthost transport requires TLS and trusted CA verification.

Checkpoint: Checkpoint: Require and verify TLS to the smarthost

Continue whenThe smarthost transport requires TLS and trusted CA verification. 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 grep 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 “Require and verify TLS to the smarthost” 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 grep 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.

config

Configure envelope and header rewriting deliberately

caution

If the relay requires an approved domain, map local service senders explicitly and preserve traceability; never rewrite arbitrary inbound mail.

Why this step matters

Configure envelope and header rewriting deliberately is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

If the relay requires an approved domain, map local service senders explicitly and preserve traceability; never rewrite arbitrary inbound mail. 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 “Configure envelope and header rewriting deliberately”. The scope must remain limited to the selected application and supported host.

Syntax explained

sudoedit: Invokes the principal tool or configuration operation for “Configure envelope and header rewriting deliberately”; 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.
/etc/email-addresses: Is the persistent configuration boundary changed by this step. Keep an attributable backup and validate the consumer before reload.

File /etc/email-addresses

Configuration

Fill variables0/1 ready

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

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

sudoedit /etc/email-addresses; sudo exim -brw {{localSender}}

Example output / evidence

The intended local sender rewrites to the approved external identity.

Checkpoint: Checkpoint: Configure envelope and header rewriting deliberately

Continue whenThe intended local sender rewrites to the approved external identity. 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 “Configure envelope and header rewriting deliberately” 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

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 routing without sending

read-only

Use exim -bt and debug routing to prove local recipients remain local while external recipients select the smarthost router and transport.

Why this step matters

Validate routing without sending is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Use exim -bt and debug routing to prove local recipients remain local while external recipients select the smarthost router and transport. 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 routing without sending”. The scope must remain limited to the selected application and supported host.

Syntax explained

exim: Invokes the principal tool or configuration operation for “Validate routing without sending”; 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/2 ready

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

Local Recipient{{localRecipient}}Operator-reviewed value used by this tutorial for localRecipient; derive it from the target environment and never from untrusted request data.External Recipient{{externalRecipient}}Operator-reviewed value used by this tutorial for externalRecipient; derive it from the target environment and never from untrusted request data.

exim -bt {{localRecipient}}; exim -bt {{externalRecipient}}; sudo exim -bt -d+route {{externalRecipient}} 2>&1 | tail -n 80

Example output / evidence

Local and external routes select the intended transports.

Checkpoint: Checkpoint: Validate routing without sending

Continue whenLocal and external routes select the intended transports. 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 exim 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 routing without sending” 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 exim 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

Test delivery, authentication failure, and relay outage

read-only

Send a tagged message, confirm the next hop and TLS cipher in logs, then use a controlled wrong credential or blocked route to prove mail defers rather than disappears.

Why this step matters

Test delivery, authentication failure, and relay outage is a separate checkpoint because it establishes one auditable part of send outbound mail through an approved provider or central relay without exposing credentials or relaying inbound mail incorrectly. Performing it independently keeps a failed prerequisite, syntax error, or compatibility mismatch from being hidden by later actions.

What to understand

Send a tagged message, confirm the next hop and TLS cipher in logs, then use a controlled wrong credential or blocked route to prove mail defers rather than disappears. 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 “Test delivery, authentication failure, and relay outage”. The scope must remain limited to the selected application and supported host.

Syntax explained

swaks: Invokes the principal tool or configuration operation for “Test delivery, authentication failure, and relay outage”; 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.

Sender{{sender}}Operator-reviewed value used by this tutorial for sender; derive it from the target environment and never from untrusted request data.External Recipient{{externalRecipient}}Operator-reviewed value used by this tutorial for externalRecipient; derive it from the target environment and never from untrusted request data.Canary{{canary}}Operator-reviewed value used by this tutorial for canary; derive it from the target environment and never from untrusted request data.

swaks --server localhost --from {{sender}} --to {{externalRecipient}} --header 'X-OneLiners-Test: {{canary}}'; sudo tail -n 100 /var/log/exim4/mainlog

Example output / evidence

Successful mail uses the smarthost; failure remains queued with a clear temporary error.

Checkpoint: Checkpoint: Test delivery, authentication failure, and relay outage

Continue whenSuccessful mail uses the smarthost; failure remains queued with a clear temporary error. 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 delivery, authentication failure, and relay outage” 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

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

External routeexim -bt {{externalRecipient}}The address routes through the smarthost router and transport.

TLS delivery evidencesudo grep '{{canary}}' /var/log/exim4/mainlogThe test delivery records the approved relay and encrypted transport.

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

Restore direct-delivery routing and protected credentials while preserving deferred queue entries.

Restore /etc/exim4, rebuild configuration, and validate external routing with exim -bt.
Restart Exim and force no queue delivery until the intended route is confirmed.
Revoke the smarthost credential if it will no longer be used.

Evidence

Sources and review

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

Ubuntu Server: install Exim4official Exim SMTP authenticationofficial Exim encrypted SMTP connectionsofficial