README.txt 8.09 KB
Newer Older
robertDouglass's avatar
robertDouglass committed
1

robertDouglass's avatar
robertDouglass committed
2 3 4 5 6
## REQUIREMENTS ##

- PHP 5.1 or greater
- Availability of a memcached daemon: http://memcached.org/
- One of the two PECL memcache packages:
7 8
  - http://pecl.php.net/package/memcache (recommended):
  - http://pecl.php.net/package/memcached
robertDouglass's avatar
robertDouglass committed
9

robertDouglass's avatar
robertDouglass committed
10
## INSTALLATION ##
11

12 13 14
These are the broad steps you need to take in order to use this software. Order
is important.

15 16 17 18 19 20 21 22 23 24 25 26 27
 1. Install the memcached binaries on your server. See for instance:
      http://www.lullabot.com/articles/how_install_memcache_debian_etch
 2. Install the PECL memcache extension for PHP. This must be version 2.2.1 or 
    higher or you will experience errors.
 3. Put your site into offline mode.
 4. Download and install the memcache module.
 5. If you have previously been running the memcache module, run update.php.
 6. Start at least one instance of memcached on your server.
 7. Edit settings.php to configure the servers, clusters and bins that memcache
    is supposed to use.
 8. Edit settings.php to make memcache the default cache class, for example:
      $conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
      $conf['cache_default_class'] = 'MemCacheDrupal';
28 29 30
 9. Make sure the following line also exists, to ensure that the special
    cache_form bin is assigned to non-volatile storage:
      $conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
31
10. Bring your site back online.
32 33 34 35

For instructions on 1 and 2 above, please see the INSTALLATION.txt file that
comes with the memcache module download.

robertDouglass's avatar
robertDouglass committed
36
## SERVERS ##
37

38 39 40 41 42 43 44
If you want the simple version, you can start one default memcache instance on
your web server like this: memcached -m 24 -p 11211 -d
If that is enough to meet your needs, there is no more configuration needed. If
you want to utilize this module's sophisticated clustering feature and spread
your cache over several machines, or if your cache is found on a machine other
than your web server, read on.

lyricnz's avatar
lyricnz committed
45 46 47 48 49
The available memcached servers are specified in $conf in settings.php. If
you do not specify any servers, memcache.inc assumes that you have a
memcached instance running on localhost:11211. If this is true, and it is
the only memcached instance you wish to use, no further configuration is
required.
robertDouglass's avatar
robertDouglass committed
50

lyricnz's avatar
lyricnz committed
51 52 53
If you have more than one memcached instance running, you need to add two
arrays to $conf; memcache_servers and memcache_bins. The arrays follow this
pattern:
robertDouglass's avatar
robertDouglass committed
54

55 56 57
'memcache_servers' => array(
  host1:port => cluster, 
  host2:port => cluster, 
58 59
  hostN:port => cluster,
  'unix:///path/to/socket' => cluster
60
)
robertDouglass's avatar
robertDouglass committed
61 62 63 64 65 66

'memcache_bins' => array(bin1 => cluster, bin2 => cluster, binN => cluster)

The bin/cluster/server model can be described as follows:

- Servers are memcached instances identified by host:port.
lyricnz's avatar
lyricnz committed
67 68

- Bins are groups of data that get cached together and map 1:1 to the $table
69
  parameter of cache_set(). Examples from Drupal core are cache_filter,
lyricnz's avatar
lyricnz committed
70 71
  cache_menu. The default is 'cache'.

72
- Clusters are groups of servers that act as a memory pool.
lyricnz's avatar
lyricnz committed
73

robertDouglass's avatar
robertDouglass committed
74
- many bins can be assigned to a cluster.
lyricnz's avatar
lyricnz committed
75

robertDouglass's avatar
robertDouglass committed
76 77
- The default cluster is 'default'.

78 79 80 81 82 83 84 85 86
Here is a simple setup that has three memcached instances, two running on
localhost, and one on a Unix socket. The 11212 instance belongs to the 'pages'
cluster and the table cache_page is mapped to the 'pages' cluster. The Unix
socket instance belongs to the 'blocks' cluster, and the table cache_block is
mapped to the 'blocks' cluster. Thus everything that gets cached, with the
exception of the page cache (cache_page) and block cache (cache_block), will be
put into 'default', or the 11211 instance. The page cache will be in 11212, and
the block cache in the Unix socket instance. Note that no port is specified for
the socket.
87 88 89

$conf = array(
  ...
Steve Rude's avatar
Steve Rude committed
90 91
  // Important to define a default cluster in both the servers
  // and in the bins. This links them together.
92
  'memcache_servers' => array('localhost:11211' => 'default',
93 94
                              'localhost:11212' => 'pages',
                              'unix:///path/to/socket' => 'blocks'),
Steve Rude's avatar
Steve Rude committed
95
  'memcache_bins' => array('cache' => 'default',
96 97
                           'cache_page' => 'pages',
                           'cache_block' => 'blocks'),
98 99
);

lyricnz's avatar
lyricnz committed
100 101
Here is an example configuration that has two clusters, 'default' and
'cluster2'. Five memcached instances are divided up between the two
102
clusters. 'cache_filter' and 'cache_menu' bins go to 'cluster2'. All other
lyricnz's avatar
lyricnz committed
103
bins go to 'default'.
robertDouglass's avatar
robertDouglass committed
104

105 106
$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
$conf['cache_default_class'] = 'MemCacheDrupal';
107 108
// The 'cache_form' bin must be assigned no non-volatile storage.
$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
robertDouglass's avatar
robertDouglass committed
109
$conf = array(
110
  'cache_default_class' = 'MemCacheDrupal',
robertDouglass's avatar
robertDouglass committed
111 112 113 114
  'memcache_servers' => array('localhost:11211' => 'default',
                              'localhost:11212' => 'default',
                              '123.45.67.890:11211' => 'default',
                              '123.45.67.891:11211' => 'cluster2',
robertDouglass's avatar
robertDouglass committed
115 116
                              '123.45.67.892:11211' => 'cluster2'),

robertDouglass's avatar
robertDouglass committed
117 118
  'memcache_bins' => array('cache' => 'default',
                           'cache_filter' => 'cluster2',
lyricnz's avatar
lyricnz committed
119
                           'cache_menu' => 'cluster2'),
robertDouglass's avatar
robertDouglass committed
120
);
121

122
## PREFIXING ##
Steve Rude's avatar
Steve Rude committed
123

124 125 126
If you want to have multiple Drupal installations share memcached instances,
you need to include a unique prefix for each Drupal installation in the $conf
array of settings.php:
Steve Rude's avatar
Steve Rude committed
127

128 129 130 131
$conf = array(
  ...
  'memcache_key_prefix' => 'something_unique',
);
robertDouglass's avatar
robertDouglass committed
132

133
## SESSIONS ##
134

135 136 137
NOTE: Session.inc is not yet ported to Drupal 7 and is not recommended for use
in production..

138 139
Here is a sample config that uses memcache for sessions. Note you MUST have
a session and a users server set up for memcached sessions to work.
140

141 142
$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
$conf['cache_default_class'] = 'MemCacheDrupal';
143 144
// The 'cache_form' bin must be assigned no non-volatile storage.
$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
$conf = array(
  'cache_default_class' = 'MemCacheDrupal',
  'session_inc' => './sites/all/modules/memcache/memcache-session.inc',
  'memcache_servers' => array(
    'localhost:11211' => 'default',
    'localhost:11212' => 'filter',
    'localhost:11213' => 'menu',
    'localhost:11214' => 'page',
    'localhost:11215' => 'session',
    'localhost:11216' => 'users',
  ),
  'memcache_bins' => array(
    'cache' => 'default',
    'cache_filter' => 'filter',
    'cache_menu' => 'menu',
    'cache_page' => 'page',
    'session' => 'session',
    'users' => 'users',
  ),
);
165 166


167
## TROUBLESHOOTING ##
168

Steve Rude's avatar
Steve Rude committed
169 170 171 172 173 174 175
PROBLEM:
Error:
Failed to set key: Failed to set key: cache_page-......

SOLUTION:
Upgrade your PECL library to PECL package (2.2.1) (or higher).

176 177 178 179
WARNING: 
Zlib compression at the php.ini level and Memcache conflict. 
See http://drupal.org/node/273824

robertDouglass's avatar
robertDouglass committed
180
## MEMCACHE ADMIN ##
181

182
A module offering a UI for memcache is included. It provides stats, a
lyricnz's avatar
lyricnz committed
183
way to clear the cache, and an interface to organize servers/bins/clusters.
184 185 186

## Memcached PECL Extension Support

187 188 189
We also now support the Memcached PECL extension. This new extension backends
to libmemcached and allows you to use some of the newer advanced features in
memcached 1.4. 
190 191 192 193 194 195 196 197 198

NOTE: It is important to realize that the memcache php.ini options do not impact
the memcached extension, this new extension doesn't read in options that way.
Instead, it takes options directly from Drupal. Because of this, you must
configure memcached in settings.php. Please look here for possible options:

http://us2.php.net/manual/en/memcached.constants.php

An example configuration block is below, this block also illustrates our
199
default options. These will be set unless overridden in settings.php.
200 201

$conf['memcache_options'] = array(
202
  Memcached::OPT_COMPRESSION => FALSE,
203 204 205 206 207
  Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT,
);

These are as follows:

208 209
 * Turn off compression, as this takes more CPU cycles than its worth for most
   users
210 211
 * Turn on consistent distribution, which allows you to add/remove servers
   easily
212 213 214 215 216 217 218

If you are using memcached 1.4 or above, you should enable the binary protocol,
which is more advanced and faster, by adding the following to settings.php:

$conf['memcache_options'] = array(
  Memcached::OPT_BINARY_PROTOCOL => TRUE,
);