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