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
  33 ********************* W A R N I N G ! ! ! ! ! ***********************
  34 Memcached has no security or authentication. Please ensure that your
  35 server is appropriately firewalled, and that the port(s) used for
  36 memcached servers are not publicly accessible. Otherwise, anyone on
  37 the internet can put data into and read data from your cache.
  38
  39 An attacker familiar with MediaWiki internals could use this to give
  40 themselves developer access and delete all data from the wiki's
  41 database, as well as getting all users' password hashes and e-mail
  42 addresses.
  43 ********************* W A R N I N G ! ! ! ! ! ***********************
  44
  45 == Setup ==
  46
  47 If you want to start small, just run one memcached on your web
  48 server:
  49
  50   memcached -d -l 127.0.0.1 -p 11000 -m 64
  51
  52 (to run in daemon mode, accessible only via loopback interface,
  53 on port 11000, using up to 64MB of memory)
  54
  55 In your LocalSettings.php file, set:
  56
  57   $wgUseMemCached = true;
  58   $wgMemCachedServers = array( "127.0.0.1:11000" );
  59
  60 The wiki should then use memcached to cache various data. To use
  61 multiple servers (physically separate boxes or multiple caches
  62 on one machine on a large-memory x86 box), just add more items
  63 to the array. To increase the weight of a server (say, because
  64 it has twice the memory of the others and you want to spread
  65 usage evenly), make its entry a subarray:
  66
  67   $wgMemCachedServers = array(
  68     "127.0.0.1:11000", # one gig on this box
  69     array("192.168.0.1:11000", 2) # two gigs on the other box
  70   );
  71
  72
  73 == PHP client for memcached ==
  74
  75 As of this writing, MediaWiki includes version 1.0.10 of the PHP
  76 memcached client by Ryan Gilfether <hotrodder@rocketmail.com>.
  77 You'll find some documentation for it in the 'php-memcached'
  78 subdirectory under the present one.
  79
  80 We intend to track updates, but if you want to check for the lastest
  81 released version, see http://www.danga.com/memcached/apis.bml
  82
  83 If you don't set $wgUseMemCached, we still create a MemCacheClient,
  84 but requests to it are no-ops and we always fall through to the
  85 database. If the cache daemon can't be contacted, it should also
  86 disable itself fairly smoothly.
  87
  88 == Keys used ==
  89
  90 User:
  91         key: $wgDBname:user:id:$sId
  92         ex: wikidb:user:id:51
  93         stores: instance of class User
  94         set in: User::loadFromSession()
  95         cleared by: User::saveSettings(), UserTalkUpdate::doUpdate()
  96
  97 Newtalk:
  98         key: $wgDBname:newtalk:ip:$ip
  99         ex: wikidb:newtalk:ip:123.45.67.89
 100         stores: integer, 0 or 1
 101         set in: User::loadFromDatabase()
 102         cleared by: User::saveSettings() # ?
 103         expiry set to 30 minutes
 104
 105 LinkCache:
 106         key: $wgDBname:lc:title:$title
 107         ex: wikidb:lc:title:Wikipedia:Welcome,_Newcomers!
 108         stores: cur_id of page, or 0 if page does not exist
 109         set in: LinkCache::addLink()
 110         cleared by: LinkCache::clearBadLink()
 111                 should be cleared on page deletion and rename
 112 MediaWiki namespace:
 113         key: $wgDBname:messages
 114         ex: wikidb:messages
 115         stores: an array where the keys are DB keys and the values are messages
 116         set in: wfMsg(), Article::editUpdates() both call wfLoadAllMessages()
 117         cleared by: nothing
 118
 119 Watchlist:
 120         key: $wgDBname:watchlist:id:$userID
 121         ex: wikidb:watchlist:id:4635
 122         stores: HTML string
 123         cleared by: nothing, expiry time $wgWLCacheTimeout (1 hour)
 124         note: emergency optimisation only
 125
 126 IP blocks:
 127         key: $wgDBname:ipblocks
 128         ex: wikidb:ipblocks
 129         stores: array of arrays, for the BlockCache class
 130         cleared by: BlockCache:clear()
 131
 132 ... more to come ...