policyd-weight.conf(5)

📦 version 0.1.15.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing

🌸 policyd-weight.conf(5) 🌸

okay bestie, so this whole thing lives in the File Formats Manual section, and it's literally the manual page for policyd-weight.conf — aka the config file that runs your whole policyd-weight setup. sit down, grab a strawberry 🍓, we're going through every single setting, no skips, no skimming, fr fr.

✨ NAME ✨

policyd-weight.conf — the configuration parameters for policyd-weight. that's it, that's the name, iconic 💅

🦋 STATUS 🦋

Beta, and the documentation is incomplete. yeah. we know. it's giving "work in progress but make it fashion" 😭

💜 DESCRIPTION 💜

policyd-weight reads a perl(1)-style configuration file, and it does that on startup, like clockwork.

and here's the cute part: the cache re-reads the config after $MAINTENANCE_LEVEL (default: 5) queries. so it keeps itself fresh. ✨

now, if you don't pass -f, it goes hunting for config files in these spots, in this order:

/etc/policyd-weight.conf
/usr/local/etc/policyd-weight.conf
./policyd-weight.conf

🎀 CACHE SETTINGS 🎀

  • $CACHESIZE (default: 2000) — sets the minimum size of the SPAM cache.
  • $CACHEMAXSIZE (default: 4000) — sets the maximum size of the SPAM cache.
  • $CACHEREJECTMSG (default: 550 temporarily blocked because of previous errors)) — this is the SMTP status code plus an explanatory message you send when you reject mail because of cached results.
  • $NTTL (default: 1) — the client gets penalized for that many retries.
  • $NTIME (default: 30) — the $NTTL counter only decrements if the client waits at least $NTIME seconds. patience is a virtue bestie 🧚
  • $POSCACHESIZE (default: 1000) — sets the minimum size of the HAM cache.
  • $POSCACHEMAXSIZE (default: 2000) — sets the maximum size of the HAM cache.
  • $PTTL (default: 60) — after that many queries, the HAM entry has to succeed one full run through the RBL checks again.
  • $PTIME (default: 3h) — after $PTIME in the HAM cache, the client has to pass the RBL checks one time again. values must be non-fractal. accepted time-units are: s(econds), m(inutes), h(ours), d(ays).
  • $TEMP_PTIME (default: 1d) — the client has to pass the RBL checks for this long to be listed as hard-HAM. after this time, the client passes immediately for PTTL within PTIME. values must be non-fractal. accepted time-units: s(econds), m(inutes), h(ours), d(ays).

🔥 DEBUG SETTINGS 🔥

  • $DEBUG (default: 0) — turns debugging on (1) or off (0). simple as.

🌈 DNS SETTINGS 🌈

  • $DNS_RETRIES (default: 2) — how many times a single DNS query may be repeated.
  • $DNS_RETRY_IVAL (default: 2) — retry a query that got no response after that many seconds.
  • $MAXDNSERR (default: 3) — if that many queries fail, the mail gets accepted with $MAXDNSERRMSG. in total DNS queries, that means: $MAXDNSERR * $DNS_RETRIES.
  • $IGNORE_RFC1918_A (default: 0) — if enabled (1), A records with RFC1918 addresses are not treated as bogus addresses by policyd-weight, which means bogus_mx_score isn't added. lowkey handy if you're doing internal stuff 👑

💖 MISC SETTINGS 💖

  • $MAINTENANCE_LEVEL (default: 5) — after that many policy requests, the cache (and, in daemon mode, the child processes) checks for configuration file changes.
  • $MAXIDLECACHE (default: 60) — after that many seconds of being idle, the cache checks for configuration file changes. self-care check-in ✨
  • $PIDFILE (default: /var/run/policyd-weight.pid) — path and filename where the master pid gets stored (daemon mode).
  • $LOCKPATH (default: /tmp/.policyd-weight/) — directory where policyd-weight stores sockets and lock-files/directories. its argument must contain a trailing slash.
  • $SPATH (default: $LOCKPATH.'/polw.sock') — path and filename that the cache has to use for communication.
  • $TCP_PORT (default: 12525) — TCP port the policy server listens on (daemon mode).
  • $BIND_ADDRESS (default: '127.0.0.1') — IP address policyd-weight binds to. currently either only one or all IPs are supported. specify 'all' if you want to listen on every IP.
  • $SOMAXCONN (default: 1024) — maximum connections policyd-weight accepts. this is set high enough to cover most scenarios.
  • $USER (default: polw) — sets the user under which policyd-weight runs.
  • $GROUP (default: $USER) — sets the group under which policyd-weight runs.

💅 OUTPUT AND LOG SETTINGS 💅

  • $ADD_X_HEADER (default: 1) — inserts an X-policyd-weight: header with evaluation messages. 1 = on, 0 = off.
  • $LOG_BAD_RBL_ONLY (default: 1) — only inserts RBL results into logging strings if the RBL score actually changes the overall score. so RBLs with a GOOD SCORE of 0 don't show up in logging strings if that RBL returned no BAD hit. 1 = on, 0 = off.
  • $MAXDNSBLMSG (default: 550 Your MTA is listed in too many DNSBLs) — the message sent to the client if it was rejected because of $MAXDNSBLHITS and/or $MAXDNSBLSCORE.
  • $REJECTMSG (default: 550 Mail appeared to be SPAM or forged. Ask your Mail/DNS-Adminisrator to correct HELO and DNS MX settings or to get removed from DNSBLs) — sets the SMTP status code for rejected mails, plus a message explaining why the action was taken.

🧚 RESOURCE AND OPTIMIZATIONS 🧚

  • $CHILDIDLE (default: 120) — how many seconds a child may be idle before it dies (daemon mode).
  • $MAX_PROC (default: 50) — process limit on how many processes policyd-weight will spawn (daemon mode).
  • $MIN_PROC (default: 2) — minimum child processes kept alive during idle times (daemon mode).
  • $PUDP (default: 0) — sets persistent UDP connections used for DNS queries on (1) or off (0).

👑 SCORE SETTINGS 👑

just so we're clear on the vibes: positive values = a bad (SPAM) score, negative values = a good (HAM) score. got it? good. 💅

  • @bogus_mx_score (2.1, 0) — if the sender domain has neither MX nor A records, or those records resolve to a bogus IP-address (private networks, for instance), then this check assigns the full score of bogus_mx_score. if there's no MX but there is an A record for the sender domain, then it only receives a penalty if it's DNSBL-listed.

Log Entries:

  • BOGUS_MX — the sender A and MX records are bogus or empty.
  • BAD_MX — the sender domain has an empty or bogus MX record and the client is DNSBL listed.

Related RFCs:

  • [1918] Address Allocation for Private Internets
  • [2821] Simple Mail Transfer Protocol (Sect 3.6 and Sect 5)
  • @client_ip_eq_helo_score (1.5, -1.25) — defines the scores for a match of the reverse record (hostname) against the HELO argument. reverse lookups are done if the forward lookups failed, and they are not trusted.

Log Entries:

  • REV_IP_EQ_HELO — the Client's PTR matched the HELO argument.
  • REV_IP_EQ_HELO_DOMAIN — domain portions of Client PTR and HELO argument matched.
  • RESOLVED_IP_IS_NOT_HELO — Client PTRs found but did not match the HELO argument.
  • @helo_score (1.5, -2) — defines scores for a match of the Client IP and its /24 subnet against the A records of the HELO or MAIL FROM domain/host. it also holds the bad score for MX verifications.

Log Entries:

  • CL_IP_EQ_HELO_NUMERIC — Client IP matches the [IPv4] HELO.
  • CL_IP_EQ_FROM_IP — Client IP matches the A record of the MAIL FROM sender domain/host.
  • CL_IP_EQ_HELO_IP — Client IP matches the A record of the HELO argument.
  • CL_IP_NE_HELO — the IP and the /24 subnet did not match A/MX records of HELO and MAIL FROM arguments and their subdomains.
  • @helo_from_mx_eq_ip_score (1.5, -3.1) — defines scores for a match of Client IP against MX records. positive (SPAM) values are used when the MAIL FROM doesn't match the HELO argument AND the client seems to be dynamic AND the client is no MX for the HELO and MAIL FROM arguments. the total DNSBL score gets added to its bad score.

Log Entries:

  • CL_IP_EQ_FROM_MX — Client IP matches the MAIL FROM domain/host MX record.
  • CL_IP_EQ_HELO_MX — Client IP matches the HELO domain/host MX record.
  • CLIENT_NOT_MX/A_FROM_DOMAIN — Client is not a verified HELO and doesn't match A/MX records of the MAIL FROM argument.
  • CLIENT/24_NOT_MX/A_FROM_DOMAIN — Client's subnet does not match A/MX records of the MAIL FROM argument.
  • $dnsbl_checks_only (default: 0) — disables HELO/RHSBL verifications and the like. does only RBL checks. 1 = on, 0 = off.
  • @dnsbl_score (default: see below) — a list of RBLs to be checked. if you want a host to not be evaluated any further when it's listed on several lists, or on a very trustworthy list, you can trigger an immediate REJECT with $MAXDNSBLHITS and/or $MAXDNSBLSCORE. a list of RBLs must be built like this:
@dnsbl_score = (
    RBLHOST1,   HIT SCORE,  MISS SCORE,     LOG NAME,
    RBLHOST2,   HIT SCORE,  MISS SCORE,     LOG NAME,
    ...
);

the default is:

@dnsbl_score = (
    "pbl.spamhaus.org",     3.25,   0,      "DYN_PBL_SPAMHAUS",
    "sbl-xbl.spamhaus.org", 4.35,   -1.5,   "SBL_XBL_SPAMHAUS",
    "bl.spamcop.net",       3.75,   -1.5,   "SPAMCOP",
    "ix.dnsbl.manitu.net",  4.35,   0,      "IX_MANITU"
);
  • @rhsbl_score (default: see below) — defines a list of RHSBL hosts which get queried for the sender domain. results additionally get scores of 0.5 * DNSBL results and @rhsbl_penalty_score. a list of RHSBL hosts to be queried must be built like this:
@rhsbl_score = (
    RHSBLHOST1,  HIT SCORE,  MISS SCORE,     LOG NAME,
    RHSBLHOST2,  HIT SCORE,  MISS SCORE,     LOG NAME,
    ...
);

the default is:

@rhsbl_score = (
    "multi.surbl.org",      4,      0,      "SURBL"
);
  • @rhsbl_penalty_score (3.1, 0) — this score gets added to each RHSBL hit if the following criteria are met:
    • Sender has a random local-part (i.e. yztrzgb@example.tld)
    • or MX records of sender domain are bogus
    • or FROM matches not HELO
    • or HELO is untrusted (Forward record matched, reverse record did not match)
  • $MAXDNSBLHITS (default: 2) — if the client is listed in more than $MAXDNSBLHITS RBLs, it gets rejected immediately with $MAXDNSBLMSG and with no further evaluation. results are cached by default.
  • $MAXDNSBLSCORE (default: 8) — if the BAD SCOREs of the @dnsbl_score-listed RBLs reach a level greater than $MAXDNSBLSCORE, the client gets rejected immediately with $MAXDNSBLMSG and with no further evaluation. results are cached by default.
  • $REJECTLEVEL (default: 1) — score results equal to or greater than this level get rejected with $REJECTMSG.
okay and that's where part 1 wraps, bestie — there's more coming, don't go anywhere 🫶

✨ SEE ALSO ✨

okay so if you wanna go deeper (and bestie, you should), go read these:

  • policyd-weight(8) — the Policyd-weight daemon itself, the main character 👑
  • perl(1) — Practical Extraction and Report Language, aka the language this whole thing is living in 💜
  • perlsyn(1) — Perl syntax, for when you're like "wait what does that line even mean" 🦋
  • access(5) — the Postfix SMTP access control table

🎀 LICENSE 🎀

GNU General Public License. that's it, that's the vibe, go forth and be free 🫶

💖 AUTHOR 💖

Robert Felber <r.felber@ek-muc.de> Autohaus Erich Kuttendreier 81827 Munich, Germany

and that's the whole page, bestie!! this version is from Aug 25th, 2006 and it's the manual for policyd-weight.conf(5) — iconic, timeless, literally a piece of history 💅✨ go configure something slay, ily, bye 🎀🦋💖

📦 where this page comes from