Postfix

---
name: postfix
description: "Expert skill 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\". Do NOT use for general Linux OS administration (systemd, package management, kernel/firewall tuning) unrelated to mail — that's the `rhel`/`ubuntu`/`debian` skill in the `os` plugin."
license: MIT
---

# Postfix MTA

This skill covers 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. Read the reference files below for configuration, TLS, authentication, anti-spam integration, virtual domains, and operational detail.

## 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)** -- Use the `email-security` skill (`security` plugin) 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:

```ini
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.

```ini
# 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

```bash
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

```bash
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

```bash
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

```ini
# 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)

```ini
# 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

```ini
# 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

```ini
# 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

```ini
# 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 | Skill | When |
|---|---|---|
| Email security | `email-security` (`security` plugin) | SPF/DKIM/DMARC standards, record syntax |
| Exchange integration | `exchange` | Postfix as edge transport for Exchange |
| M365 relay | `m365` | Postfix relay to Exchange Online |
| Linux admin | `rhel` / `ubuntu` / `debian` (`os` plugin) | 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