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 Link Cache:
 132         controlled by: $wgLinkCacheMemcached
 133         key: $wgDBname:lc:title:$title
 134         ex: wikidb:lc:title:Wikipedia:Welcome,_Newcomers!
 135         stores: cur_id of page, or 0 if page does not exist
 136         set in: LinkCache::addLink()
 137         expriry: one day
 138         cleared by: LinkCache::clearBadLink()
 139                 should be cleared on page deletion and rename
 140
 141 Localisation:
 142         key: $wgDBname:localisation:$lang
 143         ex: wikidb:localisation:de
 144         stores: array of localisation settings
 145         set in: Language::loadLocalisation()
 146         expiry: none
 147         cleared by: Language::loadLocalisation()
 148
 149 Message Cache:
 150         stored in: $parserMemc
 151         key: $wgDBname:messages, $wgDBname:messages-hash, $wgDBname:messages-status
 152         ex: wikidb:messages, wikidb:messages-hash, wikidb:messages-status
 153         stores: an array where the keys are DB keys and the values are messages
 154         set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages()
 155         expriy: $wgMsgCacheExpiry
 156         cleared by: nothing
 157
 158 Newtalk:
 159         key: $wgDBname:newtalk:ip:$ip
 160         ex: wikidb:newtalk:ip:123.45.67.89
 161         stores: integer, 0 or 1
 162         set in: User::loadFromDatabase()
 163         cleared by: User::saveSettings() # ?
 164         expiry: 30 minutes
 165
 166 Parser Cache:
 167         stored in: $parserMemc
 168         controlled by: $wgEnableParserCache
 169         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash$edit
 170                 $pageid: id of the page
 171                 $renderkey: 1 if action=render, 0 otherwise
 172                 $hash: hash of user options, see User::getPageRenderingHash()
 173                 $edit: '!edit=0' if the user can't edit the page, '' otherwise
 174         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
 175         stores: ParserOutput object
 176         modified by: Article::editUpdates()
 177         expriy: $wgParserCacheExpireTime or one hour if it contains specific magic
 178                 words
 179
 180 Ping limiter:
 181         controlled by: $wgRateLimits
 182         key: $wgDBname:limiter:action:$action:ip:$ip,
 183                 $wgDBname:limiter:action:$action:user:$id,
 184                 mediawiki:limiter:action:$action:ip:$ip and
 185                 mediawiki:limiter:action:$action:subnet:$sub
 186         ex: wikidb:limiter:action:edit:ip:123.45.67.89,
 187                 wikidb:limiter:action:edit:user:1012
 188                 mediawiki:limiter:action:edit:ip:123.45.67.89 and
 189                 mediawiki:limiter:action:$action:subnet:123.45.67
 190         stores: number of action made by user/ip/subnet
 191         cleared by: nothing
 192         expiry: expiry set for the action and group in $wgRateLimits
 193
 194
 195 Proxy Check: (deprecated)
 196         key: $wgDBname:proxy:ip:$ip
 197         ex: wikidb:proxy:ip:123.45.67.89
 198         stores: 1 if the ip is a proxy
 199         cleared by: nothing
 200         expiry: $wgProxyMemcExpiry
 201
 202 Revision text:
 203         key: $wgDBname:revisiontext:textid:$id
 204         ex: wikidb:revisiontext:textid:1012
 205         stores: text of a revision
 206         cleared by: nothing
 207         expriry: $wgRevisionCacheExpiry
 208
 209 Sessions:
 210         controlled by: $wgSessionsInMemcached
 211         key: $wgBDname:session:$id
 212         ex: wikidb:session:38d7c5b8d3bfc51egf40c69bc40f8be3
 213         stores: $SESSION, useful when using a multi-sever wiki
 214         expriy: one hour
 215         cleared by: session_destroy()
 216
 217 Sidebar:
 218         stored in: $parserMemc
 219         controlled by: $wgEnableSidebarCache
 220         key: $wgDBname:sidebar
 221         ex: wikidb:sidebar
 222         stores: the html output of the sidebar
 223         expriy: $wgSidebarCacheExpiry
 224         cleared by: MessageCache::replace()
 225
 226 Special:Allpages:
 227         key: $wgDBname:allpages:ns:$ns
 228         ex: wikidb:allpages:ns:0
 229         stores: array of pages in a namespace
 230         expiry: one hour
 231         cleared by: nothing
 232
 233 Special:Recentchanges (feed):
 234         stored in: $messageMemc
 235         key: $wgDBname:rcfeed:$format:limit:$imit:minor:$hideminor and
 236                 rcfeed:$format:timestamp
 237         ex: wikidb:rcfeed:rss:limit:50:minor:0 and rcfeed:rss:timestamp
 238         stores: xml output of feed
 239         expiry: one day
 240         clear by: calling Special:Recentchanges?action=purge
 241
 242 Statistics:
 243         controlled by: $wgStatsMethod
 244         key: $wgDBname:stats:$key
 245         ex: wikibd:stats:request_with_session
 246         stores: counter for statistics (see maintenance/stats.php script)
 247         expiry: none (?)
 248         cleared by: maintenance/clear_stats.php script
 249
 250 User:
 251         key: $wgDBname:user:id:$sId
 252         ex: wikidb:user:id:51
 253         stores: instance of class User
 254         set in: User::saveToCache()
 255         cleared by: User::saveSettings(), User::clearSharedCache()
 256
 257 ... more to come ...