Skip to content
Newer
Older
100644 219 lines (137 sloc) 7.44 KB
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
1 # Enhanced Nginx Memached Module
2
3 Goals
4 ===
5
deeaf4c Update doc
Bertrand Paquet authored Apr 22, 2012
6 This module is based on the standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule), with some additonal features :
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
7
32ea2f5 Update README.markdown
Bertrand Paquet authored May 4, 2012
8 * Send custom http headers, like `Content-Type`, `Last-Modified`. Http headers are stored in memcached, with your body data.
9 * Hash keys to use large keys (> 250 chars, memcached limit)
10 * Store data into memcached, via HTTP request to nginx
11 * Delete data from memcached, via HTTP request to nginx
12 * Flush memcached, via HTTP request to nginx
13 * Get memcached'stats, via HTTP request to nginx
8bb27f2 Update doc
Bertrand Paquet authored Apr 22, 2012
14 * Manage key namespaces, for partial memcached flush
d126e7d Update doc
Bertrand Paquet authored May 2, 2012
15 * Reply `304 Not Modified` for request with `If-Modified-Since` headers and content with `Last-Modified` in cache
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
16
d502923 Update README.markdown
Bertrand Paquet authored May 4, 2012
17 You can find some explanation around why this module has been created in this [blog post](http://blog.octo.com/en/http-caching-with-nginx-and-memcached/).
18
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
19 Note : base module configuration is identical to standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule).
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
20
81a9fc8 Add compilation instruction
Bertrand Paquet authored Feb 2, 2012
21 How to use it
22 ===
23
24 Clone the code
25
26 git clone git://github.com/bpaquet/ngx_http_enhanced_memcached_module.git
27
28 Compile Nginx with option in `./configure`
29
30 --add-module=/my/path/to/my/clone/ngx_http_enhanced_memcached_module
31
96d920c Update doc
Bertrand Paquet authored Apr 21, 2012
32 Rebuild Nginx, and enjoy !
81a9fc8 Add compilation instruction
Bertrand Paquet authored Feb 2, 2012
33
32ea2f5 Update README.markdown
Bertrand Paquet authored May 4, 2012
34 Note : this module has been tested with Nginx 1.1.14 and Nginx 1.2.0, and is used in production at [fasterize](http://www.fasterize.com)
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
35
ff51983 Update doc
Bertrand Paquet authored Apr 22, 2012
36 Base config
37 ===
38
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
39 This module has the same base configuration than the standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule).
ff51983 Update doc
Bertrand Paquet authored Apr 21, 2012
40
a50cb01 Update doc
Bertrand Paquet authored Apr 23, 2012
41 All commands and variables are prepàfixed by `enhanced`.
ff51983 Update doc
Bertrand Paquet authored Apr 21, 2012
42
43 * [`enhanced_memcached_pass`](http://wiki.nginx.org/HttpMemcachedModule#memcached_pass)
44 * [`enhanced_memcached_connect_timeout`](http://wiki.nginx.org/HttpMemcachedModule#memcached_connect_timeout)
45 * [`enhanced_memcached_read_timeout`](http://wiki.nginx.org/HttpMemcachedModule#memcached_read_timeout)
46 * [`enhanced_memcached_send_timeout`](http://wiki.nginx.org/HttpMemcachedModule#memcached_send_timeout)
47 * [`enhanced_memcached_buffer_size`](http://wiki.nginx.org/HttpMemcachedModule#memcached_buffer_size)
48 * [`enhanced_memcached_next_upstream`](http://wiki.nginx.org/HttpMemcachedModule#memcached_next_upstream)
49
50 * [`$enhanced_memcached_key`](http://wiki.nginx.org/HttpMemcachedModule#.24memcached_key)
51
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
52 Custom HTTP Headers
53 ===
54
55 Instead of inserting raw data in memcached, put something like that
56
57 EXTRACT_HEADERS
58 Content-Type: text/xml
59
60 <toto></toto>
61
62 Memcached module will set the header `Content-Type` to the specified value `text-xml` instead of the default one.
32ea2f5 Update README.markdown
Bertrand Paquet authored May 4, 2012
63 The http body will only contains `<toto></toto>`.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
64
65 Before the body, line delimiters have to be `\r\n`, like in HTTP.
66
67 You can add multiple headers if you need.
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
68 If you do'nt start with `EXTRACT_HEADERS`, enhanced memcached module will only output the content in the http body.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
69
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
70 No modification of nginx config is needed.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
71
72 Hash keys
73 ===
74
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
75 Memcached keys are limited to 250 chars.
a50cb01 Update doc
Bertrand Paquet authored Apr 23, 2012
76 To use largest keys, just add in config :
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
77
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
78 enhanced_memcached_hash_keys_with_md5 on;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
79
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
80 The enhanced memcached module will hash key with md5 algorithm before inserting into memcached, and before getting data from memcached.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
81
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
82 Store data into memcached
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
83 ===
84
85 Add a location in nginx config like that :
86
87 location / {
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
88 set $enhanced_memcached_key "$request_uri";
89 enhanced_memcached_allow_put on;
90 enhanced_memcached_pass memcached_upstream;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
91 }
92
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
93 And send a PUT HTTP request into nginx, with body containing what you want to store in memcached, under the key $enhanced_memcached_key. The `set` memcached command is used.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
94
95 Response is a HTTP code 200, with body containing the string `STORED`.
96
97 Note : You can also send get request to this location, data will be extracted from memcached, like in a standard memcached location.
98
99 Expiration time
100 ---
101
102 Expire time in memcached is set by default to 0.
103 To set another value, add following line to config :
104
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
105 set $enhanced_memcached_expire 2;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
106
107 Or
108
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
109 set $enhanced_memcached_expire $http_memcached_expire;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
110
111 The first one will set a fixed expire value (2 seconds).
112
113 The second one will take the expire value to set in memcached from http header `Memcached-Expire`.
114
115 Use the `add` memcached command
116 ---
117
118 If you want to use the `add` memcached command, add following line in config :
119
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
120 set $enhanced_memcached_use_add 1;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
121
122 Or
123
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
124 set $enhanced_memcached_use_add $http_memcached_use_add;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
125
126 The first one will always force the use of `add` memcached command.
127
128 The second one will use the `add` memcached command only if the http header `Memcached-Use-Add` is present.
129
130 If you send an `add` command on an existing key, memcached will respond `NOT_STORED`, and the nginx module will issue a HTTP code 409.
131
132
133 Delete data in memcached
134 ===
135
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
136 To delete entries in memcached, add a location in nginx config :
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
137
138 location / {
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
139 set $enhanced_memcached_key "$request_uri";
140 enhanced_memcached_allow_delete on;
141 enhanced_memcached_pass memcached_upstream;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
142 }
143
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
144 And send a DELETE HTTP request to this location.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
145
146 Response is a HTTP code 200, with body containing the string `DELETED`, or HTTP code 404, with body `NOT_FOUND` if the key does not exist in memcached.
147
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
148 Note : It can be used with `enhanced_memcached_allow_put` in the same location
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
149
150
151 Flush memcached
152 ===
153
a50cb01 Update doc
Bertrand Paquet authored Apr 23, 2012
154 To completely flush memcached, add a location in nginx config :
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
155
156 location /flush {
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
157 enhanced_memcached_flush on;
158 enhanced_memcached_pass memcached_upstream;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
159 }
160
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
161 And send a GET HTTP request on uri /flush.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
162
163 Response is a HTTP code 200, with body containing the string `OK`.
164
165 Stats memcached
166 ===
167
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
168 To get memcached stats, add a location in nginx config :
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
169
170 location /stats {
6eb60ce Update doc
Bertrand Paquet authored Apr 21, 2012
171 enhanced_memcached_stats on;
172 enhanced_memcached_pass memcached_upstream;
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
173 }
174
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
175 And send a GET HTTP request on uri /stats.
c442324 Add readme
Bertrand Paquet authored Feb 2, 2012
176
177 Response is a HTTP code 200, with body containing all stats returned by memcached.
178
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
179 Key namespaces
180 ===
181
182 This feature is an implementation of namespaces : see the [memcached documentation](http://code.google.com/p/memcached/wiki/NewProgrammingTricks#Namespacing) for more details.
183
184 You can set the namespace to use with a location by adding :
185
186 set $enhanced_memcached_key_namespace "$host";
187
deeaf4c Update doc
Bertrand Paquet authored Apr 21, 2012
188 The enhanced memached module will use the HTTP host as namespace for the current location.
8bb27f2 Update doc
Bertrand Paquet authored Apr 21, 2012
189
190 You can flush a namespace (in reality, it only increment the key prefix) with a location
191
192 location /flush_ns_to {
193 set $enhanced_memcached_key "$request_uri";
194 set $enhanced_memcached_key_namespace "$host";
195 enhanced_memcached_flush_namespace on;
196 enhanced_memcached_pass memcached_upstream;
d126e7d Update doc
Bertrand Paquet authored May 2, 2012
197 }
198
199 304 Not Modified
200 ===
201
8f9207e Update README.markdown
Bertrand Paquet authored May 4, 2012
202 For request with HTTP Header `If-Modified-Since`, and associated resource in memcached with HTTP Headers `Last-Modified`, the module will send a 304 Not Modified if resource has not been modified, and if Nginx [configuration](http://wiki.nginx.org/HttpCoreModule#if_modified_since) allows this behaviour.
203
204 License
205 ===
206
385987d Update README.markdown
Bertrand Paquet authored May 4, 2012
207 Copyright 2012 Bertrand Paquet
8f9207e Update README.markdown
Bertrand Paquet authored May 4, 2012
208
209 Licensed under the Apache License, Version 2.0 (the "License");
210 you may not use this file except in compliance with the License.
211 You may obtain a copy of the License at
212
213 http://www.apache.org/licenses/LICENSE-2.0
214
215 Unless required by applicable law or agreed to in writing, software
216 distributed under the License is distributed on an "AS IS" BASIS,
217 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
218 See the License for the specific language governing permissions and
219 limitations under the License.
Something went wrong with that request. Please try again.