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 The newer PECL module is not yet supported.
  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 mentionned 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: wfMsg(), Article::editUpdates() both call wfLoadAllMessages()
 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$edit
 157                 $pageid: id of the page
 158                 $renderkey: 1 if action=render, 0 otherwise
 159                 $hash: hash of user options, see User::getPageRenderingHash()
 160                 $edit: '!edit=0' if the user can't edit the page, '' otherwise
 161         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 162         stores: ParserOutput object
 163         modified by: Article::editUpdates()
 164         expriy: $wgParserCacheExpireTime or one hour if it contains specific magic
 165                 words
 166
 167 Ping limiter:
 168         controlled by: $wgRateLimits
 169         key: $wgDBname:limiter:action:$action:ip:$ip,
 170                 $wgDBname:limiter:action:$action:user:$id,
 171                 mediawiki:limiter:action:$action:ip:$ip and
 172                 mediawiki:limiter:action:$action:subnet:$sub
 173         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 174                 wikidb:limiter:action:edit:user:1012
 175                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 176                 mediawiki:limiter:action:$action:subnet:123.45.67
 177         stores: number of action made by user/ip/subnet
 178         cleared by: nothing
 179         expiry: expiry set for the action and group in $wgRateLimits
 180
 181
 182 Proxy Check: (deprecated)
 183         key: $wgDBname:proxy:ip:$ip
 184         ex: wikidb:proxy:ip:123.45.67.89
 185         stores: 1 if the ip is a proxy
 186         cleared by: nothing
 187         expiry: $wgProxyMemcExpiry
 188
 189 Revision text:
 190         key: $wgDBname:revisiontext:textid:$id
 191         ex: wikidb:revisiontext:textid:1012
 192         stores: text of a revision
 193         cleared by: nothing
 194         expriry: $wgRevisionCacheExpiry
 195
 196 Sessions:
 197         controlled by: $wgSessionsInMemcached
 198         key: $wgBDname:session:$id
 199         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 200         stores: $SESSION, useful when using a multi-sever wiki
 201         expriy: one hour
 202         cleared by: session_destroy()
 203
 204 Sidebar:
 205         stored in: $parserMemc
 206         controlled by: $wgEnableSidebarCache
 207         key: $wgDBname:sidebar
 208         ex: wikidb:sidebar
 209         stores: the html output of the sidebar
 210         expriy: $wgSidebarCacheExpiry
 211         cleared by: MessageCache::replace()
 212
 213 Special:Allpages:
 214         key: $wgDBname:allpages:ns:$ns
 215         ex: wikidb:allpages:ns:0
 216         stores: array of pages in a namespace
 217         expiry: one hour
 218         cleared by: nothing
 219
 220 Special:Recentchanges (feed):
 221         stored in: $messageMemc
 222         key: $wgDBname:rcfeed:$format:limit:$imit:minor:$hideminor and
 223                 rcfeed:$format:timestamp
 224         ex: wikidb:rcfeed:rss:limit:50:minor:0 and rcfeed:rss:timestamp
 225         stores: xml output of feed
 226         expiry: one day
 227         clear by: calling Special:Recentchanges?action=purge
 228
 229 Statistics:
 230         controlled by: $wgStatsMethod
 231         key: $wgDBname:stats:$key
 232         ex: wikibd:stats:request_with_session
 233         stores: counter for statistics (see maintenance/stats.php script)
 234         expiry: none (?)
 235         cleared by: maintenance/clear_stats.php script
 236
 237 User:
 238         key: $wgDBname:user:id:$sId
 239         ex: wikidb:user:id:51
 240         stores: instance of class User
 241         set in: User::saveToCache()
 242         cleared by: User::saveSettings(), User::clearSharedCache()
 243
 244 ... more to come ...