From: Daniel Gruno Date: Wed, 8 Aug 2012 19:16:12 +0000 (+0000) Subject: Updates: X-Git-Tag: 2.5.0-alpha~6460 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=4881ce1229a92d663f2b32753bd334764eb3daa7;p=thirdparty%2Fapache%2Fhttpd.git Updates: - Remove reference to functions that are now inside mod_lua - Remove a lot of "bla bla bla" placeholders - Add information about optimizing mod_lua for production use - Fix up the examples a bit git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1370899 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/developer/lua.xml b/docs/manual/developer/lua.xml index 4aee28f9969..c379d0c945f 100644 --- a/docs/manual/developer/lua.xml +++ b/docs/manual/developer/lua.xml @@ -44,13 +44,11 @@ Stuff about what mod_lua is goes here.
What we will be discussing in this document

-This document will discuss how you can bla bla bla. -In the first chapter, we will bla bla +This document will discuss several cases where mod_lua can be used +to either ease up a phase of the request processing or create more transparency in +the logic behind a decision made in a phase.

-

-In the second part of this document, we will be looking at bla bla bla -

Prerequisites @@ -65,12 +63,88 @@ and whys of various function calls.
-
Enabling mod_lua +
+ +
Optimizing mod_lua for production servers +
Setting a scope for Lua states +

+Setting the right LuaScope setting +for your Lua scripts can be essential to your server's +performance. By default, the scope is set to once, which means +that every call to a Lua script will spawn a new Lua state that handles that +script and is destroyed immediately after. This option keeps the memory +footprint of mod_lua low, but also affects the processing speed of a request. +If you have the memory to spare, you can set the scope to thread, +which will make mod_lua spawn a Lua state that lasts the entirity of a thread's +lifetime, speeding up request processing by 2-3 times. Since mod_lua will create +a state for each script, this may be an expensive move, memory-wise, so to +compromise between speed and memory usage, you can choose the server +option to create a pool of Lua states to be used. Each request for a Lua script or +a hook function will then acquire a state from the pool and release it back when it's +done using it, allowing you to still gain a significant performance increase, while +keeping your memory footprint low. Some examples of possible settings are: +

-LoadModule lua_module modules/mod_lua.so +LuaScope once +LuaScope thread +LuaScope server 5 40 +

+As a general rule of thumb: If your server has none to low usage, use once +or request, if your server has low to medium usage, use the server +pool, and if it has high usage, use the thread setting. As your server's +load increases, so will the number of states being actively used, and having your scope +set to once/request/conn will stop being beneficial to your memory footprint. +

+

+Note: The min and max settings for the +server scope denotes the minimum and maximum states to keep in a pool per +server process, so keep this below your ThreadsPerChild limit. +

+
+
Using code caching +

+By default, mod_lua stats each Lua script to determine whether a reload +(and thus, a re-interpretation and re-compilation) of a script is required. This is managed +through the LuaCodeCache directive. If you are running +your scripts on a production server, and you do not need to update them regularly, it may be +advantageous to set this directive to the forever value, which will cause mod_lua +to skip the stat process and always reuse the compiled byte-code from the first access to the +script, thus speeding up the processing. For Lua hooks, this can prove to increase peformance, +while for scripts handled by the lua-script handler, the increase in performance +may be negligible, as files httpd will stat the files regardless. +

+
+ +
Keeping the scope clean +

+For maximum performance, it is generally recommended that any initialization of libraries, +constants and master tables be kept outside the handle's scope: +

+ +--[[ This is good practice ]]-- +require "string" +require "someLibrary" +local masterTable = {} +local constant = "Foo bar baz" + +function handle(r) + do_stuff() +end + + +--[[ This is bad practice ]]-- +require "string" + +function handle(r) + require "someLibrary" + local masterTable = {} + local constant = "Foo bar baz" + do_stuff() +end +
@@ -92,8 +166,6 @@ LuaHookTranslateName /path/too/foo.lua remap This example will rewrite /foo/test.bar to the physical file /internal/test, somewhat like how mod_alias works. ]]-- -require 'apache2' -require 'string' function remap(r) -- Test if the URI matches our criteria @@ -115,8 +187,6 @@ end remap a file to one of two destinations, using a rewrite map. ]]-- -require 'apache2' -require 'string' local map = { photos = { @@ -181,8 +251,6 @@ LuaHookTranslateName /path/too/foo.lua mass_vhost This example will check a map for a virtual host and rewrite filename and document root accordingly. ]]-- -require 'apache2' -require 'string' local vhosts = { { domain = "example.com", home = "/www/example.com" }, @@ -216,8 +284,6 @@ end 60 seconds before checking for updates. For best performance, such scripts should generally be run with LuaScope set to 'thread' or 'server' ]]-- -require 'apache2' -require 'string' local cached_vhosts = {} local timeout = 60 @@ -273,9 +339,10 @@ LuaHookAuthChecker /path/too/foo.lua check_auth -require 'apache2' -require 'string' - +--[[ + A simple authentication hook that checks a table containing usernames and + passwords of two accounts. +]]-- local accounts = { bob = 'somePassword', jane = 'Iloveponies' @@ -314,10 +381,10 @@ end --- An advanced authentication checker with a database backend, --- caching account entries for 1 minute -require 'apache2' -require 'string' +--[[ + An advanced authentication checker with a database backend, + caching account entries for 1 minute +]]-- local timeout = 60 -- Set account info to be refreshed every minute local accounts = {} @@ -390,6 +457,12 @@ LuaAuthzProvider rights /path/to/lua/script.lua rights_handler +--[[ + This script has two user groups; members and admins, and whichever + is refered to by the "Require rights" directive is checked to see + if the authenticated user belongs to this group. +]]-- + local members = { "rbowen", "humbedooh", "igalic", "covener" } local admins = { "humbedooh" } @@ -431,9 +504,6 @@ LuaMapHandler ^/portal/([a-z]+)/ /path/to/lua/script.lua handle_$1 - - -
HTTPd bindings: String manipulation

@@ -814,28 +884,14 @@ print(unescaped) -- prints "This is a test"

HTTPd bindings: Request handling

-apache2.sendfile -
-apache2.port -
-apache2.options -
-apache2.allowoverrides -
apache2.requestbody
apache2.add_input_filter
apache2.get_basic_auth_pw
-apache2.get_limit_req_body -
-apache2.request_has_body -
apache2.set_document_root
-apache2.some_auth_required -
apache2.set_context_prefix
apache2.get_server_name_for_url @@ -844,18 +900,8 @@ print(unescaped) -- prints "This is a test"
apache2.make_etag
-apache2.flush -
apache2.send_interim_response
-apache2.get_server_name -
-apache2.auth_type -
-apache2.auth_name -
-apache2.satisfies -

apache2.add_input_filter( @@ -890,129 +936,6 @@ apache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..? </highlight> <p> </p> </section> -<section id="apache2.allowoverrides"> -<title>apache2.allowoverrides( - request_rec<em> r</em> - ) - -

-Returns the currently allowed overrides for this context (AuthCfg, Options etc) -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The currently allowed overrides for this context (AuthCfg, Options etc) -

-

-Example: -

- -local ctx = apache2.allowoverrides(r) -if ctx:match("AuthCfg") then - r:puts("You are allowed to override AuthCfg stuff in your .htaccess") -end - -

 

-
-
-apache2.auth_name( - request_rec<em> r</em> - ) - -

-Returns the current Authorization realm -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The current authorization realm -

-

 

-
-
-apache2.auth_type( - request_rec<em> r</em> - ) - -

-Returns the current authentication type used in the request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The current Authorization type used in the request -

-

 

-
-
-apache2.flush( - request_rec<em> r</em> - ) - -

-Flushes the content buffer, writing everything to the client immediately. -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Example: -

- -r:puts("This is buffered") -apache2.flush(r) -- now it's written to the client. - -

 

-
apache2.get_basic_auth_pw( request_rec<em> r</em> @@ -1041,76 +964,6 @@ The password from a basic authorization request or nil if none was supplied </p> <p> </p> </section> -<section id="apache2.get_limit_req_body"> -<title>apache2.get_limit_req_body( - request_rec<em> r</em> - ) - -

-Returns the current request body size limit -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The current request body size limit -

-

-Example: -

- -local limit = apache2.get_limit_req_body(r) -r:puts("You can't upload files bigger than ", limit, " bytes!") - -

 

-
-
-apache2.get_server_name( - request_rec<em> r</em> - ) - -

-Returns the current server name from the request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The server name -

-

-Example: -

- -local name = apache2.get_server_name(r) -r:puts("The ServerName is set to: ", name) - -

 

-
apache2.get_server_name_for_url( request_rec<em> r</em> @@ -1167,114 +1020,6 @@ The entity tag </p> <p> </p> </section> -<section id="apache2.options"> -<title>apache2.options( - request_rec<em> r</em> - ) - -

-Returns the currently allowed options for this context (Indexes, MultiViews etc) -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The currently allowed options for this context. -

-

-Example: -

- -local ctx = apache2.options(r) -if ctx:match("MultiViews") then - r:puts("MultiViews is enabled!") -end - -

 

-
-
-apache2.port( - request_rec<em> r</em> - ) - -

-Returns the port currently being used by the request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The current port used by the request -

-

-Example: -

- -local port = apache2.port(r) -r:puts("We are listening on port ", port) - -

 

-
-
-apache2.request_has_body( - request_rec<em> r</em> - ) - -

-Returns true if the request has a body(POST/PUT), false otherwise -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-True if the request has a body(POST/PUT), false otherwise -

-

-Example: -

- -if apache2.request_has_body(r) then - -- do stuff with the req body -end - -

 

-
apache2.requestbody( request_rec<em> r</em>,  number<em> size</em>,  string<em> filename</em> @@ -1323,43 +1068,6 @@ end </highlight> <p> </p> </section> -<section id="apache2.satisfies"> -<title>apache2.satisfies( - request_rec<em> r</em> - ) - -

-Returns how the requires lines must be met. -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-How the requirements must be met (SATISFY_ANY, SATISFY_ALL, SATISFY_NOSPEC). -

-

-Example: -

- -local how = apache2.satisfies(r) -if how == "SATISFY_ANY" then - -- ... -end - -

 

-
apache2.send_interim_response( request_rec<em> r</em>,  boolean<em> send_headers</em> @@ -1393,39 +1101,6 @@ apache2.send_interim_response(r, false) </highlight> <p> </p> </section> -<section id="apache2.sendfile"> -<title>apache2.sendfile( - request_rec<em> r</em>,  string<em> filename</em> - ) - -

-Sends a file to the client via sendfile() if possible. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
filenameThe file to send
-

-Example: -

- -apache2.sendfile(r, "/foo/bar/test.png") -- sends /foo/bar/test.png via sendfile - -

 

-
apache2.set_context_prefix( request_rec<em> r</em>,  string<em> prefix</em>,  string<em> document</em> @@ -1521,42 +1196,6 @@ True if keepalive can be set, false otherwise </p> <p> </p> </section> -<section id="apache2.some_auth_required"> -<title>apache2.some_auth_required( - request_rec<em> r</em> - ) - -

-Returns true if authorization is required for this request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-True if auth is required, false if not. -

-

-Example: -

- -if apache2.some_auth_required(r) then - print("debug: auth is required for this request\n") -end - -

 

-
@@ -1705,8 +1344,6 @@ end

apache2.add_version_component
-apache2.banner -
apache2.mpm_query
apache2.terminate @@ -1715,14 +1352,8 @@ end
apache2.scoreboard_worker
-apache2.started -
apache2.module_info
-apache2.get_server_built -
-apache2.is_initial_req -
apache2.loaded_modules
apache2.runtime_dir_relative @@ -1771,25 +1402,6 @@ end

 

-
-apache2.banner( - - ) - -

-Returns the server banner -

-

-Arguments: -

-

None

-

-Return value(s): -
-The server banner -

-

 

-
apache2.custom_response( request_rec<em> r</em>,  number<em> status</em>,  string<em> string</em> @@ -1858,53 +1470,6 @@ end </highlight> <p> </p> </section> -<section id="apache2.get_server_built"> -<title>apache2.get_server_built( - - ) - -

-Returns the date the server was built -

-

-Arguments: -

-

None

-

-Return value(s): -
-The date the server was built -

-

 

-
-
-apache2.is_initial_req( - request_rec<em> r</em> - ) - -

-Returns true if this is the main request, false if it is a sub-request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-True if this is the main request, false if it is a sub-request -

-

 

-
apache2.loaded_modules( @@ -2103,34 +1668,6 @@ A table with information about the server program </p> <p> </p> </section> -<section id="apache2.started"> -<title>apache2.started( - request_rec<em> r</em> - ) - -

-Returns the time when the server was (re)started -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The time when the server was (re)started -

-

 

-
apache2.state_query( number<em> field</em> @@ -2412,4 +1949,6 @@ r:puts("delayed") <p> </p> </section> </section> + + </manualpage>