docs/memcached.txt

   1 MediaWiki has optional support for memcached, a "high-performance,
   2 distributed memory object caching system". For general information
   3 on it, see: http://www.danga.com/memcached/
   4
   5 Memcached is likely more trouble than a small site will need, but
   6 for a larger site with heavy load, like Wikipedia, it should help
   7 lighten the load on the database servers by caching data and objects
   8 in memory.
   9
  10 == Installation ==
  11
  12 Packages are available for Fedora, Debian, Ubuntu and probably other
  13 Linux distributions. If there's no package available for your
  14 distribution, you can compile it from source.
  15
  16 == Compilation ==
  17
  18 * PHP must be compiled with --enable-sockets
  19
  20 * libevent: http://www.monkey.org/~provos/libevent/
  21   (as of 2003-08-11, 0.7a is current)
  22
  23 * optionally, epoll-rt patch for Linux kernel:
  24   http://www.xmailserver.org/linux-patches/nio-improve.html
  25
  26 * memcached: http://www.danga.com/memcached/download.bml
  27   (as of this writing, 1.1.9 is current)
  28
  29 Memcached and libevent are under BSD-style licenses.
  30
  31 The server should run on Linux and other Unix-like systems... you
  32 can run multiple servers on one machine or on multiple machines on
  33 a network; storage can be distributed across multiple servers, and
  34 multiple web servers can use the same cache cluster.
  35
  36 ********************* W A R N I N G ! ! ! ! ! ***********************
  37 Memcached has no security or authentication. Please ensure that your
  38 server is appropriately firewalled, and that the port(s) used for
  39 memcached servers are not publicly accessible. Otherwise, anyone on
  40 the internet can put data into and read data from your cache.
  41
  42 An attacker familiar with MediaWiki internals could use this to steal
  43 passwords and email addresses, or to make themselves a sysop and
  44 install malicious javascript on the site. There may be other types
  45 of vulnerability, no audit has been done -- so be safe and keep it
  46 behind a firewall.
  47 ********************* W A R N I N G ! ! ! ! ! ***********************
  48
  49 == Setup ==
  50
  51 If you installed memcached using a distro, the daemon should be started
  52 automatically using /etc/init.d/memcached.
  53
  54 To start the daemon manually, use something like:
  55
  56   memcached -d -l 127.0.0.1 -p 11211 -m 64
  57
  58 (to run in daemon mode, accessible only via loopback interface,
  59 on port 11211, using up to 64MB of memory)
  60
  61 In your LocalSettings.php file, set:
  62
  63         $wgMainCacheType = CACHE_MEMCACHED;
  64         $wgMemCachedServers = array( "127.0.0.1:11211" );
  65
  66 The wiki should then use memcached to cache various data. To use
  67 multiple servers (physically separate boxes or multiple caches
  68 on one machine on a large-memory x86 box), just add more items
  69 to the array. To increase the weight of a server (say, because
  70 it has twice the memory of the others and you want to spread
  71 usage evenly), make its entry a subarray:
  72
  73   $wgMemCachedServers = array(
  74     "127.0.0.1:11211", # one gig on this box
  75     array("192.168.0.1:11211", 2 ) # two gigs on the other box
  76   );
  77
  78 == PHP client for memcached ==
  79
  80 MediaWiki uses a fork of Ryan T. Dean's pure-PHP memcached client.
  81 It also supports the PECL PHP extension for memcached.
  82
  83 MediaWiki uses three object for object caching:
  84 * $wgMemc, controlled by $wgMainCacheType
  85 * $parserMemc, controlled by $wgParserCacheType
  86 * $messageMemc, controlled by $wgMessageCacheType
  87 If you set CACHE_NONE to one of the three control variable, (default
  88 value for $wgMainCacheType), MediaWiki still create a MemCacheClient,
  89 but requests to it are no-ops and we always fall through to the
  90 database. If the cache daemon can't be contacted, it should also
  91 disable itself fairly smoothly.
  92
  93 By default, $wgMemc is used but when it is $parserMemc or $messageMemc
  94 this is mentioned below.
  95
  96 == Keys used ==
  97
  98 (incomplete, out of date)
  99
 100 Date Formatter:
 101         key: $wgDBname:dateformatter
 102         ex: wikidb:dateformatter
 103         stores: a single instance of the DateFormatter class
 104         cleared by: nothing
 105         expiry: one hour
 106
 107 Difference Engine:
 108         key: $wgDBname:diff:version:{MW_DIFF_VERSION}:oldid:$old:newid:$new
 109         ex: wikidb:diff:version:1.11a:oldid:1:newid:2
 110         stores: body of a difference
 111         cleared by: nothing
 112         expiry: one week
 113
 114 Interwiki:
 115         key: $wgDBname:interwiki:$prefix
 116         ex: wikidb:interwiki:w
 117         stores: object from the interwiki table of the database
 118         expiry: $wgInterwikiExpiry
 119         cleared by: nothing
 120
 121 Lag time of the databases:
 122         key: $wgDBname:lag_times
 123         ex: wikidb:lag_times
 124         stores: array mapping the database id to its lag time
 125         expiry: 5 secondes
 126         cleared by: nothing
 127
 128 Localisation:
 129         key: $wgDBname:localisation:$lang
 130         ex: wikidb:localisation:de
 131         stores: array of localisation settings
 132         set in: Language::loadLocalisation()
 133         expiry: none
 134         cleared by: Language::loadLocalisation()
 135
 136 Message Cache:
 137         stored in: $messageMemc
 138         key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status
 139         ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status
 140         stores: an array where the keys are DB keys and the values are messages
 141         set in: wfMessage(), Article::editUpdates() and Title::moveTo()
 142         expiry: $wgMsgCacheExpiry
 143         cleared by: nothing
 144
 145 Newtalk:
 146         key: $wgDBname:newtalk:ip:$ip
 147         ex: wikidb:newtalk:ip:123.45.67.89
 148         stores: integer, 0 or 1
 149         set in: User::loadFromDatabase()
 150         cleared by: User::saveSettings() # ?
 151         expiry: 30 minutes
 152
 153 Parser Cache:
 154         stored in: $parserMemc
 155         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash
 156                 $pageid: id of the page
 157                 $renderkey: 1 if action=render, 0 otherwise
 158                 $hash: hash of user options applied to the page, see ParserOptions::optionsHash()
 159         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 160         stores: ParserOutput object
 161         modified by: WikiPage::doEditUpdates() or PoolWorkArticleView::doWork()
 162         expiry: $wgParserCacheExpireTime or less if it contains short lived functions
 163
 164         key: $wgDBname:pcache:idoptions:$pageid
 165         stores: CacheTime object with an additional list of used options for the hash,
 166     serves as ParserCache pointer.
 167         modified by: ParserCache::save()
 168         expiry: The same as the ParserCache entry it points to.
 169
 170 Ping limiter:
 171         controlled by: $wgRateLimits
 172         key: $wgDBname:limiter:action:$action:ip:$ip,
 173                 $wgDBname:limiter:action:$action:user:$id,
 174                 mediawiki:limiter:action:$action:ip:$ip and
 175                 mediawiki:limiter:action:$action:subnet:$sub
 176         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 177                 wikidb:limiter:action:edit:user:1012
 178                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 179                 mediawiki:limiter:action:$action:subnet:123.45.67
 180         stores: number of action made by user/ip/subnet
 181         cleared by: nothing
 182         expiry: expiry set for the action and group in $wgRateLimits
 183
 184
 185 Proxy Check: (deprecated)
 186         key: $wgDBname:proxy:ip:$ip
 187         ex: wikidb:proxy:ip:123.45.67.89
 188         stores: 1 if the ip is a proxy
 189         cleared by: nothing
 190         expiry: $wgProxyMemcExpiry
 191
 192 Revision text:
 193         key: $wgDBname:revisiontext:textid:$id
 194         ex: wikidb:revisiontext:textid:1012
 195         stores: text of a revision
 196         cleared by: nothing
 197         expiry: $wgRevisionCacheExpiry
 198
 199 Sessions:
 200         controlled by: $wgSessionsInObjectCache
 201         key: $wgBDname:session:$id
 202         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 203         stores: $SESSION, useful when using a multi-sever wiki
 204         expiry: one hour
 205         cleared by: session_destroy()
 206
 207 Sidebar:
 208         stored in: $parserMemc
 209         controlled by: $wgEnableSidebarCache
 210         key: $wgDBname:sidebar
 211         ex: wikidb:sidebar
 212         stores: the html output of the sidebar
 213         expiry: $wgSidebarCacheExpiry
 214         cleared by: MessageCache::replace()
 215
 216 Special:Allpages:
 217         key: $wgDBname:allpages:ns:$ns
 218         ex: wikidb:allpages:ns:0
 219         stores: array of pages in a namespace
 220         expiry: one hour
 221         cleared by: nothing
 222
 223 Special:Recentchanges (feed):
 224         stored in: $messageMemc
 225         key: $wgDBname:rcfeed:$format:$limit:$hideminor:$target and
 226                 rcfeed:$format:timestamp
 227         ex: wikidb:rcfeed:rss:50:: and rcfeed:rss:timestamp
 228         stores: xml output of feed
 229         expiry: one day
 230         clear by: maintenance/rebuildrecentchanges.php script, or
 231         calling Special:Recentchanges?action=purge&feed=rss,
 232         Special:Recentchanges?action=purge&feed=atom,
 233         but note need $wgGroupPermissions[...]['purge'] permission.
 234
 235 ... more to come ...