docs: per-step delivery timeouts, trusted proxies and the confirmation cap

- Describe the phases of a delivery and the unknown-outcome retry
- Document web.trusted_proxies, the form's address rules and limits.pending_per_hour
This commit is contained in:
tgiachi 2026-11-10 15:21:24 +01:00
commit fa96a398ee

View file

@ -79,7 +79,9 @@ A publisher's post passes the same identity check as any post: the `From` header
**Rate limiting.** Relays such as Amazon SES throttle sending. Set `relay.rate_per_second` to the most sends the daemon may start in one second (default `0`, unlimited). One pacer sits in front of every send attempt, retries included, and spaces them evenly. Set it a little under your relay's limit (12 for a limit of 14). Each recipient is one message, so a post to N members takes about N divided by the rate in seconds.
**Subscribe form.** A list whose archive is public and whose join policy is open gets a signup page at `/subscribe/{address}` on the public web listener, linked from its archive page. It sends the usual double opt-in message. The page that follows is always the same, whether or not the address is a member or the list qualifies for mail, so the form cannot be used to find out who is subscribed. A hidden field catches bots; each IP (the TCP peer, `X-Forwarded-For` is ignored) may post 10 times per hour, then gets `429`; behind a reverse proxy every visitor shares its address, so limit at the proxy too. The body is capped at 4 KiB.
**Subscribe form.** A list whose archive is public and whose join policy is open gets a signup page at `/subscribe/{address}` on the public web listener, linked from its archive page. It sends the usual double opt-in message. The page that follows is always the same, whether or not the address is a member or the list qualifies for mail, so the form cannot be used to find out who is subscribed. A hidden field catches bots; each client (an IPv4 address or an IPv6 /64) may post 10 times per hour, then gets `429`. Behind a reverse proxy, list the proxy in `web.trusted_proxies` (addresses or CIDR ranges, default empty): `X-Forwarded-For` is then read only from those proxies, and the client is its right-most address that is not a trusted proxy. With the list empty the header is ignored and the TCP peer is the client, so every visitor behind a proxy shares one budget. Make sure the proxy appends to `X-Forwarded-For` and cannot be bypassed. At most 100000 clients are tracked; past that, new clients get `429` until a window ends. The form refuses addresses at `localhost`, at bare IPs or `[literals]`, and at names ending in `.local`, `.localhost`, `.internal` or `.invalid`. The body is capped at 4 KiB.
**Confirmation cap.** Each subscribe or unsubscribe request sends a confirmation mail. At most `limits.pending_per_hour` of them (default 300) are accepted per hour across all lists. Past that, requests get no mail, the visitor still sees the usual page, and the daemon logs a warning at most once a minute. Raise it before a newsletter launch.
Not included: scheduled sends and open or click tracking.
@ -242,6 +244,8 @@ relay:
## Delivery and the queue
Each delivery has a time limit per step rather than one overall. Connecting, the greeting, TLS, authentication and the envelope get 60 seconds together. Sending the message gets 60 seconds plus one second per 32 KiB, at most 10 minutes. The relay then has 10 minutes to accept it, as RFC 5321 recommends, so a relay that runs content filters is not cut off and does not receive the message twice. If the relay never answers after the whole message was sent, the delivery is retried and the error in the queue says the outcome is unknown: the relay may already have it.
LMTP answers `250` when the post is in the queue, so a down relay never bounces mail back to Postfix.
It answers `451` only when the database itself fails.