greylist.conf(5)

🎀 greylist.conf(5) 🎀

okay bestie, sit DOWN, because this is the manual page for greylist.conf(5) and it is genuinely iconic. 💅

---

✨ NAME ✨

greylist.conf — the configuration file for milter-greylist(8). yep that's it, that's the name, slay.

---

🌸 DESCRIPTION 🌸

So. greylist.conf is literally the thing that configures how milter-greylist(8) operates. the format? super simple, no cap:

• every line = a keyword + optional arguments
• any line that starts with a # is a comment and gets straight up ignored, bye 👋
• blank lines are ignored too, they're just vibes
• comments at the end of lines are accepted in some situations, but do NOT take them for granted bestie, don't test it
• a statement can be continued onto the next line by using a backslash. anything after the backslash gets ignored. so like, keep it tidy. ✨

---

🦋 WHITELIST 🦋

the primary use of greylist.conf is to set up the milter-greylist(8) whitelist. but it also offers a handy blacklist feature, because why not, main character energy. 💅

Access-lists (ACL) are how you do all that. ACL let the administrator specify complex conditions on:

• sender IP
• sender DNS address
• sender e-mail address
• recipient e-mail address

and if support for DNSRBL was built-in, you can even use DNSRBL in ACL. obsessed. ✨

An access-list entry starts with the racl keyword, followed by an optional id quoted string, then the greylist, whitelist, blacklist, or continue keyword, and then by any set of the following clauses:

• addr
• domain
• from
• rawfrom
• rcpt
• rcptcount
• helo
• sm_macro
• time
• auth
• tls
• spf (if build with SPF support)
• geoip (if build with GeoIP support)
• p0f (if build with p0f support)
• ldapcheck (if build with --with-openldap)
• urlcheck (if built with --with-libcurl)
• dnsrbl (if built with --enable-dnsrbl)
• nsupdate (if supported by the DNS resolver)

A message will match an ACL entry when it complies with all of its clauses. all of them. every single one. no skipping. 🫶

The greylist, whitelist, and blacklist keywords will cause the message to be respectively greylisted, accepted or rejected if all ACL clauses match — and then ACL evaluation is terminated right there. done. periodt.

If an ACL with the continue keyword does match, nothing is decided and the next ACL gets evaluated. it's giving "we'll circle back". 🙈

Clauses can be negated by prefixing them with the not keyword. and now, the detail of all possible clauses:

• addr — this clause specifies a netblock of source IP addresses. the syntax is an IP address, followed by a slash, followed by a CIDR netmask. example time:

  racl whitelist addr 127.0.0.0/8
  racl whitelist addr 192.168.3.0/24
  racl whitelist addr ::1

if the netmask is omitted, /32 is assumed for an IPv4 address and /128 is assumed for an IPv6 address. bestie you should at least whitelist localhost (127.0.0.1/8), and if you've got user clients connecting to the machine, whitelist the addresses they connect from — unless you want them getting error messages when they send e-mail. your call, but like. 😭

• domain — this clause selects source machines based on their DNS name, performing a suffix search. for instance, this will whitelist any machine in the example.net domain:

  racl whitelist domain example.net

Suffix search matching means, for example, that gle.com will match google.com. if you want domain names to match on subdomain boundaries (e.g. gle.com will match mail.gle.com and gle.com but not google.com) then enable domainexact.

The name resolution is made by Sendmail, which hands it to milter-greylist(8). as a result, it is impossible to use DNS aliases here. on the other hand, this will work even if your DNS resolver is not thread-safe. silver lining ✨

• from — this is used to select sender e-mail addresses. you should NOT use that feature, because sender e-mail addresses can be trivially forged. like trivially trivially. 💀

Please note that the sender e-mail is cleared from spaces and anything leading an equal (=) sign so that mailing-lists return-address with unique return paths can still match. if you need the unedited sender address, use a rawfrom clause instead.

Here is an example:

  racl whitelist from postmaster@example.com

• rawfrom — same as from but the sender e-mail address is not modified to stip anything.
• rcpt — this is used to select recipient addresses. Example:

  racl greylist rcpt John.Doe@example.net

• rcptcount — followed by an operator and a recipient count, this is used to select the amount of recipients. Example:

  racl blacklist rcptcount >= 25 msg "No more than 25 recipients, please"

• helo — followed by a quoted string or a regular expression, this can be used to filter on the HELO string.
• sm_macro — this is used to select a Sendmail macro value. see the section on that topic for more information.
• time — this is used to specify a time set. it should be followed by a quoted string of crontab(5)-like time specification. here's an example that whitelists mail addressed to a single recipient during office hours (from 8:00 to 16:59 from monday to friday):

  racl whitelist time "* 8-16 * * 1-5" rcpt info@example.net

• geoip — this is used to specify a country, as reported by GeoIP. the country code must be upper case, and is only available if milter-greylist was built with GeoIP support. special country code ZZ is used when the country cannot be determined (this happens for private addresses, for instance). the geoipdb statement can be used to specify the location of the GeoIP database. the geoipv6db statement can be used to specify the location of the GeoIPv6 database. the geoip2db statement can be used to specify the location of the GeoIP2 (maxminddb) database. so many databases bestie 💖
• p0f — this is used to match against the remote system OS fingerprint genre and detail, obtained from p0f. it is only available if milter-greylist was built with p0f support. p0f clauses can be used with a quoted string for case-insensitive substring match, or against regular expressions. the p0fsock statement can be used to specify the location of the p0f socket.
• auth — this is used to select a user that succeeded SMTP AUTH. in order to select any user that succeeds SMTP AUTH, you can use a regular expression matching, like below:

  racl whitelist auth /.*/

Using such a clause automatically disable global STARTTLS and SMTP AUTH whitelisting, like if the noauth keyword would have been used. heads up. ⚠️

• tls — this is used to select the distinguished name (DN) of a user that succeeded STARTTLS. using such a clause automatically disable global STARTTLS and SMTP AUTH whitelisting, like if the noauth keyword would have been used. same energy as above, bestie.
• spf — this is used to test SPF status. possible values are pass, softfail, fail, neutral, unknown, error, none, and self. the first seven values are plain SPF validation status. the self value is a special test that checks the server's local IP address against the sender's SPF record. if that test validates, odds are good that the sender SPF record is wide open, and this is a hint that SPF should not be trusted. 👀

In order to use spf self, Postfix users must specify the local address in the configuration file, using the localaddr option.

Absence of any value after the spf keyword is a synonym for spf pass. this is present for backward compatibility. 🫶

The spf clause is only available if SPF support was compiled in. using it will disable global SPF whitelisting, like if the nospf keyword would have been used.

• ldapcheck — this is used to query an LDAP directory. see the section on that topic for more information.
• urlcheck — this is used to query an external configuration source through an URL. see the section on that topic for more information.
• dnsrbl — this is used to select a DNSRBL. see the section on that topic for more information.
• nsupdate — this always-matching clause performs a DNS update, see the section on that topic for more information.

---

💫 regex & matching tea 💫

The domain, from, and rcpt clauses may be used with regular expressions. the regular expressions must be enclosed by slashes (/). no escaping is available to provide a slash inside a regular expression, so just do not use it. regular expressions follow the format described in re_format(7). here's an example:

  racl greylist rcpt /@example\.net$/

When regular expressions are not used, from and rcpt perform a case insensitive substring match with leading and trailing brackets, spaces and tabs stripped out. domain performs a case insensitive suffix match. this means, for example, that gle.com will match google.com. if you want domain names to match on subdomain boundaries (e.g. gle.com will match mail.gle.com and gle.com but not google.com) then enable domainexact.

---

🍓 optional parameters on match 🍓

An ACL entry can also hold various optional parameters used on match:

delay, autowhite, flushaddr, nolog, code, ecode, report, maxpeek, addheader, addfooter, and msg. so many little extras, it's giving ✨options✨.

• delay — specify the greylisting delay used before the message can be accepted. this overrides the greylist global setting, and it only makes sense on an racl greylist entry.
• autowhite — specify the autowhitelisting duration for messages matching this ACL. this overrides the autowhite global setting, and it only makes sense on an racl greylist entry. Example:

  racl greylist rcpt JDoe@example.net delay 15m autowhite 3d
  racl greylist rcpt root@example.net delay 1h autowhite 3d

• flushaddr — if a message matches the rule, any entry in the greylist or autowhite databases matching the sender IP is removed. used with a DNSRBL blacklist ACL, it is useful for freeing the database from entries set up by a machine which is known to be a spammer. Example:

  racl blacklist dnsrbl "known-spammer" flushaddr

• nolog — do not generate syslog message if this rule matches. Example:

  racl whitelist default nolog

• code
• ecode
• msg

These 3 values can be used to choose the SMTP code, extended code and reply message for temporary failures and rejects. Example:

  racl blacklist dnsrbl "spamstomp" msg "IP caught by spamstomp"
  racl greylist default code "451" ecode "4.7.1"

The msg strings accepts format string substitution as documented in the FORMAT STRINGS section. for instance, %A gets substituted by the ACL line number. cute, right? 🎀

None of the last 3 values makes sense for a whitelist entry. sorry bestie, them's the rules. 💅

• report — overrides whatever text the X-Greylist header shows for messages that milter-greylist(8) lets through — whether that's because they're whitelisted or because they actually survived greylisting (peep the REPORTING section for the deets). You can do substitutions in this string, exactly as documented in FORMAT STRINGS. 💖
• maxpeek — this one only makes sense inside a RCPT-stage ACL, okay? It overrides the global maxpeek setting for the DATA-stage handling of the message. And heads up: it does absolutely nothing if the global maxpeek is set to 0. 🙈
• addheader — this quoted string is an RFC822 header that gets added to the message. Format string substitution is supported here too. No check is done for header length standard compliance, so pls make sure the substituted string stays shorter than 2048 characters, bestie. Headers get appended to the bottom, unless you specify an optional comma-separated positive index after the quoted string — in that case the header gets inserted at that index point from the top. Example time:

racl continue addheader "X-Personnal-Header: Hello world!",1

• addfooter — appends a footer to the message. The usual escape sequences like \n work for special characters. The string is subject to format string expansion as described in the FORMAT STRINGS section. The footer will not be appended if milter-greylist wasn't able to capture the whole message, so maxpeek must be set appropriately. 👑

---

Entries in the access-list are evaluated sequentially, so order is literally everything. The first matching entry is the one that decides if a message gets whitelisted or greylisted. And there's a special default clause you can drop into the last ACL entry to act as a wildcard. 🦋

Here are a few complete ACL examples:

Example 1:

racl whitelist from friend@toto.com rcpt grandma@example.com
racl whitelist from other.friend@example.net rcpt grandma@example.com
racl greylist rcpt grandma@example.com
racl whitelist default

Example 2:

racl whitelist addr 193.54.0.0/16 domain friendly.com
racl greylist rcpt user1@atmine.com
racl greylist rcpt user2@atmine.com
racl greylist rcpt user3@atmine.com
racl whitelist default

Example 3:

racl whitelist rcpt /@.*otherdomain\.org$/
racl whitelist addr 192.168.42.0/24 rcpt user1@mydomain.org
racl whitelist from friend@example.net rcpt /@.*mydomain\.org$/
racl whitelist rcpt user2@mydomain.org
racl greylist rcpt /@.*mydomain\.org$/
racl whitelist default

🫶 DATA-STAGE ACL 🫶

ACLs using the racl keyword get evaluated at the RCPT stage of the SMTP transaction. But bestie, you can also have an ACL evaluated at the DATA stage of the SMTP transaction, using the dacl keyword — provided the message went through RCPT-stage ACL, and possibly greylisting. 💅

Heads up: you cannot use the greylist action at DATA-stage if the RCPT-stage ACL that matched had a greylist action itself. Just so you know.

The following clauses can be used to work on message content:

• dkim — DKIM status (if built with DKIM support). Possible values are pass, fail, unknown, error, and none.
• header — string or regular expression searched in message headers.
• body — string or regular expression searched in message body.
• msgsize — operator followed by a message size (k or M suffix allowed for kilobytes or megabytes). Example:

dacl blacklist msgsize >= 4M msg "No more than 4 MB please"

• spamd — SpamAssassin score (if built with SpamAssassin support). If used without a comparison operator, spamd is true if the score is above threshold. The spamdsock keyword can be used to specify the location of the spamd socket.

Example 1:

spamdsock unix "/var/spamassassin/spamd.sock"
racl whitelist default
dacl greylist spamd

Example 2:

spamdsock inet "127.0.0.1:783"
racl whitelist default
dacl blacklist spamd > 15 msg "Your message is considered spam."
dacl greylist  spamd > 10 delay 2h
dacl greylist  spamd > 5  delay 1h

Note that if there are multiple recipients, a rcpt clause at DATA stage evaluates to true if it matches any of them. And if you wanna match an exact set of recipients, you can use multiple rcpt clauses along with a rcptcount clause. ✨

🌸 LISTS 🌸

It is often useful to group several users or sender IP addresses into a single ACL. This can be done with lists. Lists must be first defined and given a name before they can be used in ACL entries. Example:

list "my users" rcpt { user1@example.com user2@example.com }
list "local" addr { 192.0.2.0/24 10.0.0.0/8 }

racl whitelist list "local"
racl greylist list "my users"
racl whitelist default

💜 BACKWARD COMPATIBILITY 💜

Previous versions of milter-greylist(8) used addr, domain, from, and rcpt lines, without the racl keyword. Access-list management is intended to replace them. These lines are still accepted by milter-greylist(8), but they are deprecated. 😭 milter-greylist(8) handles them as access-list entries with a single clause. They are added at the head of the access-list, so using these keywords and access-lists may lead to unspecified behaviour. Do not mix them, fr fr.

Test mode (using -T) is also deprecated. Access-list semantics do not depend on this flag.

milter-greylist(8) also used to only have a RCPT-stage ACL, which was configured through acl statements. These have been replaced by racl statements (as opposed to dacl statements for DATA-stage ACL). acl statements are still accepted for backward compatibility and are a synonym for racl statements.

🌈 MX SYNC 🌈

Synchronization of the greylist among multiple MX is configured using the peer keyword. List each other MX IP addresses using the peer keyword. Example:

peer 192.0.2.18
peer 192.0.2.17
peer 192.0.2.22 timeout 7
peer 192.0.2.38 timeout 5m

You can list the local machine in the peer statements — it will be ignored. 🙈

The timeout clause sets a peer communication timeout to have proper retrial in case of a slow MX peer. The default value is 3 seconds. The special value of 0 disables the connection retrials.

By default, milter-greylist will listen on all interfaces using TCP port 5252 or the port number given by service named mxglsync if defined in /etc/services or other directory service. This behaviour can be changed by using the syncaddr keyword. A few examples:

syncaddr *
syncaddr * port 7689
syncaddr 192.0.2.2 port 9785
syncaddr 2001:db8::1:c3b5:123
syncaddr 2001:db8::1:c3b5:123 port 1234

Using '*' as the address means to bind to all local interfaces' addresses. Note that if you are not using the default port, all MXs must use the same port number. 💅

For outbound connections the system is selecting one of the possible addresses. If you want to use a specific IP you can use:

syncsrcaddr 123.456.78.9

🎀 TEXT DUMP 🎀

milter-greylist(8) uses a text dump of its database to resume operation after a crash. The dump is performed at regular time interval, but since it's a heavy operation, you might wanna configure a particular time interval using the dumpfreq option.

If the dumpfreq value is too small, it will kill performance. If it is too high, you will loose a bigger part of the database on a crash. 😬

Set dumpfreq to 0 to get a dump on each change (kills performance), set it to -1 to never dump to a file (unsafe, as you lose the whole greylist on each crash), or give a time value for the delay between dumps. The time is given in seconds, except if a unit is given: m for minutes, h for hours, and d for days.

You may further improve the performance of the dump operation at the expense of humanly readable timestamp, which by default appears as a comment at the end of each line in the dumpfile. You may disable generation of this comment by specifying dump_no_time_translation option in the configuration file. This is specifically recommended if your dumpfile grows to 100's of megabytes — it can reduce the time needed for the dump operation by the order of magnitude! 🔥

⭐ REPORTING ⭐

By default, milter-greylist(8) will add a X-Greylist header to any message it handles. The header shows what happened to the message: delayed or not delayed, and why. The following options can be used in greylist.conf to alter this behavior:

• report none — never add a X-Greylist header.
• report delays — only add a header if the message was delayed.
• report nodelays — add a header if the message was not delayed. The header explains why the message was not delayed.
• report all — always add a header. This is the default.

🦋 SENDER CALLBACK SYSTEMS 🦋

Sender callback systems are another anti-spam measure that attempts to send a DSN to the sender address before accepting a message. If that fails, then the sender address is wrong and the message is rejected. Such systems usually stop their callback check at the RCPT stage of the SMTP transaction.

Greylisting temporarily rejects at the RCPT stage, so sender callback and greylisting love to fight each other. 😭 milter-greylist(8) proposes a workaround to that problem with the delayedreject option. For messages coming from <> (that is, for DSN), it will cause the temporary reject to happen at the DATA stage of the SMTP transaction instead of the RCPT stage. That way, milter-greylist(8) will cope much better with sender callback systems. 💖

This has a minor drawback (and this is why it is not enabled by default): for a multi recipient DSN, whitelisted recipient will not be honoured — the message will be delayed for everyone. 🙈

👑 SENDMAIL MACROS 👑

Any sendmail macro can be used as a clause in the access list. You need to define a (macro, value) pair using the sm_macro keyword before using it. Here is an example that uses the {client_resolve} macro to apply a larger greylisting delay to hosts that have a bogus reverse DNS:

sm_macro "maybe_forged" "{client_resolve}" "FORGED"

racl greylist sm_macro "maybe_forged" delay 1h
racl greylist default delay 15m

A regular expression can be used as the macro value. It must be surrounded with slashes and not by quotes. The special value unset can also be used to match an unset macro:

sm_macro "not_foo" "{foo}" unset

Note that any Sendmail macro that is not exported using the Milter.macros.envrcpt setting of sendmail.cf will be seen as unset from milter-greylist. ✨

🌈 DNSRBL 🌈

DNS Reverse Black List — DNSRBL for short — is the glow-up that lets a whole ACL get toggled on and off. But bestie, they gotta be defined and named first, you can't just manifest them. Here's an example where hosts stuck in the SORBS dynamic pool get a bigger greylisting delay (and yes, that pool includes DSL and cable customer ranges, which are famously riddled with spamware infections, no cap):

dnsrbl "SORBS DUN" dnsbl.sorbs.net 127.0.0.10/32

racl greylist dnsrbl "SORBS DUN" delay 1h
racl greylist default delay 15m

A DNSRBL definition kicks off with the dnsrbl keyword, then the quoted name of the DNSRBL, then the DNS domain where addresses get looked up, then the answer we're counting as a positive hit. That's it, that's the whole vibe.

🚨 Two things, and I mean it: DNSRBL support only exists if you turned it on with the --enable-dnsrbl config flag. And please, please make sure milter-greylist(8) is linked against a thread-safe DNS resolver — otherwise it shall crash. Like, crash crash. 💀

---

🌸 DNS updates 🌸

ACLs can trigger a DNS update, which is how you feed a DNSRBL. This functionality is enabled at build time — but only if the DNS resolver actually has DNS update support, so it's giving "depends on your build" energy.

Configuration happens with the nsupdate statement, which you're allowed to use several times, plus the optional tsig statement if you want authenticated DNS update. Example syntax:

tsig "dns-update" "hmac-md5" "1B2M2Y8AsgTpgAmY7PhCfg=="
nsupdate "bl.example.net" { rname "%j.bl.example.net" rvalue "127.0.0.2" tsig "dns-update" }

The options for nsupdate are:

• rname — the created record name, which uses format strings.
• rvalue — the created record value, which uses format strings.
• servers — a quoted comma-separated list of the DNS servers the update should be sent to. Default is to use the system configuration, usually from /etc/resolv.conf.
• ttl — TTL of the created DNS record. Default is 0 seconds.
• class — created record class, as a numeric value. Default is 1, for the IN class.
• type — created record type, as a numeric value. Default is 1, for the A type.
• tsig — the name of a tsig configuration, which must have been supplied before. If unspecified, unauthenticated DNS updates are performed.

Once it's configured, DNS updates can be used in any ACL:

racl blacklist rcpt spamtrap@example.net nsupdate "bl.example.net"

---

✨ PROPERTIES ✨

Properties are variables that can be set, evaluated and printed in an ACL. A property can be dropped once the current recipient is processed, or it can be retained until the message is processed. They get created through these always-matching ACL clauses:

• set $name="value" — sets a property that will be retained for all next recipients. The right hand side of the clause may be a quoted string (which gets substituted using format strings, as described in the FORMAT STRINGS section), a number, or another property name (which gets substituted by the property value).
• rset $name="value" — same as the set clause, except the property gets dropped once the current user has been processed.
• urlcheck — these clauses cause properties to be fetched from an external web service. See the URL checks section below for the deets.
• ldapcheck — these clauses cause properties to be fetched from an LDAP directory. See the LDAP CHECKS section below for the deets.

Properties can be used as the left-hand side part of ACL clauses:

racl blacklist $name "badvalue"
racl blacklist $name /badregex/

If used on the left-hand side and prefixed by a star, the property gets evaluated as a glob(7) pattern. In the example below, if the sender DNS domain is test.example.net and $domain is *.example.net, we get a match:

racl blacklist *$domain "%f"

They're also available as the right-hand side of many ACL clauses:

racl continue set $badword="spam"
racl blacklist body $badword

Values of properties can be obtained in any quoted string that is subject to format string expansion:

racl continue set $webmaster="webmaster@example.net"
racl blacklist domain evil.net msg "blacklisted, ask $P{webmaster} why"

When the property value is a number, it can be increased or decreased using this syntax:

racl continue set $score+=5
racl continue set $score-=5

Here again, the right hand side may be a quoted string, a number, or another property. For the quoted string and property cases, a conversion is first made to an integer, using 0 as the value on failure. And note — no arithmetic evaluation occurs. For instance, the quoted string "1 + 1" will be evaluated as 0. Yes really. 🙈

The log ACL clause can be helpful when you need to figure out what happens to property values during the ACL flow. See the CUSTOM REPORT section for more details.

---

🦋 URL checks 🦋

milter-greylist(8) is able to query external sources of information through various URLs — if it was built with --with-libcurl. Here's an example:

urlcheck "glusr" "http://www.example.net/mgl-config?rcpt=%r" 5

racl greylist urlcheck "glusr" delay 15m
racl whitelist default

That trailing 5 at the end of the urlcheck definition is the maximum number of simultaneous connections we want to launch on this URL. For each message, the URL gets queried, with % format tags being substituted. For instance, %r is substituted by the recipient. See the FORMAT STRINGS section for the complete list of substitutions.

milter-greylist(8) expects an answer containing a list of \n terminated lines, with key: value pairs. The most basic answer to get a match is:

milterGreylistStatus: Ok

TRUE can be used as an alias for Ok here.

The answer can be more complex, with keys that will overload the ACL settings:

• milterGreylistDelay — the greylisting delay to use (time unit suffix allowed).
• milterGreylistAutowhite — the autowhite delay to use (time unit suffix allowed).
• milterGreylistFlushAddr — the value is ignored. If this key is present, then the IP address for the sender machine will be flushed from the greylist and autowhite databases.
• milterGreylistCode — the SMTP code to return (e.g.: 551).
• milterGreylistECode — the SMTP extended code to return (e.g.: 5.7.1).
• milterGreylistMsg — the string to return with SMTP codes.
• milterGreylistReport — the string to display in the X-Greylist header.
• milterGreylistIgnore — this line will be ignored, without warnings in the logs.
• milterGreylistAction — this feature is nifty but use it with caution, as it makes the access list a bit difficult to understand. By specifying the values greylist, whitelist, or blacklist, it is possible to overload the ACL action itself.

The ACL will match if any of the above keys is returned: milterGreylistStatus is not mandatory.

Optional keywords can be appended to a urlcheck definition:

• postmsg — on a DATA-stage ACL, this causes the message to be sent (up to maxpeek bytes) in a POST request. Here's an example:

urlcheck "extfilter" "http://www.example.net/f.cgi" 5 postmsg

dacl blacklist urlcheck "extfilter"
dacl whitelist default

• getprop — gather the properties returned by the URL and reuse them in the ACL. The gathered properties can be accessed in the current and following ACL by prefixing them with a dollar ($).
• clear — this causes gathered properties to be cleared on each new recipient. This avoids properties for several recipients mixing together.
• fork — tells milter-greylist(8) to fork a separate instance of itself for performing the queries. Use it if you encounter thread-safety problems. fork is not compatible with postmsg.
• domatch — causes the ldapcheck clause to be evaluated in the ACL. Default behavior is to ignore the result and just fetch properties, except if the LDAP directory is unreachable, in which case a temporary failure occurs. The fixldapcheck global settings may also be used to globally cause all ldapcheck and urlcheck clauses to match.

Here's an example that uses various DNSRBLs depending on a per-recipient setting stored in the dnsrbl attribute of an LDAP directory:

dnsrbl "RBL2" "rbl.example.net" "127.0.0.2"
dnsrbl "RBL3" "rbl.example.net" "127.0.0.3"
dnsrbl "RBL4" "rbl.example.net" "127.0.0.4"
urlcheck "userconf" "ldap://localhost/dc=example,dc=net?milterGreylistStatus,dnsrbl?one?mail=%r" 5 getprop clear

racl blacklist urlcheck "userconf" $dnsrbl "RBL2" dnsrbl "RBL2"
racl blacklist $dnsrbl "RBL3" dnsrbl "RBL3"
racl blacklist $dnsrbl "RBL4" dnsrbl "RBL4"

Note that when matching gathered properties, format strings and regex can be used. 👑

---

🎀 LDAP CHECKS 🎀

If milter-greylist was built with --with-openldap, then you can also use ldapcheck for pulling information from an LDAP directory. This works exactly like urlcheck, except that properties are always collected — the getprop option is implicit.

A list of LDAP URLs to use can be specified with the ldapconf keyword. The network timeout is optional.

ldapconf "ldap://localhost ldaps://ldap.example.net" timeout 2s

When ldaps:// is used, the system's ldap.conf file is used to locate x509 certificates.

When defining LDAP queries with the ldapcheck statement, note that the scheme and host part of the URL are ignored. Servers listed in ldapconf are used instead.

---

💜 RATE LIMIT 💜

The ratelimit keyword specifies a ratelimit configuration to be used in access lists. It must be followed by the rate limit configuration name, what is being accounted (i.e.: session for SMTP sessions, rcpt for recipients, data for bytes in body and headers), the actual limit, and the sampling period. Example:

ratelimit "internalclients" rcpt 10 / 1m

racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
   msg "you speak too much"

The ratelimit keyword can also have an option key statement, which determines the set of keys for message accounting. The default is %i for per-IP-address accounting (see the FORMAT STRINGS sections for the possible syntax of this field). Here's an example that configures a rate limit of 100 messages per hour for each individual recipient-IP set:

ratelimit "internalclients" rcpt 100 / 1h key "%r%i"

racl blacklist addr 192.0.2.0/24 ratelimit "internalclients" \
   msg "you speak too much"

💖 CUSTOM REPORTS 💖

ok so the stat keyword lets you build your own custom report for milter-greylist activity. iconic behavior honestly. you give it an output (either a file or an external command) plus a format string. here's a lil example bestie:

         stat ">>/var/log/milter-greylist.log" "%T{%T},%i,%f,%r,%A\n"

if your output starts with >> or >, congrats, it's a file. use >> to append to a file that already exists, and use > to overwrite it (gone, reduced to atoms, so be careful 💀). if the output starts with a | then it's a shell command instead, like this:

         stat "|logger -p local7.info" "%T{%T},%i,%f,%r,%A\n"

the format string gets substituted the exact same way URL checks format strings do: %r gets swapped for the recipient, %f for the sender, and so on and so forth. run, don't walk, to the FORMAT STRINGS section for the full list of available substitutions. ✨

there's also an always-matching log ACL clause that you can use to yeet a formatted string to syslog with LOG_INFO level. example time:

        racl continue rcpt /@example\.com$/ log "I was here"

---

🌈 COMMAND-LINE FLAG EQUIVALENTS 🌈

most milter-greylist(8) command-line options have equivalent options that you can set in the config file. big news. but heads up: if a command line option is supplied, it always overrides the config file. always. no discussion. 💅

and if a command-line equivalent keyword gets used more than once? the last keyword wins and overrides all the previous ones. periodt.

• verbose — turns on debug output. equivalent to the -v flag.
• quiet — do not tell clients how much time remains before their e-mail will be accepted. equivalent to the -q flag.
• nodetach — do not fork and go into the background. equivalent to the -D flag.
• noauth — greylist clients regardless if they succeeded SMTP AUTH or STARTTLS. equivalent to the -A flag.
• noaccessdb — normally milter-greylist(8) will whitelist a message if sendmail(8) defines a ${greylist} macro set to WHITE. this enables complex whitelisting rules based on the Sendmail access DB. this option inhibits that behavior. 🙅
• nospf — greylist clients regardless if they are SPF-compliant. equivalent to the -S flag.
• testmode — enable test mode. equivalent to the -T flag. > this option is deprecated, bestie. it's giving legacy.
• greylist — the argument sets how much time milter-greylist(8) will want the client to wait between the first attempt and the time the message is accepted. time is given in seconds, except if a unit is given: m for minutes, h for hours, and d for days. the greylist keyword is equivalent to the -w option. example that sets the delay to 45 minutes:

           greylist 45m

• autowhite — sets the auto-whitelisting duration, equivalent to the -a command-line option. same as with the greylist keyword, units can be supplied. here's an example for a 3 day long auto-whitelisting:

           autowhite 3d

• pidfile — makes milter-greylist(8) write its PID into the file given as argument, exactly like the -P command line argument does. the path to the file must be absolute and it must be enclosed in quotes. example:

           pidfile "/var/run/greylist.pid"

• dumpfile — chooses the location of the greylist dump file, like the -d command line option does. the path must be absolute and enclosed in quotes. it can optionally be followed by an octal permission mode. example:

           dumpfile "/var/milter-greylist/greylist.db" 640

• subnetmatch — equivalent to the -L command line option. takes a slash followed by a CIDR mask as argument, and it commands the subnet matching feature. example, for a class C wide matching:

           subnetmatch /24

• subnetmatch6 — equivalent to the -M command line option. takes a slash followed by a prefixlen as argument, and it commands the subnet matching feature. example, for a subnet wide matching:

           subnetmatch6 /64

• socket — like the -p command line option, this keyword specifies the socket used to communicate with sendmail(8). it must be enclosed in quotes and can optionally be followed by an octal permission mode (valid values are 666, 660 or 600 — any other value causes an error, so don't try it 🙈):

           socket "/var/milter-greylist/milter-greylist.sock" 660

• user — should be followed by a quoted user login and optionally a colon followed by a groupname. like the -u option, this is used to run milter-greylist(8) as a non root user. example:

           user "smmsp"

---

🦋 MISCELLANEOUS 🦋

these options have no command line equivalent. they're just built different:

• logfac — sets the syslog facility for messages. can be set to any of the standard facilities: kern, user, mail, daemon, auth, syslog, lpr, news, uucp, cron, authpriv, ftp, local0, local1, local2, local3, local4, local5, local6, local7. can also be set to none to disable syslog output completely. (silence era 🎀)
• timeout — used to control how long greylist tuples are retained in the database. value is in seconds, except if a suffix is given (m for minutes, h for hours, d for days). default is 5 days.
• extendedregex — use extended regular expressions instead of basic regular expressions.
• unbracket — attempt to resolve sender address when the MTA handed it as a bracketed IP address (e.g.: [192.0.2.18]). default is to leave it as is.
• maxpeek — limit (in bytes) how much of messages are examined for header and body searches.
• lazyaw — make auto-whitelist look at just the IP instead of the (sender IP, sender e-mail address, recipient e-mail address) tuple. lowkey efficient of it.
• domainexact — match on subdomain boundaries instead of the default suffix matching. e.g. if domainexact is not enabled (the default) then gle.com will match google.com in addition to gle.com. if domainexact is enabled then domain names will match on subdomain boundaries (e.g. gle.com will match mail.gle.com and gle.com but not google.com).
• drac db — tell where the DRAC DB file is. this is only available if DRAC support was compiled in. example:

           drac db "/usr/local/etc/drac.db"

• nodrac — disable DRAC.
• logexpired — this option causes greylist entries that expire to be logged via syslog. this lets you easily collect the IP addresses and sender names and use them for blacklisting, SPAM scoring, etc. normally, expiration's are only logged if the debug option is set, but that generates a lot of extra messages. so this is the chill version. ✨
• localaddr — this keyword can be used to manually define the local MTA's IP address for such uses as spf self and p0f in absence of the milter-API {if_addr} macro support in your MTA (Postfix, Sun/Oracle CommSuite Messaging Server). this is not so useful when using Sendmail, since it serves the macro and the local address can be detected automatically.

the configuration file is reloaded automatically once it is modified when new e-mail arrives. most configuration keywords will take effect immediately, except the following, which will only take effect after a restart of milter-greylist(8): nodetach, pidfile, socket, and user. 👑

the dumpfreq option can be changed dynamically, but the change will only take effect after the next dump.

• multiracl — by default, once a RCPT-stage ACL whitelists a recipient, the next recipient gets automatically whitelisted. this historical behavior can be considered a bug, and this option disables it. not me fixing the ancient bug bestie 🫶

---

💫 FORMAT STRINGS 💫

Okay bestie, this is the fun part. Lots of statements in the config file take format strings, and inside those strings you can drop in these %-prefixed tokens and they get swapped out for real values. Here's the complete list of available substitutions — though ngl, not every single one of them is relevant in every context. Just so you know. 💅

• %r — the message recipient e-mail address. Heads up: this one is not substituted for DATA stage ACL, because a message can have a whole squad of recipients and the manpage isn't picking favorites.
• %f — the message sender e-mail address.
• %i — the sender machine IP address.
• %j — the reversed sender machine IP address. So like, 192.0.2.12 becomes 12.2.0.192. Flip era. 🔄
• %I — the sender machine IP address masked by a CIDR. Example: %I{/24}.
• %d — the sender machine DNS address.
• %h — the SMTP transaction HELO string.
• %mr — the mailbox part of %r (the bit before the @ sign). Again, not substituted for DATA stage ACL, multiple recipients and all that.
• %sr — the site part of %r (the bit after the @ sign). Same deal: not substituted for DATA stage ACL.
• %mf — the mailbox part of %f (before the @ sign).
• %sf — the site part of %f (after the @ sign).
• %md — the machine part of %d (before the first . sign).
• %sd — the site part of %d (after the first . sign).
• %Xc — the SMTP code returned.
• %Xe — the SMTP extended code returned.
• %Xm — the SMTP message returned.
• %Xh — the message displayed in the X-Greylist header.
• %D — comma-separated list of DNSRBL for which the sender host matched.
• %M — a sendmail macro value. Examples: %Mj or %M{if_addr}.
• %g — a regex back reference. Like, %g{\2} gets substituted by the string matching the second parenthesis group in all ACL regex clauses. Regex girlies rise. 🧚
• %T — a brace-enclosed strftime(3) format string, substituted by the system time. Example: %T{%Y%m%d:%H%M%S}.
• %v — milter-greylist's version.
• %G — Offset to GMT (e.g.: -0100).
• %C — Sender IP country code, as reported by GeoIP. Only available if milter-greylist was built with GeoIP support.
• %Fx — p0f OS fingerprint genre and detail. Only available if milter-greylist was built with p0f support.
• %V — Shortcut to "milter-greylist-%v (%Mj [%M{if_addr}]); %T{%a, %d %b %Y %T} %G (%T{%Z})". Yes it's a whole vibe in one token, obsessed.
• %S — the action performed: accept, tempfail, or reject.
• %A — the line number of the ACL that caused the action.
• %a — the id string of the ACL that caused the action. If no id was given, the line number is used instead.
• %cA — the line number of the ACL being evaluated, whether it matches or not.
• %ca — the id string of the ACL being evaluated, whether it matches or not. If no id was given, the line number is used instead.
• %Et — total elapsed time in seconds before a greylisted message has been accepted.
• %Eh — hours elapsed.
• %Em — minutes elapsed (modulo one hour).
• %Es — seconds elapsed (modulo one minute).
• %E — shortcut to %Eh:%Em:Es.
• %Rt — total remaining time in seconds before a greylisted message will be accepted.
• %Rh — hours remaining.
• %Rm — minutes remaining (modulo one hour).
• %Rs — seconds remaining (modulo one minute).
• %R — shortcut to %Rh:%Rm:Rs.
• %Hs — SpamAssassin score (if build with SpamAssassin support).
• %pn — Name of last LDAP or CURL gathered property that matched an ACL.
• %pv — Value of last LDAP or CURL gathered property that matched an ACL.
• %pr — Recipient that caused storage of the last matching LDAP or CURL gathered property.
• %P — a LDAP or CURL gathered property. Example: %P{mail}. Note that this copes very badly with multivalued properties. Like, genuinely badly. Fair warning bestie. 😭
• %Qd — DKIM query result (pass, fail, etc.), if built with DKIM support.
• %Qs — SPF query result (pass, (soft)fail, etc.), if built with SPF support.
• %QA — Authentication results summary, suitable for Authentication-Results header. Will included formatted query results from DKIM and SPF if checked.
• %QS — SPF result, suitable for Received-SPF header. Available when compiled with libspf2.
• %% — a single % character. The escape hatch. 🫶

---

🌈 AUTHORS 🌈

The one and only Emmanuel Dreyfus — <manu@netbsd.org>. 👑

And fr fr, milter-greylist received many contributions from (in alphabetical order, we're respectful here): Adrian Dabrowski, Aida Shinra, Adam Katz, Alexander Lobodzinski, Alexandre Cherif, Alexey Popov, Andrew McGill, Attila Bruncsak, Benoit Branciard, Bernhard Schneider, Bob Smith, Constantine A. Murenin, Chris Bennett, Christian Pelissier, Cyril Guibourg, Dan Hollis, David Binderman, Denis Solovyov, Elrond, Enrico Scholz, Eugene Crosser, Fabien Tassin, Fredrik Pettai, Gary Aitken, Georg Horn, Gert Doering, Greg Troxel, Guido Kerkewitz, Hajimu Umemoto, Hideki ONO, Ivan F. Martinez, Jacques Beigbeder, Jean Benoit, Jean-Jacques Puig, Jeff Rife, Jim Klimov, Jobst Schmalenbach, Joe Pruett, Joel Bertrand, Johann E. Klasek, Johann Klasek, John Thiltges, John Wood, Jorgen Lundman, Kazuyuki Yoshida, Klas Heggemann, Kouhei Sutou, Laurence Moindrot, Lev Walkin, Manuel Badzong, Markus Wennrich, Mart Pirita, Martin Paul, Matt Kettler, Mattheu Herrb, Matthias Scheler, Matthieu Herrb, Michael Fromme, Moritz Both, Nerijus Baliunas, Ole Hansen, Pavel Cahyna, Pascal Lalonde, Per Holm, Petar Bogdanovic, Petr Kristof, Piotr Wadas, R P Herrold, Ralf S. Engelschall, Ranko Zivojnovic, Remy Card, Rick Adams, Rogier Maas, Romain Kang, Rudy Eschauzier, Stephane Lentz, Steven Hiscocks, Thomas Scheunemann, Tim Mooney, Vincent Dufresne, Wolfgang Solfrank, and Yaroslav Boychuk. An entire group chat of legends. 💖

Thanks to Helmut Messerer and Thomas Pfau for their feedback on the first releases of this software. Early adopters, we salute you. 🫡

---

🦋 SEE ALSO 🦋

Go read these next, bestie:

• milter-greylist(8), sendmail(8), syslogd(8).

Evan Harris's paper:

http://projects.puremagic.com/greylisting/

milter-greylist's web site:

http://hcpnet.free.fr/milter-greylist/

---

And that's the whole page, start to finish. This was greylist.conf(5) — dated May 10, 2005, the day this icon was born. Go forth and greylist responsibly, bestie. Slay. Periodt. 💅✨