9 Squid caching proxy server (http://www.squid-cache.org/.) With it, you |
9 Squid caching proxy server (http://www.squid-cache.org/.) With it, you |
10 can dynamically alter URI requests that pass through Squid based on |
10 can dynamically alter URI requests that pass through Squid based on |
11 various criteria. |
11 various criteria. |
12 |
12 |
13 It uses a state machine to parse URIs and rules, and a constant database |
13 It uses a state machine to parse URIs and rules, and a constant database |
14 to store and access those rules. |
14 to store and access those rules. It can then either perform conditional |
|
15 rewrites internally, or by evaluating Lua scripts. |
15 |
16 |
16 |
17 |
17 Why is it called "volta"? |
18 Why is it called "volta"? |
18 ------------------------- |
19 ------------------------- |
19 |
20 |
72 ---------------- |
73 ---------------- |
73 |
74 |
74 Volta's rule syntax is designed to be easy to parse by humans and |
75 Volta's rule syntax is designed to be easy to parse by humans and |
75 machines. Blank lines are skipped, as is any line that starts with the |
76 machines. Blank lines are skipped, as is any line that starts with the |
76 '#' character, so you can keep the ascii version of your rules well |
77 '#' character, so you can keep the ascii version of your rules well |
77 documented and in version control. |
78 documented and in version control. There is no practical limit on the |
|
79 number of rules in this database. |
78 |
80 |
79 When compiling the ruleset into the database format, volta detects |
81 When compiling the ruleset into the database format, volta detects |
80 malformed rules and stops if there are any problems, leaving your |
82 malformed rules and stops if there are any problems, leaving your |
81 original database intact. You can change the ruleset at any time while |
83 original database intact. You can change the ruleset at any time while |
82 volta is running, and the new rules will take affect within about 10 |
84 volta is running, and the new rules will take affect within about 10 |
83 seconds. No need to restart squid! |
85 seconds. No need to restart squid! |
84 |
86 |
85 There are two types of rules -- positive matches, and negative matches. |
87 There are two types of rules -- positive matches, and negative matches. |
86 Positive matches cause the rewrite, negative matches allow the original |
88 Positive matches cause the rewrite, negative matches intentionally allow |
87 request to pass. Rule order is consistent, top-down, first match wins. |
89 the original request to pass. Rule order is consistent, top-down, first |
88 Fields are separated by any amount of whitespace (spaces or tabs.) |
90 match wins. Fields are separated by any amount of whitespace (spaces or |
|
91 tabs.) |
89 |
92 |
90 |
93 |
91 ### Positive matches: |
94 ### Positive matches: |
92 |
95 |
93 First field: the hostname to match. |
96 First field: the hostname to match. |
102 |
105 |
103 Second field: the path to match. |
106 Second field: the path to match. |
104 |
107 |
105 This can be an exact match ('/path/to/something.html'), a regular |
108 This can be an exact match ('/path/to/something.html'), a regular |
106 expression ('\.(jpg|gif|png)$'), or a single '*' to match for any |
109 expression ('\.(jpg|gif|png)$'), or a single '*' to match for any |
107 path. Regular expressions are matches without case sensitivity. There |
110 path. Regular expressions are matched without case sensitivity. There |
108 is currently no support for capturing, though this may be added in |
111 is currently no internal support for captures, though you can use |
109 a future release. |
112 a Lua rule (see below) for more complex processing. |
110 |
113 |
111 |
114 |
112 Third field: The redirect code and url to rewrite to. |
115 Third field: The redirect code and url to rewrite to. |
113 |
116 |
114 Any pieces of a url that are omitted are automatically replaced |
117 Any pieces of a url that are omitted are automatically replaced |
115 with the original request's element -- the exception is a hostname, |
118 with the original request's element -- the exception is a hostname, |
116 which is required. If you omit a redirect code, the URL rewrite is |
119 which is required. If you omit a redirect code, the URL rewrite is |
117 transparent to the client. You can attach a 301: or 302: prefix to |
120 transparent to the client. You can attach a 301: or 302: prefix to |
118 cause a permanent or temporary code to be respectively sent, instead. |
121 cause a permanent or temporary code to be respectively sent, instead. |
119 |
122 |
|
123 If you require more complex processing than what volta provides |
|
124 internally, you can also specify a path to a Lua script (prefixed |
|
125 with 'lua:'.) See the 'Lua rules' section of this README for more |
|
126 information. |
|
127 |
120 |
128 |
121 ### Negative matches: |
129 ### Negative matches: |
122 |
130 |
123 First field: the hostname to match. |
131 First field: the hostname to match. |
124 |
132 |
167 |
175 |
168 martini.nu /blog/2011 - |
176 martini.nu /blog/2011 - |
169 martini.nu /blog 301:martini.nu/content-archived.html |
177 martini.nu /blog 301:martini.nu/content-archived.html |
170 |
178 |
171 |
179 |
|
180 Send all requests to reddit/r/WTF/* through a lua script for further processing. |
|
181 |
|
182 reddit.com /r/wtf lua:/path/to/a/lua-script.lua |
|
183 |
|
184 |
172 Turn off rewriting for specific network segment or IP address: |
185 Turn off rewriting for specific network segment or IP address: |
173 |
186 |
174 Squid has this ability built in -- see the 'url_rewrite_access' setting. |
187 Squid has this ability built in -- see the 'url_rewrite_access' setting. |
175 |
188 Alternatively, do the checks in lua. |
|
189 |
|
190 |
|
191 |
|
192 Lua Rules |
|
193 --------- |
|
194 |
|
195 Volta has an embedded Lua interpreter that you can use to perform all |
|
196 kinds of conditional rewrites. Read more about the syntax of the Lua |
|
197 language here: http://www.lua.org/manual/5.1/ |
|
198 |
|
199 ### Loading a script |
|
200 |
|
201 To use a Lua script, prefix the rewrite target of a volta rule with |
|
202 'lua:'. The rest of the target is then treated as a path to the script. |
|
203 (You can find an example in the Examples section of this README.) |
|
204 |
|
205 You can specify a path to either an ascii file, or Lua bytecode. (If |
|
206 speed is an absolute premium, I'm seeing around a 25% performance |
|
207 increase by using Lua bytecode files.) |
|
208 |
|
209 You can use different scripts for different rules, or use the same |
|
210 script across any number of separate rules. |
|
211 |
|
212 There is no need to restart squid when modifying Lua rules. Changes are |
|
213 seen immediately. |
|
214 |
|
215 |
|
216 ### Environment |
|
217 |
|
218 * Global variable declarations are disabled, so scripts can't accidently stomp on each other. All variables must be declared with the 'local' keyword. |
|
219 * There is a global table called 'shared' you may use if you want to share data between separate scripts, or remember things in-between rule evaluations. |
|
220 * The details of the request can be found in a table, appropriately named 'request'. HTTP scheme, host, path, port, method, client_ip, and domain are all available by default from the request table. |
|
221 * Calling Lua's print() function emits debug information to stderr. Use a debug level of 2 or higher to see it. |
|
222 |
|
223 |
|
224 ### Return value |
|
225 |
|
226 The return value of the script is sent unmodified to squid, which should |
|
227 be a URL the request is rewritten to, with an optional redirect code |
|
228 prefix (301 or 302.) |
|
229 |
|
230 Omitting a return value, or returning 'nil' has the same effect as a negative |
|
231 rule match -- the original request is allowed through without any rewrite. |
|
232 |
|
233 |
|
234 An extremely simple Lua rule script can be found in the 'examples' |
|
235 directory, distributed with volta. |
|
236 |
|
237 |
|
238 |