prosody-modules
99860e1b817d
mod_dnsbl/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_dnsbl/README.markdown @ 6161:99860e1b817d

mod_dnsbl: Flag accounts registered by IPs matching blocklists
author Matthew Wild <mwild1@gmail.com>
date Wed, 22 Jan 2025 18:04:26 +0000
comparison
equal deleted inserted replaced
6160:4887f68130c0 6161:99860e1b817d
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'Flag accounts registered by IPs matching blocklists'
5 depends:
6 - mod_anti_spam
7 ---
8
9 This module is designed for servers with public registration enabled, and
10 makes it easier to identify accounts that have been registered by potentially
11 "bad" IP addresses, e.g. those that are likely to be used by spam bots.
12
13 **Note:** Running a Prosody instance with public registration enabled opens up
14 your server as a potential relay for spam and abuse, which can have a negative
15 impact on your server and the network as a whole. We do not recommended it
16 unless you have prior experience operating public internet services and are
17 prepared for the time and effort necessary to tackle any issues. For other
18 advice, see the Prosody documentation on [public servers](https://prosody.im/doc/public_servers).
19
20 ## How does it work?
21
22 When a user account is registered on your server, this module checks the user's
23 IP address against a list of configured blocklists. If a match is found, it
24 flags the account using [mod_flags].
25
26 Flags can be reviewed and managed by using the mod_flags commands and flagged
27 accounts can be automatically restricted, e.g. by mod_firewall or similar.
28
29 This module supports two kinds of block lists:
30
31 - DNS blocklists (DNSBLs)
32 - Text files, with one IP/subnet per line
33
34 ## Configuration
35
36 **Note:** mod_dnsbl requires mod_anti_spam to be installed, but it does not
37 need to be enabled or loaded (only some code is shared). mod_flags is also
38 required, and this will be automatically loaded if not specified in the
39 config file.
40
41 The main configuration option is `dnsbls`, a list of DNSBL addresses:
42
43 ```lua
44 dnsbls = {
45 "dnsbl.dronebl.org";
46 "cbl.abuseat.org";
47 }
48 ```
49
50 You can set a message to be sent to users who register from a matched IP
51 address:
52
53 ```lua
54 dnsbl_message = "Your IP address has been detected on a block list. Some functionality may be restricted."
55 ```
56
57 You can change the default flag that is applied to accounts:
58
59 ```lua
60 dnsbl_flag = "dnsbl_hit"
61 ```
62
63 ### File-based blocklists
64
65 As well as real DNSBLs, you can also put file-based blocklists here, by
66 prefixing `@` to a filesystem path (Prosody must have read permission to
67 access the file):
68
69 ```lua
70 dnsbls = {
71 "dnsbl.dronebl.org";
72 "@/etc/prosody/ip_blocklist.txt";
73 }
74 ```
75
76 The file must contain a single IP address or subnet on each line, though blank
77 lines and comments are ignored. For example:
78
79 ```
80 # This is a comment
81 203.0.113.0/24
82 2001:db8:7894::/64
83 ```
84
85 File-based lists are automatically reloaded when you reload Prosody's
86 configuration.
87
88 ### Advanced configuration
89
90 You can override the flag and message on a per-blocklist basis with a slightly
91 more detailed configuration syntax:
92
93 ```lua
94 dnsbls = {
95 ["dnsbl.dronebl.org"] = {
96 flag = "dnsbl_hit";
97 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}";
98 };
99 ["@/etc/prosody/ip_blocklist.txt"] = {
100 flag = "local_blocklist";
101 message = "Your account is restricted";
102 };
103 }
104 ```
105
106 ## Compatibility
107
108 Compatible with Prosody 0.12 and later.
109
110 If you are using Prosody 0.12, make sure you install mod_flags from the
111 community module repository. If you are using a later version, mod_flags is
112 already included with Prosody.