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         See MessageCache.php.
 135
 136 Newtalk:
 137         key: $wgDBname:newtalk:ip:$ip
 138         ex: wikidb:newtalk:ip:123.45.67.89
 139         stores: integer, 0 or 1
 140         set in: User::loadFromDatabase()
 141         cleared by: User::saveSettings() # ?
 142         expiry: 30 minutes
 143
 144 Parser Cache:
 145         access: ParserCache
 146         backend: $wgParserCacheType
 147         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash
 148                 $pageid: id of the page
 149                 $renderkey: 1 if action=render, 0 otherwise
 150                 $hash: hash of user options applied to the page, see ParserOptions::optionsHash()
 151         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 152         stores: ParserOutput object
 153         modified by: WikiPage::doEditUpdates() or PoolWorkArticleView::doWork()
 154         expiry: $wgParserCacheExpireTime or less if it contains short lived functions
 155
 156         key: $wgDBname:pcache:idoptions:$pageid
 157         stores: CacheTime object with an additional list of used options for the hash,
 158     serves as ParserCache pointer.
 159         modified by: ParserCache::save()
 160         expiry: The same as the ParserCache entry it points to.
 161
 162 Ping limiter:
 163         controlled by: $wgRateLimits
 164         key: $wgDBname:limiter:action:$action:ip:$ip,
 165                 $wgDBname:limiter:action:$action:user:$id,
 166                 mediawiki:limiter:action:$action:ip:$ip and
 167                 mediawiki:limiter:action:$action:subnet:$sub
 168         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 169                 wikidb:limiter:action:edit:user:1012
 170                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 171                 mediawiki:limiter:action:$action:subnet:123.45.67
 172         stores: number of action made by user/ip/subnet
 173         cleared by: nothing
 174         expiry: expiry set for the action and group in $wgRateLimits
 175
 176
 177 Proxy Check: (deprecated)
 178         key: $wgDBname:proxy:ip:$ip
 179         ex: wikidb:proxy:ip:123.45.67.89
 180         stores: 1 if the ip is a proxy
 181         cleared by: nothing
 182         expiry: $wgProxyMemcExpiry
 183
 184 Revision text:
 185         key: $wgDBname:revisiontext:textid:$id
 186         ex: wikidb:revisiontext:textid:1012
 187         stores: text of a revision
 188         cleared by: nothing
 189         expiry: $wgRevisionCacheExpiry
 190
 191 Sessions:
 192         controlled by: $wgSessionsInObjectCache
 193         key: $wgBDname:session:$id
 194         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 195         stores: $SESSION, useful when using a multi-sever wiki
 196         expiry: one hour
 197         cleared by: session_destroy()
 198
 199 Sidebar:
 200         access: WANObjectCache
 201         controlled by: $wgEnableSidebarCache
 202         key: $wgDBname:sidebar
 203         ex: wikidb:sidebar
 204         stores: the html output of the sidebar
 205         expiry: $wgSidebarCacheExpiry
 206         cleared by: MessageCache::replace()
 207
 208 Special:Allpages:
 209         key: $wgDBname:allpages:ns:$ns
 210         ex: wikidb:allpages:ns:0
 211         stores: array of pages in a namespace
 212         expiry: one hour
 213         cleared by: nothing
 214
 215 Special:Recentchanges (feed):
 216         backend: $wgMessageCacheType
 217         key: $wgDBname:rcfeed:$format:$limit:$hideminor:$target and
 218                 rcfeed:$format:timestamp
 219         ex: wikidb:rcfeed:rss:50:: and rcfeed:rss:timestamp
 220         stores: xml output of feed
 221         expiry: one day
 222         clear by: maintenance/rebuildrecentchanges.php script, or
 223         calling Special:Recentchanges?action=purge&feed=rss,
 224         Special:Recentchanges?action=purge&feed=atom,
 225         but note need $wgGroupPermissions[...]['purge'] permission.
 226
 227 ... more to come ...