POSTGREY(8)

📦
version 1.37 · 8 versions
, in debian bookworm, ubuntu noble

💖 POSTGREY 💖

okay bestie, gather round, because this is the postgrey manual page (section 8, system admin commands, iykyk) and it is literally the Postfix Greylisting Policy Server. no cap. let's get into it 🦋

✨ SYNOPSIS ✨

postgrey [options...]

and here's the full menu of flags, every single one, don't skip:

  • -h, --help — show the help text and dip out immediately 💅
  • --version — spill the version info and exit
  • -v, --verbose — turn the verbosity up (more talking, more info)
  • --syslog-facility — which syslog facility to use (default is mail)
  • -q, --quiet — turn the verbosity down, shhh 🤫
  • -u, --unix=PATH — listen on the unix socket at PATH
  • --socketmode=MODE — permissions for that unix socket (default is 0666)
  • -i, --inet=[HOST:]PORT — listen on PORT, and on localhost if you don't bother specifying HOST
  • -d, --daemonize — run it in the background, main character energy 👑
  • --pidfile=PATH — drop the daemon's pid into this file
  • --user=USER — run as USER (default: postgrey)
  • --group=GROUP — run as group GROUP (default: postgrey)
  • --dbdir=PATH — put the db files in PATH (default: /var/lib/postgrey)
  • --delay=N — greylist for N seconds (default: 300)
  • --max-age=N — delete entries that are older than N days, counted since the last time they were seen (default: 35)
  • --retry-window=N — only allow N days for the first retrial (default: 2). slap an h on the end if you wanna say it in hours instead ⏰
  • --greylist-action=A — if it's greylisted, return A to Postfix (default: DEFER_IF_PERMIT)
  • --greylist-text=TXT — the response when a mail gets greylisted (default is Greylisted + a help url, more on that below)
  • --lookup-by-subnet — strip the last N bits off IP addresses, where N comes from ipv4cidr and ipv6cidr (this is the default, btw)
  • --ipv4cidr=N — what cidr to use for the subnet on IPv4 addresses when you're using lookup-by-subnet (default: 24)
  • --ipv6cidr=N — what cidr to use for the subnet on IPv6 addresses when you're using lookup-by-subnet (default: 64)
  • --lookup-by-host — do not strip the last 8 bits off IP addresses
  • --privacy — store the data using one-way hash functions 🔒
  • --hostname=NAME — set the hostname (default: whatever hostname says)
  • --exim — don't reuse a socket for more than one query (exim compatible)
  • --whitelist-clients=FILE — default: /etc/postgrey/whitelist_clients
  • --whitelist-recipients=FILE — default: /etc/postgrey/whitelist_recipients
  • --auto-whitelist-clients=N — whitelist a host after its first successful delivery. N is the minimal count of mails before a client gets whitelisted (it's turned on by default with value 5). specify N=0 to disable it entirely.
  • --listen-queue-size=N — allow for N waiting connections to our socket
  • --x-greylist-header=TXT — header for when a mail was delayed by greylisting. default: X-Greylist: delayed <seconds> seconds by postgrey-<version> at <server>; <date>
🫶 heads up bestie: the --whitelist-x options can be specified multiple times, and by default /etc/postgrey/whitelist_clients.local and /etc/postgrey/whitelist_recipients.local are also read, so you can stash your local entries in there.

🌸 DESCRIPTION 🌸

Postgrey is a Postfix policy server that implements greylisting. it's giving gatekeeping but make it useful.

here's the whole vibe: when Postfix gets a request to deliver a mail over SMTP, postgrey builds the triplet CLIENT_IP / SENDER / RECIPIENT. if that's the very first time this triplet has ever been seen — or if it was first seen less than delay seconds ago (and 300 is the default, remember) — then the mail gets rejected with a temporary error. the hope is that spammers and viruses just won't bother trying again later, even though RFC says they're supposed to. and that's the whole trick. iconic. 😌

⚠️ okay real talk, do not use --lookup-by-host unless you genuinely know what you're doing. there are SO many mail servers out there that send from a whole pool of addresses, so they can swap IP every time they retry. that's exactly why, without this option, postgrey strips the last byte off the IP address when it does database lookups. 💀

🎀 Installation 🎀

  1. make a postgrey user and the directory where the database goes, dbdir (default: /var/lib/postgrey)
  2. write an init script to start postgrey at boot, then start it. something like this, for example:
postgrey --inet=10023 -d

contrib/postgrey.init in the postgrey source distribution includes an LSB-compliant init script by Adrian von Bidder for the Debian system.

  1. put something like this in /etc/main.cf:
smtpd_recipient_restrictions =
              permit_mynetworks
              ...
              reject_unauth_destination
              check_policy_service inet:127.0.0.1:10023
  1. install the provided whitelist_clients and whitelist_recipients in /etc/postgrey.
  2. put the users who do not want greylisting into /etc/postgrey/whitelist_recipients.

🌈 Whitelists 🌈

whitelists let you name client addresses or recipient addresses that should get no greylisting at all. the drama-free list. per default, postgrey reads these files:

/etc/postgrey/whitelist_clients
/etc/postgrey/whitelist_clients.local
/etc/postgrey/whitelist_recipients
/etc/postgrey/whitelist_recipients.local

you can point it at different paths with the --whitelist-x options. 🫶

postgrey whitelists follow pretty much the same syntax rules as Postfix access tables. here's what you can write for recipient addresses:

  • domain.addr — matches domain.addr domain and subdomains.
  • name@ — matches name@.* and extended addresses name+blabla@.*.
  • name@domain.addr — matches name@domain.addr and extended addresses.
  • /regexp/ — anything that matches regexp (the full address is matched).

and here's what you can write for client addresses:

  • domain.addr — matches domain.addr domain and subdomains.
  • IP1.IP2.IP3.IP4 — matches IP address IP1.IP2.IP3.IP4. you can also leave off one number, and then only the first specified numbers get checked.
  • IP1.IP2.IP3.IP4/MASK — CIDR-style network. example: 192.168.1.0/24
  • /regexp/ — anything that matches regexp (the full address is matched).

🦋 Auto-whitelisting clients 🦋

with the --auto-whitelist-clients option, a client IP address gets automatically whitelisted when these conditions are met:

  • At least 5 successful attempts of delivering a mail (after greylisting was done). That number can be changed by specifying a number after the --auto-whitelist-clients argument. Only one attempt per hour counts.
  • The client was last seen before --max-age days (35 per default).

💅 Greylist Action 💅

to set the action that gets returned to postfix when a message fails postgrey's tests and should be deferred, use the --greylist-action=ACTION option.

by default, postgrey returns DEFER_IF_PERMIT, which makes postfix check the rest of the restrictions and only defer the message if it would otherwise be accepted. a delay action of 451 makes postfix always defer the message with an SMTP reply code of 451 (temp fail).

peep the postfix manual page access(5) for a whole discussion of the actions allowed. 📖

⭐ Greylist Text ⭐

when a message is greylisted, an error message like this one gets sent at the SMTP level:

Greylisted, see http://postgrey.schweikert.ch/help/example.com.html

usually no user should ever see that error message, and the whole idea of that URL is to give some help to system administrators who see it, or to users of broken mail clients that try to send mails directly and get a greylisting error. note that the default help-URL contains the original recipient domain (example.com), so domain-specific help can be shown to the user (on the default page it says to contact postmaster@example.com).

you can change the text (and the URL) with the --greylist-text parameter. these special variables get replaced in the text:

  • %s — how many seconds are left until the greylisting is over (300).
  • %r — the mail-domain of the recipient (example.com).

🔥 Greylist Header 🔥

when a message is greylisted, an extra header can be prepended to the header section of the mail:

X-Greylist: delayed %t seconds by postgrey-%v at %h; %d

you can change the text with the --x-greylist-header parameter. these special variables get replaced in the text:

  • %t — how many seconds the mail has been delayed due to greylisting.
  • %v — the version of postgrey.
  • %d — the date.
  • %h — the host.

🔒 Privacy 🔒

the --privacy option enables the use of a SHA1 hash function to store IPs and emails in the greylisting database. this will defeat straight-forward attempts to retrieve mail user behaviours. sneaky, but make it ethical. 🕵️

👀 SEE ALSO 👀

peep <http://www.greylisting.org/> for a description of what greylisting even is, and <http://www.postfix.org/SMTPD_POLICY_README.html> for a description of how Postfix policy servers work. iykyk 📚

Copyright (c) 2004-2007 by ETH Zurich. All rights reserved. Copyright (c) 2007 by Open Systems AG. All rights reserved.

📜 LICENSE 📜

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

💜 AUTHOR 💜

David Schweikert <david@schweikert.ch>

and that's the whole page bestie, no notes, you ate that 🍓 this was perl v5.36.0, dated 2023-04-30, and it's POSTGREY(8) — go forth and greylist responsibly, ily, bye!! 💖✨🎀

📦 where this page comes from