Issue #1547390 by Jeremy: cleanup admin wstats overview page.
[project/memcache.git] / README.txt
1 ## IMPORTANT NOTE ##
2
3 This file contains installation instructions for the 7.x-1.x version of the
4 Drupal Memcache module. Configuration differs between 7.x and 6.x versions
5 of the module, so be sure to follow the 6.x instructions if you are configuring
6 the 6.x-1.x version of this module!
7
8 ## REQUIREMENTS ##
9
10 - PHP 5.1 or greater
11 - Availability of a memcached daemon: http://memcached.org/
12 - One of the two PECL memcache packages:
13   - http://pecl.php.net/package/memcache (recommended)
14   - http://pecl.php.net/package/memcached (latest versions require PHP 5.2 or
15     greater)
16
17 ## INSTALLATION ##
18
19 These are the steps you need to take in order to use this software. Order
20 is important.
21
22  1. Install the memcached binaries on your server and start the memcached
23     service.
24  2. Install your chosen PECL memcache extension -- this is the memcache client
25     library which will be used by the Drupal memcache module to interact with
26     the memcached server(s). Generally PECL memcache (3.0.6+) is recommended,
27     but PECL memcached (2.0.1+) also works well for some people. There are
28     known issues with older version.
29  3. Put your site into offline mode.
30  4. Download and install the memcache module.
31  5. If you have previously been running the memcache module, run update.php.
32  6. Edit settings.php to configure the servers, clusters and bins that memcache
33     is supposed to use.
34  7. Edit settings.php to make memcache the default cache class, for example:
35       $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
36       $conf['cache_default_class'] = 'MemCacheDrupal';
37     The cache_backends path needs to be adjusted based on where you installed
38     the module.
39  8. Make sure the following line also exists, to ensure that the special
40     cache_form bin is assigned to non-volatile storage:
41       $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
42  9. Optionally also add the following two lines to tell Drupal not to bootstrap
43     the database when serving cached pages to anonymous visitors:
44       $conf['page_cache_without_database'] = TRUE;
45       $conf['page_cache_invoke_hooks'] = FALSE;
46     If setting page_cache_without_database to TRUE, you also have to set
47     page_cache_invoke_hooks to FALSE or you'll see an error like "Fatal error:
48     Call to undefined function module_list()".
49 10. Bring your site back online.
50
51 For more detailed instructions on (1) and (2) above, please see the
52 documentation online on drupal.org which includes links to external
53 walk-throughs for various operating systems.
54
55 ## Advanced Configuration ##
56
57 This module is capable of working with one memcached instance or with multiple
58 memcached instances run across one or more servers. The default is to use one
59 server accessible on localhost port 11211. If that meets your needs, then the
60 configuration settings outlined above are sufficient for the module to work.
61 If you want to use multiple memcached instances, or if you are connecting to a
62 memcached instance located on a remote machine, further configuration is
63 required.
64
65 The available memcached servers are specified in $conf in settings.php. If you
66 do not specify any servers, memcache.inc assumes that you have a memcached
67 instance running on localhost:11211. If this is true, and it is the only
68 memcached instance you wish to use, no further configuration is required.
69
70 If you have more than one memcached instance running, you need to add two arrays
71 to $conf; memcache_servers and memcache_bins. The arrays follow this pattern:
72
73 'memcache_servers' => array(
74   server1:port => cluster1,
75   server2:port => cluster2,
76   serverN:port => clusterN,
77   'unix:///path/to/socket' => clusterS
78 )
79
80 'memcache_bins' => array(
81    bin1 => cluster1,
82    bin2 => cluster2,
83    binN => clusterN,
84    binS => clusterS
85 )
86
87 The bin/cluster/server model can be described as follows:
88
89 - Servers are memcached instances identified by host:port.
90
91 - Clusters are groups of servers that act as a memory pool. Each cluster can
92   contain one or more servers.
93
94 - Bins are groups of data that get cached together and map 1:1 to the $table
95   parameter of cache_set(). Examples from Drupal core are cache_filter and
96   cache_menu. The default is 'cache'.
97
98 - Multiple bins can be assigned to a cluster.
99
100 - The default cluster is 'default'.
101
102 ## LOCKING ##
103
104 The memcache-lock.inc file included with this module can be used as a drop-in
105 replacement for the database-mediated locking mechanism provided by Drupal
106 core. To enable, define the following in your settings.php:
107
108 $conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
109
110 Locks are written in the 'semaphore' table, which will map to the 'default'
111 memcache cluster unless you explicitly configure a 'semaphore' cluster.
112
113 ## STAMPEDE PROTECTION ##
114
115 Memcache includes stampede protection for rebuilding expired and invalid cache
116 items.  To enable stampede protection, define the following in settings.php:
117
118 $conf['memcache_stampede_protection'] = TRUE;
119
120 To avoid lock stampedes, it is important that you enable the memacache lock
121 implementation when enabling stampede protection -- enabling stampede protection
122 without enabling the Memache lock implementation can cause worse performance.
123
124 Only change the following values if you're sure you know what you're doing,
125 which requires reading the memcachie.inc code.
126
127 The value passed to lock_acquire, defaults to '15':
128   $conf['memcache_stampede_semaphore'] = 15;
129
130 The value passed to lock_wait, defaults to 5:
131   $conf['memcache_stampede_wait_time'] = 5;
132
133 The maximum number of calls to lock_wait() due to stampede protection during a
134 single request, defaults to 3:
135   $conf['memcache_stampede_wait_limit'] = 3;
136
137 When adjusting these variables, be aware that:
138  - there is unlikely to be a good use case for setting wait_time higher
139    than stampede_semaphore;
140  - wait_time * wait_limit is designed to default to a number less than
141    standard web server timeouts (i.e. 15 seconds vs. apache's default of
142    30 seconds).
143
144 ## EXAMPLES ##
145
146 Example 1:
147
148 First, the most basic configuration which consists of one memcached instance
149 running on localhost port 11211 and all caches except for cache_form being
150 stored in memcache. We also enable stampede protection, and the memcache
151 locking mechanism. Finally, we tell Drupal to not bootstrap the database when
152 serving cached pages to anonymous visitors.
153
154   $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
155   $conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
156   $conf['memcache_stampede_protection'] = TRUE;
157   $conf['cache_default_class'] = 'MemCacheDrupal';
158
159   // The 'cache_form' bin must be assigned to non-volatile storage.
160   $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
161
162   // Don't bootstrap the database when serving pages from the cache.
163   $conf['page_cache_without_database'] = TRUE;
164   $conf['page_cache_invoke_hooks'] = FALSE;
165
166 Note that no servers or bins are defined.  The default server and bin
167 configuration which is used in this case is equivalant to setting:
168
169   $conf['memcache_servers'] = array('localhost:11211' => 'default');
170
171
172 Example 2:
173
174 In this example we define three memcached instances, two accessed over the
175 network, and one on a Unix socket -- please note this is only an illustration of
176 what is possible, and is not a recommended configuration as it's highly unlikely
177 you'd want to configure memcache to use both sockets and network addresses like
178 this, instead you'd consistently use one or the other.
179
180 The instance on port 11211 belongs to the 'default' cluster where everything
181 gets cached that isn't otherwise defined. (We refer to it as a "cluster", but in
182 this example our "clusters" involve only one instance.) The instance on port
183 11212 belongs to the 'pages' cluster, with the 'cache_page' table mapped to
184 it -- so the Drupal page cache is stored in this cluster.  Finally, the instance
185 listening on a socket is part of the 'blocks' cluster, with the 'cache_block'
186 table mapped to it -- so the Drupal block cache is stored here. Note that
187 sockets do not have ports.
188
189   $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
190   $conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
191   $conf['memcache_stampede_protection'] = TRUE;
192   $conf['cache_default_class'] = 'MemCacheDrupal';
193
194   // The 'cache_form' bin must be assigned no non-volatile storage.
195   $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
196
197   // Don't bootstrap the database when serving pages from the cache.
198   $conf['page_cache_without_database'] = TRUE;
199   $conf['page_cache_invoke_hooks'] = FALSE;
200
201   // Important to define a default cluster in both the servers
202   // and in the bins. This links them together.
203   $conf['memcache_servers'] = array('10.1.1.1:11211' => 'default',
204                                     '10.1.1.1:11212' => 'pages',
205                                     'unix:///path/to/socket' => 'blocks');
206   $conf['memcache_bins'] = array('cache' => 'default',
207                                  'cache_page' => 'pages',
208                                  'cache_block' => 'blocks');
209
210
211 Example 3:
212
213 Here is an example configuration that has two clusters, 'default' and
214 'cluster2'. Five memcached instances running on four different servers are
215 divided up between the two clusters. The 'cache_filter' and 'cache_menu' bins
216 go to 'cluster2'. All other bins go to 'default'.
217
218   $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
219   $conf['lock_inc'] = 'sites/all/modules/memcache/memcache-lock.inc';
220   $conf['memcache_stampede_protection'] = TRUE;
221   $conf['cache_default_class'] = 'MemCacheDrupal';
222
223   // The 'cache_form' bin must be assigned no non-volatile storage.
224   $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
225
226   // Don't bootstrap the database when serving pages from the cache.
227   $conf['page_cache_without_database'] = TRUE;
228   $conf['page_cache_invoke_hooks'] = FALSE;
229
230   $conf['memcache_servers'] = array('10.1.1.6:11211' => 'default',
231                                     '10.1.1.6:11212' => 'default',
232                                     '10.1.1.7:11211' => 'default',
233                                     '10.1.1.8:11211' => 'cluster2',
234                                     '10.1.1.9:11211' => 'cluster2');
235
236   $conf['memcache_bins'] = array('cache' => 'default',
237                                  'cache_filter' => 'cluster2',
238                                  'cache_menu' => 'cluster2');
239   );
240
241
242 ## PREFIXING ##
243
244 If you want to have multiple Drupal installations share memcached instances,
245 you need to include a unique prefix for each Drupal installation in the $conf
246 array of settings.php:
247
248 $conf['memcache_key_prefix'] = 'something_unique';
249
250 Note: if the length of your prefix + key + bin combine to be more than 250
251 characters, they will be automatically hashed. Memcache only supports key
252 lengths up to 250 bytes. You can optionally configure the hashing algorithm
253 used, however sha1 was selected as the default because it performs quickly with
254 minimal collisions.
255
256 $conf['memcache_key_hash_algorithm'] = 'sha1';
257
258 Visit http://www.php.net/manual/en/function.hash-algos.php to learn more about
259 which hash algorithms are available.
260
261 ## MULTIPLE SERVERS ##
262
263 To use this module with multiple memcached servers, it is important that you set
264 the hash strategy to consistent. This is controlled in the PHP extension, not the
265 Drupal module.
266
267 If using PECL memcache:
268 Edit /etc/php.d/memcache.ini (path may changed based on package/distribution) and
269 set the following:
270 memcache.hash_strategy=consistent
271
272 You need to reload apache httpd after making that change.
273
274 If using PECL memcached:
275 Memcached options can be controlled in settings.php.  The following setting is
276 needed:
277 $conf['memcache_options'] = array(
278   Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT,
279 );
280
281 ## SESSIONS ##
282
283 NOTE: Session.inc is not yet ported to Drupal 7 and is not recommended for use
284 in production.
285
286 Here is a sample config that uses memcache for sessions. Note you MUST have
287 a session and a users server set up for memcached sessions to work.
288
289 $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
290 $conf['cache_default_class'] = 'MemCacheDrupal';
291
292 // The 'cache_form' bin must be assigned no non-volatile storage.
293 $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
294 $conf['session_inc'] = 'sites/all/modules/memcache/unstable/memcache-session.inc';
295
296 $conf['memcache_servers'] = array(
297     '10.1.1.1:11211' => 'default',
298     '10.1.1.1:11212' => 'filter',
299     '10.1.1.1:11213' => 'menu',
300     '10.1.1.1:11214' => 'page',
301     '10.1.1.1:11215' => 'session',
302     '10.1.1.1:11216' => 'users',
303 );
304 $conf['memcache_bins'] = array(
305     'cache' => 'default',
306     'cache_filter' => 'filter',
307     'cache_menu' => 'menu',
308     'cache_page' => 'page',
309     'session' => 'session',
310     'users' => 'users',
311 );
312
313 ## TROUBLESHOOTING ##
314
315 PROBLEM:
316 Error:
317 Failed to set key: Failed to set key: cache_page-......
318
319 SOLUTION:
320 Upgrade your PECL library to PECL package (2.2.1) (or higher).
321
322 WARNING:
323 Zlib compression at the php.ini level and Memcache conflict.
324 See http://drupal.org/node/273824
325
326 ## MEMCACHE ADMIN ##
327
328 A module offering a UI for memcache is included. It provides aggregated and
329 per-page statistics for memcache.
330
331 ## Memcached PECL Extension Support
332
333 We also support the Memcached PECL extension. This extension backends
334 to libmemcached and allows you to use some of the newer advanced features in
335 memcached 1.4.
336
337 NOTE: It is important to realize that the memcache php.ini options do not impact
338 the memcached extension, this new extension doesn't read in options that way.
339 Instead, it takes options directly from Drupal. Because of this, you must
340 configure memcached in settings.php. Please look here for possible options:
341
342 http://us2.php.net/manual/en/memcached.constants.php
343
344 An example configuration block is below, this block also illustrates our
345 default options (selected through performance testing). These options will be
346 set unless overridden in settings.php.
347
348 $conf['memcache_options'] = array(
349   Memcached::OPT_COMPRESSION => FALSE,
350   Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT,
351 );
352
353 These are as follows:
354
355  * Turn off compression, as this takes more CPU cycles than it's worth for most
356    users
357  * Turn on consistent distribution, which allows you to add/remove servers
358    easily
359
360 Other options you could experiment with:
361  + Memcached::OPT_BINARY_PROTOCOL => TRUE,
362     * This enables the Memcache binary protocol (only available in Memcached
363       1.4 and later). Note that some users have reported SLOWER performance
364       with this feature enabled. It should only be enabled on extremely high
365       traffic networks where memcache network traffic is a bottleneck.
366       Additional reading about the binary protocol:
367         http://code.google.com/p/memcached/wiki/MemcacheBinaryProtocol
368
369  + Memcached::OPT_TCP_NODELAY => TRUE,
370     * This enables the no-delay feature for connecting sockets; it's been
371       reported that this can speed up the Binary protocol (see above). This
372       tells the TCP stack to send packets immediately and without waiting for
373       a full payload, reducing per-packet network latency (disabling "Nagling").