Diff

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mod_dnsbl/README.markdown	Tue Mar 18 00:16:25 2025 +0700
@@ -0,0 +1,112 @@
+---
+labels:
+- 'Stage-Alpha'
+summary: 'Flag accounts registered by IPs matching blocklists'
+depends:
+  - mod_anti_spam
+---
+
+This module is designed for servers with public registration enabled, and
+makes it easier to identify accounts that have been registered by potentially
+"bad" IP addresses, e.g. those that are likely to be used by spam bots.
+
+**Note:** Running a Prosody instance with public registration enabled opens up
+your server as a potential relay for spam and abuse, which can have a negative
+impact on your server and the network as a whole. We do not recommended it
+unless you have prior experience operating public internet services and are
+prepared for the time and effort necessary to tackle any issues. For other
+advice, see the Prosody documentation on [public servers](https://prosody.im/doc/public_servers).
+
+## How does it work?
+
+When a user account is registered on your server, this module checks the user's
+IP address against a list of configured blocklists. If a match is found, it
+flags the account using [mod_flags].
+
+Flags can be reviewed and managed by using the mod_flags commands and flagged
+accounts can be automatically restricted, e.g. by mod_firewall or similar.
+
+This module supports two kinds of block lists:
+
+- DNS blocklists (DNSBLs)
+- Text files, with one IP/subnet per line
+
+## Configuration
+
+**Note:** mod_dnsbl requires mod_anti_spam to be installed, but it does not
+need to be enabled or loaded (only some code is shared). mod_flags is also
+required, and this will be automatically loaded if not specified in the
+config file.
+
+The main configuration option is `dnsbls`, a list of DNSBL addresses:
+
+```lua
+dnsbls = {
+  "dnsbl.dronebl.org";
+  "cbl.abuseat.org";
+}
+```
+
+You can set a message to be sent to users who register from a matched IP
+address:
+
+```lua
+dnsbl_message = "Your IP address has been detected on a block list. Some functionality may be restricted."
+```
+
+You can change the default flag that is applied to accounts:
+
+```lua
+dnsbl_flag = "dnsbl_hit"
+```
+
+### File-based blocklists
+
+As well as real DNSBLs, you can also put file-based blocklists here, by
+prefixing `@` to a filesystem path (Prosody must have read permission to
+access the file):
+
+```lua
+dnsbls = {
+  "dnsbl.dronebl.org";
+  "@/etc/prosody/ip_blocklist.txt";
+}
+```
+
+The file must contain a single IP address or subnet on each line, though blank
+lines and comments are ignored. For example:
+
+```
+# This is a comment
+203.0.113.0/24
+2001:db8:7894::/64
+```
+
+File-based lists are automatically reloaded when you reload Prosody's
+configuration.
+
+### Advanced configuration
+
+You can override the flag and message on a per-blocklist basis with a slightly
+more detailed configuration syntax:
+
+```lua
+dnsbls = {
+  ["dnsbl.dronebl.org"] = {
+    flag = "dnsbl_hit";
+    message = "Your account is restricted because your IP address has been detected as running an open proxy. For more information see https://dronebl.org/lookup?ip={registration.ip}";
+  };
+  ["@/etc/prosody/ip_blocklist.txt"] = {
+    flag = "local_blocklist";
+    message = "Your account is restricted";
+  };
+}
+```
+
+## Compatibility
+
+Compatible with Prosody 0.12 and later.
+
+If you are using Prosody 0.12, make sure you install mod_flags from the
+community module repository. If you are using a later version, mod_flags is
+already included with Prosody.