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 11000, 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:11000", # one gig on this box
  75     array("192.168.0.1:11000", 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 Ajax Search:
 101         key: $wgDBname:ajaxsearch:md5( $search )
 102         ex: wikidb:ajaxsearch:9565814d5d564fa898dd6111b94fae0b
 103         stores: array with the result of research of a given text
 104         cleared by: nothing
 105         expiry: 30 minutes
 106
 107 Date Formatter:
 108         key: $wgDBname:dateformatter
 109         ex: wikidb:dateformatter
 110         stores: a single instance of the DateFormatter class
 111         cleared by: nothing
 112         expiry: one hour
 113
 114 Difference Engine:
 115         key: $wgDBname:diff:version:{MW_DIFF_VERSION}:oldid:$old:newid:$new
 116         ex: wikidb:diff:version:1.11a:oldid:1:newid:2
 117         stores: body of a difference
 118         cleared by: nothing
 119         expiry: one week
 120
 121 Interwiki:
 122         key: $wgDBname:interwiki:$prefix
 123         ex: wikidb:interwiki:w
 124         stores: object from the interwiki table of the database
 125         expiry: $wgInterwikiExpiry
 126         cleared by: nothing
 127
 128 Lag time of the databases:
 129         key: $wgDBname:lag_times
 130         ex: wikidb:lag_times
 131         stores: array mapping the database id to its lag time
 132         expriy: 5 secondes
 133         cleared by: nothing
 134
 135 Localisation:
 136         key: $wgDBname:localisation:$lang
 137         ex: wikidb:localisation:de
 138         stores: array of localisation settings
 139         set in: Language::loadLocalisation()
 140         expiry: none
 141         cleared by: Language::loadLocalisation()
 142
 143 Message Cache:
 144         stored in: $messageMemc
 145         key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status
 146         ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status
 147         stores: an array where the keys are DB keys and the values are messages
 148         set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages()
 149         expriy: $wgMsgCacheExpiry
 150         cleared by: nothing
 151
 152 Newtalk:
 153         key: $wgDBname:newtalk:ip:$ip
 154         ex: wikidb:newtalk:ip:123.45.67.89
 155         stores: integer, 0 or 1
 156         set in: User::loadFromDatabase()
 157         cleared by: User::saveSettings() # ?
 158         expiry: 30 minutes
 159
 160 Parser Cache:
 161         stored in: $parserMemc
 162         controlled by: $wgEnableParserCache
 163         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash$edit
 164                 $pageid: id of the page
 165                 $renderkey: 1 if action=render, 0 otherwise
 166                 $hash: hash of user options, see User::getPageRenderingHash()
 167                 $edit: '!edit=0' if the user can't edit the page, '' otherwise
 168         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 169         stores: ParserOutput object
 170         modified by: Article::editUpdates()
 171         expriy: $wgParserCacheExpireTime or one hour if it contains specific magic
 172                 words
 173
 174 Ping limiter:
 175         controlled by: $wgRateLimits
 176         key: $wgDBname:limiter:action:$action:ip:$ip,
 177                 $wgDBname:limiter:action:$action:user:$id,
 178                 mediawiki:limiter:action:$action:ip:$ip and
 179                 mediawiki:limiter:action:$action:subnet:$sub
 180         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 181                 wikidb:limiter:action:edit:user:1012
 182                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 183                 mediawiki:limiter:action:$action:subnet:123.45.67
 184         stores: number of action made by user/ip/subnet
 185         cleared by: nothing
 186         expiry: expiry set for the action and group in $wgRateLimits
 187
 188
 189 Proxy Check: (deprecated)
 190         key: $wgDBname:proxy:ip:$ip
 191         ex: wikidb:proxy:ip:123.45.67.89
 192         stores: 1 if the ip is a proxy
 193         cleared by: nothing
 194         expiry: $wgProxyMemcExpiry
 195
 196 Revision text:
 197         key: $wgDBname:revisiontext:textid:$id
 198         ex: wikidb:revisiontext:textid:1012
 199         stores: text of a revision
 200         cleared by: nothing
 201         expriry: $wgRevisionCacheExpiry
 202
 203 Sessions:
 204         controlled by: $wgSessionsInMemcached
 205         key: $wgBDname:session:$id
 206         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 207         stores: $SESSION, useful when using a multi-sever wiki
 208         expriy: one hour
 209         cleared by: session_destroy()
 210
 211 Sidebar:
 212         stored in: $parserMemc
 213         controlled by: $wgEnableSidebarCache
 214         key: $wgDBname:sidebar
 215         ex: wikidb:sidebar
 216         stores: the html output of the sidebar
 217         expriy: $wgSidebarCacheExpiry
 218         cleared by: MessageCache::replace()
 219
 220 Special:Allpages:
 221         key: $wgDBname:allpages:ns:$ns
 222         ex: wikidb:allpages:ns:0
 223         stores: array of pages in a namespace
 224         expiry: one hour
 225         cleared by: nothing
 226
 227 Special:Recentchanges (feed):
 228         stored in: $messageMemc
 229         key: $wgDBname:rcfeed:$format:limit:$imit:minor:$hideminor and
 230                 rcfeed:$format:timestamp
 231         ex: wikidb:rcfeed:rss:limit:50:minor:0 and rcfeed:rss:timestamp
 232         stores: xml output of feed
 233         expiry: one day
 234         clear by: calling Special:Recentchanges?action=purge
 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/stats.php script)
 241         expiry: none (?)
 242         cleared by: maintenance/clear_stats.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 ...