LoadModule lua_module modules/mod_lua.so
AddModule mod_lua.c
<IfModule mod_lua.c>
LuaPath "conf/lua/handlers/?.lua"
LuaRequire httpd run
<Files *.lua>
SetHandler lua-script
LuaHandlerResponse run
</Files>
# The Files directive may to be replaced by:
#AddHandler lua-script .lua
#LuaHandlerResponse run
</IfModule>
LuaPath path-to-Lua-require LuaPath "conf/lua/handlers/?.lua"LuaPath directive modify LUA_PATH global variable in global lua_State of mod_lua. See Lua manual for a syntax description from LUA_PATH. The default value is "?;?.lua".
The virtual host context is "ignored", because only exists one global lua_State in mod_lua. :)
The recomended use is or only a LuaPath in server config or set a LuaPath on end of config file to allow the future requires by global lua_State in mod_lua.
LuaRequire package1 [package ...] LuaRequire httpd runThis directive are used to load Lua packages and files from disk. This is implemented using Lua built-in require function.
The "httpd" package must be loaded and should be the first. The httpd package offers some interfaces from Apache for other packages.
The packages are loaded in the order and LUA_PATH is used to find the respective file.
In mod_lua's currently implementation, doesn't exist mutiples lua_State in Apache, therefore a Lua module loaded in a virtual host is visible for all server. See here the packages currently available in for Lua.
VERY IMPORTANT: the start code from package is executed as root!
LuaHandler* Lua-handler [Lua-handler ...] LuaHandlerResponse runTheses directives assign one or more Lua-handlers for a Apache event. The "*" must be filled with a event name. The package of handler must be loaded before with LuaRequire.
The form of Lua-handler is: name {"." name} . Or using Perl's regex: /^[a-zA-Z_][0-9a-zA-Z_]*(\.[a-zA-Z_][0-9a-zA-Z_]*)*$/ .
If Lua-handler is a table, mod_lua find the "handler" key on this table. Lua-handler must be a Lua function. See prototype this function on handler enviroment.
The Lua-handlers are caller in the order, but this feature is experimental in currency version, only one handler should used today. The LuaPath and LuaRequire directives must load the packages before LuaHandler* to be used.
The post_read_request handler is called every time an Apache process receives an incoming request, at the point at which the server has read the incoming request's data and parsed the HTTP header fields but before the server has translated the URI to a filename.
Is is called once per transaction and is intended to allow modules to step in and perform special processing on the incoming data. However, because there's no way for modules to step in and actually contribute to the parsing of the HTTP header, this phase is more often used just as a convenient place to do processing that must occour once per transaction.
All post_read_request handlers will be called unless one aborts by returning an error code or terminating the phase with DONE.
The uri_translate handler is invoked after Apache has parsed out the request. Its job is to take the request, which is in the form of a partial URI, and transform it into a filename.
The handler can also step in to alter the URI itself, to change the request method, or to install new handlers based on the URI. The URI translation phase is often used to recognize and handle proxy requests.
Apache will walk through the registered uri_translate handlers until one returns a status other than DECLINED. This is in contrast to most of the other phases, for which Apache will continue to invoke registered handlers even after one has returned OK.
After the URI translation phase, Apache again gives you another chance to examine the request headers and to take special action in the header_parser phase. Unlike the post_read_request phase, at this point the URI has been mapped to a physical pathname. Therefore PerlHandlerHeaderParser is the first handler directive that has directory context.
The header_parser phase is free to examine and change request fields in the HTTP header, or even to abort the transaction entirely. For this reason, it's common to use this phase to block abusive robots before they start chewing into the resources that may be required in the phases that follow. All registered header_parser handlers will be unless one returns an error code or DONE.
The access_checker handler is the first of three handlers that are invoked in authentication and authorization.
The access_checker handler is designed to do simple acess control based on the browser's IP address, hostname, phase of the moon, or other aspects of the transation that have nothing to do with the remote user's identity.
The handler is expected to return OK to allow the transaction to continue, FORBIDDEN to abort the transaction with an unauthorized access error, or DECLINED to punt the decision to the next handler. Apache will continue to step through all registered access handlers until one returns a code other than DECLINED or OK.
The authentication handler (sometimes referred to in the Apache documentation as check_user_id) is called whenever the request file or directory is password-protected. This, in turn, requires that the directory be associated with AuthName, AuthType, and at least one require directive.
It is the job of the authentication handler to check a user's identification credentials, usually by checking the username and password against a database.
If the credentials check out, the handler should return OK. Otherwise the handler returns AUTH_REQUIRED to indicate that the user has not authenticated successfully. When Apache sends the HTTP header with code, the browser will normally pop up a dialog box that prompts the user for login information.
Apache will call all registered authentication handlers, only ending the phase after the last handler has had a chance to weigh in on the decision or when a handler aborts the transaction by returning AUTH_REQUIRED or another error code. As usual, handlers may also return DECLINED to defer the decision to the next handler in line.
Provided that the authentication handler has sucessfully verifed the user's identify, the transaction passes into the authorization handler, where the server determines whether the authenticated user is authorized to access the requested URI. This is often used in conjunction with databases to restrict acess to a document based on the user's membership in a particular group. However, the authorization handler can base its decision on anything that can be derived from the user's name, such as the user's position in an organizational chart or the user's gender.
Handlers for the authorization phase are only called when the file or directory is password-protected, using the same criteria described earlier for authentication. The handler is expected to return DECLINED to defer the decision, OK to indicate its acceptance of the user's authorization, or AUTH_REQUIRED to indicate that the user is not authorizes to access the required document.
Like the authentication hanlder, Apache will try all tre authorization handlers in turn until one returns AUTH_REQUIRED or another error code.
After the optional access control and authentication phases, Apache enters the type_checker phase. It is the responsibility of the type_checker handler to assign a provisional MIME type to the requested document. The assigned MIME type will be taken into consideration when Apache decides what content handler to call to generate the body of the document.
Because content handler are free to change the MIME type of the documents they process, the MIME type chosen during the type checking phase is not necessarily the same MIME type the is ultimately sent to the browser. The type checker is also used by Apache's automatic directory indexing routines to decide what icon to display next to the filename.
The default Apache type checker generally just looks up the filename extension in a table of MIME types. By declaring a custom type checker, you can replace this with something more sophisticated, such as looking up the file's MIME type in a document management database.
Because it makes no sense to have multiple handlers trying to set the MIME type of a file acording to different sets of rules, the type checker handlers behave like content handlers and URI translation handlers. apache steps through eaxh registered handler in turn until one returns OK or aborts with an error code. The phase finishes as soon as one module indicates thatit has successfully handled the transaction
After the type_checker phase but before the content handling phase is an od beast called the fixup phase. This phase is a chance to make any last-minute changes to the tansaction before the response is sent. The fixup handles's job is like that of the restaurant prep cook who gets all the ingredients cut, sorted, and put in their proper places before the chef goes to work. An example alluded to earlier, mod_env defines a fixup handler to add variables to the enviroment from configured SetEnv and PassEnv directives. These variables are put to use by several different modules in the upcoming response phase, including mod_cig, mod_include , mod_pearl.
All fixup handlers are run during an HTTP request, stopping only when a module aborts with an error code.
The next step is the content generation, or response phase, installed by the generic-sounding LuaHandlerResponse directive. Because of its importance, probably 90 percent of the modules you'll write will handle this part of the transaction. the content handler is the master chef of the Apache kitchen, taking all the ingredients assembled by the previous phases-the URI, the translated pathname, the provisional MIME type, and the parsed HTTP headers-ihpping them up into a tasty document and serving the result to the browser.
There can be only one master chef in a kitchen, and so it is with Apache content handlers. If multiple modules have registered their desire to de the content handler for a request, Apache will try them each in turn until one returns OK or aborts the tansaction with an error code. If a handler returns DECLINED, Apache moves on to the next module in the list.
The mod_lua relaxes this restriction somewhat, allowing several content handlers to collaborate to build up a composite document using a technique called "chaining".
Just before entering the cleanup phase, the log handler will be called in the logging phase. This is true regardless of wheather the transaction was successfully completed or was aborted somewhere along the way with an error. Everything known about the transaction, including the original request, the translated name, the MIME type, the number of bytes sent and received, the length of time the transaction took, and the status code returned by the last handler to be called, is passed to the log handler in the request record. The handler typically records the information in some way, either by writting information into a relational database. Log handlers can of course do whatever they like with the information, such as keeping a running total of the number of bytes transferred and throwing out the rest.
All registered log handlers are called in turn, even after one of them returns OK. If a log handler returns HTTP error status, it and all the log handlers that ordinaly follow it, including the built-in ones, will be aborted. This should be avoided unless you really want to prevent some transactions frim being logged.