$ guides / postfix / postfix-milter-timeouts ▌

Operations Guides

Postfix Milter timeouts: smtpd hangs when a milter stops responding

When a before-queue milter like OpenDKIM, milter-greylist, or a custom policy daemon stops responding, smtpd processes block during the SMTP transaction. Each connection that hits a milter callback waits for the full timeout duration before Postfix gives up. During that wait, the smtpd process handling that connection is occupied and counts toward the service’s maxproc limit.

The first visible symptom is usually not mail bouncing or deferring. It is mail acceptance slowing down. SMTP clients connect, get a 220 greeting, then stall during the DATA phase. As more smtpd processes accumulate waiting for milter responses, fewer remain available for new connections. Eventually new connections queue in the listen backlog or are refused entirely.

The critical decision point is milter_default_action, which determines what Postfix does when the timeout fires: accept the message without the milter’s verdict, tempfail it, reject it, or disconnect the client. On Postfix 3.11+ the default changed from tempfail to shutdown, which disconnects the SMTP client with a 421 response. Knowing which default your version applies is the difference between a degraded system and one that appears down.

What this means

A before-queue milter is invoked by smtpd at specific SMTP protocol stages: CONNECT, HELO, MAIL FROM, RCPT TO, and DATA (end-of-message). For each stage, smtpd sends a request to the milter and waits for a response before continuing the SMTP transaction. If the milter hangs, the smtpd process blocks.

Three timeout parameters control how long smtpd waits:

Parameter	Default	Applies to
`milter_connect_timeout`	30s	Milter connection establishment
`milter_command_timeout`	30s	Individual SMTP commands (HELO, MAIL FROM, RCPT TO)
`milter_content_timeout`	300s	Message body / DATA phase (end-of-message)

When a milter hangs during the DATA phase, the smtpd process blocks for up to milter_content_timeout (300 seconds by default). When it hangs during a command stage, the block lasts up to milter_command_timeout (30 seconds). Either way, that smtpd process is unavailable for other work.

flowchart TD
    A[Milter stops responding] --> B[smtpd blocks on milter reply]
    B --> C[Process tied up for full timeout]
    C --> D{maxproc reached?}
    D -- Not yet --> E[Mail acceptance slows]
    D -- Yes --> F[New connections queue in listen backlog]
    C --> G[Timeout fires: milter_default_action]
    G --> H[tempfail: 4xx, client retries]
    G --> I[accept: mail passes unfiltered]
    G --> J[shutdown: 421, client dropped]

The cascade is straightforward: milter stops responding, smtpd blocks on the milter reply, the process stays tied up, more processes accumulate toward maxproc, and new connections cannot get smtpd processes. When the timeout fires, milter_default_action determines the outcome.

Postfix 3.11 changed the default `milter_default_action` from tempfail to shutdown. The shutdown action disconnects the remote SMTP client with a 421 response instead of returning a 4xx tempfail that lets the client retry on the same connection. This was introduced to fix a problem where a single milter error would tempfail all subsequent messages on a long-lived SMTP connection.

Common causes

Cause	What it looks like	First thing to check
Milter process dead or crashed	smtpd logs `milter-reject: END-OF-MESSAGE` with 4.7.1; no milter process in process table	`systemctl status opendkim` or equivalent; verify milter socket exists
Milter socket permission mismatch	Postfix logs “connect to milter” errors with “No such file or directory” or “Permission denied”; milter is running but socket is unreachable	Socket path relative to Postfix chroot at `/var/spool/postfix`
Milter overloaded or slow	Connections accepted but DATA phase takes 10-60+ seconds; milter process at high CPU or memory; intermittent `milter-reject` entries	Milter process resource usage; milter response latency
Per-milter syntax error	smtpd fails to start; log shows “malformed option: missing ‘=’ after attribute name”	Check `smtpd_milters` for spaces around `=` in per-milter settings
DNS-dependent milter timing out	milter-greylist or SPF-based milter slow on certain sender domains; only some messages affected	DNS resolver latency from the MTA host

Quick checks

# Check current milter timeout and default action settings
postconf -h milter_connect_timeout milter_command_timeout milter_content_timeout milter_default_action

# Show configured milters
postconf -h smtpd_milters non_smtpd_milters

# Show smtpd master.cf entry (includes maxproc)
postconf -M smtp/inet

# Current smtpd process count vs maxproc (default maxproc is 100)
pgrep -c smtpd

# Recent milter-related log entries
journalctl -u postfix -g milter --since "1 hour ago" | tail -30
# On systems without journald:
grep -i milter /var/log/mail.log | tail -30   # Debian/Ubuntu
grep -i milter /var/log/maillog | tail -30    # RHEL/CentOS

# Milter-reject patterns (classic timeout symptom)
journalctl -u postfix -g 'milter-reject' --since "1 hour ago" | tail -20

# Check milter process health
systemctl status opendkim   # or milter-greylist, rspamd, etc.

# Check milter socket accessibility from Postfix chroot perspective
ls -la /var/spool/postfix/var/run/opendkim/ 2>/dev/null
# If milter listens on a TCP port:
ss -tlnp | grep -E '8891|12345'

How to diagnose it

Confirm smtpd processes are accumulating. Compare the current smtpd process count against the service’s maxproc (postconf -M smtp/inet, default 100). If the count is near maxproc but legitimate traffic is low, processes are stuck on slow operations. When maxproc is reached, new connections queue in the kernel listen backlog and clients experience delayed 220 banners.
Check milter health directly. Verify the milter process is running and its socket or TCP port is accessible. If Postfix runs chrooted (common on Debian and Ubuntu), the milter socket must be inside /var/spool/postfix or Postfix cannot reach it. A socket at /var/run/opendkim/opendkim.sock is unreachable from inside the chroot. It must be at /var/spool/postfix/var/run/opendkim/opendkim.sock.
Examine the log timeline. Look for the progression: “connect from” (client connects), then a long gap, then either milter-reject: END-OF-MESSAGE or a timeout warning. The gap between connection and milter-reject tells you which timeout is firing. A roughly 30-second gap points to milter_command_timeout. A roughly 300-second gap points to milter_content_timeout.
Determine whether all messages or only some are affected. If only messages from certain sender domains are slow, the milter may be doing DNS lookups that time out. If all messages are affected, the milter process itself is likely down or unresponsive.
Check your Postfix version and milter_default_action. Run postconf -h milter_default_action to see the effective value. On Postfix 3.11+, the default is reportedly shutdown, meaning clients get disconnected with 421 rather than receiving a tempfail. This changes the visible symptom: instead of deferred messages in the queue, you see connection drops and clients retrying from scratch.
Test the milter socket directly. If the milter uses a unix socket inside the chroot, verify file permissions and ownership. Postfix runs as the postfix user. The socket must be accessible by that user or by a group that includes it. On systems using TCP milter connections, verify the port is listening and responds.

Metrics and signals to monitor

Signal	Why it matters	Warning sign
smtpd process count vs maxproc	Each blocked smtpd reduces acceptance capacity	Sustained count above 80% of maxproc
milter-reject log rate	Indicates milter timeouts firing in production	Sudden spike or sustained nonzero rate
Listen backlog queue depth	smtpd has reached maxproc and connections are queuing	Growing backlog with delayed 220 banners
Incoming queue growth	Mail accepted but not entering active delivery	Incoming queue growing while active queue stays low
Milter process CPU and memory	Milter overloaded or leaking	Sustained high resource usage or upward growth trend
Milter socket responsiveness	Milter reachable and answering	Connection refused or timeout on direct health check

Fixes

Fix the milter process

If the milter is crashed, restart it. But also investigate why it crashed. Common causes include OOM kills (check dmesg or journalctl -k), database connection failure (ClamAV signature database, Redis for Rspamd), or a bad configuration reload. Restarting without fixing the root cause will repeat the cycle.

Fix socket permissions

The most common cause of “milter unreachable” is a socket path that Postfix cannot access due to its chroot environment. On Debian and Ubuntu, smtpd runs chrooted to /var/spool/postfix by default.

Configure the milter to create its socket at a path inside the chroot. For OpenDKIM, set the socket in /etc/opendkim.conf to a path like local:/var/spool/postfix/var/run/opendkim/opendkim.sock, then reference it in Postfix as unix:/var/run/opendkim/opendkim.sock (the path is relative to the chroot). Alternatively, add the postfix user to the milter’s group so it can access the socket.

Tune milter timeouts per-milter

On Postfix 3.0+, you can set per-milter timeouts and default actions using curly-brace syntax in smtpd_milters:

smtpd_milters = inet:localhost:8891, { inet:localhost:12345, command_timeout=60s, content_timeout=120s, default_action=accept }

Do not put spaces around the = sign in per-milter settings. Spaces cause Postfix to fail at startup with “malformed option: missing ‘=’ after attribute name”.

The default milter_command_timeout of 30 seconds may be too short for milters that do DNS lookups, such as milter-greylist, SPF verification, or Rspamd. Increasing to 60-120 seconds for command-stage timeouts is reasonable. Be cautious about increasing content_timeout too far: if the timeout exceeds the remote SMTP client’s patience, the client may hang up and redeliver, causing duplicate messages.

Choose milter_default_action deliberately

The tradeoff matters:

accept: Mail passes through without the milter’s verdict. Degraded filtering but mail flows. Appropriate for DKIM-signing milters where missing the signature is minor compared to blocking all mail.
tempfail: Mail gets a 4xx response. Clients retry later. Standard behavior on Postfix before 3.11.
reject: Mail gets a 5xx response. Clients do not retry. Use only when you are certain the milter’s absence warrants permanent rejection.
shutdown (Postfix 3.10.8+): Postfix disconnects the SMTP client with 421. Prevents cascading tempfails on pipelined connections but appears as a connection drop to the client. Default on Postfix 3.11+.

For most production setups, accept is the safest degradation mode for non-critical milters. Configure it per-milter if you have multiple milters with different criticality levels. A DKIM-signing milter can safely default to accept while a policy enforcement milter might warrant tempfail.

Increase smtpd maxproc

If the milter is intermittently slow rather than dead, increasing smtpd’s maxproc can provide more headroom. But this is a band-aid, not a fix: more smtpd processes mean more memory usage and potentially more concurrent load on the already-struggling milter.

To increase maxproc, edit the smtp/inet service line in /etc/postfix/master.cf. The maxproc is the column before the command name:

# Increase the value in the maxproc column for smtp/inet
smtp      inet  n       -       y       -       200      smtpd

Then run postfix reload.

Emergency bypass

If mail acceptance is critically blocked and you need to restore flow immediately, temporarily remove the milter:

# CAUTION: this disables filtering on all inbound mail until reverted
postconf -e 'smtpd_milters='
postfix reload

This accepts mail without milter processing. Revert as soon as the milter is healthy.

Note: if you also use non_smtpd_milters, be aware that those milters must not REJECT or TEMPFAIL. When non_smtpd_milters reject or tempfail, Postfix reports a configuration error and mail stays in the queue, because there is no SMTP session to return a response on.

Prevention

Monitor milter response time independently. Do not rely on Postfix logs alone. A health check that connects to the milter socket and measures response latency catches degradation before timeouts fire.
Monitor smtpd process count against maxproc. Sustained counts above 80% indicate processes are blocked on slow operations. Alert before reaching the limit.
Set per-milter timeouts based on milter function. A DKIM-signing milter has different latency characteristics than a greylisting milter that does DNS lookups. Postfix 3.0+ per-milter settings let you tune each one independently.
Verify socket permissions after package updates. Updates to OpenDKIM, Postfix, or the OS can reset socket paths or group memberships. This is the most common cause of milter breakage after routine maintenance.
Test milter failure behavior before you need it. Stop the milter in a staging environment and observe whether milter_default_action behaves as expected.
Keep Postfix patched. Postfix 3.11.5 (July 2026) reportedly includes a fix for a milter client heap overwrite and a cleanup daemon heap over-read that can trigger during a milter shutdown reply. If you run 3.11.x, upgrade to 3.11.5.
Document your milter dependency chain. Know which milters are critical (security policy enforcement) versus additive (DKIM signing, greylisting) so you can make informed decisions about per-milter default_action.

How Netdata helps

smtpd process count vs maxproc correlation: Netdata collects process counts per second, letting you see the exact moment smtpd processes start accumulating and correlate it with milter log events.
Queue subsystem breakdown: Incoming queue growth with low active queue is the signature of filter or milter backpressure. Netdata surfaces each Postfix queue directory independently so you can distinguish milter backpressure from delivery failures.
Milter process health: Netdata monitors the milter process itself (CPU, memory, file descriptors), catching resource exhaustion before it manifests as smtpd hangs.
System-level context: CPU saturation, memory pressure, and disk I/O contention on the MTA host can all degrade milter performance. Netdata’s per-second system metrics let you correlate milter degradation with underlying resource contention.