annotate mod_host_guard.wiki @ 445:8a6190c56c8f

Add note about requirement for LuaBitOp library (thanks Jonathan)
author MWild1@gmail.com
date Fri, 28 Mar 2014 14:26:45 +0000
parents caffa894b070
children 528721aaea46
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
240
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
1 #summary Granular remote host blacklisting plugin
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
2 #labels Stage-Stable
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
3
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
4 = Details =
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
5
247
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
6 As often it's undesiderable to employ only whitelisting logics in public environments, this module let's you more selectively
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
7 restrict access to your hosts (component or server host) either disallowing access completely (with optional exceptions) or
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
8 blacklisting certain sources.
240
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
9
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
10 = Usage =
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
11
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
12 Copy the plugin into your prosody's modules directory.
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
13 And add it between your enabled modules into the global section (modules_enabled):
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
14
247
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
15 * The plugin can work either by blocking all remote access (s2s) to a certain resource with optional exceptions (useful for components)
240
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
16 * Or by selectively blocking certain remote hosts through blacklisting (by using host_guard_selective and host_guard_blacklisting)
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
17
282
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
18 = Configuration =
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
19
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
20 || *Option name* || *Description* ||
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
21 || host_guard_blockall || A list of local hosts to protect from incoming s2s ||
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
22 || host_guard_blockall_exceptions || A list of remote hosts that are always allowed to access hosts listed in host_guard_blockall ||
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
23 || host_guard_selective || A list of local hosts to allow selective filtering (blacklist) of incoming s2s connections ||
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
24 || host_guard_blacklist || A blacklist of remote hosts that are not allowed to access hosts listed in host_guard_selective ||
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
25
caffa894b070 Add table of config options with descriptions
MWild1@gmail.com
parents: 281
diff changeset
26 == Example ==
280
22f6a2a998cf Made it clearer?
maranda3985@gmail.com
parents: 247
diff changeset
27 <code language="lua">
22f6a2a998cf Made it clearer?
maranda3985@gmail.com
parents: 247
diff changeset
28 host_guard_blockall = { "no_access.yourhost.com", "no_access2.yourhost.com" } -- insert here the local hosts where you want to forbid all remote traffic to.
281
a0d014edd8df Refined.
maranda3985@gmail.com
parents: 280
diff changeset
29 host_guard_blockall_exceptions = { "i_can_access.no_access.yourhost.com" } -- optional exceptions for the above.
280
22f6a2a998cf Made it clearer?
maranda3985@gmail.com
parents: 247
diff changeset
30 host_guard_selective = { "no_access_from_blsted.myhost.com", "no_access_from_blsted.mycomponent.com" } -- insert here the local hosts where you want to employ blacklisting.
281
a0d014edd8df Refined.
maranda3985@gmail.com
parents: 280
diff changeset
31 host_guard_blacklist = { "remoterogueserver.com", "remoterogueserver2.com" } -- above option/mode mandates the use of a blacklist, you may blacklist remote servers here.
280
22f6a2a998cf Made it clearer?
maranda3985@gmail.com
parents: 247
diff changeset
32 </code>
240
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
33
247
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
34 The above is updated when the server configuration is reloaded so that you don't need to restart the server.
012884e6ba5d edited wiki to reflect changes.
Marco Cirillo <maranda@lightwitch.org>
parents: 240
diff changeset
35
240
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
36 = Compatibility =
8b15faa008e3 added wiki.
Marco Cirillo <maranda@lightwitch.org>
parents:
diff changeset
37
280
22f6a2a998cf Made it clearer?
maranda3985@gmail.com
parents: 247
diff changeset
38 * Works with 0.8.x, successive versions and trunk.