ANVIL(8)

💖 ANVIL(8) 💖

okay so bestie, you've stumbled into the System Manager's Manual, section 8, and the star of the show is anvil. sit down, grab a snack, we're doing this 🍓

---

✨ NAME ✨

anvil — Postfix session count and request rate control 💅

---

🌸 SYNOPSIS 🌸

anvil [generic Postfix daemon options]

---

🦋 DESCRIPTION 🦋

okay so the Postfix anvil(8) server is basically the bouncer at the club 💪 it keeps statistics about client connection counts, or about client request rates. and why do we care? because that info is what lets you defend against clients that hammer a server — either with too many simultaneous sessions, or with too many successive requests inside a configurable time interval. rude behavior, honestly. not on our watch 💀

and listen, this server is designed to run under control by the Postfix master(8) server. it does not freelance. it does not go rogue. it has a manager and it respects them.

now, throughout this whole page, ident means a (service, client) combination. the exact syntax of that info is application-dependent — and here's the gag — the anvil(8) server literally does not care 🙈 it just passes it along like a good little relay. iconic.

---

🔥 CONNECTION COUNT/RATE CONTROL 🔥

wanna register a new connection? send this to the anvil(8) server:

request=connect
ident=string

and the anvil(8) server hits you back with the number of simultaneous connections AND the number of connections per unit time for that (service, client) combo you specified with ident:

status=0
count=number
rate=number

now to register a disconnect event, send:

request=disconnect
ident=string

and the anvil(8) server replies with:

status=0

no notes. clean. periodt ✨

---

💜 MESSAGE RATE CONTROL 💜

to register a message delivery request, send this:

request=message
ident=string

the anvil(8) server answers with the number of message delivery requests per unit time for the (service, client) combination specified with ident:

status=0
rate=number

---

🎀 RECIPIENT RATE CONTROL 🎀

to register a recipient request, send:

request=recipient
ident=string

the anvil(8) server answers with the number of recipient addresses per unit time for the (service, client) combination specified with ident:

status=0
rate=number

---

🌈 TLS SESSION NEGOTIATION RATE CONTROL 🌈

heads up bestie: everything in this section is available with Postfix 2.3 and later. if you're on something older, this part is not for you, sorry 😭

to register a request for a new (i.e. not cached) TLS session, send:

request=newtls
ident=string

the anvil(8) server answers with the number of new TLS session requests per unit time for the (service, client) combination specified with ident:

status=0
rate=number

and now — and this is the good part — if you wanna retrieve new TLS session request rate info without updating the counter information, you send:

request=newtls_report
ident=string

and the anvil(8) server answers with the number of new TLS session requests per unit time for the (service, client) combination specified with ident:

status=0
rate=number

look at you, reading without writing. main character energy 👑

---

👑 AUTH RATE CONTROL 👑

to register an AUTH request, send:

request=auth
ident=string

the anvil(8) server answers with the number of auth requests per unit time for the (service, client) combination specified with ident:

status=0
rate=number

---

🔒 SECURITY 🔒

the anvil(8) server does not talk to the network and does not talk to local users, and it can run chrooted at fixed low privilege. it's giving "minding its own business" and honestly? we stan 🫶

the anvil(8) server maintains an in-memory table with information about recent clients requests. and no, nothing gets written down permanently — no persistent state is kept, because standard system library routines are not sufficiently robust for update-intensive applications. that's not a vibe, that's just the truth.

⚠️ even though the in-memory state is kept only temporarily, this may require a lot of memory on systems that handle connections from many remote clients. so if your box is sweating 💀 the move is: reduce the time unit over which state is kept. less time kept = less memory held. simple math, slay.

---

🩺 DIAGNOSTICS 🩺

problems and transactions get logged to syslogd(8) or postlogd(8). that's the diary, basically 📓

upon exit, and every anvil_status_update_time seconds, the server logs the maximal count and rate values measured, together with (service, client) information and the time of day associated with those events. receipts. timestamps. the whole package.

and to avoid unnecessary overhead, no measurements are done for activity that isn't concurrency limited or rate limited. efficiency queen. she does not do unpaid labor 💅

---

💀 BUGS 💀

okay so this is the part where we're honest. here we go:

• systems behind network address translating routers or proxies appear to have the same client address and can run into connection count and/or rate limits falsely. not their fault, but the damage is real 😭
• in this preliminary implementation, a count (or rate) limited server process can have only one remote client at a time. and if a server process reports multiple simultaneous clients, state is kept only for the last reported client. yeah. only the last one. the others get ghosted 🙈
• the anvil(8) server automatically discards client request information after it expires. and to stop the anvil(8) server from discarding client request rate information too early or too late, a rate limited service should always register connect/disconnect events even when it does not explicitly limit them. yes, even then. always. i said what i said 🎀

---

⚙️ CONFIGURATION PARAMETERS ⚙️

on low-traffic mail systems, changes to main.cf get picked up automatically, because anvil(8) processes run for only a limited amount of time. on other mail systems, run the command postfix reload to speed up a change. faster. better. reloaded ✨

and just so we're clear: the text below is only a parameter summary. for more details, including examples, go read postconf(5). iykyk.

• anvil_rate_time_unit (60s) — the time unit over which client connection rates and other rates are calculated.
• anvil_status_update_time (600s) — how frequently the anvil(8) connection and rate limiting server logs peak usage information.
• config_directory (see 'postconf -d' output) — the default location of the Postfix main.cf and master.cf configuration files.
• daemon_timeout (18000s) — how much time a Postfix daemon process may take to handle a request before it is terminated by a built-in watchdog timer.
• ipc_timeout (3600s) — the time limit for sending or receiving information over an internal communication channel.
• max_idle (100s) — the maximum amount of time that an idle Postfix daemon process waits for an incoming connection before terminating voluntarily.
• max_use (100) — the maximal number of incoming connections that a Postfix daemon process will service before terminating voluntarily.
• process_id (read-only) — the process ID of a Postfix command or daemon process.
• process_name (read-only) — the process name of a Postfix command or daemon process.
• syslog_facility (mail) — the syslog facility of Postfix logging.
• syslog_name (see 'postconf -d' output) — a prefix that is prepended to the process name in syslog records, so that, for example, "smtpd" becomes "prefix/smtpd".

available in Postfix 3.3 and later:

• service_name (read-only) — the master.cf service name of a Postfix daemon process.

---

🫶 SEE ALSO 🫶

• smtpd(8), Postfix SMTP server
• postconf(5), configuration parameters
• master(5), generic daemon options

---

📚 README FILES 📚

use "postconf readme_directory" or "postconf html_directory" to locate this information.

• TUNING_README, performance tuning

---

📜 LICENSE 📜

the Secure Mailer license must be distributed with this software. not optional. read it, bestie 📖

---

🕰️ HISTORY 🕰️

the anvil service is available in Postfix 2.2 and later. she's been around. she's seen things. she's still serving 💅

---

🌟 AUTHOR(S) 🌟

• Wietse Venema
• IBM T.J. Watson Research
• P.O. Box 704
• Yorktown Heights, NY 10598, USA
• Wietse Venema
• Google, Inc.
• 111 8th Avenue
• New York, NY 10011, USA

---

and that's the whole page, bestie 💖 it's ANVIL(8) out of the System Manager's Manual — go forth, rate limit responsibly, and remember: no measurements are done for activity that isn't concurrency limited or rate limited ✨🦋🌸