| 1 |
// $Id: README.txt,v 1.4.2.8 2007/12/05 10:33:31 robertDouglass Exp $
|
| 2 |
|
| 3 |
## INSTALLATION ##
|
| 4 |
|
| 5 |
These are the broad steps you need to take in order to use this software. Order
|
| 6 |
is important.
|
| 7 |
|
| 8 |
1. Install the memcached binaries on your server. See http://www.lullabot.com/articles/how_install_memcache_debian_etch
|
| 9 |
2. Install the PECL memcache extension for PHP. This must be version 2.2.1 or higher or you will experience errors.
|
| 10 |
3. Put your site into offline mode.
|
| 11 |
4. Download and install the memcache module.
|
| 12 |
5. If you have previously been running the memcache module, run update.php.
|
| 13 |
6. Apply the DRUPAL-5-x-cache-serialize.patch from the patches folder that
|
| 14 |
comes with the module. Version specific, so use DRUPAL-5-6-cache-serialize.patch
|
| 15 |
if you are running Drupal 5.6.
|
| 16 |
7. Start at least one instance of memcached on your server.
|
| 17 |
8. Edit settings.php to configure the servers, clusters and bins that memcache
|
| 18 |
is supposed to use.
|
| 19 |
9. Edit settings.php to include either memcache.inc or memcache.db.inc. For
|
| 20 |
example, $conf['cache_inc'] ='sites/all/modules/memcache/memcache.db.inc';
|
| 21 |
10. Bring your site back online.
|
| 22 |
|
| 23 |
For instructions on 1 and 2 above, please see the INSTALLATION.txt file that
|
| 24 |
comes with the memcache module download.
|
| 25 |
|
| 26 |
Either the memcache.inc or the memcache.db.inc file is intended to be used
|
| 27 |
instead of cache.inc, utilizing Drupal's pluggable cache system. The .db.inc
|
| 28 |
variant saves all data to the database as well, so the site will still have
|
| 29 |
the performance benefits of cache even if you take your memcache offline. The
|
| 30 |
site should not ever break due to memcache not being available... it is only
|
| 31 |
a question of whether caching is still available or not. The memcache.inc file
|
| 32 |
doesn't save any data to the database and thus has the biggest potential for
|
| 33 |
increasing your site's performance. If you use this file it is important to
|
| 34 |
have enough memory allocated to memcache to store everything (including the page
|
| 35 |
cache), otherwise the cache misses will negate the benefit of the cache hits.
|
| 36 |
|
| 37 |
Update $conf in settings.php to tell Drupal which cache_inc file to use:
|
| 38 |
|
| 39 |
$conf = array(
|
| 40 |
// The path to wherever memcache.inc is. The easiest is to simply point it
|
| 41 |
// to the copy in your module's directory.
|
| 42 |
'cache_inc' => './sites/all/modules/memcache/memcache.inc',
|
| 43 |
// or
|
| 44 |
// 'cache_inc' => './sites/all/modules/memcache/memcache.db.inc',
|
| 45 |
);
|
| 46 |
|
| 47 |
## SERVERS ##
|
| 48 |
|
| 49 |
If you want the simple version, you can start one default memcache instance on
|
| 50 |
your web server like this: memcached -m 24 -p 11211 -d
|
| 51 |
If that is enough to meet your needs, there is no more configuration needed. If
|
| 52 |
you want to utilize this module's sophisticated clustering feature and spread
|
| 53 |
your cache over several machines, or if your cache is found on a machine other
|
| 54 |
than your web server, read on.
|
| 55 |
|
| 56 |
The available memcached servers are specified in $conf in settings.php. If
|
| 57 |
you do not specify any servers, memcache.inc assumes that you have a
|
| 58 |
memcached instance running on localhost:11211. If this is true, and it is
|
| 59 |
the only memcached instance you wish to use, no further configuration is
|
| 60 |
required.
|
| 61 |
|
| 62 |
If you have more than one memcached instance running, you need to add two
|
| 63 |
arrays to $conf; memcache_servers and memcache_bins. The arrays follow this
|
| 64 |
pattern:
|
| 65 |
|
| 66 |
'memcache_servers' => array(host1:port => cluster, host2:port => cluster, hostN:port => cluster)
|
| 67 |
|
| 68 |
'memcache_bins' => array(bin1 => cluster, bin2 => cluster, binN => cluster)
|
| 69 |
|
| 70 |
The bin/cluster/server model can be described as follows:
|
| 71 |
|
| 72 |
- Servers are memcached instances identified by host:port.
|
| 73 |
|
| 74 |
- Bins are groups of data that get cached together and map 1:1 to the $table
|
| 75 |
param in cache_set(). Examples from Drupal core are cache_filter,
|
| 76 |
cache_menu. The default is 'cache'.
|
| 77 |
|
| 78 |
- Clusters are groups of servers that act as a memory pool.
|
| 79 |
|
| 80 |
- many bins can be assigned to a cluster.
|
| 81 |
|
| 82 |
- The default cluster is 'default'.
|
| 83 |
|
| 84 |
Here is a simple setup that has two memcached instances, both running on
|
| 85 |
localhost. The 11212 instance belongs to the 'pages' cluster and the table
|
| 86 |
cache_page is mapped to the 'pages' cluster. Thus everything that gets cached,
|
| 87 |
with the exception of the page cache (cache_page), will be put into 'default',
|
| 88 |
or the 11211 instance. The page cache will be in 11212.
|
| 89 |
|
| 90 |
$conf = array(
|
| 91 |
...
|
| 92 |
// Important to define a default cluster in both the servers
|
| 93 |
// and in the bins. This links them together.
|
| 94 |
'memcache_servers' => array('localhost:11211' => 'default',
|
| 95 |
'localhost:11212' => 'pages'),
|
| 96 |
'memcache_bins' => array('cache' => 'default',
|
| 97 |
'cache_page' => 'pages'),
|
| 98 |
);
|
| 99 |
|
| 100 |
Here is an example configuration that has two clusters, 'default' and
|
| 101 |
'cluster2'. Five memcached instances are divided up between the two
|
| 102 |
clusters. 'cache_filter' and 'cache_menu' bins goe to 'cluster2'. All other
|
| 103 |
bins go to 'default'.
|
| 104 |
|
| 105 |
$conf = array(
|
| 106 |
'cache_inc' => './includes/memcache.inc',
|
| 107 |
'memcache_servers' => array('localhost:11211' => 'default',
|
| 108 |
'localhost:11212' => 'default',
|
| 109 |
'123.45.67.890:11211' => 'default',
|
| 110 |
'123.45.67.891:11211' => 'cluster2',
|
| 111 |
'123.45.67.892:11211' => 'cluster2'),
|
| 112 |
|
| 113 |
'memcache_bins' => array('cache' => 'default',
|
| 114 |
'cache_filter' => 'cluster2',
|
| 115 |
'cache_menu' => 'cluster2'),
|
| 116 |
);
|
| 117 |
## PREFIXING ##
|
| 118 |
|
| 119 |
If you want to have multiple Drupal installations share memcached instances,
|
| 120 |
you need to include a unique prefix for each Drupal installation in the $conf
|
| 121 |
array of settings.php:
|
| 122 |
|
| 123 |
$conf = array(
|
| 124 |
...
|
| 125 |
'memcache_key_prefix' => 'something_unique',
|
| 126 |
);
|
| 127 |
|
| 128 |
## PATCHES ##
|
| 129 |
|
| 130 |
The DRUPAL-5-cache-serialize.patch must be applied to your Drupal installation
|
| 131 |
for this software to work. The patch depends on a column that needs to get added
|
| 132 |
to all of the existing cache tables for your site. This column has been
|
| 133 |
introduced in the DRUPAL-6 development branch so this patch is future-safe if
|
| 134 |
you ever upgrade to DRUPAL-6. To actually add the column to your database, you
|
| 135 |
need to either install the memcache.module, or, if it is already installed and
|
| 136 |
you are updating to this version, run update.php. Either installing the module
|
| 137 |
or running update.php will add the needed column, Uninstalling the module will
|
| 138 |
remove the column.
|
| 139 |
|
| 140 |
## TROUBLESHOOTING ##
|
| 141 |
|
| 142 |
PROBLEM:
|
| 143 |
Warning: require_once(a) [function.require-once]: failed to open stream:
|
| 144 |
No such file or directory in /includes/bootstrap.inc on line 853
|
| 145 |
|
| 146 |
SOLUTION:
|
| 147 |
This error occurs after you apply the DRUPAL-5-cache-serialize.patch because
|
| 148 |
the code in the patch now expects the cached variables to be unserialized
|
| 149 |
but they are still serialized in the cache. Clear the cache table:
|
| 150 |
|
| 151 |
mysql> TRUNCATE cache;
|
| 152 |
Query OK, 0 rows affected (0.01 sec)
|
| 153 |
|
| 154 |
PROBLEM:
|
| 155 |
Fatal error: Cannot use string offset as an array in includes/menu.inc on line 452
|
| 156 |
|
| 157 |
SOLUTION:
|
| 158 |
Similar to the error above, this occurs after applying the
|
| 159 |
DRUPAL-5-cache-serialize.patch due to the conflict between the existing
|
| 160 |
cached menu and what the patched code is expecting. Clear cache_menu:
|
| 161 |
|
| 162 |
mysql> TRUNCATE cache_menu;
|
| 163 |
Query OK, 0 rows affected (0.33 sec)
|
| 164 |
|
| 165 |
PROBLEM:
|
| 166 |
Error:
|
| 167 |
Failed to set key: Failed to set key: cache_page-......
|
| 168 |
|
| 169 |
SOLUTION:
|
| 170 |
Upgrade your PECL library to PECL package (2.2.1) (or higher).
|
| 171 |
|
| 172 |
## MEMCACHE ADMIN ##
|
| 173 |
|
| 174 |
A module offering a UI for memcache is on the way. It will provide stats, a
|
| 175 |
way to clear the cache, and an interface to organize servers/bins/clusters.
|
Parent Directory
| 
Revision Log
| 
Revision Graph