prosody-modules
d611ed13df7e
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

Annotate

mod_dnsbl/README.markdown @ 6209:d611ed13df7e draft

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