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 you 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         expriy: 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         expriy: $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         controlled by: $wgEnableParserCache
 156         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash
 157                 $pageid: id of the page
 158                 $renderkey: 1 if action=render, 0 otherwise
 159                 $hash: hash of user options applied to the page, see ParserOptions::optionsHash()
 160         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 161         stores: ParserOutput object
 162         modified by: WikiPage::doEditUpdates() or PoolWorkArticleView::doWork()
 163         expiry: $wgParserCacheExpireTime or less if it contains short lived functions
 164
 165         key: $wgDBname:pcache:idoptions:$pageid
 166         stores: CacheTime object with an additional list of used options for the hash,
 167     serves as ParserCache pointer.
 168         modified by: ParserCache::save()
 169         expiry: The same as the ParserCache entry it points to.
 170
 171 Ping limiter:
 172         controlled by: $wgRateLimits
 173         key: $wgDBname:limiter:action:$action:ip:$ip,
 174                 $wgDBname:limiter:action:$action:user:$id,
 175                 mediawiki:limiter:action:$action:ip:$ip and
 176                 mediawiki:limiter:action:$action:subnet:$sub
 177         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 178                 wikidb:limiter:action:edit:user:1012
 179                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 180                 mediawiki:limiter:action:$action:subnet:123.45.67
 181         stores: number of action made by user/ip/subnet
 182         cleared by: nothing
 183         expiry: expiry set for the action and group in $wgRateLimits
 184
 185
 186 Proxy Check: (deprecated)
 187         key: $wgDBname:proxy:ip:$ip
 188         ex: wikidb:proxy:ip:123.45.67.89
 189         stores: 1 if the ip is a proxy
 190         cleared by: nothing
 191         expiry: $wgProxyMemcExpiry
 192
 193 Revision text:
 194         key: $wgDBname:revisiontext:textid:$id
 195         ex: wikidb:revisiontext:textid:1012
 196         stores: text of a revision
 197         cleared by: nothing
 198         expriry: $wgRevisionCacheExpiry
 199
 200 Sessions:
 201         controlled by: $wgSessionsInObjectCache
 202         key: $wgBDname:session:$id
 203         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 204         stores: $SESSION, useful when using a multi-sever wiki
 205         expriy: one hour
 206         cleared by: session_destroy()
 207
 208 Sidebar:
 209         stored in: $parserMemc
 210         controlled by: $wgEnableSidebarCache
 211         key: $wgDBname:sidebar
 212         ex: wikidb:sidebar
 213         stores: the html output of the sidebar
 214         expriy: $wgSidebarCacheExpiry
 215         cleared by: MessageCache::replace()
 216
 217 Special:Allpages:
 218         key: $wgDBname:allpages:ns:$ns
 219         ex: wikidb:allpages:ns:0
 220         stores: array of pages in a namespace
 221         expiry: one hour
 222         cleared by: nothing
 223
 224 Special:Recentchanges (feed):
 225         stored in: $messageMemc
 226         key: $wgDBname:rcfeed:$format:$limit:$hideminor:$target and
 227                 rcfeed:$format:timestamp
 228         ex: wikidb:rcfeed:rss:50:: and rcfeed:rss:timestamp
 229         stores: xml output of feed
 230         expiry: one day
 231         clear by: maintenance/rebuildrecentchanges.php script, or
 232         calling Special:Recentchanges?action=purge&feed=rss,
 233         Special:Recentchanges?action=purge&feed=atom,
 234         but note need $wgGroupPermissions[...]['purge'] permission.
 235
 236 Statistics:
 237         controlled by: $wgStatsMethod
 238         key: $wgDBname:stats:$key
 239         ex: wikibd:stats:request_with_session
 240         stores: counter for statistics (see maintenance/showCacheStats.php script)
 241         expiry: none (?)
 242         cleared by: maintenance/clearCacheStats.php script
 243
 244 User:
 245         key: $wgDBname:user:id:$sId
 246         ex: wikidb:user:id:51
 247         stores: instance of class User
 248         set in: User::saveToCache()
 249         cleared by: User::saveSettings(), User::clearSharedCache()
 250
 251 ... more to come ...