README.md
1About
2=====
3`ngx_cache_purge` is `nginx` module which adds ability to purge content from
4`FastCGI`, `proxy`, `SCGI` and `uWSGI` caches. A purge operation removes the
5content with the same cache key as the purge request has.
6
7
8Sponsors
9========
10Work on the original patch was fully funded by [yo.se](http://yo.se).
11
12
13Status
14======
15This module is production-ready.
16
17
18Configuration directives (same location syntax)
19===============================================
20fastcgi_cache_purge
21-------------------
22* **syntax**: `fastcgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]`
23* **default**: `none`
24* **context**: `http`, `server`, `location`
25
26Allow purging of selected pages from `FastCGI`'s cache.
27
28
29proxy_cache_purge
30-----------------
31* **syntax**: `proxy_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]`
32* **default**: `none`
33* **context**: `http`, `server`, `location`
34
35Allow purging of selected pages from `proxy`'s cache.
36
37
38scgi_cache_purge
39----------------
40* **syntax**: `scgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]`
41* **default**: `none`
42* **context**: `http`, `server`, `location`
43
44Allow purging of selected pages from `SCGI`'s cache.
45
46
47uwsgi_cache_purge
48-----------------
49* **syntax**: `uwsgi_cache_purge on|off|<method> [purge_all] [from all|<ip> [.. <ip>]]`
50* **default**: `none`
51* **context**: `http`, `server`, `location`
52
53Allow purging of selected pages from `uWSGI`'s cache.
54
55
56Configuration directives (separate location syntax)
57===================================================
58fastcgi_cache_purge
59-------------------
60* **syntax**: `fastcgi_cache_purge zone_name key`
61* **default**: `none`
62* **context**: `location`
63
64Sets area and key used for purging selected pages from `FastCGI`'s cache.
65
66
67proxy_cache_purge
68-----------------
69* **syntax**: `proxy_cache_purge zone_name key`
70* **default**: `none`
71* **context**: `location`
72
73Sets area and key used for purging selected pages from `proxy`'s cache.
74
75
76scgi_cache_purge
77----------------
78* **syntax**: `scgi_cache_purge zone_name key`
79* **default**: `none`
80* **context**: `location`
81
82Sets area and key used for purging selected pages from `SCGI`'s cache.
83
84
85uwsgi_cache_purge
86-----------------
87* **syntax**: `uwsgi_cache_purge zone_name key`
88* **default**: `none`
89* **context**: `location`
90
91Sets area and key used for purging selected pages from `uWSGI`'s cache.
92
93Configuration directives (Optional)
94===================================================
95
96cache_purge_response_type
97-----------------
98* **syntax**: `cache_purge_response_type html|json|xml|text`
99* **default**: `html`
100* **context**: `http`, `server`, `location`
101
102Sets a response type of purging result.
103
104
105
106Partial Keys
107============
108Sometimes it's not possible to pass the exact key cache to purge a page. For example; when the content of a cookie or the params are part of the key.
109You can specify a partial key adding an asterisk at the end of the URL.
110
111 curl -X PURGE /page*
112
113The asterisk must be the last character of the key, so you **must** put the $uri variable at the end.
114
115
116
117Sample configuration (same location syntax)
118===========================================
119 http {
120 proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
121
122 server {
123 location / {
124 proxy_pass http://127.0.0.1:8000;
125 proxy_cache tmpcache;
126 proxy_cache_key $uri$is_args$args;
127 proxy_cache_purge PURGE from 127.0.0.1;
128 }
129 }
130 }
131
132
133Sample configuration (same location syntax - purge all cached files)
134====================================================================
135 http {
136 proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
137
138 server {
139 location / {
140 proxy_pass http://127.0.0.1:8000;
141 proxy_cache tmpcache;
142 proxy_cache_key $uri$is_args$args;
143 proxy_cache_purge PURGE purge_all from 127.0.0.1;
144 }
145 }
146 }
147
148
149Sample configuration (separate location syntax)
150===============================================
151 http {
152 proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
153
154 server {
155 location / {
156 proxy_pass http://127.0.0.1:8000;
157 proxy_cache tmpcache;
158 proxy_cache_key $uri$is_args$args;
159 }
160
161 location ~ /purge(/.*) {
162 allow 127.0.0.1;
163 deny all;
164 proxy_cache_purge tmpcache $1$is_args$args;
165 }
166 }
167 }
168
169Sample configuration (Optional)
170===============================================
171 http {
172 proxy_cache_path /tmp/cache keys_zone=tmpcache:10m;
173
174 cache_purge_response_type text;
175
176 server {
177
178 cache_purge_response_type json;
179
180 location / { #json
181 proxy_pass http://127.0.0.1:8000;
182 proxy_cache tmpcache;
183 proxy_cache_key $uri$is_args$args;
184 }
185
186 location ~ /purge(/.*) { #xml
187 allow 127.0.0.1;
188 deny all;
189 proxy_cache_purge tmpcache $1$is_args$args;
190 cache_purge_response_type xml;
191 }
192
193 location ~ /purge2(/.*) { # json
194 allow 127.0.0.1;
195 deny all;
196 proxy_cache_purge tmpcache $1$is_args$args;
197 }
198 }
199
200 server {
201
202 location / { #text
203 proxy_pass http://127.0.0.1:8000;
204 proxy_cache tmpcache;
205 proxy_cache_key $uri$is_args$args;
206 }
207
208 location ~ /purge(/.*) { #text
209 allow 127.0.0.1;
210 deny all;
211 proxy_cache_purge tmpcache $1$is_args$args;
212 }
213
214 location ~ /purge2(/.*) { #html
215 allow 127.0.0.1;
216 deny all;
217 proxy_cache_purge tmpcache $1$is_args$args;
218 cache_purge_response_type html;
219 }
220 }
221 }
222
223
224
225Solve problems
226==============
227* Enabling [`gzip_vary`](https://nginx.org/r/gzip_vary) can lead to different results when clearing, when enabling it, you may have problems clearing the cache. For reliable operation, you can disable [`gzip_vary`](https://nginx.org/r/gzip_vary) inside the location [#20](https://github.com/nginx-modules/ngx_cache_purge/issues/20).
228
229
230Testing
231=======
232`ngx_cache_purge` comes with complete test suite based on [Test::Nginx](http://github.com/agentzh/test-nginx).
233
234You can test it by running:
235
236`$ prove`
237
238
239License
240=======
241 Copyright (c) 2009-2014, FRiCKLE <info@frickle.com>
242 Copyright (c) 2009-2014, Piotr Sikora <piotr.sikora@frickle.com>
243 All rights reserved.
244
245 This project was fully funded by yo.se.
246
247 Redistribution and use in source and binary forms, with or without
248 modification, are permitted provided that the following conditions
249 are met:
250 1. Redistributions of source code must retain the above copyright
251 notice, this list of conditions and the following disclaimer.
252 2. Redistributions in binary form must reproduce the above copyright
253 notice, this list of conditions and the following disclaimer in the
254 documentation and/or other materials provided with the distribution.
255
256 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
257 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
258 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
259 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
260 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
261 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
262 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
263 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
264 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
265 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
266 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
267
268
269See also
270========
271- [ngx_slowfs_cache](http://github.com/FRiCKLE/ngx_slowfs_cache).
272- http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#purger
273- http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html#fastcgi_cache_purge
274- https://github.com/wandenberg/nginx-selective-cache-purge-module
275- https://github.com/wandenberg/nginx-sorted-querystring-module
276- https://github.com/ledgetech/ledge
277- [Faking Surrogate Cache-Keys for Nginx Plus](https://www.innoq.com/en/blog/faking-surrogate-cache-keys-for-nginx-plus/) ([gist](https://gist.github.com/titpetric/2f142e89eaa0f36ba4e4383b16d61474))
278- [Delete NGINX cached md5 items with a PURGE with wildcard support](https://gist.github.com/nosun/0cfb58d3164f829e2f027fd37b338ede)
279