README.md
1About
2=====
3`ngx_slowfs_cache` is `nginx` module which allows caching of static files
4(served using `root` directive). This enables one to create fast caches
5for files stored on slow filesystems, for example:
6
7- storage: network disks, cache: local disks,
8- storage: 7,2K SATA drives, cache: 15K SAS drives in RAID0.
9
10
11**WARNING! There is no point in using this module when cache is placed
12on the same speed disk(s) as origin.**
13
14
15Sponsors
16========
17`ngx_slowfs_cache` was fully funded by [c2hosting.com](http://c2hosting.com).
18
19
20Status
21======
22This module is production-ready and it's compatible with following nginx
23releases:
24
25- 0.7.x (tested with 0.7.60 to 0.7.69),
26- 0.8.x (tested with 0.8.0 to 0.8.55),
27- 0.9.x (tested with 0.9.0 to 0.9.7),
28- 1.0.x (tested with 1.0.0 to 1.0.15),
29- 1.1.x (tested with 1.1.0 to 1.1.19),
30- 1.2.x (tested with 1.2.0 to 1.2.7),
31- 1.3.x (tested with 1.3.0 to 1.3.14).
32
33
34Configuration notes
35===================
36`slowfs_cache_path` and `slowfs_temp_path` values should point to the same
37filesystem, otherwise files will be copied twice.
38
39`ngx_slowfs_cache` currently doesn't work when AIO is enabled.
40
41
42Configuration directives
43========================
44slowfs_cache
45------------
46* **syntax**: `slowfs_cache zone_name`
47* **default**: `none`
48* **context**: `http`, `server`, `location`
49
50Sets area used for caching (previously definied using `slowfs_cache_path`).
51
52
53slowfs_cache_key
54----------------
55* **syntax**: `slowfs_cache_key key`
56* **default**: `none`
57* **context**: `http`, `server`, `location`
58
59Sets key for caching.
60
61
62slowfs_cache_purge
63------------------
64* **syntax**: `slowfs_cache_purge zone_name key`
65* **default**: `none`
66* **context**: `location`
67
68Sets area and key used for purging selected pages from cache.
69
70
71slowfs_cache_path
72-----------------
73* **syntax**: `slowfs_cache_path path [levels] keys_zone=zone_name:zone_size [inactive] [max_size]`
74* **default**: `none`
75* **context**: `http`
76
77Sets cache area and its structure.
78
79
80slowfs_temp_path
81----------------
82* **syntax**: `slowfs_temp_path path [level1] [level2] [level3]`
83* **default**: `/tmp 1 2`
84* **context**: `http`
85
86Sets temporary area where files are stored before they are moved to cache area.
87
88
89slowfs_cache_min_uses
90---------------------
91* **syntax**: `slowfs_cache_min_uses number`
92* **default**: `1`
93* **context**: `http`, `server`, `location`
94
95Sets number of uses after which file is copied to cache.
96
97
98slowfs_cache_valid
99------------------
100* **syntax**: `slowfs_cache_valid [reply_code] time`
101* **default**: `none`
102* **context**: `http`, `server`, `location`
103
104Sets time for which file will be served from cache.
105
106
107slowfs_big_file_size
108--------------------
109* **syntax**: `slowfs_big_file_size size`
110* **default**: `128k`
111* **context**: `http`, `server`, `location`
112
113Sets minimum file size for `big` files. Worker processes `fork()` child process
114before they start copying `big` files to avoid any service disruption.
115
116
117Configuration variables
118=======================
119$slowfs_cache_status
120--------------------
121Represents availability of cached file.
122
123Possible values are: `MISS`, `HIT` and `EXPIRED`.
124
125
126Sample configuration
127====================
128 http {
129 slowfs_cache_path /tmp/cache levels=1:2 keys_zone=fastcache:10m;
130 slowfs_temp_path /tmp/temp 1 2;
131
132 server {
133 location / {
134 root /var/www;
135 slowfs_cache fastcache;
136 slowfs_cache_key $uri;
137 slowfs_cache_valid 1d;
138 }
139
140 location ~ /purge(/.*) {
141 allow 127.0.0.1;
142 deny all;
143 slowfs_cache_purge fastcache $1;
144 }
145 }
146 }
147
148Testing
149=======
150`ngx_slowfs_cache` comes with complete test suite based on [Test::Nginx](http://github.com/agentzh/test-nginx).
151
152You can test it by running:
153
154`$ prove`
155
156
157License
158=======
159 Copyright (c) 2009-2012, FRiCKLE <info@frickle.com>
160 Copyright (c) 2009-2012, Piotr Sikora <piotr.sikora@frickle.com>
161 Copyrithg (c) 2002-2012, Igor Sysoev <igor@sysoev.ru>
162 All rights reserved.
163
164 This project was fully funded by c2hosting.com.
165 Included cache_purge functionality was fully funded by yo.se.
166
167 Redistribution and use in source and binary forms, with or without
168 modification, are permitted provided that the following conditions
169 are met:
170 1. Redistributions of source code must retain the above copyright
171 notice, this list of conditions and the following disclaimer.
172 2. Redistributions in binary form must reproduce the above copyright
173 notice, this list of conditions and the following disclaimer in the
174 documentation and/or other materials provided with the distribution.
175
176 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
177 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
178 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
179 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
180 HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
181 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
182 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
183 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
184 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
185 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
186 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
187
188
189See also
190========
191- [ngx_cache_purge](http://github.com/FRiCKLE/ngx_cache_purge).
192