Installation
These are the broad steps you need to take in order to use this
software on Drupal 6.x.Information pertaining to the Drupal 7.x version
is also found in the README.txt file from the module distribution.
For 6.x (order is important):
-
Install the memcached binaries on your server. See
-
Install the PECL memcache extension for PHP.
-
In php.ini set memcache.hash_strategy="consistent".
-
Put your site into offline mode.
-
Download and install the memcache module.
-
If you have previously been running the memcache module, run update.php.
-
Start at least one instance of memcached on your server.
-
Edit settings.php to configure the servers, clusters and bins that memcache is supposed to use. (see code snippet below)
-
Edit settings.php to include memcache.inc. For example, $conf['cache_inc'] ='sites/all/modules/memcache/memcache.inc';
-
Bring your site back online.
For 7.x (order is important):
-
Install the memcached binaries on your server. See
-
Install the PECL memcache extension for PHP. This must be version 2.2.1 or higher or you will experience errors.
-
Put your site into offline mode.
-
Download and install the memcache module.
-
If you have previously been running the memcache module, run update.php.
-
Start at least one instance of memcached on your server.
-
Edit settings.php to make memcache the default cache class, for example:
$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';
// The 'cache_form' bin must be assigned no non-volatile storage.
$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';
$conf['cache_default_class'] = 'MemCacheDrupal';
$conf['memcache_key_prefix'] = 'something_unique';
-
Bring your site back online.
For instructions on 1 and 2 above, please see the INSTALLATION.txt file that comes with the memcache module download.
Servers
NOTE: As of 6.15, it is possible to efficiently run memcache in one
daemon, shared by all bins. You can safely ignore advice found elsewhere
on the internet that advises one memcached daemon per bin.
In terms of reporting, there are still some advantages to having more
daemons. 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.
Security
You should probably lock down the memcache server so that it only listens for connections from the hosts that need to be served.
The default on some installations is that memcache listens to
connections from all addresses. To close that hole, modify your
memcached configuration as follows:
On RHEL/CentOS, edit /etc/sysconfig/memcached:
OPTIONS="-l ${HOSTIP}"
For example:
OPTIONS="-l 127.0.0.1"
On Debian/Ubuntu, edit /etc/memcached.conf:
-l ${HOSTIP}
For example:
-l 127.0.0.1
Configuration
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 the local machine on port
11211 (127.0.0.1:11211).
If this is true, and it is the only memcached instance you wish to
use, no further configuration is required. 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:
<?php
$conf['memcache_servers'] = array(
host1:port => cluster,
host2:port => cluster,
hostN:port => cluster);$conf['memcache_bins'] = array(
bin1 => cluster,
bin2 => cluster,
binN => cluster);?>
WARNING: Avoid the use of "localhost" and instead use real IP
addresses or hostnames that will remain consistent across the network.
The bin/cluster/server model can be described as follows:
-
Servers are memcached instances identified by host:port.
-
Bins are groups of data that get cached together and map 1:1 to the
$table param in cache_set(). Examples from Drupal core are cache_filter,
cache_menu. The default is 'cache'.
-
Clusters are groups of servers that act as a memory pool.
-
Many bins can be assigned to a cluster.
-
The default cluster is 'default'.
Here is a simple setup that has two memcached instances, both
running on 10.1.1.1. The 11212 instance belongs to the 'pages' cluster
and the table cache_page is mapped to the 'pages' cluster. Thus
everything that gets cached, with the exception of the page cache
(cache_page), will be put into 'default', or the 11211 instance. The
page cache will be in 11212.
<?php
$conf['memcache_servers'] = array(
'10.1.1.1:11211' => 'default',
'10.1.1.1:11212' => 'pages');$conf['memcache_bins'] = array(
'cache_page' => 'pages',
);?>
Here is an example configuration that has two clusters, 'default' and
'cluster2'. Five memcached instances are divided up between the two
clusters. 'cache_filter' and 'cache_menu' bins go to 'cluster2'. All
other bins go to 'default'.
D6:
<?php
$conf['cache_inc'] = './sites/all/modules/memcache/memcache.inc';$conf['memcache_servers'] = array(
'10.1.1.1:11211' => 'default',
'10.1.1.1:11212' => 'default',
'10.1.1.2:11211' => 'default',
'10.1.1.3:11211' => 'cluster2',
'10.1.1.4:11211' => 'cluster2');$conf['memcache_bins'] = array(
'cache' => 'default',
'cache_filter' => 'cluster2',
'cache_menu' => 'cluster2');?>
D7:
<?php
$conf['cache_backends'][] = 'sites/all/modules/memcache/memcache.inc';$conf['cache_default_class'] = 'MemCacheDrupal';// The 'cache_form' bin must be assigned no non-volatile storage.$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';$conf['memcache_servers'] = array(
'10.1.1.1:11211' => 'default',
'10.1.1.1:11212' => 'default',
'10.1.1.2:11211' => 'default',
'10.1.1.3:11211' => 'cluster2',
'10.1.1.4:11211' => 'cluster2');$conf['memcache_bins'] = array(
'cache' => 'default',
'cache_filter' => 'cluster2',
'cache_menu' => 'cluster2');?>
Prefixing
If you want to have multiple Drupal installations share memcached
instances, you need to include a unique prefix for each Drupal
installation in the
$confarray in settings.php:
<?php
$conf['memcache_key_prefix'] = 'something_unique';?>
Sessions
NOTE: Session.inc is not yet stable in Drupal 7 (see
#656838: [META] Port sessions to D7 for current status).
You MUST have setup separate memcached instances for both session and users for memcached sessions to work.
Here is a sample config that uses memcache for sessions.
<?php
$conf['cache_default_class'] = 'MemCacheDrupal';// The 'cache_form' bin must be assigned no non-volatile storage.$conf['cache_class_cache_form'] = 'DrupalDatabaseCache';$conf['session_inc'] = './sites/all/modules/memcache/memcache-session.inc';$conf['memcache_servers'] = array(
'localhost:11211' => 'default',
'localhost:11212' => 'session',
'localhost:11213' => 'users',
);$conf['memcache_bins'] = array(
'cache' => 'default',
'session' => 'session',
'users' => 'users',
);?>
Troubleshooting
See the
troubleshooting guide.
Memcache Admin
A module offering a UI for memcache is included. It provides aggregated and per-page statistics for memcache.
Memcached PECL Extension Support
We also support the Memcached PECL extension. This extension backends
to libmemcached and allows you to use some of the newer advanced
features in memcached 1.4.
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 see the
PECL Memcached documentation for possible options.
An example configuration block is below, this block also illustrates the
default options (selected through performance testing). These options will be set unless overridden in settings.php.
<?php
$conf['memcache_options'] = array(
Memcached::OPT_COMPRESSION => FALSE,
Memcached::OPT_DISTRIBUTION => Memcached::DISTRIBUTION_CONSISTENT,
);?>
These are as follows:
- Turn off compression, as this takes more CPU cycles than it's worth for most users
- Turn on consistent distribution, which allows you to add/remove servers easily
Other options you could experiment with:
- Memcached::OPT_BINARY_PROTOCOL => TRUE
- This enables the Memcache binary protocol (only available in
Memcached 1.4 and later). Note that some users have reported SLOWER
performance with this feature enabled. It should only be enabled on
extremely high traffic networks where memcache network traffic is a
bottleneck.
Additional reading about the binary protocol:
http://code.google.com/p/memcached/wiki/MemcacheBinaryProtocol
- Memcached::OPT_TCP_NODELAY => TRUE
- This enables the no-delay feature for connecting sockets; it's been
reported that this can speed up the Binary protocol (see above). This
tells the TCP stack to send packets immediately and without waiting for a
full payload, reducing per-packet network latency (disabling
"Nagling").
