8
8
This module is under active development and is production ready.
11
This document describes ngx_lua v0.5.0rc24
12
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 18
11
This document describes ngx_lua v0.5.0rc28
12
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 16
16
16
# set search paths for pure Lua external libraries (';;' is the default path):
183
This module embeds Lua, via the standard interpreter or LuaJIT, into
184
Nginx and by leveraging Nginx subrequests, allows the integration of the
185
powerful Lua threads ( Lua coroutines) into the Nginx event model.
183
This module embeds Lua, via the standard Lua interpreter or LuaJIT, into
184
Nginx and by leveraging Nginx's subrequests, allows the integration of
185
the powerful Lua threads (Lua coroutines) into the Nginx event model.
187
187
Unlike Apache's mod_lua
188
188
(<http://httpd.apache.org/docs/2.3/mod/mod_lua.html>) and Lighttpd's
189
189
mod_magnet (<http://redmine.lighttpd.net/wiki/1/Docs:ModMagnet>), Lua
190
190
code executed using this module can be *100% non-blocking* on network
191
traffic as long as either of the ngx.location.capture or
192
ngx.location.capture_multi interfaces are used to handle requests to
193
upstream services such as mysql, postgresql, memcached, redis, or
194
upstream http web services. (see [[HttpDrizzleModule]], ngx_postgres
191
traffic as long as the Nginx API for Lua provided by this module is used
192
to handle requests to upstream services such as mysql, postgresql,
193
memcached, redis, or upstream http web services. (See
194
ngx.location.capture, ngx.location.capture_multi, ngx.socket.tcp,
195
[[HttpDrizzleModule]], ngx_postgres
195
196
(<http://github.com/FRiCKLE/ngx_postgres/>), [[HttpMemcModule]],
196
197
[[HttpRedis2Module]] and [[HttpProxyModule]] modules for details).
198
199
The Lua interpreter or LuaJIT instance is shared across all the requests
199
200
in a single nginx worker process but request contexts are segregated
200
using lightweight Lua coroutines. Loaded Lua modules persist at the
201
using lightweight Lua coroutines. Loaded Lua modules persist in the
201
202
nginx worker process level resulting in a small memory footprint even
202
203
when under heavy loads.
217
218
access_by_lua_file, and rewrite_by_lua_file will not be cached and the
218
219
Lua "package.loaded" table will be cleared at the entry point of every
219
220
request (such that Lua modules will not be cached either). With this in
220
place, developers can adopt an edit and refresh approach.
221
place, developers can adopt an edit-and-refresh approach.
222
223
Please note however, that Lua code inlined into nginx.conf such as those
223
224
specified by set_by_lua, content_by_lua, access_by_lua, and
251
252
(i.e., compile-once flag) is specified.
253
254
The default number of entries allowed is 1024 and when this limit is
254
reached, new regexes will not be cached (as if the "o" option was not
255
specified) and there will be one, and only one, warning in the
255
reached, new regular expressions will not be cached (as if the "o"
256
option was not specified) and there will be one, and only one, warning
257
in the "error.log" file:
258
259
2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex cache max entries (1024), ...
260
Do not activate the "o" option for regexes (and/or "replace" string
261
arguments for ngx.re.sub and ngx.re.gsub) that are generated *on the
262
fly* and give rise to infinite variations to avoid hitting the specified
261
Do not activate the "o" option for regular expressions (and/or "replace"
262
string arguments for ngx.re.sub and ngx.re.gsub) that are generated *on
263
the fly* and give rise to infinite variations to avoid hitting the
266
267
syntax: *lua_package_path <lua-style-path-str>*
273
274
Sets the Lua module search path used by scripts specified by set_by_lua,
274
275
content_by_lua and others. The path string is in standard Lua path form,
275
and ";;" can be used to stand for the original path.
276
and ";;" can be used to stand for the original search paths.
278
Since the "v0.5.0rc29" release, the special notation $prefix or
279
"${prefix}" can be used in the search path string to indicate the path
280
of the "server prefix" usually determined by the "-p PATH" command-line
281
option while starting the Nginx server.
277
283
lua_package_cpath
278
284
syntax: *lua_package_cpath <lua-style-cpath-str>*
280
default: *The content of LUA_CPATH environ variable or Lua's compiled-in
286
default: *The content of LUA_CPATH environment variable or Lua's
287
compiled-in defaults.*
286
292
set_by_lua, content_by_lua and others. The cpath string is in standard
287
293
Lua cpath form, and ";;" can be used to stand for the original cpath.
295
Since the "v0.5.0rc29" release, the special notation $prefix or
296
"${prefix}" can be used in the search path string to indicate the path
297
of the "server prefix" usually determined by the "-p PATH" command-line
298
option while starting the Nginx server.
290
301
syntax: *set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]*
306
317
Note that I/O operations such as ngx.say, ngx.exec, echo and similar are
307
318
not permitted within the context of this directive.
309
In addition, note that this directive can only output a value to a
320
In addition, note that this directive can only write out a value to a
310
321
single Nginx variable at a time. However, a workaround is possible using
311
322
the ngx.var.VARIABLE interface.
333
344
set_by_lua $bar 'tonumber(ngx.var.foo) + 1';
334
345
set $baz "bar: $bar"; # $baz == "bar: 33"
347
Since the "0.5.0rc29" release, Nginx variable interpolation is disabled
348
in the "<lua-script-str>" argument of this directive, and you can use
349
the dollar sign character ("$") directly.
336
351
This directive requires the ngx_devel_kit
337
352
(<https://github.com/simpl/ngx_devel_kit>) module.
347
362
Equivalent to set_by_lua, except that the file specified by
348
"<path-to-lua-script-file>" contains the lua code to be executed.
350
When the Lua code cache is on (default state), the user code is loaded
351
once at the first request and cached and the Nginx config must be
363
"<path-to-lua-script-file>" contains the Lua code to be executed.
365
Nginx variable interpolation is supported in the
366
"<path-to-lua-script-file>" argument string of this directive. But
367
special care must be taken for injection attacks.
369
When a relative path like "foo/bar.lua" is given, they will be turned
370
into the absoluate path relative to the "server prefix" path determined
371
by the "-p PATH" command-line option while starting the Nginx server.
373
When the Lua code cache is turned on (by default), the user code is
374
loaded once at the first request and cached and the Nginx config must be
352
375
reloaded each time the Lua source file is modified. The Lua code cache
353
376
can be temporarily disabled during development by switching
354
377
lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.
366
Acts as a "content handler" and executes lua code string specified in
367
"<lua-script-str>" for every request. The lua code may make API calls
389
Acts as a "content handler" and executes Lua code string specified in
390
"<lua-script-str>" for every request. The Lua code may make API calls
368
391
and is executed as a new spawned coroutine in an independent global
369
392
environment (i.e. a sandbox).
382
405
Equivalent to content_by_lua, except that the file specified by
383
"<path-to-lua-script-file>" contains the lua code to be executed.
406
"<path-to-lua-script-file>" contains the Lua code to be executed.
385
408
Nginx variables can be used in the "<path-to-lua-script-file>" string to
386
409
provide flexibility. This however carries some risks and is not
387
410
ordinarily recommended.
389
When the Lua code cache is on (default state), the user code is loaded
390
once at the first request and cached and the Nginx config must be
412
When a relative path like "foo/bar.lua" is given, they will be turned
413
into the absoluate path relative to the "server prefix" path determined
414
by the "-p PATH" command-line option while starting the Nginx server.
416
When the Lua code cache is turned on (by default), the user code is
417
loaded once at the first request and cached and the Nginx config must be
391
418
reloaded each time the Lua source file is modified. The Lua code cache
392
419
can be temporarily disabled during development by switching
393
420
lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.
430
457
? echo "res = $b";
433
because "if" runs *before* rewrite_by_lua even if it is put after
460
because "if" runs *before* rewrite_by_lua even if it is placed after
434
461
rewrite_by_lua in the config.
436
463
The right way of doing this is as follows:
508
535
Here the Lua code "ngx.exit(503)" will never run. This will be the case
509
536
if "rewrite ^ /bar last" is used as this will similarly initiate an
510
537
internal redirection. If the "break" modifier is used instead, there
511
will be no internal rediction and the rewrite_by_lua code will be
538
will be no internal redirection and the rewrite_by_lua code will be
514
541
rewrite_by_lua_file
525
552
provide flexibility. This however carries some risks and is not
526
553
ordinarily recommended.
528
When the Lua code cache is on (default state), the user code is loaded
529
once at the first request and cached and the Nginx config must be
555
When a relative path like "foo/bar.lua" is given, they will be turned
556
into the absoluate path relative to the "server prefix" path determined
557
by the "-p PATH" command-line option while starting the Nginx server.
559
When the Lua code cache is turned on (by default), the user code is
560
loaded once at the first request and cached and the Nginx config must be
530
561
reloaded each time the Lua source file is modified. The Lua code cache
531
562
can be temporarily disabled during development by switching
532
563
lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.
539
570
phase: *access tail*
541
Acts as an access phase handler and executes lua code string specified
572
Acts as an access phase handler and executes Lua code string specified
542
573
in "<lua-script-str>" for every request. The Lua code may make API calls
543
574
and is executed as a new spawned coroutine in an independent global
544
575
environment (i.e. a sandbox).
619
650
provide flexibility. This however carries some risks and is not
620
651
ordinarily recommended.
622
When the Lua code cache is on (default state), the user code is loaded
623
once at the first request and cached and the Nginx config must be
653
When a relative path like "foo/bar.lua" is given, they will be turned
654
into the absoluate path relative to the "server prefix" path determined
655
by the "-p PATH" command-line option while starting the Nginx server.
657
When the Lua code cache is turned on (by default), the user code is
658
loaded once at the first request and cached and the Nginx config must be
624
659
reloaded each time the Lua source file is modified. The Lua code cache
625
660
can be temporarily disabled during development by switching
626
661
lua_code_cache "off" in "nginx.conf" to avoid repeatedly reloading
662
697
phase: *output-header-filter*
664
699
Equivalent to header_filter_by_lua, except that the file specified by
665
"<path-to-lua-script-file>" contains the lua code to be executed.
700
"<path-to-lua-script-file>" contains the Lua code to be executed.
702
When a relative path like "foo/bar.lua" is given, they will be turned
703
into the absoluate path relative to the "server prefix" path determined
704
by the "-p PATH" command-line option while starting the Nginx server.
667
706
This directive was first introduced in the "v0.2.1rc20" release.
799
838
This buffer does not have to be that big to hold everything at the same
800
839
time because cosocket supports 100% non-buffered reading and parsing. So
801
840
even 1 byte buffer size should still work everywhere but the performance
804
843
This directive was first introduced in the "v0.5.0rc1" release.
867
906
This directive is turned "on" by default.
869
THis directive was first introduced in the "v0.5.0rc19" release.
908
This directive was first introduced in the "v0.5.0rc19" release.
910
rewrite_by_lua_no_postpone
911
syntax: *rewrite_by_lua_no_postpone on|off*
913
default: *rewrite_by_lua_no_postpone off*
915
context: *http, server, location, location-if*
917
Controls whether or not to disable postponing rewrite_by_lua and
918
rewrite_by_lua_file directives to run at the end of the "rewrite"
919
request-processing phase. By default, this directive is turned off and
920
the Lua code is postponed to run at the end of the "rewrite" phase.
922
This directive was first introduced in the "v0.5.0rc29" release.
871
924
Nginx API for Lua
910
963
relatively small amount of data can be done using the standard Lua "io"
911
964
library but huge file reading and writing should be avoided wherever
912
965
possible as they may block the Nginx process significantly. Delegating
913
all network and disk I/O operations to Nginx subrequests (via the
966
all network and disk I/O operations to Nginx's subrequests (via the
914
967
ngx.location.capture method and similar) is strongly recommended for
915
968
maximum performance.
1058
1111
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1059
1112
header_filter_by_lua**
1061
Writes "ngx.NOTICE" log level arguments prefixed with "lua print:" to
1062
the nginx "error.log" file.
1114
Writes argument values into the nginx "error.log" file with the
1115
"ngx.NOTICE" log level.
1064
1117
It is equivalent to
1066
ngx.log(ngx.NOTICE, 'lua print: ', a, b, ...)
1119
ngx.log(ngx.NOTICE, ...)
1068
1121
Lua "nil" arguments are accepted and result in literal "nil" strings
1069
1122
while Lua booleans result in literal "true" or "false" strings. And the
1164
1217
rather than the original "hello" value.
1166
1219
Arbitrary data values, including Lua closures and nested tables, can be
1167
inserted into this "matic" table. It also allows the registration of
1220
inserted into this "magic" table. It also allows the registration of
1168
1221
custom meta methods.
1170
1223
Overriding "ngx.ctx" with a new Lua table is also supported, for
1180
1233
Issue a synchronous but still non-blocking *Nginx Subrequest* using
1183
Nginx subrequests provide a powerful way to make non-blocking internal
1236
Nginx's subrequests provide a powerful way to make non-blocking internal
1184
1237
requests to other locations configured with disk file directory or *any*
1185
1238
other nginx C modules like "ngx_proxy", "ngx_fastcgi", "ngx_memc",
1186
1239
"ngx_postgres", "ngx_drizzle", and even "ngx_lua" itself and etc etc
1203
1256
"res.header" holds all the response headers of the subrequest and it is
1204
1257
a normal Lua table. For multi-value response headers, the value is a Lua
1205
1258
(array) table that holds all the values in the order that they appear.
1206
For instance, if the subrequest response headers contains the following
1259
For instance, if the subrequest response headers contain the following
1209
1262
Set-Cookie: a=3
1222
1275
to prepare internal-only locations.
1224
1277
An optional option table can be fed as the second argument, which
1225
support the options:
1278
supports the options:
1227
1280
* "method" specify the subrequest's request method, which only accepts
1228
1281
constants like "ngx.HTTP_POST". =item *
1236
1289
"ctx" specify a Lua table to be the ngx.ctx table for the
1237
1290
subrequest. It can be the current request's ngx.ctx table, which
1238
effectively make the parent and its subrequest to share exactly the
1291
effectively makes the parent and its subrequest to share exactly the
1239
1292
same context table. This option was first introduced in the
1240
1293
"v0.3.1rc25" release. =item *
1288
1341
This is functionally identical to the previous examples.
1290
1343
The "share_all_vars" option controls whether to share nginx variables
1291
among the current request and new subrequests. If this option is set to
1344
among the current request and its subrequests. If this option is set to
1292
1345
"true", then the current request and associated subrequests will share
1293
1346
the same Nginx variable scope. Hence, changes to Nginx variables made by
1294
1347
a subrequest will affect the current request.
1717
1770
See also ngx.req.set_uri.
1719
1772
ngx.req.get_uri_args
1720
syntax: *args = ngx.req.get_uri_args(count_limit?)*
1773
syntax: *args = ngx.req.get_uri_args(max_args?)*
1722
1775
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1723
1776
header_filter_by_lua**
1783
1836
arguments are silently discarded to guard against potential denial of
1784
1837
service attacks.
1786
However, the optional "count_limit" function argument can be used to
1839
However, the optional "max_args" function argument can be used to
1787
1840
override this limit:
1789
1842
local args = ngx.req.get_uri_args(10)
1794
1847
local args = ngx.req.get_uri_args(0)
1796
Removing the "count_limit" cap is strongly discouraged.
1849
Removing the "max_args" cap is strongly discouraged.
1798
1851
ngx.req.get_post_args
1799
syntax: *ngx.req.get_post_args(count_limit?)*
1852
syntax: *ngx.req.get_post_args(max_args?)*
1801
1854
context: *rewrite_by_lua*, access_by_lua*, content_by_lua*,
1802
1855
header_filter_by_lua**
1866
1919
arguments are silently discarded to guard against potential denial of
1867
1920
service attacks.
1869
However, the optional "count_limit" function argument can be used to
1922
However, the optional "max_args" function argument can be used to
1870
1923
override this limit:
1872
1925
local args = ngx.req.get_post_args(10)
1877
1930
local args = ngx.req.get_post_args(0)
1879
Removing the "count_limit" cap is strongly discouraged.
1932
Removing the "max_args" cap is strongly discouraged.
1881
1934
ngx.req.get_headers
1882
syntax: *headers = ngx.req.get_headers(count_limit?)*
1935
syntax: *headers = ngx.req.get_headers(max_headers?)*
1884
1937
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1885
1938
header_filter_by_lua**
1915
1968
are silently discarded to guard against potential denial of service
1918
However, the optional "count_limit" function argument can be used to
1971
However, the optional "max_headers" function argument can be used to
1919
1972
override this limit:
1921
1974
local args = ngx.req.get_headers(10)
1926
1979
local args = ngx.req.get_headers(0)
1928
Removing the "count_limit" cap is strongly discouraged.
1981
Removing the "max_headers" cap is strongly discouraged.
1930
1983
ngx.req.set_header
1931
1984
syntax: *ngx.req.set_header(header_name, header_value)*
2210
2263
ngx.exec("/foo", "a=3&b=hello%20world")
2212
Alternatively, a Lua table can passed for the "args" argument for
2265
Alternatively, a Lua table can be passed for the "args" argument for
2213
2266
ngx_lua to carry out URI escaping and string concatenation
2396
2449
that this function does not block the Nginx event loop even in the
2397
2450
synchronous mode.
2399
When "ngx.flush(true)" is called immediately after "ngx.print" or
2400
"ngx.say", it causes the latter functions to run in synchronous mode.
2401
This can be particularly useful for streaming output.
2452
When "ngx.flush(true)" is called immediately after ngx.print or ngx.say,
2453
it causes the latter functions to run in synchronous mode. This can be
2454
particularly useful for streaming output.
2403
2456
Note that "ngx.flush" is non functional when in the HTTP 1.0 output
2404
2457
buffering mode. See HTTP 1.0 support.
2525
2578
This method was first introduced in the "v0.3.1rc27" release.
2581
syntax: *table = ngx.decode_args(str, max_args?)*
2583
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
2584
header_filter_by_lua**
2586
Decodes a URI encoded query-string into a Lua table. This is the inverse
2587
function of ngx.encode_args.
2589
The optional "max_args" argument can be used to specify the
2590
maximalnumber of arguments parsed from the "str" argument. By default, a
2591
maximum of 100 request arguments are parsed (including those with the
2592
same name) and that additional URI arguments are silently discarded to
2593
guard against potential denial of service attacks.
2595
This argument can be set to zero to remove the limit and to process all
2596
request arguments received:
2598
local args = ngx.decode_args(str, 0)
2600
Removing the "max_args" cap is strongly discouraged.
2602
This method was introduced in the "v0.5.0rc29".
2527
2604
ngx.encode_base64
2528
2605
syntax: *newstr = ngx.encode_base64(str)*
3965
4042
parser before running.
3967
4044
Alternatively, the regex pattern can be presented as a long-bracketed
3968
lua string literal by encasing it in "long brackets", "[[...]]", in
4045
Lua string literal by encasing it in "long brackets", "[[...]]", in
3969
4046
which case backslashes have to only be escaped once for the Nginx config
4041
4118
* doing very complex URL dispatch in Lua at rewrite phase,
4043
* using Lua to implement advanced caching mechanism for nginx
4120
* using Lua to implement advanced caching mechanism for Nginx's
4044
4121
subrequests and arbitrary locations.
4046
4123
The possibilities are unlimited as the module allows bringing together
4162
4239
* use "ngx_hash_t" to optimize the built-in header look-up process for
4163
4240
ngx.req.set_header, ngx.header.HEADER, and etc.
4165
* fix HTTP 1.0 support: we should by default close the current HTTP
4166
1.0 connection right away if no "Content-Length" response header is
4167
set. the current automatic full buffering bahvior is way too
4170
4242
* add configure options for different strategies of handling the
4171
4243
cosocket connection exceeding in the pools.
4173
4245
* add directives to run Lua codes when nginx stops/reloads.
4175
* deal with TCP 3-second delay problem under great connection harness.
4177
4247
* add APIs to access cookies as key/value pairs.
4179
4249
* add "ignore_resp_headers", "ignore_resp_body", and "ignore_resp"
added
removed
debian/modules/nginx-lua/README
