Issue #2144525 by 1pKab, Spleshka: Error with the new compression settings in add...
[project/memcache_storage.git] / README.txt
1 ==================
2 ## REQUIREMENTS ##
3 ==================
4
5 - Availability of a memcached daemon: http://memcached.org/
6 - PECL memcache package: http://pecl.php.net/package/memcache (version 2.2.1 or greater).
7   OR PECL memcached package: http://pecl.php.net/package/memcached (version 2.0.1 or greater).
8
9
10 ==================
11 ## INSTALLATION ##
12 ==================
13
14 These are the broad steps you need to take in order to use this software. ORDER IS IMPORTANT!
15
16  1. Install the memcached binaries on your server and start the memcached
17     service. See for instance: http://www.lullabot.com/articles/how_install_memcache_debian_etch
18
19  2. Install your chosen PECL memcache extension -- this is the memcache client
20     library which will be used by the Drupal memcache module to interact with
21     the memcached server(s). Generally PECL memcached (2.0.1+) is recommended,
22     but PECL memcache (2.2.1+) also works well for some people. Use of older
23     versions may cause problems.
24
25  3. Start at least one instance of memcached on your server.
26
27  4. Download and extract Memcache Storage module into sites/all/modules directory.
28
29  5. Install the Memcache Storage module as usual.
30
31  6. Put your site into offline mode.
32
33  7. Edit settings.php to configure Memcache Storage module (see ## CONFIGURATIONS ## section).
34
35  8. Go to Status report page (/admin/reports/status) to check Memcache Storage status.
36
37  9. Bring your site back online.
38
39
40 ====================
41 ## CONFIGURATIONS ##
42 ====================
43
44 Note: all module settings should be changed only in settings.php.
45
46
47 1. QUICK CONFIGURATION
48
49 To add memcached support for your site you should simply add following settings at the bottom of settings.php:
50
51 ..
52 $conf['cache_backends'][] = 'sites/all/modules/memcache_storage/memcache_storage.inc';
53 $conf['cache_default_class'] = 'MemcacheStorage';
54 $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
55 $conf['cache_class_cache_update'] = 'DrupalDatabaseCache';
56 ..
57
58
59 2. ADVANCED CONFIGURATION
60
61 Memcache Storage module provides some additional settings for advanced users.
62
63
64 2.1. DEBUG MODE.
65
66 To enable the debug mode you can by setting 'memcache_storage_debug' to TRUE:
67
68 ..
69 $conf['memcache_storage_debug'] = TRUE;
70 ..
71
72 Default: FALSE
73
74 At the bottom of each page will be displayed all stats about memcached operations.
75
76
77 2.2. KEY PREFIX.
78
79 Add custom prefix to every memcache key.
80 You may need this if you are using one memcached instance for different sites.
81
82 ..
83 $conf['memcache_storage_key_prefix'] = 'some_key';
84 ..
85
86 Default: ''
87
88 Note that after changing this setting all cache stored in memcached pool will be flushed.
89
90
91 2.3. COMPRESSION MODE (ONLY FOR MEMCACHE EXTENSION)
92
93 You may set compress mode for all data stored in memcached pool.
94
95 ..
96 $conf['memcache_storage_compress_data'] = TRUE;
97 ..
98
99 Default: FALSE
100 See: http://www.php.net/manual/en/memcache.set.php
101
102 Enabling or disabling compression mode may lead to the minor performance changes.
103 This is depends on your server configuration.
104
105
106 2.4. COMPRESSION FOR BIG VALUES (ONLY FOR MEMCACHE EXTENSION)
107
108 Compress Threshold enables automatic compression of large values.
109
110 ..
111 $conf['memcache_storage_compress_threshold'] = array(
112   'threshold' => 20000,
113   'min_savings' => 0.2,
114 );
115 ..
116
117 Default: array('threshold' => 20000, 'min_savings' => 0.2)
118 See: http://www.php.net/manual/en/memcache.setcompressthreshold.php
119
120
121 2.5. WILDCARDS INVALIDATION.
122
123 Memcache is not allowed to flush data using wildcards so we have to store all wildcards and its creation time in variables.
124 This value allows to flush wildcards after some time when they might be expired to avoid collecting big wildcards arrays.
125
126 ..
127 $conf['memcache_storage_wildcard_invalidate'] = 60 * 60 * 24 * 30;  // 30 days.
128 ..
129
130 Default: 60 * 60 * 24 * 30 // 30 days.
131
132
133 2.6. MULTIPLE SERVERS SUPPORT.
134
135 The available memcached servers are specified in $conf in settings.php. If
136 you do not specify any servers, memcache.inc assumes that you have a
137 memcached instance running on localhost:11211. If this is true, and it is
138 the only memcached instance you wish to use, no further configuration is
139 required.
140
141 If you have more than one memcached instance running, you need to add two
142 arrays to $conf: memcache_servers and memcache_bins. The arrays follow this
143 pattern:
144
145 ..
146 $conf['memcache_servers'] => array(
147   'host1:port1' => 'default',
148   'host2:port2' => 'cluster_name2',
149   'host3:port3' => 'cluster_name3',
150 );
151
152 $conf['memcache_bins'] = array(
153   'cache'           => 'default',
154   'cache_page'      => 'cluster_name2',
155   'cache_bootstrap' => 'cluster_name3',
156 );
157 ..
158
159 The bin/cluster/server model can be described as follows:
160
161 - Servers are memcached instances identified by host:port.
162
163 - Bins are groups of data that get cached together and map 1:1 to the $table
164   parameter of cache_set(). Examples from Drupal core are cache_filter,
165   cache_menu. The default is 'cache'.
166
167 - Clusters are groups of servers that act as a memory pool.
168
169 - Many bins can be assigned to a cluster.
170
171 - The default cluster is 'default'.
172
173 Here is a simple setup that has two memcached instances, both running on
174 localhost. The 11212 instance belongs to the 'pages' cluster and the table
175 cache_page is mapped to the 'pages' cluster. Thus everything that gets cached,
176 with the exception of the page cache (cache_page), will be put into 'default',
177 or the 11211 instance. The page cache will be stored in 123.1.3.4:11212.
178
179 ..
180 $conf['memcache_servers'] => array(
181   '127.0.0.1:11211' => 'default',
182   '127.0.0.1:12211' => 'default',
183   '123.1.3.4:11211' => 'pages',
184 );
185
186 $conf['memcache_bins'] = array(
187   'cache'      => 'default',
188   'cache_page' => 'pages',
189 );
190 ..
191
192 Also you may use unix sockets as a host. See example:
193
194 ..
195 $conf['memcache_servers'] = array(
196   'unix:///path/to/memcached.socket1' => 'default',
197   'unix:///path/to/memcached.socket2' => 'bootstrap',
198   'unix:///path/to/memcached.socket3' => 'field',
199   'unix:///path/to/memcached.socket4' => 'menu',
200   'unix:///path/to/memcached.socket5' => 'page',
201   'unix:///path/to/memcached.socket6' => 'path',
202 );
203
204 $conf['memcache_bins'] = array(
205   'cache'            => 'default',
206   'cache_bootstrap'  => 'bootstrap',
207   'cache_field'      => 'field',
208   'cache_menu'       => 'menu',
209   'cache_page'       => 'page',
210   'cache_path'       => 'path',
211 );
212 ..
213
214 See: http://drupal.org/node/1181968
215
216 All cache bins not matched in the $conf['memcache_bins'] will use 'default' server.
217
218
219 2.7. CUSTOM PAGE CACHE EXPIRATION
220
221 If you want to configure expiration of cached pages separately from other cache bins, you may use following settings:
222
223 ..
224 $conf['memcache_storage_page_cache_custom_expiration'] = TRUE;
225 $conf['memcache_storage_page_cache_expire'] = 60 * 60 * 24;  // 1 day.
226 ..
227
228 In this case page cache won't be flushed automatically. It will expire only after one day.
229
230 Here you may use cool trick that will greatly reduce server load. See next config:
231
232 ..
233 $conf['memcache_storage_page_cache_custom_expiration'] = TRUE;
234 $conf['memcache_storage_page_cache_expire'] = 0;  // NEVER EXPIRE.
235 ..
236
237 In this case page cache will NEVER expire (until memcached daemon is rebooted, or cache was rewriten because of lack of the memory).
238 But you have to expire cached pages anyway. What could you do? Answer is simple: enable Memcache Storage Page Cache module!
239 This module allows you to configure custom actions for page cache expiration.
240 The idea of this module is simple: No need to expire cached page, if it was not updated.
241 You may configure custom actions that will expire page cache only for pages where content is REALLY UPDATED!
242
243
244 2.8. LOCKING
245
246 The memcache-lock.inc file included with this module can be used as a drop-in
247 replacement for the database-mediated locking mechanism provided by Drupal
248 core. To enable, define the following in your settings.php:
249
250 ..
251 $conf['lock_inc'] = 'sites/all/modules/memcache_storage/includes/lock.inc';
252 ..
253
254 Locks are written in the 'semaphore' table, which will map to the 'default'
255 memcache cluster unless you explicitly configure a 'semaphore' cluster.
256
257 Read more about locking mechanism here http://api.drupal.org/api/drupal/includes!lock.inc/group/lock/7.
258
259
260 2.9. PREFERRED EXTENSION
261
262 As Memcache Storage supports both PECL memcache and PECL memcached extensions,
263 you may choose which extension to use. But this requires only when both extenstions are enabled on a server.
264
265 ..
266 $conf['memcache_extension'] = 'Memcached';
267 ..
268
269 default: 'Memcache';
270
271
272 2.10. CONFIGURE PECL MEMCACHED EXTENSION
273
274 NOTE: It is important to realize that the memcached php.ini options do not impact
275 the memcached extension, this new extension doesn't read in options that way.
276 Instead, it takes options directly from Drupal. Because of this, you must
277 configure memcached in settings.php. Please look here for possible options:
278
279 http://www.php.net/manual/en/memcached.constants.php
280
281 An example configuration block is below, this block also illustrates our
282 default options. These will be set unless overridden in settings.php.
283
284 ..
285 $conf['memcache_options'] = array(
286   Memcached::OPT_COMPRESSION => FALSE,
287   Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT,
288 );
289 ..
290
291 These are as follows:
292
293  * Turn off compression, as this takes more CPU cycles than its worth for most users
294  * Turn on consistent distribution, which allows you to add/remove servers easily
295
296 If you are using memcached 1.4 or above, you could enable the binary protocol,
297 which is more advanced and faster, by adding the following to settings.php:
298
299 ..
300 $conf['memcache_options'] = array(
301   Memcached::OPT_BINARY_PROTOCOL => TRUE,
302 );
303 ..
304
305 If you experience slower performance when using the binary protocol, consider
306 enabling tcp no-delay mode as well:
307
308 ..
309 $conf['memcache_options'] = array(
310   Memcached::OPT_TCP_NODELAY => TRUE,
311   Memcached::OPT_BINARY_PROTOCOL => TRUE,
312 );
313 ..
314
315
316 2.11. SASL SUPPORT (ONLY FOR PECL MEMCACHED)
317
318 Memcached daemon supports authentication via SASL protocol.
319
320 This can be used to effectively limit which users on a system can access memcached,
321 as well as to strengthen it's security (not cool if user A can read data from user B...)
322 -- particularly useful on a shared hosting environment or on a open system.
323
324 Note that:
325
326 - SASL works only when binary protocol is enabled, so you need to configure your memcached daemon to work with binary protocol (-B binary).
327 - This method is only available when the Memcached PECL extension is build with SASL support.
328
329 How to enable SASL in Memcached daemon (http://code.google.com/p/memcached/wiki/SASLHowto):
330
331 - Add the flag "-S" in /etc/memcached.conf (Debian).
332 - Create an user for the login being used for memcached under php: "sudo saslpasswd2 -a memcached -c someuser" and type a password.
333
334 Enable SASL in Memcached PECL extension (http://php.net/manual/en/book.memcached.php):
335
336 - Add the option "memcached.use_sasl = 1" in /etc/php5/mods-available/memcached.ini or on your site's php.ini;
337
338 Configure Memcache Storage:
339
340 ..
341 $conf['memcache_sasl_auth'] = array(
342   'user' => 'someuser',
343   'password' => 'somepassword',
344 );
345 ..
346
347
348 2.12. PERSISTENT CONNECTION
349
350 PHP may open persistent connection to memcached daemon.
351
352 ..
353 $conf['memcache_storage_persistent_connection'] = TRUE;
354 ..
355
356 Default: FALSE
357
358
359 2.13. SESSIONS SUPPORT
360
361 Memcache Storage allows you to store all session data in memory.
362 It helps database to reduce amount of queries.
363
364 ..
365 $conf['session_inc'] = 'sites/all/modules/memcache_storage/includes/session.inc';
366 ..
367
368 Read more about sessions here http://api.drupal.org/api/drupal/includes!session.inc/7
369
370 2.14 STORING SESSIONS IN A CUSTOM MEMCACHED INSTANCE
371
372 By default all sessions are stored in 'default' memcached instance.
373 If you want to change this, you need to set up a proper configuration
374 for memcache_servers (add a new one), and point sessions bin to the
375 new server:
376
377 ..
378
379 # Configure at least two memcached servers.
380 $conf['memcache_servers'] = array(
381   '127.0.0.1:11211' => 'default',
382   '127.0.0.1:11212' => 'sessions_instance',
383 );
384
385 # Note that you need to set up this for 'sessions' AND for 'users' bins.
386 $conf['memcache_bins'] = array(
387   'sessions'  => 'sessions_instance',
388   'users'     => 'sessions_instance',
389 );
390
391 Please, do not forget, that you need to create a separate memcached instance
392 on you web server first.
393
394 2.15. INTEGRATION WITH NGINX
395
396 Since 7.x-1.1 Memcache Storage supports integration with servers that may read cached pages
397 directly from memcached pool. It stores a plain HTML text instead of object. This allows
398 server to read this HTML and serve it to user, without passing request to the backend.
399 It is very cool performance improvement because it may handle a REALLY LOT of anonymous
400 reqests per second.
401
402 To enable this feature you have to add this lines to your settings.php file:
403
404 ..
405 # Advanced usage of Drupal page cache.
406 $conf['cache_backends'][] = 'sites/all/modules/memcache_storage/memcache_storage.page_cache.inc';
407 $conf['cache_class_cache_page'] = 'MemcacheStoragePageCache';
408
409 # Enable storing of plain HTML text instead of Drupal usual cache object.
410 $conf['memcache_storage_external_page_cache'] = TRUE;
411 ..
412
413 Part of Nginx config that you will need to implement:
414
415 ..
416   # Set content type for the rest requests.
417   default_type text/html;
418
419   # Trying to find page cache in memcached pool.
420   add_header X-Nginx-Page-Cache HIT;
421   set $memcached_key "[PREFIX]-cache_page-$scheme://$server_name$uri$is_args$args";
422   memcached_pass unix:/var/run/memcached/memcached.socket0;
423
424   proxy_intercept_errors on;
425   error_page 404 502 = @drupal;
426 ..
427
428 If you didn't define $conf['memcache_storage_key_prefix'] $memcache_key will look like that:
429
430 ..
431   set $memcached_key "cache_page-$scheme://$server_name$uri$is_args$args";
432 ..
433
434 I promise that later I will create an article with full example of Nginx configuration.
435 But now I can show you only main part of it. All the rest you have to do yourself.
436 You may find useful this article: http://nginx.org/en/docs/http/ngx_http_memcached_module.html
437
438
439 ====================================
440 ## DRUSH SUPPORT ##
441 ====================================
442
443 1. To flush ALL DATA stored in memcached print one of the following drush command:
444
445 ..
446 drush memcache-storage-flush
447 drush ms-flush
448 ..
449
450 2. To remove cache object from bin use next commands:
451
452 drush memcache-storage-clear-cache CACHE_ID CACHE_BIN
453
454 Examples:
455
456 drush memcache-storage-clear-cache panels:223  // Removes cache with ID 'panels:223' from bin 'cache'.
457 drush ms-cc module_implements cache_bootstrap  // Removes cache with ID 'module_implements' from bin 'cache_bootstrap'.
458
459 3. To invalidate all cache objects in some cache bin, use this command:
460
461 drush memcache-storage-flush-bin CACHE_BIN
462
463 Examples:
464
465 drush memcache-storage-flush-bin  // Flushes cache bin 'cache'.
466 drush ms-fb cache_bootstrap  // Flushes cache bin 'cache_bootstrap'.
467
468
469 ====================================
470 ## ADVANCED CONFIGARATION EXAMPLE ##
471 ====================================
472
473 # Move all cached data (except form cache) to memcache storage.
474 $conf['cache_backends'][] = 'sites/all/modules/memcache_storage/memcache_storage.inc';
475 $conf['cache_default_class'] = 'MemcacheStorage';
476 $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
477 $conf['cache_class_cache_update'] = 'DrupalDatabaseCache';
478
479 # Advanced usage of Drupal page cache.
480 $conf['cache_backends'][] = 'sites/all/modules/memcache_storage/memcache_storage.page_cache.inc';
481 $conf['cache_class_cache_page'] = 'MemcacheStoragePageCache';
482
483 # Do not connect to the database when serving cached page for anonymous users.
484 $conf['page_cache_invoke_hooks'] = FALSE;
485 $conf['page_cache_without_database'] = TRUE;
486
487 # Open persistent memcached connection.
488 $conf['memcache_storage_persistent_connection'] = TRUE;
489
490 # Configure Memcache Storage module.
491 $conf['memcache_storage_debug'] = TRUE;
492 $conf['memcache_storage_key_prefix'] = 'build-1';
493 $conf['memcache_storage_wildcard_invalidate'] = 60 * 60 * 24 * 5; // 5 days.
494
495 # Add multiple memcached instances.
496 $conf['memcache_servers'] = array(
497   'unix:///var/run/memcached/memcached.socket0' => 'default',
498   'unix:///var/run/memcached/memcached.socket1' => 'bootstrap',
499   'unix:///var/run/memcached/memcached.socket2' => 'field',
500   'unix:///var/run/memcached/memcached.socket3' => 'page',
501 );
502
503 # Set reference between cache bins and memcache server names.
504 # All other bins will be refered to the 'default' server.
505 $conf['memcache_bins'] = array(
506   'cache_bootstrap'  => 'bootstrap',
507   'cache_field'      => 'field',
508   'cache_page'       => 'page',
509 );
510
511 # Set custom expiration for cached pages.
512 $conf['memcache_storage_page_cache_custom_expiration'] = TRUE;
513 $conf['memcache_storage_page_cache_expire'] = 60 * 60 * 24;  // 1 day.
514
515 # Set current extension.
516 $conf['memcache_extension'] = 'Memcached';
517
518 # Configure memcached extenstion.
519 $conf['memcache_options'] = array(
520   Memcached::OPT_TCP_NODELAY => TRUE,
521   Memcached::OPT_BINARY_PROTOCOL => TRUE,
522 );
523
524 # Move storage for lock system into memcached.
525 $conf['lock_inc'] = 'sites/all/modules/memcache_storage/includes/lock.inc';
526
527 # Move storage for sessions into memcached.
528 $conf['session_inc'] = 'sites/all/modules/memcache_storage/includes/session.inc';
529
530 =============
531 ## CREDITS ##
532 =============
533
534 Module was designed and developed by Maslouski Yauheni (http://drupalace.ru).
535 Module development was not sponsored by anyone. It was created for the love of Drupal.