Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 228 lines (143 sloc) 7.78 kb
c442324b »
2012-02-02 Add readme
1 # Enhanced Nginx Memached Module
2
3 Goals
4 ===
5
48d9bd48 »
2013-02-13 Improve doc
6 This module is based on the standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule), with some additonal features :
c442324b »
2012-02-02 Add readme
7
32ea2f50 »
2012-05-04 Update README.markdown
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
8bb27f2d »
2012-04-22 Update doc
14 * Manage key namespaces, for partial memcached flush
d126e7d0 »
2012-05-02 Update doc
15 * Reply `304 Not Modified` for request with `If-Modified-Since` headers and content with `Last-Modified` in cache
c442324b »
2012-02-02 Add readme
16
d502923c »
2012-05-04 Update README.markdown
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
deeaf4cc »
2012-04-22 Update doc
19 Note : base module configuration is identical to standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule).
c442324b »
2012-02-02 Add readme
20
81a9fc8b »
2012-02-02 Add compilation instruction
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
48d9bd48 »
2013-02-13 Improve doc
27
81a9fc8b »
2012-02-02 Add compilation instruction
28 Compile Nginx with option in `./configure`
48d9bd48 »
2013-02-13 Improve doc
29
81a9fc8b »
2012-02-02 Add compilation instruction
30 --add-module=/my/path/to/my/clone/ngx_http_enhanced_memcached_module
31
96d920c9 »
2012-04-21 Update doc
32 Rebuild Nginx, and enjoy !
81a9fc8b »
2012-02-02 Add compilation instruction
33
32ea2f50 »
2012-05-04 Update README.markdown
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)
6eb60cee »
2012-04-21 Update doc
35
ff519831 »
2012-04-22 Update doc
36 Base config
37 ===
38
deeaf4cc »
2012-04-22 Update doc
39 This module has the same base configuration than the standard [Nginx Memcached module](http://wiki.nginx.org/HttpMemcachedModule).
ff519831 »
2012-04-22 Update doc
40
a50cb011 »
2012-04-23 Update doc
41 All commands and variables are prepàfixed by `enhanced`.
ff519831 »
2012-04-22 Update doc
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
c442324b »
2012-02-02 Add readme
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
48d9bd48 »
2013-02-13 Improve doc
59
c442324b »
2012-02-02 Add readme
60 <toto></toto>
61
62 Memcached module will set the header `Content-Type` to the specified value `text-xml` instead of the default one.
32ea2f50 »
2012-05-04 Update README.markdown
63 The http body will only contains `<toto></toto>`.
c442324b »
2012-02-02 Add readme
64
65 Before the body, line delimiters have to be `\r\n`, like in HTTP.
66
48d9bd48 »
2013-02-13 Improve doc
67 Another example with special chars and two headers:
68
69 EXTRACT_HEADERS\r\n
70 Content-Type: text/html\r\n
71 Cache-Control:max-age=21600\r\n
72 \r\n
73 <html><body>toto</body></html>
74
75
c442324b »
2012-02-02 Add readme
76 You can add multiple headers if you need.
48d9bd48 »
2013-02-13 Improve doc
77 If you do'nt start with `EXTRACT_HEADERS`, enhanced memcached module will only output the content in the http body.
c442324b »
2012-02-02 Add readme
78
deeaf4cc »
2012-04-22 Update doc
79 No modification of nginx config is needed.
c442324b »
2012-02-02 Add readme
80
81 Hash keys
82 ===
83
deeaf4cc »
2012-04-22 Update doc
84 Memcached keys are limited to 250 chars.
a50cb011 »
2012-04-23 Update doc
85 To use largest keys, just add in config :
c442324b »
2012-02-02 Add readme
86
6eb60cee »
2012-04-21 Update doc
87 enhanced_memcached_hash_keys_with_md5 on;
48d9bd48 »
2013-02-13 Improve doc
88
89 The enhanced memcached module will hash keys with md5 algorithm before inserting into memcached, and before getting data from memcached.
c442324b »
2012-02-02 Add readme
90
8bb27f2d »
2012-04-22 Update doc
91 Store data into memcached
c442324b »
2012-02-02 Add readme
92 ===
93
94 Add a location in nginx config like that :
95
96 location / {
6eb60cee »
2012-04-21 Update doc
97 set $enhanced_memcached_key "$request_uri";
98 enhanced_memcached_allow_put on;
99 enhanced_memcached_pass memcached_upstream;
c442324b »
2012-02-02 Add readme
100 }
48d9bd48 »
2013-02-13 Improve doc
101
6eb60cee »
2012-04-21 Update doc
102 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.
c442324b »
2012-02-02 Add readme
103
104 Response is a HTTP code 200, with body containing the string `STORED`.
105
106 Note : You can also send get request to this location, data will be extracted from memcached, like in a standard memcached location.
107
108 Expiration time
109 ---
110
111 Expire time in memcached is set by default to 0.
112 To set another value, add following line to config :
113
6eb60cee »
2012-04-21 Update doc
114 set $enhanced_memcached_expire 2;
c442324b »
2012-02-02 Add readme
115
48d9bd48 »
2013-02-13 Improve doc
116 Or
c442324b »
2012-02-02 Add readme
117
6eb60cee »
2012-04-21 Update doc
118 set $enhanced_memcached_expire $http_memcached_expire;
c442324b »
2012-02-02 Add readme
119
120 The first one will set a fixed expire value (2 seconds).
121
122 The second one will take the expire value to set in memcached from http header `Memcached-Expire`.
123
124 Use the `add` memcached command
125 ---
126
127 If you want to use the `add` memcached command, add following line in config :
128
6eb60cee »
2012-04-21 Update doc
129 set $enhanced_memcached_use_add 1;
c442324b »
2012-02-02 Add readme
130
48d9bd48 »
2013-02-13 Improve doc
131 Or
c442324b »
2012-02-02 Add readme
132
6eb60cee »
2012-04-21 Update doc
133 set $enhanced_memcached_use_add $http_memcached_use_add;
c442324b »
2012-02-02 Add readme
134
135 The first one will always force the use of `add` memcached command.
136
137 The second one will use the `add` memcached command only if the http header `Memcached-Use-Add` is present.
138
139 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.
140
141
142 Delete data in memcached
143 ===
144
8bb27f2d »
2012-04-22 Update doc
145 To delete entries in memcached, add a location in nginx config :
c442324b »
2012-02-02 Add readme
146
147 location / {
6eb60cee »
2012-04-21 Update doc
148 set $enhanced_memcached_key "$request_uri";
149 enhanced_memcached_allow_delete on;
150 enhanced_memcached_pass memcached_upstream;
c442324b »
2012-02-02 Add readme
151 }
48d9bd48 »
2013-02-13 Improve doc
152
8bb27f2d »
2012-04-22 Update doc
153 And send a DELETE HTTP request to this location.
c442324b »
2012-02-02 Add readme
154
155 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.
156
6eb60cee »
2012-04-21 Update doc
157 Note : It can be used with `enhanced_memcached_allow_put` in the same location
c442324b »
2012-02-02 Add readme
158
159
160 Flush memcached
161 ===
162
a50cb011 »
2012-04-23 Update doc
163 To completely flush memcached, add a location in nginx config :
48d9bd48 »
2013-02-13 Improve doc
164
c442324b »
2012-02-02 Add readme
165 location /flush {
6eb60cee »
2012-04-21 Update doc
166 enhanced_memcached_flush on;
167 enhanced_memcached_pass memcached_upstream;
c442324b »
2012-02-02 Add readme
168 }
169
8bb27f2d »
2012-04-22 Update doc
170 And send a GET HTTP request on uri /flush.
c442324b »
2012-02-02 Add readme
171
172 Response is a HTTP code 200, with body containing the string `OK`.
173
174 Stats memcached
175 ===
176
8bb27f2d »
2012-04-22 Update doc
177 To get memcached stats, add a location in nginx config :
c442324b »
2012-02-02 Add readme
178
179 location /stats {
6eb60cee »
2012-04-21 Update doc
180 enhanced_memcached_stats on;
181 enhanced_memcached_pass memcached_upstream;
c442324b »
2012-02-02 Add readme
182 }
183
8bb27f2d »
2012-04-22 Update doc
184 And send a GET HTTP request on uri /stats.
c442324b »
2012-02-02 Add readme
185
186 Response is a HTTP code 200, with body containing all stats returned by memcached.
187
8bb27f2d »
2012-04-22 Update doc
188 Key namespaces
189 ===
190
191 This feature is an implementation of namespaces : see the [memcached documentation](http://code.google.com/p/memcached/wiki/NewProgrammingTricks#Namespacing) for more details.
192
193 You can set the namespace to use with a location by adding :
194
195 set $enhanced_memcached_key_namespace "$host";
196
deeaf4cc »
2012-04-22 Update doc
197 The enhanced memached module will use the HTTP host as namespace for the current location.
8bb27f2d »
2012-04-22 Update doc
198
48d9bd48 »
2013-02-13 Improve doc
199 You can flush a namespace (in reality, it only increment the key prefix) with a location
8bb27f2d »
2012-04-22 Update doc
200
201 location /flush_ns_to {
202 set $enhanced_memcached_key "$request_uri";
203 set $enhanced_memcached_key_namespace "$host";
204 enhanced_memcached_flush_namespace on;
205 enhanced_memcached_pass memcached_upstream;
d126e7d0 »
2012-05-02 Update doc
206 }
207
208 304 Not Modified
209 ===
210
8f9207e9 »
2012-05-04 Update README.markdown
211 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.
212
213 License
214 ===
215
385987d8 »
2012-05-04 Update README.markdown
216 Copyright 2012 Bertrand Paquet
8f9207e9 »
2012-05-04 Update README.markdown
217
218 Licensed under the Apache License, Version 2.0 (the "License");
219 you may not use this file except in compliance with the License.
220 You may obtain a copy of the License at
221
222 http://www.apache.org/licenses/LICENSE-2.0
223
224 Unless required by applicable law or agreed to in writing, software
225 distributed under the License is distributed on an "AS IS" BASIS,
226 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
227 See the License for the specific language governing permissions and
228 limitations under the License.
Something went wrong with that request. Please try again.