You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.markdown
+26-26Lines changed: 26 additions & 26 deletions
Original file line number
Diff line number
Diff line change
@@ -69,7 +69,7 @@ This module is production ready.
69
69
Version
70
70
=======
71
71
72
-
This document describes srcache-nginx-module [v0.26](https://github.com/agentzh/srcache-nginx-module/tags) released on 20 March 2014.
72
+
This document describes srcache-nginx-module [v0.26](https://github.com/openresty/srcache-nginx-module/tags) released on 20 March 2014.
73
73
74
74
Synopsis
75
75
========
@@ -164,7 +164,7 @@ Description
164
164
165
165
This module provides a transparent caching layer for arbitrary nginx locations (like those use an upstream or even serve static disk files). The caching behavior is mostly compatible with [RFC 2616](http://www.ietf.org/rfc/rfc2616.txt).
166
166
167
-
Usually, [memc-nginx-module](http://github.com/agentzh/memc-nginx-module) is used together with this module to provide a concrete caching storage backend. But technically, any modules that provide a REST interface can be used as the fetching and storage subrequests used by this module.
167
+
Usually, [memc-nginx-module](http://github.com/openresty/memc-nginx-module) is used together with this module to provide a concrete caching storage backend. But technically, any modules that provide a REST interface can be used as the fetching and storage subrequests used by this module.
168
168
169
169
For main requests, the [srcache_fetch](#srcache_fetch) directive works at the end of the access phase, so the [standard access module](http://nginx.org/en/docs/http/ngx_http_access_module.html)'s [allow](http://nginx.org/en/docs/http/ngx_http_access_module.html#allow) and [deny](http://nginx.org/en/docs/http/ngx_http_access_module.html#deny) direcives run *before* ours, which is usually the desired behavior for security reasons.
170
170
@@ -179,7 +179,7 @@ Subrequest caching
179
179
180
180
For *subrequests*, we explicitly **disallow** the use of this module because it's too difficult to get right. There used to be an implementation but it was buggy and I finally gave up fixing it and abandoned it.
181
181
182
-
However, if you're using [lua-nginx-module](http://github.com/chaoslawful/lua-nginx-module), it's easy to do subrequest caching in Lua all by yourself. That is, first issue a subrequest to an [memc-nginx-module](http://github.com/agentzh/memc-nginx-module) location to do an explicit cache lookup, if cache hit, just use the cached data returned; otherwise, fall back to the true backend, and finally do a cache insertion to feed the data into the cache.
182
+
However, if you're using [lua-nginx-module](http://github.com/openresty/lua-nginx-module), it's easy to do subrequest caching in Lua all by yourself. That is, first issue a subrequest to an [memc-nginx-module](http://github.com/openresty/memc-nginx-module) location to do an explicit cache lookup, if cache hit, just use the cached data returned; otherwise, fall back to the true backend, and finally do a cache insertion to feed the data into the cache.
183
183
184
184
Using this module for main request caching and Lua for subrequest caching is the approach that we're taking in our business. This hybrid solution works great in production.
185
185
@@ -234,16 +234,16 @@ http {
234
234
```
235
235
Here's what is going on in the sample above:
236
236
1. We first define three upstreams, `moon`, `earth`, and `sun`. These are our three memcached servers.
237
-
1. And then we group them together as an upstream list entity named `universe` with the `upstream_list` directive provided by [set-misc-nginx-module](http://github.com/agentzh/set-misc-nginx-module).
237
+
1. And then we group them together as an upstream list entity named `universe` with the `upstream_list` directive provided by [set-misc-nginx-module](http://github.com/openresty/set-misc-nginx-module).
238
238
1. After that, we define an internal location named `/memc` for talking to the memcached cluster.
239
-
1. In this `/memc` location, we first set the `$memc_key` variable with the query string (`$args`), and then use the [set_hashed_upstream](http://github.com/agentzh/set-misc-nginx-module#set_hashed_upstream) directive to hash our [$memc_key](http://github.com/agentzh/memc-nginx-module#memc_key) over the upsteam list `universe`, so as to obtain a concrete upstream name to be assigned to the variable `$backend`.
240
-
1. We pass this `$backend` variable into the [memc_pass](http://github.com/agentzh/memc-nginx-module#memc_pass) directive. The `$backend` variable can hold a value among `moon`, `earth`, and `sun`.
241
-
1. Also, we define the memcached caching expiration time to be 3600 seconds (i.e., an hour) by overriding the [$memc_exptime](http://github.com/agentzh/memc-nginx-module#memc_exptime) variable.
239
+
1. In this `/memc` location, we first set the `$memc_key` variable with the query string (`$args`), and then use the [set_hashed_upstream](http://github.com/openresty/set-misc-nginx-module#set_hashed_upstream) directive to hash our [$memc_key](http://github.com/openresty/memc-nginx-module#memc_key) over the upsteam list `universe`, so as to obtain a concrete upstream name to be assigned to the variable `$backend`.
240
+
1. We pass this `$backend` variable into the [memc_pass](http://github.com/openresty/memc-nginx-module#memc_pass) directive. The `$backend` variable can hold a value among `moon`, `earth`, and `sun`.
241
+
1. Also, we define the memcached caching expiration time to be 3600 seconds (i.e., an hour) by overriding the [$memc_exptime](http://github.com/openresty/memc-nginx-module#memc_exptime) variable.
242
242
1. In our main public location `/`, we configure the `$uri` variable as our cache key, and then configure [srcache_fetch](#srcache_fetch) for cache lookups and [srcache_store](#srcache_store) for cache updates. We're using two subrequests to our `/memc` location defined earlier in these two directives.
243
243
244
-
One can use [lua-nginx-module](http://github.com/chaoslawful/lua-nginx-module)'s [set_by_lua](http://github.com/chaoslawful/lua-nginx-module#set_by_lua) or [rewrite_by_lua](http://github.com/chaoslawful/lua-nginx-module#rewrite_by_lua) directives to inject custom Lua code to compute the `$backend` and/or `$key` variables in the sample above.
244
+
One can use [lua-nginx-module](http://github.com/openresty/lua-nginx-module)'s [set_by_lua](http://github.com/openresty/lua-nginx-module#set_by_lua) or [rewrite_by_lua](http://github.com/openresty/lua-nginx-module#rewrite_by_lua) directives to inject custom Lua code to compute the `$backend` and/or `$key` variables in the sample above.
245
245
246
-
One thing that should be taken care of is that memcached does have restriction on key lengths, i.e., 250 bytes, so for keys that may be very long, one could use the [set_md5](http://github.com/agentzh/set-misc-nginx-module#set_md5) directive or its friends to pre-hash the key to a fixed-length digest before assigning it to `$memc_key` in the `/memc` location or the like.
246
+
One thing that should be taken care of is that memcached does have restriction on key lengths, i.e., 250 bytes, so for keys that may be very long, one could use the [set_md5](http://github.com/openresty/set-misc-nginx-module#set_md5) directive or its friends to pre-hash the key to a fixed-length digest before assigning it to `$memc_key` in the `/memc` location or the like.
247
247
248
248
Further, one can utilize the [srcache_fetch_skip](#srcache_fetch_skip) and [srcache_store_skip](#srcache_store_skip) directives to control what to cache and what not on a per-request basis, and Lua can also be used here in a similar way. So the possibility is really unlimited.
249
249
@@ -303,11 +303,11 @@ location = /redis2 {
303
303
}
304
304
```
305
305
306
-
This example makes use of the [$echo_request_body](http://github.com/agentzh/echo-nginx-module#echo_request_body) variable provided by [echo-nginx-module](http://github.com/agentzh/echo-nginx-module). Note that you need the latest version of [echo-nginx-module](http://github.com/agentzh/echo-nginx-module), `v0.38rc2` because earlier versions may not work reliably.
306
+
This example makes use of the [$echo_request_body](http://github.com/openresty/echo-nginx-module#echo_request_body) variable provided by [echo-nginx-module](http://github.com/openresty/echo-nginx-module). Note that you need the latest version of [echo-nginx-module](http://github.com/openresty/echo-nginx-module), `v0.38rc2` because earlier versions may not work reliably.
307
307
308
-
Also, you need both [HttpRedisModule](http://wiki.nginx.org/HttpRedisModule) and [redis2-nginx-module](http://github.com/agentzh/redis2-nginx-module). The former is used in the [srcache_fetch](#srcache_fetch) subrequest and the latter is used in the [srcache_store](#srcache_store) subrequest.
308
+
Also, you need both [HttpRedisModule](http://wiki.nginx.org/HttpRedisModule) and [redis2-nginx-module](http://github.com/openresty/redis2-nginx-module). The former is used in the [srcache_fetch](#srcache_fetch) subrequest and the latter is used in the [srcache_store](#srcache_store) subrequest.
309
309
310
-
The Nginx core also has a bug that could prevent [redis2-nginx-module](http://github.com/agentzh/redis2-nginx-module)'s pipelining support from working properly in certain extreme conditions. And the following patch fixes this:
310
+
The Nginx core also has a bug that could prevent [redis2-nginx-module](http://github.com/openresty/redis2-nginx-module)'s pipelining support from working properly in certain extreme conditions. And the following patch fixes this:
we want to remove the `SID` and `UID` arguments from it. It is easy to achieve if you use [lua-nginx-module](http://github.com/chaoslawful/lua-nginx-module) at the same time:
327
+
we want to remove the `SID` and `UID` arguments from it. It is easy to achieve if you use [lua-nginx-module](http://github.com/openresty/lua-nginx-module) at the same time:
328
328
329
329
```nginx
330
330
@@ -340,7 +340,7 @@ location = /t {
340
340
}
341
341
```
342
342
343
-
Here we use the [echo](http://github.com/agentzh/echo-nginx-module#echo) directive from [echo-nginx-module](http://github.com/agentzh/echo-nginx-module) to dump out
343
+
Here we use the [echo](http://github.com/openresty/echo-nginx-module#echo) directive from [echo-nginx-module](http://github.com/openresty/echo-nginx-module) to dump out
344
344
the final value of [$args](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_args) in the end. You can replace it with your
345
345
[[HttpSRCacheModule]] configurations and upstream configurations instead for
346
346
your case. Let's test this /t interface with curl:
@@ -435,7 +435,7 @@ location / {
435
435
# proxy_pass/fastcgi_pass/content_by_lua/...
436
436
}
437
437
```
438
-
where [lua-nginx-module](http://github.com/chaoslawful/lua-nginx-module) is used to calculate the value of the `$skip` variable at the (earlier) rewrite phase. Similarly, the `$key` variable can be computed by Lua using the [set_by_lua](http://github.com/chaoslawful/lua-nginx-module#set_by_lua) or [rewrite_by_lua](http://github.com/chaoslawful/lua-nginx-module#rewrite_by_lua) directive too.
438
+
where [lua-nginx-module](http://github.com/openresty/lua-nginx-module) is used to calculate the value of the `$skip` variable at the (earlier) rewrite phase. Similarly, the `$key` variable can be computed by Lua using the [set_by_lua](http://github.com/openresty/lua-nginx-module#set_by_lua) or [rewrite_by_lua](http://github.com/openresty/lua-nginx-module#rewrite_by_lua) directive too.
439
439
440
440
The standard [map](http://nginx.org/en/docs/http/ngx_http_map_module.html#map) directive can also be used to compute the value of the `$skip` variable used in the sample above:
441
441
@@ -918,7 +918,7 @@ This variable was first introduced in the `v0.14` release.
918
918
Known Issues
919
919
============
920
920
* On certain systems, enabling aio and/or sendfile may stop [srcache_store](#srcache_store) from working. You can disable them in the locations configured by [srcache_store](#srcache_store).
921
-
* The [srcache_store](#srcache_store) directive can not be used to capture the responses generated by [echo-nginx-module](http://github.com/agentzh/echo-nginx-module)'s subrequest directivees like [echo_subrequest_async](http://github.com/agentzh/echo-nginx-module#echo_subrequest_async) and [echo_location](http://github.com/agentzh/echo-nginx-module#echo_location).
921
+
* The [srcache_store](#srcache_store) directive can not be used to capture the responses generated by [echo-nginx-module](http://github.com/openresty/echo-nginx-module)'s subrequest directivees like [echo_subrequest_async](http://github.com/openresty/echo-nginx-module#echo_subrequest_async) and [echo_location](http://github.com/openresty/echo-nginx-module#echo_location).
922
922
923
923
[Back to TOC](#table-of-contents)
924
924
@@ -929,7 +929,7 @@ Caveats
929
929
930
930
proxy_set_header Accept-Encoding "";
931
931
```
932
-
* Do *not* use [ngx_http_rewrite_module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)'s [if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) directive in the same location as this module's, because "[if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) is evil". Instead, use [ngx_http_map_module](http://nginx.org/en/docs/http/ngx_http_map_module.html) or [lua-nginx-module](http://github.com/chaoslawful/lua-nginx-module) combined with this module's [srcache_store_skip](#srcache_store_skip) and/or [srcache_fetch_skip](#srcache_fetch_skip) directives. For example:
932
+
* Do *not* use [ngx_http_rewrite_module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html)'s [if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) directive in the same location as this module's, because "[if](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html#if) is evil". Instead, use [ngx_http_map_module](http://nginx.org/en/docs/http/ngx_http_map_module.html) or [lua-nginx-module](http://github.com/openresty/lua-nginx-module) combined with this module's [srcache_store_skip](#srcache_store_skip) and/or [srcache_fetch_skip](#srcache_fetch_skip) directives. For example:
933
933
```nginx
934
934
935
935
map $request_method $skip_fetch {
@@ -977,8 +977,8 @@ It is recommended to install this module as well as the Nginx core and many othe
977
977
Alternatively, you can build Nginx with this module all by yourself:
978
978
979
979
* Grab the nginx source code from [nginx.org](http://nginx.org), for example, the version 1.5.11 (see [Nginx Compatibility](#compatibility)),
980
-
* and then apply the patch to your nginx source tree that fixes an important bug in the mainline Nginx core: <https://raw.github.com/agentzh/ngx_openresty/master/patches/nginx-1.4.3-upstream_truncation.patch> (you do NOT need this patch if you are using nginx 1.5.3 and later versions.)
981
-
* after that, download the latest version of the release tarball of this module from srcache-nginx-module [file list](http://github.com/agentzh/srcache-nginx-module/tags),
980
+
* and then apply the patch to your nginx source tree that fixes an important bug in the mainline Nginx core: <https://raw.github.com/openresty/ngx_openresty/master/patches/nginx-1.4.3-upstream_truncation.patch> (you do NOT need this patch if you are using nginx 1.5.3 and later versions.)
981
+
* after that, download the latest version of the release tarball of this module from srcache-nginx-module [file list](http://github.com/openresty/srcache-nginx-module/tags),
982
982
* and finally build the Nginx source with this module
983
983
```nginx
984
984
@@ -1040,20 +1040,20 @@ Bugs and Patches
1040
1040
1041
1041
Please submit bug reports, wishlists, or patches by
1042
1042
1043
-
1. creating a ticket on the [GitHub Issue Tracker](http://github.com/agentzh/srcache-nginx-module/issues),
1043
+
1. creating a ticket on the [GitHub Issue Tracker](http://github.com/openresty/srcache-nginx-module/issues),
1044
1044
1. or posting to the [OpenResty community](#community).
1045
1045
1046
1046
[Back to TOC](#table-of-contents)
1047
1047
1048
1048
Source Repository
1049
1049
=================
1050
-
Available on github at [agentzh/srcache-nginx-module](http://github.com/agentzh/srcache-nginx-module).
1050
+
Available on github at [openresty/srcache-nginx-module](http://github.com/openresty/srcache-nginx-module).
1051
1051
1052
1052
[Back to TOC](#table-of-contents)
1053
1053
1054
1054
Test Suite
1055
1055
==========
1056
-
This module comes with a Perl-driven test suite. The [test cases](http://github.com/agentzh/srcache-nginx-module/tree/master/test/t) are [declarative](http://github.com/agentzh/srcache-nginx-module/blob/master/test/t/main-req.t) too. Thanks to the [Test::Nginx](http://search.cpan.org/perldoc?Test::Base) module in the Perl world.
1056
+
This module comes with a Perl-driven test suite. The [test cases](http://github.com/openresty/srcache-nginx-module/tree/master/test/t) are [declarative](http://github.com/openresty/srcache-nginx-module/blob/master/test/t/main-req.t) too. Thanks to the [Test::Nginx](http://search.cpan.org/perldoc?Test::Base) module in the Perl world.
1057
1057
1058
1058
To run it on your side:
1059
1059
```bash
@@ -1064,7 +1064,7 @@ You need to terminate any Nginx processes before running the test suite if you h
1064
1064
1065
1065
Because a single nginx server (by default, `localhost:1984`) is used across all the test scripts (`.t` files), it's meaningless to run the test suite in parallel by specifying `-jN` when invoking the `prove` utility.
1066
1066
1067
-
Some parts of the test suite requires modules [ngx_http_rewrite_module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html), [echo-nginx-module](http://github.com/agentzh/echo-nginx-module), [rds-json-nginx-module](http://github.com/agentzh/rds-json-nginx-module), and [drizzle-nginx-module](http://github.com/chaoslawful/drizzle-nginx-module) to be enabled as well when building Nginx.
1067
+
Some parts of the test suite requires modules [ngx_http_rewrite_module](http://nginx.org/en/docs/http/ngx_http_rewrite_module.html), [echo-nginx-module](http://github.com/openresty/echo-nginx-module), [rds-json-nginx-module](http://github.com/openresty/rds-json-nginx-module), and [drizzle-nginx-module](http://github.com/openresty/drizzle-nginx-module) to be enabled as well when building Nginx.
1068
1068
1069
1069
[Back to TOC](#table-of-contents)
1070
1070
@@ -1105,7 +1105,7 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
0 commit comments