README.rdoc
1= mod_memcache_block v0.99 (beta)
2
3John Adams <jna@twitter.com>
4May 6, 2009
5
6== Description
7
8mod_memcache_block is an Apache module that allows you to block access to your servers using a block list stored in memcache. It also offers distributed rate limiting based on HTTP response code.
9
10== FEATURES
11
12* Distributed White and Black listing of IPs, ranges, and CIDR blocks
13
14* Configurable timeouts, memcache server listings
15
16* Support for continuous hasing using libmemcached's Ketama
17
18* Windowded Rate limiting based on Response code (to block brute-force dictionary attacks against .htpasswd, for example)
19
20== REQUIREMENTS
21
22* libmemcached-0.25 or better
23
24* Memcached server
25
26* Apache 2.x (tested with 2.2.11)
27
28== INSTALLATION
29
301. Install libmemcached-0.25 or better.
312. Install memcached-1.26
323. Edit the Makefile to indicate the location of libmemcached
334. Type "make", then "make install"
345. Update your apache configuration
356. Restart the server with apachectl restart
36
37== CONFIGURATION
38
39The following configuration directives are used by mod_memcache_block:
40
41[MBEnable On|Off] Default: On
42 On or Off, controls if this module is enabled or not (default on)
43
44[MBServers serverlist] A list of participating memcache servers, in the form
45 (servername:port,servername:port...)
46
47[MBPrefix n] The Memcache key prefix prepended to all keys
48
49[MBTimeout n] The timeout, in microseconds, to wait for a backend memcached
50
51[MBExpiration n] The Duration, in seconds, of an automatic rate-limit based block
52
53[MBTableRefresh n] How long to wait between refreshes of the block table. Do not
54 set this to a low value, or the server will spend lots of time
55 during request processing reloading the white/blacklist tables.
56 This translates into ((2 * MBMaxBlocks) * Workers) memcached
57 gets every n seconds.
58
59[MBMaxBlocks n] The size of the block table (the number of keys to look for in memcached)
60 A Restart is required if this value changes.
61
62[MBRateLimit On|Off] Default: On
63 Whether or not the module honors ResponseLimit directives.
64
65[MBResponseLimit CODE COUNT PERIOD] If the module receives more than COUNT responses with HTTP
66 response code CODE within PERIOD seconds, add the IP to memcache
67 with a TTL of MBExpiration seconds.
68
69== EXAMPLE
70
71Add the following lines to your Apache configuration, in the global area. Only one configuration may exist.
72
73 <IfModule memcache_block_module>
74 MBEnable On
75 # You must set timeout BEFORE the server list. If you want to have
76 # different timeouts for different sets of servers, just change it
77 # before adding more servers.
78 MBTimeout 2
79 MBServers 127.0.0.1:11211
80 MBPrefix block
81 MBExpiration 3600
82 # if you change the size of MaxBlocks, you must restart the server.
83 MBMaxBlocks 10
84 MBRateLimitByResult 401 20 3600
85 </IfModule>
86
87== KEY STORAGE
88
89mod_memcache_block writes and uses many keys in memcache. They are:
90
91[PREFIX:w:n (where 0 < n < max_blocks-1) "whitelist"]
92 The list of ranges to whitelist, in one of the following forms:
93
94 exact_string An exact string to match against the remote IP (i.e. ::1 or 127.0.0.1)
95 n.n.n.n/x A netblock in CIDR form, like 192.168.1.0/24
96 n.n.n.n-y.y.y.y A range of IPs to block, in sequential order
97
98 The enclosed setblocks.rb and removeblocks.rb ruby scripts are good
99 examples on how to add blocks to memcache. Note that keys can fall
100 out of cache! It's a good idea to refresh the list periodically and
101 to run a dedicated set of servers to manage blocks.
102
103[PREFIX:b:n (where 0 < n < max_blocks-1) "blacklist"]
104 The list of ranges to blacklist, in the same format as the
105 whitelist. If the user is in the whitelist and the blacklist, the
106 whitelist takes precedence.
107
108[PREFIX:c:IP_ADDRESS:response_code "counter"]
109 The number of times the address and response code tuple has been seen
110
111[PREFIX:d:IP_ADDRESS "Deny"]
112 If this memcache key exists, access is denied to the site. The
113 difference between this key, and the blacklist (b) key, is that
114 this key is automatically created with a TTL of MBExpiration when
115 the response count (as specified in MBRateLimit) is exceeded. When
116 the key expires from cache, the IP address is allowed back in.
117
118== KNOWN BUGS
119
120* If all memcache servers die and this module cannot connect to memcached, it will fail open (which, in our opinion, is the right thing to do.) Errors will appear in the apache error log.
121