1: {{{
2: #!rst
3: ==============
4: a power-magnet
5: ==============
6:
7: ------------------
8: Module: mod_magnet
9: ------------------
10:
11:
12:
13: .. contents:: Table of Contents
14:
15: Requirements
16: ============
17:
18: :Version: lighttpd 1.4.12 or higher
19: :Packages: lua >= 5.1
20:
21: Overview
22: ========
23:
24: mod_magnet is a module to control the request handling in lighty.
25:
26: .. note::
27:
28: Keep in mind that the magnet is executed in the core of lighty. EVERY long-running operation is blocking
29: ALL connections in the server. You are warned. For time-consuming or blocking scripts use mod_fastcgi and friends.
30:
31: For performance reasons mod_magnet caches the compiled script. For each script-run the script itself is checked for
32: freshness and recompile if neccesary.
33:
34:
35: Installation
36: ============
37:
38: mod_magnet needs a lighty which is compiled with the lua-support ( --with-lua). Lua 5.1 or higher are required by
39: the module. Use "--with-lua=lua5.1" to install on Debian and friends. ::
40:
41: server.modules = ( ..., "mod_magnet", ... )
42:
43: Options
44: =======
45:
46: mod_magnet can attract a request in several stages in the request-handling.
47:
48: * either at the same level as mod_rewrite, before any parsing of the URL is done
49: * or at a later stage, when the doc-root is known and the physical-path is already setup
50:
51: It depends on the purpose of the script which stage you want to intercept. Usually you want to use
52: the 2nd stage where the physical-path which relates to your request is known. At this level you
53: can run checks against lighty.env["physical.path"].
54:
55: ::
56:
57: magnet.attract-raw-url-to = ( ... )
58: magnet.attract-physical-path-to = ( ... )
59:
60: You can define multiple scripts when separated by a semicolon. The scripts are executed in the specified
61: order. If one of them a returning a status-code, the following scripts will not be executed.
62:
63: Tables
64: ======
65:
66: Most of the interaction between between mod_magnet and lighty is done through tables. Tables in lua are hashes (Perl), dictionaries (Java), arrays (PHP), ...
67:
68: Request-Environment
69: -------------------
70:
71: Lighttpd has its internal variables which are exported as read/write to the magnet.
72:
73: If "http://example.org/search.php?q=lighty" is requested this results in a request like ::
74:
75: GET /search.php?q=lighty HTTP/1.1
76: Host: example.org
77:
78: When you are using ``attract-raw-url-to`` you can access the following variables:
79:
80: * parts of the request-line
81:
82: * lighty.env["request.uri"] = "/search.php?q=lighty"
83:
84: * HTTP request-headers
85:
86: * lighty.request["Host"] = "example.org"
87:
88: Later in the request-handling, the URL is splitted, cleaned up and turned into a physical path name:
89:
90: * parts of the URI
91:
92: * lighty.env["uri.path"] = "/search.php"
93: * lighty.env["uri.path-raw"] = "/search.php"
94: * lighty.env["uri.scheme"] = "http"
95: * lighty.env["uri.authority"] = "example.org"
96: * lighty.env["uri.query"] = "q=lighty"
97:
98: * filenames, pathnames
99:
100: * lighty.env["physical.path"] = "/my-docroot/search.php"
101: * lighty.env["physical.rel-path"] = "/search.php"
102: * lighty.env["physical.doc-root"] = "/my-docroot"
103:
104: All of them are readable, not all of the are writable (or don't have an effect if you write to them).
105:
106: As a start, you might want to use those variables for writing: ::
107:
108: -- 1. simple rewriting is done via the request.uri
109: lighty.env["request.uri"] = ...
110: return lighty.RESTART_REQUEST
111:
112: -- 2. changing the physical-path
113: lighty.env["physical.path"] = ...
114:
115: -- 3. changing the query-string
116: lighty.env["uri.query"] = ...
117:
118: Response Headers
119: ----------------
120:
121: If you want to set a response header for your request, you can add a field to the lighty.header[] table: ::
122:
123: lighty.header["Content-Type"] = "text/html"
124:
125: Sending Content
126: ===============
127:
128: You can generate your own content and send it out to the clients. ::
129:
130: lighty.content = { "<pre>", { filename = "/etc/passwd" }, "</pre>" }
131: lighty.header["Content-Type"] = "text/html"
132:
133: return 200
134:
135: The lighty.content[] table is executed when the script is finished. The elements of the array are processed left to right and the elements can either be a string or a table. Strings are included AS IS into the output of the request.
136:
137: * Strings
138:
139: * are included as is
140:
141: * Tables
142:
143: * filename = "<absolute-path>" is required
144: * offset = <number> [default: 0]
145: * length = <number> [default: size of the file - offset]
146:
147: Internally lighty will use the sendfile() call to send out the static files at full speed.
148:
149: Status Codes
150: ============
151:
152: You might have seen it already in other examples: In case you are handling the request completly in the magnet you
153: can return your own status-codes. Examples are: Redirected, Input Validation, ... ::
154:
155: if (lighty.env["uri.scheme"] == "http") then
156: lighty.header["Location"] = "https://" .. lighty.env["uri.authority"] .. lighty.env["request.uri"]
157: return 302
158: end
159:
160: You every number above and equal to 100 is taken as final status code and finishes the request. No other modules are
161: executed after this return.
162:
163: A special return-code is lighty.RESTART_REQUEST (currently equal to 99) which is usually used in combination with
164: changing the request.uri in a rewrite. It restarts the splitting of the request-uri again.
165:
166: If you return nothing (or nil) the request-handling just continues.
167:
168: Debugging
169: =========
170:
171: To easy debugging we overloaded the print()-function in lua and redirect the output of print() to the error-log. ::
172:
173: print("Host: " .. lighty.request["Host"])
174: print("Request-URI: " .. lighty.env["request.uri"])
175:
176:
177: Examples
178: ========
179:
180: Sending text-files as HTML
181: --------------------------
182:
183: This is a bit simplistic, but it illustrates the idea: Take a text-file and cover it in a <pre> tag.
184:
185: Config-file ::
186:
187: magnet.attract-physical-path-to = server.docroot + "/readme.lua"
188:
189: readme.lua ::
190:
191: lighty.content = { "<pre>", { filename = "/README" }, "</pre>" }
192: lighty.header["Content-Type"] = "text/html"
193:
194: return 200
195:
196: Maintainance pages
197: ------------------
198:
199: Your side might be on maintainance from time to time. Instead of shutting down the server confusing all
200: users, you can just send a maintainance page.
201:
202: Config-file ::
203:
204: magnet.attract-physical-path-to = server.docroot + "/maintainance.lua"
205:
206: maintainance.lua ::
207:
208: require "lfs"
209:
210: if (nil == lfs.attributes(lighty.env["physical.doc-root"] .. "/maintainance.html")) then
211: lighty.content = ( lighty.env["physical.doc-root"] .. "/maintainance.html" )
212:
213: lighty.header["Content-Type"] = "text/html"
214:
215: return 200
216: end
217:
218: mod_flv_streaming
219: -----------------
220:
221: Config-file ::
222:
223: magnet.attract-physical-path-to = server.docroot + "/flv-streaming.lua"
224:
225: flv-streaming.lua::
226:
227: if (lighty.env["uri.query"]) then
228: -- split the query-string
229: get = {}
230: for k, v in string.gmatch(lighty.env["uri.query"], "(%w+)=(%w+)") do
231: get[k] = v
232: end
233:
234: if (get["start"]) then
235: -- missing: check if start is numeric and positive
236:
237: -- send te FLV header + a seek into the file
238: lighty.content = { "FLV\x1\x1\0\0\0\x9\0\0\0\x9",
239: { filename = lighty.env["physical.path"], offset = get["start"] } }
240: lighty.header["Content-Type"] = "video/x-flv"
241:
242: return 200
243: end
244: end
245:
246:
247: selecting a random file from a directory
248: ----------------------------------------
249:
250: Say, you want to send a random file (ad-content) from a directory.
251:
252: To simplify the code and to improve the performance we define:
253:
254: * all images have the same format (e.g. image/png)
255: * all images use increasing numbers starting from 1
256: * a special index-file names the highest number
257:
258: Config ::
259:
260: server.modules += ( "mod_magnet" )
261: magnet.attract-physical-path-to = "random.lua"
262:
263: random.lua ::
264:
265: dir = lighty.env["physical.path"]
266:
267: f = assert(io.open(dir .. "/index", "r"))
268: maxndx = f:read("*all")
269: f:close()
270:
271: ndx = math.random(maxndx)
272:
273: lighty.content = { { filename = dir .. "/" .. ndx }}
274: lighty.header["Content-Type"] = "image/png"
275:
276: return 200
277:
278: denying illegal character sequences in the URL
279: ----------------------------------------------
280:
281: Instead of implementing mod_security, you might just want to apply filters on the content
282: and deny special sequences that look like SQL injection.
283:
284: A common injection is using UNION to extend a query with another SELECT query.
285:
286: ::
287:
288: if (string.find(lighty.env["request.uri"], "UNION%s")) then
289: return 400
290: end
291:
292: Traffic Quotas
293: --------------
294:
295: If you only allow your virtual hosts a certain amount for traffic each month and want to
296: disable them if the traffic is reached, perhaps this helps: ::
297:
298: host_blacklist = { ["www.example.org"] = 0 }
299:
300: if (host_blacklist[lighty.request["Host"]]) then
301: return 404
302: end
303:
304: Just add the hosts you want to blacklist into the blacklist table in the shown way.
305:
306: Complex rewrites
307: ----------------
308:
309: If you want to implement caching on your document-root and only want to regenerate
310: content if the requested file doesn't exist, you can attract the physical.path: ::
311:
312: magnet.attract-physical-path-to = ( server.document-root + "/rewrite.lua" )
313:
314: rewrite.lua ::
315:
316: require "lfs"
317:
318: attr = lfs.attributes(lighty.env["physical.path"])
319:
320: if (not attr) then
321: -- we couldn't stat() the file for some reason
322: -- let the backend generate it
323:
324: lighty.env["uri.path"] = "/dispatch.fcgi"
325: lighty.env["physical.rel-path"] = lighty.env["uri.path"]
326: lighty.env["physical.path"] = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"]
327: fi
328:
329: luafilesystem
330: +++++++++++++
331:
332: We are requiring the lua-module 'lfs' (http://www.keplerproject.org/luafilesystem/).
333:
334: I had to compile lfs myself for lua-5.1 which required a minor patch as compat-5.1 is not needed::
335:
336: $ wget http://luaforge.net/frs/download.php/1487/luafilesystem-1.2.tar.gz
337: $ wget http://www.lighttpd.net/download/luafilesystem-1.2-lua51.diff
338: $ gzip -cd luafilesystem-1.2.tar.gz | tar xf -
339: $ cd luafilesystem-1.2
340: $ patch -ls -p1 < ../luafilesystem-1.2-lua51.diff
341: $ make install
342:
343: It will install lfs.so into /usr/lib/lua/5.1/ which is where lua expects the extensions on my system.
344:
345: SuSE and Gentoo are known to have their own lfs packages and don't require a compile.
346:
347: Usertracking
348: ------------
349:
350: ... or how to store data globally in the script-context:
351:
352: Each script has its own script-context. When the script is started it only contains the lua-functions
353: and the special lighty.* name-space. If you want to save data between script runs, you can use the global-script
354: context:
355:
356: ::
357:
358: if (nil == _G["usertrack"]) then
359: _G["usertrack"] = {}
360: end
361: if (nil == _G["usertrack"][lighty.request["Cookie"]]) then
362: _G["usertrack"][lighty.request["Cookie"]]
363: else
364: _G["usertrack"][lighty.request["Cookie"]] = _G["usertrack"][lighty.request["Cookie"]] + 1
365: end
366:
367: print _G["usertrack"][lighty.request["Cookie"]]
368:
369: The global-context is per script. If you update the script without restarting the server, the context will still be maintained.
370:
371: Counters
372: --------
373:
374: mod_status support a global statistics page and mod_magnet allows to add and update values in the status page:
375:
376: Config ::
377:
378: status.statistics-url = "/server-counters"
379: magnet.attract-raw-url-to = server.docroot + "/counter.lua"
380:
381: counter.lua ::
382:
383: lighty.status["core.connections"] = lighty.status["core.connections"] + 1
384:
385: Result::
386:
387: core.connections: 7
388: fastcgi.backend.php-foo.0.connected: 0
389: fastcgi.backend.php-foo.0.died: 0
390: fastcgi.backend.php-foo.0.disabled: 0
391: fastcgi.backend.php-foo.0.load: 0
392: fastcgi.backend.php-foo.0.overloaded: 0
393: fastcgi.backend.php-foo.1.connected: 0
394: fastcgi.backend.php-foo.1.died: 0
395: fastcgi.backend.php-foo.1.disabled: 0
396: fastcgi.backend.php-foo.1.load: 0
397: fastcgi.backend.php-foo.1.overloaded: 0
398: fastcgi.backend.php-foo.load: 0
399:
400: Porting mod_cml scripts
401: -----------------------
402:
403: mod_cml got replaced by mod_magnet.
404:
405: A CACHE_HIT in mod_cml::
406:
407: output_include = { "file1", "file2" }
408:
409: return CACHE_HIT
410:
411: becomes::
412:
413: content = { { filename = "/path/to/file1" }, { filename = "/path/to/file2"} }
414:
415: return 200
416:
417: while a CACHE_MISS like (CML) ::
418:
419: trigger_handler = "/index.php"
420:
421: return CACHE_MISS
422:
423: becomes (magnet) ::
424:
425: lighty.env["request.uri"] = "/index.php"
426:
427: return lighty.RESTART_REQUEST
428:
429: }}}
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to magnet.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated