From 5448b5728c7bf1dc368c37f417a8f83a39b043c3 Mon Sep 17 00:00:00 2001 From: Matt Simerson Date: Tue, 7 Jan 2025 20:01:43 -0800 Subject: [PATCH] update dns-list docs, delete dnswl --- content/8.plugins/dns-list.md | 148 +++++++++++++++++++++------------- content/8.plugins/dnswl.md | 81 ------------------- 2 files changed, 90 insertions(+), 139 deletions(-) delete mode 100644 content/8.plugins/dnswl.md diff --git a/content/8.plugins/dns-list.md b/content/8.plugins/dns-list.md index 1fa7997a..f09b5b57 100644 --- a/content/8.plugins/dns-list.md +++ b/content/8.plugins/dns-list.md @@ -4,83 +4,115 @@ description: Haraka dns lists plugin - DNS Blacklists navigation.title: dns-list --- -# dns-list plugin +# haraka-plugin-dns-list -This plugin looks up the connecting IP address in an IP blocklist. Mails -found to be in the blocklist are rejected. +## dns lists -Configuration -------------- +Looks up the IP address of the remote host in DNS lists. There are several types of DNS based lists: -This plugins uses the following files: +### block -dns-list.ini - INI format with options described below: +Block lists (aka: DNSBL) are designed to be used for blocking mail from any host listed in them. Block lists are the most common DNS list type and lists without a type specified are considered block lists. The default action for block lists is to reject the connection. This can be changed by setting `reject=false` in the zone's settings block. -* zones +### allow - A comma or semi-colon list of zones to query. It will be merged with - any lists in dnsbl.zones. +When the remote IP is found in an allow list, this plugin returns OK for the ehlo, helo, and mail hooks. -* periodic\_checks +IMPORTANT! The order of plugins in config/plugins is important when this feature is used. It should be listed _before_ any plugins that you wish to skip, but after any plugins that accept recipients. - If enabled, this will check all the zones every n minutes. - The minimum value that will be accepted here is 5. Any value less - than 5 will cause the checks to be run at start-up only. +### karma - The checks confirm that the list is responding and that it is not - listing the world. If any errors are detected, then the zone is - disabled and will be re-checked on the next test. If a zone - subsequently starts working correctly then it will be re-enabled. +Karma lists can have different results for IPs beyond a simple block or allow. See [hostkarma.junkemailfilter.com](https://hostkarma.junkemailfilter.com) for details. -* enable\_stats +## INSTALL - To use this feature you must have installed the 'redis' module and - have a redis server running. +```sh +cd /path/to/local/haraka +npm install haraka-plugin-dns-list +echo "dns-list" >> config/plugins +service haraka restart +``` - When enabled, this will record several list statistics to redis. +## Configure - It will track the total number of queries (TOTAL) and the average - response time (AVG\_RT) and the return type (e.g. LISTED or ERROR) - to a redis hash where the key is 'dns-list-stat:zone' and the hash - field is the response type. +If the default configuration is insufficient, copy the config file from the distribution into your haraka config dir and modify it: - It will also track the positive response overlap between the lists - in another redis hash where the key is 'dns-list-overlap:zone' and - the hash field is the other list names. +```sh +cp node_modules/haraka-plugin-dns-list/config/dns-list.ini config/dns-list.ini +$EDITOR config/dns-list.ini +``` - Example: - 
redis 127.0.0.1:6379> hgetall dns-list-stat:zen.spamhaus.org
-    1) "TOTAL"
-    2) "23"
-    3) "ENOTFOUND"
-    4) "11"
-    5) "LISTED"
-    6) "12"
-    7) "AVG_RT"
-    8) "45.5"
-    redis 127.0.0.1:6379> hgetall dns-list-overlap:zen.spamhaus.org
-    1) "b.barracudacentral.org"
-    2) "1"
-    3) "bl.spamcop.net"
-    4) "1"
-    5) "TOTAL"
-    6) "1"
-
+dns-lists.ini - INI format with options described below: -* stats\_redis\_host +#### [main] periodic_checks=30 - In the form of `host:port` this option allows you to specify a different - host on which redis runs. +Check every DNS zone every `N` minutes. When the value is less than 5, checks will only be run at start-up. -* reject (default: true) +The checks confirm that lists are responding correctly. When errors are detected, the zone is disabled and will be checked at the next interval. When a zone resumes working correctly it will be enabled. - Reject connections from IPs that are blacklisted. Setting this to false - makes dnsbl informational. reject=false is best used in conjunction with - plugins like [karma](/plugins/karma) that employ a scoring - engine to make choices about message delivery. +#### [main] zones -* search: (default: first) +An array or comma separated list of zones to query. - first: consider first DNSBL response conclusive. End processing. - all: process all DNSBL results +#### [main] search: (default: all) +- first: consider first DNS list response conclusive. End processing. +- all: process all DNS list results + +#### [stats] enable=true + +This feature requires the [redis](https://github.com/haraka/haraka-plugin-redis) plugin. When enabled, this will record several list statistics to redis: + +- the total number of queries (TOTAL) +- the average response time (AVG_RT) +- the return type (e.g. LISTED or ERROR) + +to a redis hash where the key is `dns-list-stat:zone` and the hash field is the response type. + +It will also track the positive response overlap between the lists in another redis hash where the key is `dns-list-overlap:zone` and the hash field is the other list names. Example: + +``` +redis 127.0.0.1:6379> hgetall dns-list-stat:zen.spamhaus.org +1) "TOTAL" +2) "23" +3) "ENOTFOUND" +4) "11" +5) "LISTED" +6) "12" +7) "AVG_RT" +8) "45.5" + +redis 127.0.0.1:6379> hgetall dns-list-overlap:zen.spamhaus.org +1) "b.barracudacentral.org" +2) "1" +3) "bl.spamcop.net" +4) "1" +5) "TOTAL" +6) "1" +``` + +#### [stats] redis_host + +In the form of `host:port` this option allows you to specify a different host on which redis runs. + +### Per-Zone DNS list settings + +The exact name of the DNS zone (as specified above in main.zones) may contain settings about that DNS list. + +- type=[ block, allow, karma ] +- reject=true (default: true) Reject connections from IPs on block lists. Setting this to false makes dnsbl informational. reject=false is best used in conjunction with plugins like [karma](https://github.com/haraka/haraka-plugin-karma) that employ a scoring engine to make choices about message delivery. +- ipv6=true | false + +#### dnswl + +```ini +ok_helo=false +ok_mail=false +``` + +if DNSBL returns OK on the mail hook, it prevents any subsequent mail hooks in other plugins from running. This might include [SPF](haraka-plugin-spf), [known senders](https://github.com/haraka/haraka-plugin-known-senders), [karma](https://github.com/haraka/haraka-plugin-karma), recipient plugins, and any other plugins that want to do transaction initialization on `hook_mail`. It can be dangerous. + +[ci-img]: https://github.com/haraka/haraka-plugin-dns-list/actions/workflows/ci.yml/badge.svg +[ci-url]: https://github.com/haraka/haraka-plugin-dns-list/actions/workflows/ci.yml +[clim-img]: https://codeclimate.com/github/haraka/haraka-plugin-dns-list/badges/gpa.svg +[clim-url]: https://codeclimate.com/github/haraka/haraka-plugin-dns-list diff --git a/content/8.plugins/dnswl.md b/content/8.plugins/dnswl.md deleted file mode 100644 index e35343df..00000000 --- a/content/8.plugins/dnswl.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: dnswl - DNSWL plugin for Haraka -description: Haraka dnswl plugin - DNSWL -navigation.title: dnswl ---- - -# dnswl plugin - -This plugin looks up the connecting IP address in an IP whitelist. -If the host is listed, then the plugin will return OK for all hooks -up to hook\_data. - -IMPORTANT! The order of plugins in config/plugins is important when -this plugin is used. It should be listed *before* any plugins that -you wish to skip, but after any plugins that accept recipients. - -Configuration -------------- - -This plugins uses the following files: - -dnswl.zones - Contains a list of zones to query, one per line. - -dnswl.ini - INI format with options described below: - -* zones - - A comma or semi-colon list of zones to query. It will be merged with - any lists in dnswl.zones. - -* periodic\_checks - - If enabled, this will check all the zones every n minutes. - The minimum value that will be accepted here is 5. Any value less - than 5 will cause the checks to be run at start-up only. - - The checks confirm that the list is responding and that it is not - listing the world. If any errors are detected, then the zone is - disabled and will be re-checked on the next test. If a zone - subsequently starts working correctly then it will be re-enabled. - -* enable\_stats - - To use this feature you must have installed the 'redis' module and - have a redis server running. - - When enabled, this will record several list statistics to redis. - - It will track the total number of queries (TOTAL) and the average - response time (AVG\_RT) and the return type (e.g. LISTED or ERROR) - to a redis hash where the key is 'dns-list-stat:zone' and the hash - field is the response type. - - It will also track the positive response overlap between the lists - in another redis hash where the key is 'dns-list-overlap:zone' and - the hash field is the other list names. - - Example: - 
redis 127.0.0.1:6379> hgetall dns-list-stat:zen.spamhaus.org
-    1) "TOTAL"
-    2) "23"
-    3) "ENOTFOUND"
-    4) "11"
-    5) "LISTED"
-    6) "12"
-    7) "AVG_RT"
-    8) "45.5"
-    redis 127.0.0.1:6379> hgetall dns-list-overlap:zen.spamhaus.org
-    1) "b.barracudacentral.org"
-    2) "1"
-    3) "bl.spamcop.net"
-    4) "1"
-    5) "TOTAL"
-    6) "1"
-
- -* stats\_redis\_host - - In the form of `host:port` this option allows you to specify a different - host on which redis runs. -