API: Add isset() to avoid PHP warning
[mediawiki.git] / docs / memcached.txt
blobad2307fda08044cecc3000bcbfc8782928c03d69
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/
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.
10 == Installation ==
12 Packages are available for Fedora, Debian, Ubuntu and probably other
13 Linux distributions. If there's no package available for your
14 distribution, you can compile it from source.
16 == Compilation ==
18 * PHP must be compiled with --enable-sockets
20 * libevent: http://www.monkey.org/~provos/libevent/
21   (as of 2003-08-11, 0.7a is current)
23 * optionally, epoll-rt patch for Linux kernel:
24   http://www.xmailserver.org/linux-patches/nio-improve.html
26 * memcached: http://www.danga.com/memcached/download.bml
27   (as of this writing, 1.1.9 is current)
29 Memcached and libevent are under BSD-style licenses.
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.
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.
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 ! ! ! ! ! ***********************
49 == Setup ==
51 If you installed memcached using a distro, the daemon should be started
52 automatically using /etc/init.d/memcached.
54 To start the daemon manually, use something like:
56   memcached -d -l 127.0.0.1 -p 11211 -m 64
58 (to run in daemon mode, accessible only via loopback interface,
59 on port 11211, using up to 64MB of memory)
61 In your LocalSettings.php file, set:
63         $wgMainCacheType = CACHE_MEMCACHED;
64         $wgMemCachedServers = array( "127.0.0.1:11211" );
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:
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   );
78 == PHP client for memcached ==
80 MediaWiki uses a fork of Ryan T. Dean's pure-PHP memcached client.
81 It also supports the PECL PHP extension for memcached.
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.
93 By default, $wgMemc is used but when it is $parserMemc or $messageMemc
94 this is mentioned below.
96 == Keys used ==
98 (incomplete, out of date)
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
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
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
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
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()
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: wfMessage(), Article::editUpdates() and Title::moveTo()
142         expriy: $wgMsgCacheExpiry
143         cleared by: nothing
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
153 Parser Cache:
154         stored in: $parserMemc
155         key: $wgDBname:pcache:idhash:$pageid-$renderkey!$hash
156                 $pageid: id of the page
157                 $renderkey: 1 if action=render, 0 otherwise
158                 $hash: hash of user options applied to the page, see ParserOptions::optionsHash()
159         ex: wikidb:pcache:idhash:1-0!1!0!!en!2
160         stores: ParserOutput object
161         modified by: WikiPage::doEditUpdates() or PoolWorkArticleView::doWork()
162         expiry: $wgParserCacheExpireTime or less if it contains short lived functions
164         key: $wgDBname:pcache:idoptions:$pageid
165         stores: CacheTime object with an additional list of used options for the hash,
166     serves as ParserCache pointer.
167         modified by: ParserCache::save()
168         expiry: The same as the ParserCache entry it points to.
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
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
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
199 Sessions:
200         controlled by: $wgSessionsInObjectCache
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()
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()
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
223 Special:Recentchanges (feed):
224         stored in: $messageMemc
225         key: $wgDBname:rcfeed:$format:$limit:$hideminor:$target and
226                 rcfeed:$format:timestamp
227         ex: wikidb:rcfeed:rss:50:: and rcfeed:rss:timestamp
228         stores: xml output of feed
229         expiry: one day
230         clear by: maintenance/rebuildrecentchanges.php script, or
231         calling Special:Recentchanges?action=purge&feed=rss,
232         Special:Recentchanges?action=purge&feed=atom,
233         but note need $wgGroupPermissions[...]['purge'] permission.
235 Statistics:
236         controlled by: $wgStatsMethod
237         key: $wgDBname:stats:$key
238         ex: wikibd:stats:request_with_session
239         stores: counter for statistics (see maintenance/showCacheStats.php script)
240         expiry: none (?)
241         cleared by: maintenance/clearCacheStats.php script
243 User:
244         key: $wgDBname:user:id:$sId
245         ex: wikidb:user:id:51
246         stores: instance of class User
247         set in: User::saveToCache()
248         cleared by: User::saveSettings(), User::clearSharedCache()
250 ... more to come ...