docs/memcached.txt

   1 memcached support for MediaWiki:
   2
   3 From ca August 2003, MediaWiki has optional support for memcached, a
   4 "high-performance, distributed memory object caching system".
   5 For general information on it, see: http://www.danga.com/memcached/
   6
   7 Memcached is likely more trouble than a small site will need, but
   8 for a larger site with heavy load, like Wikipedia, it should help
   9 lighten the load on the database servers by caching data and objects
  10 in memory.
  11
  12 == Requirements ==
  13
  14 * PHP must be compiled with --enable-sockets
  15
  16 * libevent: http://www.monkey.org/~provos/libevent/
  17   (as of 2003-08-11, 0.7a is current)
  18
  19 * optionally, epoll-rt patch for Linux kernel:
  20   http://www.xmailserver.org/linux-patches/nio-improve.html
  21
  22 * memcached: http://www.danga.com/memcached/download.bml
  23   (as of this writing, 1.1.9 is current)
  24
  25 Memcached and libevent are under BSD-style licenses.
  26
  27 The server should run on Linux and other Unix-like systems... you
  28 can run multiple servers on one machine or on multiple machines on
  29 a network; storage can be distributed across multiple servers, and
  30 multiple web servers can use the same cache cluster.
  31
  32 ********************* W A R N I N G ! ! ! ! ! ***********************
  33 Memcached has no security or authentication. Please ensure that your
  34 server is appropriately firewalled, and that the port(s) used for
  35 memcached servers are not publicly accessible. Otherwise, anyone on
  36 the internet can put data into and read data from your cache.
  37
  38 An attacker familiar with MediaWiki internals could use this to give
  39 themselves developer access and delete all data from the wiki's
  40 database, as well as getting all users' password hashes and e-mail
  41 addresses.
  42 ********************* W A R N I N G ! ! ! ! ! ***********************
  43
  44 == Setup ==
  45
  46 If you want to start small, just run one memcached on your web
  47 server:
  48
  49   memcached -d -l 127.0.0.1 -p 11000 -m 64
  50
  51 (to run in daemon mode, accessible only via loopback interface,
  52 on port 11000, using up to 64MB of memory)
  53
  54 In your LocalSettings.php file, set:
  55
  56         $wgMainCacheType = CACHE_MEMCACHED;
  57         $wgMemCachedServers = array( "127.0.0.1:11000" );
  58
  59 The wiki should then use memcached to cache various data. To use
  60 multiple servers (physically separate boxes or multiple caches
  61 on one machine on a large-memory x86 box), just add more items
  62 to the array. To increase the weight of a server (say, because
  63 it has twice the memory of the others and you want to spread
  64 usage evenly), make its entry a subarray:
  65
  66   $wgMemCachedServers = array(
  67     "127.0.0.1:11000", # one gig on this box
  68     array("192.168.0.1:11000", 2 ) # two gigs on the other box
  69   );
  70
  71 == PHP client for memcached ==
  72
  73 As of this writing, MediaWiki includes version 1.0.10 of the PHP
  74 memcached client by Ryan Gilfether <hotrodder@rocketmail.com>.
  75 You'll find some documentation for it in the 'php-memcached'
  76 subdirectory under the present one.
  77
  78 We intend to track updates, but if you want to check for the lastest
  79 released version, see http://www.danga.com/memcached/apis.bml
  80
  81 MediaWiki use three object for memcaching:
  82 * $wgMemc, controlled by $wgMainCacheType
  83 * $parserMemc, controlled by $wgParserCacheType
  84 * $messageMemc, controlled by $wgMessageCacheType
  85 If you set CACHE_NONE to one of the three control variable, (default
  86 value for $wgMainCacheType), MediaWiki still create a MemCacheClient,
  87 but requests to it are no-ops and we always fall through to the
  88 database. If the cache daemon can't be contacted, it should also
  89 disable itself fairly smoothly.
  90
  91 By default, $wgMemc is used but when it is $parserMemc or $messageMemc
  92 this is mentionned below.
  93
  94 == Keys used ==
  95
  96 Ajax Search:
  97         key: $wgDBname:ajaxsearch:md5( $search )
  98         ex: wikidb:ajaxsearch:9565814d5d564fa898dd6111b94fae0b
  99         stores: array with the result of research of a given text
 100         cleared by: nothing
 101         expiry: 30 minutes
 102
 103 Date Formatter:
 104         key: $wgDBname:dateformatter
 105         ex: wikidb:dateformatter
 106         stores: a single instance of the DateFormatter class
 107         cleared by: nothing
 108         expiry: one hour
 109
 110 Difference Engine:
 111         key: $wgDBname:diff:version:{MW_DIFF_VERSION}:oldid:$old:newid:$new
 112         ex: wikidb:diff:version:1.11a:oldid:1:newid:2
 113         stores: body of a difference
 114         cleared by: nothing
 115         expiry: one week
 116
 117 Interwiki:
 118         key: $wgDBname:interwiki:$prefix
 119         ex: wikidb:interwiki:w
 120         stores: object from the interwiki table of the database
 121         expiry: $wgInterwikiExpiry
 122         cleared by: nothing
 123
 124 Lag time of the databases:
 125         key: $wgDBname:lag_times
 126         ex: wikidb:lag_times
 127         stores: array mapping the database id to its lag time
 128         expriy: 5 secondes
 129         cleared by: nothing
 130
 131 Localisation:
 132         key: $wgDBname:localisation:$lang
 133         ex: wikidb:localisation:de
 134         stores: array of localisation settings
 135         set in: Language::loadLocalisation()
 136         expiry: none
 137         cleared by: Language::loadLocalisation()
 138
 139 Message Cache:
 140         stored in: $parserMemc
 141         key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status
 142         ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status
 143         stores: an array where the keys are DB keys and the values are messages
 144         set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages()
 145         expriy: $wgMsgCacheExpiry
 146         cleared by: nothing
 147
 148 Newtalk:
 149         key: $wgDBname:newtalk:ip:$ip
 150         ex: wikidb:newtalk:ip:123.45.67.89
 151         stores: integer, 0 or 1
 152         set in: User::loadFromDatabase()
 153         cleared by: User::saveSettings() # ?
 154         expiry: 30 minutes
 155
 156 Parser Cache:
 157         stored in: $parserMemc
 158         controlled by: $wgEnableParserCache
 159         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash$edit
 160                 $pageid: id of the page
 161                 $renderkey: 1 if action=render, 0 otherwise
 162                 $hash: hash of user options, see User::getPageRenderingHash()
 163                 $edit: '!edit=0' if the user can't edit the page, '' otherwise
 164         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 165         stores: ParserOutput object
 166         modified by: Article::editUpdates()
 167         expriy: $wgParserCacheExpireTime or one hour if it contains specific magic
 168                 words
 169
 170 Ping limiter:
 171         controlled by: $wgRateLimits
 172         key: $wgDBname:limiter:action:$action:ip:$ip,
 173                 $wgDBname:limiter:action:$action:user:$id,
 174                 mediawiki:limiter:action:$action:ip:$ip and
 175                 mediawiki:limiter:action:$action:subnet:$sub
 176         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 177                 wikidb:limiter:action:edit:user:1012
 178                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 179                 mediawiki:limiter:action:$action:subnet:123.45.67
 180         stores: number of action made by user/ip/subnet
 181         cleared by: nothing
 182         expiry: expiry set for the action and group in $wgRateLimits
 183
 184
 185 Proxy Check: (deprecated)
 186         key: $wgDBname:proxy:ip:$ip
 187         ex: wikidb:proxy:ip:123.45.67.89
 188         stores: 1 if the ip is a proxy
 189         cleared by: nothing
 190         expiry: $wgProxyMemcExpiry
 191
 192 Revision text:
 193         key: $wgDBname:revisiontext:textid:$id
 194         ex: wikidb:revisiontext:textid:1012
 195         stores: text of a revision
 196         cleared by: nothing
 197         expriry: $wgRevisionCacheExpiry
 198
 199 Sessions:
 200         controlled by: $wgSessionsInMemcached
 201         key: $wgBDname:session:$id
 202         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 203         stores: $SESSION, useful when using a multi-sever wiki
 204         expriy: one hour
 205         cleared by: session_destroy()
 206
 207 Sidebar:
 208         stored in: $parserMemc
 209         controlled by: $wgEnableSidebarCache
 210         key: $wgDBname:sidebar
 211         ex: wikidb:sidebar
 212         stores: the html output of the sidebar
 213         expriy: $wgSidebarCacheExpiry
 214         cleared by: MessageCache::replace()
 215
 216 Special:Allpages:
 217         key: $wgDBname:allpages:ns:$ns
 218         ex: wikidb:allpages:ns:0
 219         stores: array of pages in a namespace
 220         expiry: one hour
 221         cleared by: nothing
 222
 223 Special:Recentchanges (feed):
 224         stored in: $messageMemc
 225         key: $wgDBname:rcfeed:$format:limit:$imit:minor:$hideminor and
 226                 rcfeed:$format:timestamp
 227         ex: wikidb:rcfeed:rss:limit:50:minor:0 and rcfeed:rss:timestamp
 228         stores: xml output of feed
 229         expiry: one day
 230         clear by: calling Special:Recentchanges?action=purge
 231
 232 Statistics:
 233         controlled by: $wgStatsMethod
 234         key: $wgDBname:stats:$key
 235         ex: wikibd:stats:request_with_session
 236         stores: counter for statistics (see maintenance/stats.php script)
 237         expiry: none (?)
 238         cleared by: maintenance/clear_stats.php script
 239
 240 User:
 241         key: $wgDBname:user:id:$sId
 242         ex: wikidb:user:id:51
 243         stores: instance of class User
 244         set in: User::saveToCache()
 245         cleared by: User::saveSettings(), User::clearSharedCache()
 246
 247 ... more to come ...