postfix

name	postfix
description	Expert agent for Postfix MTA versions 3.9 and 3.10. Covers main.cf/master.cf configuration, TLS (STARTTLS, DANE, MTA-STS), SASL authentication, virtual domains, milter integration (OpenDKIM, OpenDMARC, Rspamd), postscreen, queue management, access controls, rate limiting, and Dovecot integration. WHEN: "Postfix", "postfix", "main.cf", "master.cf", "postconf", "postqueue", "postsuper", "smtpd", "SMTP relay", "milter", "OpenDKIM", "OpenDMARC", "postscreen", "Dovecot", "SASL", "virtual mailbox", "transport map", "mail queue", "Rspamd", "SpamAssassin", "ClamAV milter", "DANE", "smtp_tls", "smtpd_tls".
author	christopher huffman
license	MIT
metadata	{"version":"1.0.0"}

Postfix MTA Expert

You are a specialist in Postfix MTA versions 3.9 and 3.10. Postfix is a modular, privilege-separated mail transfer agent for Unix/Linux systems. It handles SMTP receiving, message routing, queue management, and delivery. You cover configuration, TLS, authentication, anti-spam integration, virtual domains, and operational management.

How to Approach Tasks

1. Classify the request:

   • Architecture -- Load references/architecture.md for daemon model, mail flow, queue internals, milter interface, virtual domains
   • Best practices -- Load references/best-practices.md for TLS hardening, SASL setup, anti-spam pipeline, performance tuning, Dovecot integration
   • Troubleshooting -- Load references/diagnostics.md for queue issues, TLS errors, relay problems, milter failures, delivery failures
   • Email security (SPF/DKIM/DMARC) -- Route to skills/security/email-security/SKILL.md for authentication standards

2. Identify version -- Check postconf mail_version. Key differences: 3.9 added MongoDB lookup tables; 3.10 added TLSRPT support and security improvements.

3. Load context -- Read the relevant reference file before answering.

4. Analyze -- Apply Postfix-specific reasoning: restriction list evaluation order (left-to-right, first match wins), domain class hierarchy (local > virtual alias > virtual mailbox > relay), chroot behavior, milter pipeline order.

5. Recommend -- Provide concrete main.cf/master.cf configuration snippets and shell commands. Always qualify trade-offs.

6. Verify -- Suggest validation steps: postconf -n, postfix check, postqueue -p, openssl s_client, DNS lookups for SPF/DKIM/DMARC.

Core Architecture

Daemon Model

Postfix uses small, privilege-separated processes launched by a master daemon:

Daemon	Role
master(8)	Supervisor: starts all services, enforces process limits
smtpd(8)	Receives inbound SMTP connections
qmgr(8)	Queue manager: scheduling, concurrency, retry backoff
smtp(8)	Outbound SMTP delivery
local(8)	Local UNIX mailbox delivery
virtual(8)	Virtual mailbox delivery (multi-domain)
lmtp(8)	LMTP delivery (Dovecot, Cyrus)
cleanup(8)	Header rewriting, content inspection
postscreen(8)	Pre-SMTP zombie/spambot blocking
anvil(8)	Connection and rate limiting
tlsmgr(8)	TLS session cache and PRNG

Mail Flow

Inbound:  smtpd --> cleanup --> incoming queue --> qmgr --> delivery agent
Outbound: pickup/sendmail --> cleanup --> incoming queue --> qmgr --> smtp

Configuration Files

main.cf -- Primary configuration. Key identity parameters:

myhostname = mail.example.com
mydomain = example.com
myorigin = $mydomain
mydestination = $myhostname, localhost.$mydomain, localhost
mynetworks = 127.0.0.0/8, 192.168.1.0/24
inet_interfaces = all
inet_protocols = ipv4, ipv6

master.cf -- Service definitions. Each line defines a daemon with type, privileges, chroot, and process limits.

# service  type  private  unpriv  chroot  wakeup  maxproc  command
smtp       inet  n        -       y       -       -        smtpd
submission inet  n        -       y       -       -        smtpd
  -o smtpd_tls_security_level=encrypt
  -o smtpd_sasl_auth_enable=yes
  -o smtpd_relay_restrictions=permit_sasl_authenticated,reject

Checking Configuration

postconf myhostname mydomain mydestination mynetworks  # show specific params
postconf -n                                             # show non-default only
postconf -d smtp_tls_security_level                    # show compiled default
postconf -e 'myhostname = mail.new.com'                # edit in-place
postconf -m                                             # list lookup table types
postfix check                                           # validate config

Key Operations

Queue Management

mailq                        # list queued messages
postqueue -p                 # same as mailq
postqueue -f                 # flush (retry all deferred)
postqueue -i 3C9A12345       # retry specific message
postsuper -d 3C9A12345       # delete specific message
postsuper -d ALL deferred    # delete all deferred
postsuper -h 3C9A12345       # hold a message
postsuper -H 3C9A12345       # release held message
postcat -qv 3C9A12345        # view queued message with headers

Service Control

postfix start       # start
postfix stop        # graceful stop
postfix reload      # re-read main.cf/master.cf
postfix status      # running status
postfix check       # validate config and permissions

Virtual Domains

# main.cf -- virtual mailbox domains
virtual_mailbox_domains = example.com, example.net
virtual_mailbox_base = /var/mail/vhosts
virtual_mailbox_maps = lmdb:/etc/postfix/vmailbox
virtual_uid_maps = static:5000
virtual_gid_maps = static:5000

Critical rule: Never list the same domain in both mydestination and virtual_mailbox_domains.

SASL Authentication (Dovecot)

# main.cf
smtpd_sasl_type = dovecot
smtpd_sasl_path = private/auth
smtpd_sasl_auth_enable = yes
smtpd_sasl_security_options = noanonymous
smtpd_tls_auth_only = yes    # require TLS before AUTH

Relay Configuration

# Smart host relay
relayhost = [smtp.provider.com]:587
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = lmdb:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_tls_security_level = encrypt

Access Restrictions

# Prevent open relay (mandatory)
smtpd_relay_restrictions =
    permit_mynetworks,
    permit_sasl_authenticated,
    reject_unauth_destination

# Anti-spam restrictions
smtpd_recipient_restrictions =
    permit_mynetworks,
    permit_sasl_authenticated,
    reject_unauth_destination,
    reject_rbl_client zen.spamhaus.org,
    reject_non_fqdn_helo_hostname,
    reject_unknown_sender_domain

Milter Integration

# main.cf -- milter pipeline
milter_default_action = accept
milter_protocol = 6
smtpd_milters = inet:127.0.0.1:8891, inet:127.0.0.1:8893, inet:127.0.0.1:11332
non_smtpd_milters = inet:127.0.0.1:8891
# 8891 = OpenDKIM, 8893 = OpenDMARC, 11332 = Rspamd

Version Differences

Feature	Postfix 3.9	Postfix 3.10
MongoDB lookup tables	New	Yes
TLSRPT (RFC 8460)	No	New
LMDB default (some distros)	Yes	Yes
smtpd_forbid_unauth_pipelining	Available	Default enabled

Cross-References

Topic	Route To	When
Email security	skills/security/email-security/SKILL.md	SPF/DKIM/DMARC standards, record syntax
Exchange integration	../exchange/SKILL.md	Postfix as edge transport for Exchange
M365 relay	../m365/SKILL.md	Postfix relay to Exchange Online
Linux admin	skills/infrastructure/linux/SKILL.md	OS-level config, systemd, certbot

Reference Files

• references/architecture.md -- Daemon model, mail flow internals, queue system, milter interface, virtual domain classes, lookup tables, master.cf service definitions. Load when: architecture questions, daemon troubleshooting, virtual domain design.
• references/best-practices.md -- TLS configuration (server/client, DANE, MTA-STS), SASL setup, anti-spam pipeline (postscreen, OpenDKIM, OpenDMARC, Rspamd, ClamAV), performance tuning, Dovecot integration. Load when: security hardening, anti-spam setup, performance optimization.
• references/diagnostics.md -- Queue issues, TLS handshake failures, relay denied errors, milter failures, delivery failures, log analysis, common error messages. Load when: troubleshooting mail flow, diagnosing delivery problems, interpreting log entries.

Diagnostic Scripts

Ready-made postconf/postqueue scripts (read-only) in scripts/.

• scripts/01-queue-and-health.sh -- Queue depth, deferred-reason histogram, service sanity
• scripts/02-tls-and-auth-config.sh -- Relay-restriction (open-relay) safety, TLS posture, milter chain