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 = [ "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 = [
  74     "127.0.0.1:11211", # one gig on this box
  75     [ "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 the ObjectCache class to retrieve instances of
  84 BagOStuff by purpose, controlled by the following variables:
  85 * $wgMainCacheType
  86 * $wgParserCacheType
  87 * $wgMessageCacheType
  88
  89 If you set one of these to CACHE_NONE, MediaWiki still creates a
  90 BagOStuff object, but calls it to it are no-ops. If the cache daemon
  91 can't be contacted, it should also disable itself fairly smoothly.
  92
  93 == Keys used ==
  94
  95 (incomplete, out of date)
  96
  97 Date Formatter:
  98         key: $wgDBname:dateformatter
  99         ex: wikidb:dateformatter
 100         stores: a single instance of the DateFormatter class
 101         cleared by: nothing
 102         expiry: one hour
 103
 104 Difference Engine:
 105         key: $wgDBname:diff:version:{MW_DIFF_VERSION}:oldid:$old:newid:$new
 106         ex: wikidb:diff:version:1.11a:oldid:1:newid:2
 107         stores: body of a difference
 108         cleared by: nothing
 109         expiry: one week
 110
 111 Interwiki:
 112         key: $wgDBname:interwiki:$prefix
 113         ex: wikidb:interwiki:w
 114         stores: object from the interwiki table of the database
 115         expiry: $wgInterwikiExpiry
 116         cleared by: nothing
 117
 118 Lag time of the databases:
 119         key: $wgDBname:lag_times
 120         ex: wikidb:lag_times
 121         stores: array mapping the database id to its lag time
 122         expiry: 5 secondes
 123         cleared by: nothing
 124
 125 Localisation:
 126         key: $wgDBname:localisation:$lang
 127         ex: wikidb:localisation:de
 128         stores: array of localisation settings
 129         set in: Language::loadLocalisation()
 130         expiry: none
 131         cleared by: Language::loadLocalisation()
 132
 133 Message Cache:
 134         backend: $wgMessageCacheType
 135         key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status
 136         ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status
 137         stores: an array where the keys are DB keys and the values are messages
 138         set in: wfMessage(), Article::editUpdates() and Title::moveTo()
 139         expiry: $wgMsgCacheExpiry
 140         cleared by: nothing
 141
 142 Newtalk:
 143         key: $wgDBname:newtalk:ip:$ip
 144         ex: wikidb:newtalk:ip:123.45.67.89
 145         stores: integer, 0 or 1
 146         set in: User::loadFromDatabase()
 147         cleared by: User::saveSettings() # ?
 148         expiry: 30 minutes
 149
 150 Parser Cache:
 151         access: ParserCache
 152         backend: $wgParserCacheType
 153         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash
 154                 $pageid: id of the page
 155                 $renderkey: 1 if action=render, 0 otherwise
 156                 $hash: hash of user options applied to the page, see ParserOptions::optionsHash()
 157         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 158         stores: ParserOutput object
 159         modified by: WikiPage::doEditUpdates() or PoolWorkArticleView::doWork()
 160         expiry: $wgParserCacheExpireTime or less if it contains short lived functions
 161
 162         key: $wgDBname:pcache:idoptions:$pageid
 163         stores: CacheTime object with an additional list of used options for the hash,
 164     serves as ParserCache pointer.
 165         modified by: ParserCache::save()
 166         expiry: The same as the ParserCache entry it points to.
 167
 168 Ping limiter:
 169         controlled by: $wgRateLimits
 170         key: $wgDBname:limiter:action:$action:ip:$ip,
 171                 $wgDBname:limiter:action:$action:user:$id,
 172                 mediawiki:limiter:action:$action:ip:$ip and
 173                 mediawiki:limiter:action:$action:subnet:$sub
 174         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 175                 wikidb:limiter:action:edit:user:1012
 176                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 177                 mediawiki:limiter:action:$action:subnet:123.45.67
 178         stores: number of action made by user/ip/subnet
 179         cleared by: nothing
 180         expiry: expiry set for the action and group in $wgRateLimits
 181
 182
 183 Proxy Check: (deprecated)
 184         key: $wgDBname:proxy:ip:$ip
 185         ex: wikidb:proxy:ip:123.45.67.89
 186         stores: 1 if the ip is a proxy
 187         cleared by: nothing
 188         expiry: $wgProxyMemcExpiry
 189
 190 Revision text:
 191         key: $wgDBname:revisiontext:textid:$id
 192         ex: wikidb:revisiontext:textid:1012
 193         stores: text of a revision
 194         cleared by: nothing
 195         expiry: $wgRevisionCacheExpiry
 196
 197 Sessions:
 198         controlled by: $wgSessionsInObjectCache
 199         key: $wgBDname:session:$id
 200         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 201         stores: $SESSION, useful when using a multi-sever wiki
 202         expiry: one hour
 203         cleared by: session_destroy()
 204
 205 Sidebar:
 206         access: WANObjectCache
 207         controlled by: $wgEnableSidebarCache
 208         key: $wgDBname:sidebar
 209         ex: wikidb:sidebar
 210         stores: the html output of the sidebar
 211         expiry: $wgSidebarCacheExpiry
 212         cleared by: MessageCache::replace()
 213
 214 Special:Allpages:
 215         key: $wgDBname:allpages:ns:$ns
 216         ex: wikidb:allpages:ns:0
 217         stores: array of pages in a namespace
 218         expiry: one hour
 219         cleared by: nothing
 220
 221 Special:Recentchanges (feed):
 222         backend: $wgMessageCacheType
 223         key: $wgDBname:rcfeed:$format:$limit:$hideminor:$target and
 224                 rcfeed:$format:timestamp
 225         ex: wikidb:rcfeed:rss:50:: and rcfeed:rss:timestamp
 226         stores: xml output of feed
 227         expiry: one day
 228         clear by: maintenance/rebuildrecentchanges.php script, or
 229         calling Special:Recentchanges?action=purge&feed=rss,
 230         Special:Recentchanges?action=purge&feed=atom,
 231         but note need $wgGroupPermissions[...]['purge'] permission.
 232
 233 ... more to come ...