~spuul/nginx/trunk

This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.9.4] released on 10 January 2014.

This module embeds Lua, via the standard Lua 5.1 interpreter or [http://luajit.org/luajit.html LuaJIT 2.0/2.1], into Nginx and by leveraging Nginx's subrequests, allows the integration of the powerful Lua threads (Lua coroutines) into the Nginx event model.

* [https://github.com/agentzh/lua-resty-websocket lua-resty-websocket]

* [https://github.com/agentzh/lua-resty-lock lua-resty-lock]

* [https://github.com/agentzh/lua-resty-string lua-resty-string]

== lua_use_default_type ==

'''syntax:''' ''lua_use_default_type on | off''

 

'''default:''' ''lua_use_default_type on''

 

'''context:''' ''http, server, location, location if''

 

Specifies whether to use the MIME type specified by the [http://nginx.org/en/docs/http/ngx_http_core_module.html#default_type default_type] directive for the default value of the <code>Content-Type</code> response header. If you do not want a default <code>Content-Type</code> response header for your Lua request handlers, then turn this directive off.

 

This directive is turned on by default.

 

This directive was first introduced in the <code>v0.9.1</code> release.

 

'''context:''' ''http, server, location, location if''

 

Enables or disables the Lua code cache for Lua code in <code>*_by_lua_file</code> directives (like [[#set_by_lua_file|set_by_lua_file]] and

[[#content_by_lua_file|content_by_lua_file]]) and Lua modules.

 

When turning off, every request served by ngx_lua will run in a separate Lua VM instance, starting from the <code>0.9.3</code> release. So the Lua files referenced in [[#set_by_lua_file|set_by_lua_file]],

and etc will not be cached

and all Lua modules used will be loaded from scratch. With this in place, developers can adopt an edit-and-refresh approach.

[[#access_by_lua|access_by_lua]], and [[#rewrite_by_lua|rewrite_by_lua]] will not be updated when you edit the inlined Lua code in your <code>nginx.conf</code> file because only the Nginx config file parser can correctly parse the <code>nginx.conf</code>

file and the only way is to reload the config file

by sending a <code>HUP</code> signal or just to restart Nginx.

 

Even when the code cache is enabled, Lua files which are loaded by <code>dofile</code> or <code>loadfile</code>

in *_by_lua_file cannot be cached (unless you cache the results yourself). Usually you can either use the [[#init_by_lua|init_by_lua]]

or [[#init-by_lua_file|init_by_lua_file]] directives to load all such files or just make these Lua files true Lua modules

and load them via <code>require</code>.

 

The ngx_lua module does not support the <code>stat</code> mode available with the

Apache <code>mod_lua</code> module (yet).

development as it has a significant negative impact on overall performance. For example, the performance a "hello world" Lua example can drop by an order of magnitude after disabling the Lua code cache.

== lua_regex_match_limit ==

'''syntax:''' ''lua_regex_match_limit <num>''

 

'''default:''' ''lua_regex_match_limit 0''

 

'''context:''' ''http''

 

Specifies the "match limit" used by the PCRE library when executing the [[#ngx.re.match|ngx.re API]]. To quote the PCRE manpage, "the limit ... has the effect of limiting the amount of backtracking that can take place."

 

When the limit is hit, the error string "pcre_exec() failed: -8" will be returned by the [[#ngx.re.match|ngx.re API]] functions on the Lua land.

 

When setting the limit to 0, the default "match limit" when compiling the PCRE library is used. And this is the default value of this directive.

 

This directive was first introduced in the <code>v0.8.5</code> release.

 

'''context:''' ''http''

'''context:''' ''http''

    init_by_lua 'cjson = require "cjson"';

    location /foo {

        set $a 12; # create and initialize $a

        set $b ""; # create and initialize $b

        rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';

        echo "res = $b";

    }

        body_filter_by_lua 'ngx.arg[1] = string.len(ngx.arg[1]) .. "\\n"';

Note that the cosocket connection pool is per nginx worker process rather than per nginx server instance, so size limit specified here also applies to every single nginx worker process.

    local _M = {}

    function _M.foo(a)

        say(a)

 

    return _M

  ngx.HTTP_OPTIONS   (added in the v0.5.0rc24 release)

  ngx.HTTP_MKCOL     (added in the v0.8.2 release)

  ngx.HTTP_COPY      (added in the v0.8.2 release)

  ngx.HTTP_MOVE      (added in the v0.8.2 release)

  ngx.HTTP_PROPFIND  (added in the v0.8.2 release)

  ngx.HTTP_PROPPATCH (added in the v0.8.2 release)

  ngx.HTTP_LOCK      (added in the v0.8.2 release)

  ngx.HTTP_UNLOCK    (added in the v0.8.2 release)

  ngx.HTTP_PATCH     (added in the v0.8.2 release)

  ngx.HTTP_TRACE     (added in the v0.8.2 release)

You should always read the request body (by either calling [[#ngx.req.read_body|ngx.req.read_body]] or configuring [[#lua_need_request_body|lua_need_request_body]] on) before initiating a subrequest.

 

Returns a Lua table with three slots (<code>res.status</code>, <code>res.header</code>, <code>res.body</code>, and <code>res.truncated</code>).

 

<code>res.status</code> holds the response status code for the subrequest response.

<code>res.body</code> holds the subrequest's response body data, which might be truncated. You always need to check the <code>res.truncated</code> boolean flag to see if <code>res.body</code> contains truncated data.

 

* <code>always_forward_body</code>

: when set to true, the current (parent) request's request body will always be forwarded to the subrequest being created if the <code>body</code> option is not specified. The request body read by either [[#ngx.req.read_body|ngx.req.read_body()]] or [[#lua_need_request_body|lua_need_request_body on]] will be directly forwarded to the subrequest without copying the whole request body data when creating the subrequest (no matter the request body data is buffered in memory buffers or temporary files). By default, this option is <code>false</code> and when the <code>body</code> option is not specified, the request body of the current (parent) request is only forwarded when the subrequest takes the <code>PUT</code> or <code>POST</code> request method.

When the <code>body</code> option is not specified and the <code>always_forward_body</code> option is false (the default value), the <code>POST</code> and <code>PUT</code> subrequests will inherit the request bodies of the parent request (if any).

Note that calling this function instead of using <code>ngx.var.request_body</code> or <code>ngx.var.echo_request_body</code> is more efficient because it can save one dynamic memory allocation and one data copy.

'''syntax:''' ''tcpsock, err = ngx.req.socket(raw)''

 

Chunked request bodies are not yet supported in this API.

 

Since the <code>v0.9.0</code> release, this function accepts an optional boolean <code>raw</code> argument. When this argument is <code>true</code>, this function returns a full duplex cosocket object wrapping around the raw downstream connection socket, upon which you can call the [[#tcpsock:receive|receive]], [[#tcpsock:receiveuntil|receiveuntil]], and [[#tcpsock:send|send]] methods.

 

When the <code>raw</code> argument is <code>true</code>, it is required that no pending data from any previous [[#ngx.say|ngx.say]], [[#ngx.print|ngx.print]], or [[#ngx.send_headers|ngx.send_headers]] calls exists. So if you have these downstream output calls previously, you should call [[#ngx.flush|ngx.flush(true)]] before calling <code>ngx.req.socket(true)</code> to ensure that there is no pending output data. If the request body has not been read yet, then this "raw socket" can also be used to read the request body.

 

You can use the "raw request socket" returned by <code>ngx.req.socket(true)</code> to implement fancy protocols like [http://en.wikipedia.org/wiki/WebSocket WebSocket], or just emit your own raw HTTP response header or body data. You can refer to the [https://github.com/agentzh/lua-resty-websocket lua-resty-websocket library] for a real world example.

'''syntax:''' ''ok, err = ngx.send_headers()''

Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.

 

'''syntax:''' ''ok, err = ngx.print(...)''

Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.

 

'''syntax:''' ''ok, err = ngx.say(...)''

'''syntax:''' ''ok, err = ngx.flush(wait?)''

Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*''

It is recommended, though not necessary (for contexts other than [[#header_filter_by_lua|header_filter_by_lua]], to combine the <code>return</code> statement with this call, i.e., <code>return ngx.exit(...)</code>, to give a visual hint to others reading the code.

 

When being used in the context of [[#header_filter_by_lua|header_filter_by_lua]], <code>ngx.exit()</code> is an asynchronous operation and will return immediately. This behavior might change in the future. So always use <code>return</code> at the same time, as suggested above.

'''syntax:''' ''ok, err = ngx.eof()''

Since <code>v0.8.3</code> this function returns <code>1</code> on success, or returns <code>nil</code> and a string describing the error otherwise.

 

'''syntax:''' ''captures, err = ngx.re.match(subject, regex, options?, ctx?, res_table?)''

    U             similar to "u" but disables PCRE's UTF-8 validity check on

                  the subject string. first introduced in ngx_lua v0.8.1.

 

The optional fourth argument, <code>ctx</code>, can be a Lua table holding an optional <code>pos</code> field. When the <code>pos</code> field in the <code>ctx</code> table argument is specified, <code>ngx.re.match</code> will start matching from that offset (starting from 1). Regardless of the presence of the <code>pos</code> field in the <code>ctx</code> table, <code>ngx.re.match</code> will always set this <code>pos</code> field to the position ''after'' the substring matched by the whole pattern in case of a successful match. When match fails, the <code>ctx</code> table will be left intact.

         -- ctx.pos == 5

         -- ctx.pos == 5

Starting from the <code>0.9.4</code> release, this function also accepts a 5th argument, <code>res_table</code>, for letting the caller supply the Lua table used to hold all the capturing results. This table will always be cleared before inserting the resulting capturing data. This is very useful for recycling Lua tables and saving GC and table allocation overhead.

 

== ngx.re.find ==

'''syntax:''' ''from, to, err = ngx.re.find(subject, regex, options?, ctx?, nth?)''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*''

 

Similar to [[#ngx.re.match|ngx.re.match]] but only returns the begining index (<code>from</code>) and end index (<code>to</code>) of the matched substring. The returned indexes are 1-based and can be fed directly into the [http://www.lua.org/manual/5.1/manual.html#pdf-string.sub string.sub] API function to obtain the matched substring.

 

In case of errors (like bad regexes or any PCRE runtime errors), this API function returns two <code>nil</code> values followed by a string describing the error.

 

If no match is found, this function just returns a <code>nil</code> value.

 

Below is an example:

 

<geshi lang="lua">

    local s = "hello, 1234"

    local from, to, err = ngx.re.find(s, "([0-9]+)", "jo")

    if from then

        ngx.say("from: ", from)

        ngx.say("to: ", to)

        ngx.say("matched: ", string.sub(s, from, to))

    else

        if err then

            ngx.say("error: ", err)

            return

        end

        ngx.say("not matched!")

    end

</geshi>

 

This example produces the output

 

    from: 8

    to: 11

    matched: 1234

 

Because this API function does not create new Lua strings nor new Lua tables, it is much faster than [[#ngx.re.match|ngx.re.match]]. It should be used wherever possible.

 

Since the <code>0.9.3</code> release, an optional 5th argument, <code>nth</code>, is supported to specify which (submatch) capture's indexes to return. When <code>nth</code> is 0 (which is the default), the indexes for the whole matched substring is returned; when <code>nth</code> is 1, then the 1st submatch capture's indexes are returned; when <code>nth</code> is 2, then the 2nd submatch capture is returned, and so on. When the specified submatch does not have a match, then two <code>nil</code> values will be returned. Below is an example for this:

 

<geshi lang="lua">

    local str = "hello, 1234"

    local from, to = ngx.re.find(str, "([0-9])([0-9]+)", "jo", nil, 2)

    if from then

        ngx.say("matched 2nd submatch: ", string.sub(str, from, to))  -- yields "234"

    end

</geshi>

 

This API function was first introduced in the <code>v0.9.2</code> release.

 

'''syntax:''' ''dict = ngx.shared[name_var]''

 

* [[#ngx.shared.DICT.get_stale|get_stale]]

In case of errors, <code>nil</code> and a string describing the error will be returned.

 

== ngx.shared.DICT.get_stale ==

'''syntax:''' ''value, flags, stale = ngx.shared.DICT:get_stale(key)''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*''

 

Similar to the [[#ngx.shared.DICT.get|get]] method but returns the value even if the key has already expired.

 

Returns a 3rd value, <code>stale</code>, indicating whether the key has expired or not.

 

Note that the value of an expired key is not guaranteed to be available so one should never rely on the availability of expired items.

 

This method was first introduced in the <code>0.8.6</code> release.

 

See also [[#ngx.shared.DICT|ngx.shared.DICT]].

 

Flushes out all the items in the dictionary. This method does not actuall free up all the memory blocks in the dictionary but just marks all the existing items as expired.

Unlike the [[#ngx.shared.DICT.flush_all|flush_all]] method, this method actually free up the memory used by the expired items.

 

In case of any connection errors, this method always automatically closes the current connection.

 

Since the <code>v0.8.8</code> release, this method no longer automatically closes the current connection when the read timeout error happens. For other connection errors, this method always automatically closes the connection.

 

Since the <code>v0.8.8</code> release, this method no longer automatically closes the current connection when the read timeout error happens. For other connection errors, this method always automatically closes the connection.

 

 

 

 

create new timers with nonzero delays and in that case <code>ngx.timer.at</code> will return <code>nil</code> and

Starting from the <code>v0.9.3</code> release, it is allowed to create zero-delay timers even when the Nginx worker process starts shutting down.

 

[[#ngx.md5|ngx.md5]]/[[#ngx.sha1_bin|ngx.sha1_bin]], are all allowed. But the subrequest API (like

== ngx.config.debug ==

'''syntax:''' ''debug = ngx.config.debug''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, init_by_lua*''

 

This boolean field indicates whether the current Nginx is a debug build, i.e., being built by the <code>./configure</code> option <code>--with-debug</code>.

 

This field was first introduced in the <code>0.8.7</code>.

 

== ngx.config.prefix ==

 

'''syntax:''' ''prefix = ngx.config.prefix()''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, init_by_lua*''

 

Returns the Nginx server "prefix" path, as determined by the <code>-p</code> command-line option when running the nginx executable, or the path specified by the <code>--prefix</code> command-line option when building Nginx with the <code>./configure</code> script.

 

This function was first introduced in the <code>0.9.2</code>.

 

== ngx.config.nginx_version ==

 

'''syntax:''' ''ver = ngx.config.nginx_version''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, init_by_lua*''

 

This field take an integral value indicating the version number of the current Nginx core being used. For example, the version number <code>1.4.3</code> results in the Lua number 1004003.

 

This API was first introduced in the <code>0.9.3</code> release.

 

== ngx.config.ngx_lua_version ==

 

'''syntax:''' ''ver = ngx.config.ngx_lua_version''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, init_by_lua*''

 

This field take an integral value indicating the version number of the current <code>ngx_lua</code> module being used. For example, the version number <code>0.9.3</code> results in the Lua number 9003.

 

This API was first introduced in the <code>0.9.3</code> release.

 

== ngx.worker.exiting ==

 

'''syntax:''' ''exiting = ngx.worker.exiting()''

 

'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*, ngx.timer.*, init_by_lua*''

 

This function returns a boolean value indicating whether the current Nginx worker process already starts exiting. Nginx worker process exiting happens on Nginx server quit or configuration reload (aka HUP reload).

 

This API was first introduced in the <code>0.9.3</code> release.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*, init_by_lua*, ngx.timer.*''

This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.

 

As from the <code>v0.5.0rc32</code> release, all <code>*_by_lua_file</code> configure directives (such as [[#content_by_lua_file|content_by_lua_file]]) support loading Lua 5.1 and LuaJIT 2.0/2.1 raw bytecode files directly.

Please note that the bytecode format used by LuaJIT 2.0/2.1 is not compatible with that used by the standard Lua 5.1 interpreter. So if using LuaJIT 2.0/2.1 with ngx_lua, LuaJIT compatible bytecode files must be generated as shown:

Also, the bytecode files generated by LuaJIT 2.1 is ''not'' compatible with LuaJIT 2.0, and vice versa. The support for LuaJIT 2.1 bytecode was first added in ngx_lua v0.9.3.

 

Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances linked to LuaJIT 2.0/2.1 or vice versa, will result in an error message, such as that below, being logged into the Nginx <code>error.log</code> file:

= System Environment Variable Support =

 

If you want to access the system environment variable, say, <code>foo</code>, in Lua via the standard Lua API [http://www.lua.org/manual/5.1/manual.html#pdf-os.getenv os.getenv], then you should also list this environment variable name in your <code>nginx.conf</code> file via the [http://nginx.org/en/docs/ngx_core_module.html#env env directive]. For example,

 

<geshi lang="nginx">

    env foo;

</geshi>

 

= Statically Linking Pure Lua Modules =

 

When LuaJIT 2.x is used, it is possible to statically link the bytecode of pure Lua modules into the Nginx executable.

 

Basically you use the <code>luajit</code> executable to compile <code>.lua</code> Lua module files to <code>.o</code> object files containing the exported bytecode data, and then link the <code>.o</code> files directly in your Nginx build.

 

Below is a trivial example to demonstrate this. Consider that we have the following <code>.lua</code> file named <code>foo.lua</code>:

 

<geshi lang="lua">

    -- foo.lua

    local _M = {}

 

    function _M.go()

        print("Hello from foo")

    end

 

    return _M

</geshi>

 

And then we compile this <code>.lua</code> file to <code>foo.o</code> file:

 

    /path/to/luajit/bin/luajit -bg foo.lua foo.o

 

What matters here is the name of the <code>.lua</code> file, which determines how you use this module later on the Lua land. The file name <code>foo.o</code> does not matter at all except the <code>.o</code> file extension (which tells <code>luajit</code> what output format is used). If you want to strip the Lua debug information from the resulting bytecode, you can just specify the <code>-b</code> option above instead of <code>-bg</code>.

 

Then when building Nginx or OpenResty, pass the <code>--with-ld-opt="foo.o"</code> option to the <code>./configure</code> script:

 

<geshi lang="bash">

    ./configure --with-ld-opt="/path/to/foo.o" ...

</geshi>

 

Finally, you can just do the following in any Lua code run by ngx_lua:

 

<geshi lang="lua">

    local foo = require "foo"

    foo.go()

</geshi>

 

And this piece of code no longer depends on the external <code>foo.lua</code> file any more because it has already been compiled into the <code>nginx</code> executable.

 

If you want to use dot in the Lua module name when calling <code>require</code>, as in

 

<geshi lang="lua">

    local foo = require "resty.foo"

</geshi>

 

then you need to rename the <code>foo.lua</code> file to <code>resty_foo.lua</code> before compiling it down to a <code>.o</code> file with the <code>luajit</code> command-line utility.

 

It is important to use exactly the same version of LuaJIT when compiling <code>.lua</code> files to <code>.o</code> files as building nginx + ngx_lua. This is because the LuaJIT bytecode format may be incompatible between different LuaJIT versions. When the bytecode format is incompatible, you will see a Lua runtime error saying that the Lua module is not found.

 

When you have multiple <code>.lua</code> files to compile and link, then just specify their <code>.o</code> files at the same time in the value of the <code>--with-ld-opt</code> option. For instance,

 

<geshi lang="bash">

    ./configure --with-ld-opt="/path/to/foo.o /path/to/bar.o" ...

</geshi>

 

If you have just too many <code>.o</code> files, then it might not be feasible to name them all in a single command. In this case, you can build a static library (or archive) for your <code>.o</code> files, as in

 

<geshi lang="bash">

    ar rcus libmyluafiles.a *.o

</geshi>

 

then you can link the <code>myluafiles</code> archive as a whole to your nginx executable:

 

<geshi lang="bash">

    ./configure \

        --with-ld-opt="-L/path/to/lib -Wl,--whole-archive -lmyluafiles -Wl,--no-whole-archive"

</geshi>

 

where <code>/path/to/lib</code> is the path of the directory containing the <code>libmyluafiles.a</code> file. It should be noted that the linker option <code>--whole-archive</code> is required here because otherwise our archive will be skipped because no symbols in our archive are mentioned in the main parts of the nginx executable.

 

    local _M = {}

 

    function _M.get_age(name)

 

    return _M

* Lua's <code>dofile</code> builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0/2.1 and when [[#ngx.location.capture|ngx.location.capture]] is called, [[#ngx.exec|ngx.exec]], [[#ngx.exit|ngx.exit]] or [[#ngx.req.read_body|ngx.req.read_body]] or similar in the file to be loaded by <code>dofile</code>, a coroutine yield across the C function boundary will be initiated. This however is not normally allowed within ngx_lua and will usually result in error messages like <code>lua handler aborted: runtime error: attempt to yield across C-call boundary</code>. To avoid this, define a real Lua module and use the Lua <code>require</code> builtin instead.

* As the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], [[#ngx.redirect|ngx.redirect]], [[#ngx.exec|ngx.exec]], and [[#ngx.exit|ngx.exit]] cannot be used within the context of a Lua [http://www.lua.org/manual/5.1/manual.html#pdf-pcall pcall()] or [http://www.lua.org/manual/5.1/manual.html#pdf-xpcall xpcall()] or even the first line of the <code>for ... in ...</code> statement when the standard Lua 5.1 interpreter is used and the <code>attempt to yield across metamethod/C-call boundary</code> error will be produced. Please use LuaJIT 2.x, which supports a fully resumable VM, to avoid this.

Generally, use of Lua global variables is a really really bad idea in the context of ngx_lua because

# misuse of Lua globals has very bad side effects for concurrent requests when these variables are actually supposed to be local only,

# Lua global variables require Lua table look-up in the global environment (which is just a Lua table), which is kinda expensive, and

# some Lua global variable references are just typos, which are hard to debug.

 

It's *highly* recommended to always declare them via "local" in the scope that is reasonable.

 

To find out all the uses of Lua global variables in your Lua code, you can run the [https://github.com/agentzh/nginx-devel-utils/blob/master/lua-releng lua-releng tool] across all your .lua source files:

<geshi lang="text">

$ lua-releng

Checking use of Lua global variables in file lib/foo/bar.lua ...

        1       [1489]  SETGLOBAL       7 -1    ; contains

        55      [1506]  GETGLOBAL       7 -3    ; setvar

        3       [1545]  GETGLOBAL       3 -4    ; varexpand

The output says that the line 1489 of file <code>lib/foo/bar.lua</code> writes to a global variable named <code>contains</code>, the line 1506 reads from the global variable <code>setvar</code>, and line 1545 reads the global <code>varexpand</code>.

This tool will guarantee that local variables in the Lua module functions are all declared with the <code>local</code> keyword, otherwise a runtime exception will be thrown. It prevents undesirable race conditions while accessing such variables. See [[#Data_Sharing_within_an_Nginx_Worker|Data Sharing within an Nginx Worker]] for the reasons behind this.

== Mixing with SSI Not Supported ==

 

Mixing SSI with ngx_lua in the same Nginx request is not supported at all. Just use ngx_lua exclusively. Everything you can do with SSI can be done atop ngx_lua anyway and it can be more efficient when using ngx_lua.

 

== SPDY Mode Not Fully Supported ==

 

Certain Lua APIs provided by ngx_lua do not work in Nginx's SPDY mode yet: [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], and [[#ngx.req.socket|ngx.req.socket]].

 

The possibilities are unlimited as the module allows bringing together various elements within Nginx as well as exposing the power of the Lua language to the user. The module provides the full flexibility of scripting while offering performance levels comparable with native C language programs both in terms of CPU time as well as memory footprint. This is particularly the case when LuaJIT 2.x is enabled.

* 1.5.x (last tested: 1.5.8)

* 1.4.x (last tested: 1.4.4)

* 1.2.x (last tested: 1.2.9)

The [http://openresty.org ngx_openresty bundle] can be used to install Nginx, ngx_lua, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0/2.1, as well as a package of powerful companion Nginx modules. The basic installation step is a simple <code>./configure --with-luajit && make && make install</code>.

# Install LuaJIT 2.0 or 2.1 (recommended) or Lua 5.1 (Lua 5.2 is ''not'' supported yet). LuajIT can be downloaded from the [http://luajit.org/download.html the LuaJIT project website] and Lua 5.1, from the [http://www.lua.org/ Lua project website].  Some distribution package managers also distribute LuajIT and/or Lua.

    wget 'http://nginx.org/download/nginx-1.5.8.tar.gz'

    tar -xzvf nginx-1.5.8.tar.gz

    cd nginx-1.5.8/

    # tell nginx's build system where to find LuaJIT 2.0:

 

    # tell nginx's build system where to find LuaJIT 2.1:

    export LUAJIT_LIB=/path/to/luajit/lib

    export LUAJIT_INC=/path/to/luajit/include/luajit-2.1

Note that it is recommended to use LuaJIT 2.0 or LuaJIT 2.1 instead of the standard Lua 5.1 interpreter wherever possible.

Everything should be installed correctly, except for one small tweak.

* Nginx version >= 1.4.2

** Test::Nginx: http://github.com/agentzh/test-nginx 

** [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]

** [http://github.com/agentzh/set-misc-nginx-module ngx_set_misc]

** [http://mdounin.ru/files/ngx_http_auth_request_module-0.2.tar.gz ngx_auth_request] (this is not needed if you're using Nginx 1.5.4+.

** [http://github.com/agentzh/echo-nginx-module ngx_echo]

** [http://github.com/agentzh/memc-nginx-module ngx_memc]

** [http://github.com/agentzh/srcache-nginx-module ngx_srcache]

** ngx_lua (i.e., this module)

** [http://github.com/agentzh/headers-more-nginx-module ngx_headers_more]

** [http://github.com/chaoslawful/drizzle-nginx-module ngx_drizzle]

** [http://github.com/agentzh/rds-json-nginx-module ngx_rds_json]

** [https://github.com/FRiCKLE/ngx_coolkit ngx_coolkit]

** [http://github.com/agentzh/redis2-nginx-module ngx_redis2]

 

The order in which these modules are added during configuration is important because the position of any filter module in the

filtering chain determines the final output, for example. The correct adding order is shown above.

 

* 3rd-party Lua libraries:

** [http://www.kyne.com.au/~mark/software/lua-cjson.php lua-cjson]

** memcached: listening on the default port, 11211.

** redis: listening on the default port, 6379.

 

See also the [https://github.com/chaoslawful/lua-nginx-module/blob/master/util/build2.sh developer build script] for more details on setting up the testing environment.

 

To run the whole test suite in the default testing mode:

<geshi lang="text">

    cd /path/to/lua-nginx-module

    export PATH=/path/to/your/nginx/sbin:$PATH

    prove -I/path/to/test-nginx/lib -r t

</geshi>

 

To run specific test files:

<geshi lang="text">

    cd /path/to/lua-nginx-module

    export PATH=/path/to/your/nginx/sbin:$PATH

    prove -I/path/to/test-nginx/lib t/002-content.t t/003-errors.t

</geshi>

 

To run a specific test block in a particular test file, add the line <code>--- ONLY</code> to the test block you want to run, and then use the `prove` utility to run that <code>.t</code> file.

 

There are also various testing modes based on mockeagain, valgrind, and etc. Refer to the [http://search.cpan.org/perldoc?Test::Nginx Test::Nginx documentation] for more details for various advanced testing modes. See also the test reports for the Nginx test cluster running on Amazon EC2: http://qa.openresty.org.

* [http://github.com/agentzh/lua-resty-websocket lua-resty-websocket] library for both WebSocket server and client, based on ngx_lua cosocket.

* [http://github.com/agentzh/lua-resty-lock lua-resty-lock] library for a nonblocking simple lock API.

* [https://github.com/agentzh/nginx-systemtap-toolkit Nginx Systemtap Toolkit]