The ngx_http_perl_module
module is used to implement location and variable handlers in Perl and insert Perl calls into SSI.
This module is not built by default, it should be enabled with the --with-http_perl_module
configuration parameter.
This module requires Perl version 5.6.1 or higher. The C compiler should be compatible with the one used to build Perl.
The module is experimental, caveat emptor applies.
In order for Perl to recompile the modified modules during reconfiguration, it should be built with the -Dusemultiplicity=yes
or -Dusethreads=yes
parameters. Also, to make Perl leak less memory at run time, it should be built with the -Dusemymalloc=no
parameter. To check the values of these parameters in an already built Perl (preferred values are specified in the example), run:
$ perl -V:usemultiplicity -V:usemymalloc usemultiplicity='define'; usemymalloc='n';
Note that after rebuilding Perl with the new -Dusemultiplicity=yes
or -Dusethreads=yes
parameters, all binary Perl modules will have to be rebuilt as well — they will just stop working with the new Perl.
There is a possibility that the main process and then worker processes will grow in size after every reconfiguration. If the main process grows to an unacceptable size, the live upgrade procedure can be applied without changing the executable file.
While the Perl module is performing a long-running operation, such as resolving a domain name, connecting to another server, or querying a database, other requests assigned to the current worker process will not be processed. It is thus recommended to perform only such operations that have predictable and short execution time, such as accessing the local file system.
http { perl_modules perl/lib; perl_require hello.pm; perl_set $msie6 ' sub { my $r = shift; my $ua = $r->header_in("User-Agent"); return "" if $ua =~ /Opera/; return "1" if $ua =~ / MSIE [6-9]\.\d+/; return ""; } '; server { location / { perl hello::handler; } }
The perl/lib/hello.pm
module:
package hello; use nginx; sub handler { my $r = shift; $r->send_http_header("text/html"); return OK if $r->header_only; $r->print("hello!\n<br/>"); if (-f $r->filename or -d _) { $r->print($r->uri, " exists!\n"); } return OK; } 1; __END__
Syntax: | perl module::function|'sub { ... }'; |
---|---|
Default: | — |
Context: | location , limit_except |
Sets a Perl handler for the given location.
Syntax: | perl_modules path; |
---|---|
Default: | — |
Context: | http |
Sets an additional path for Perl modules.
Syntax: | perl_require module; |
---|---|
Default: | — |
Context: | http |
Defines the name of a module that will be loaded during each reconfiguration. Several perl_require
directives can be present.
Syntax: | perl_set
$variable
module::function|'sub { ... }'; |
---|---|
Default: | — |
Context: | http |
Installs a Perl handler for the specified variable.
An SSI command calling Perl has the following format:
<!--# perl sub="module
::function
" arg="parameter1
" arg="parameter2
" ... -->
$r->args
$r->filename
$r->has_request_body(handler)
package hello; use nginx; sub handler { my $r = shift; if ($r->request_method ne "POST") { return DECLINED; } if ($r->has_request_body(\&post)) { return OK; } return HTTP_BAD_REQUEST; } sub post { my $r = shift; $r->send_http_header; $r->print("request_body: \"", $r->request_body, "\"<br/>"); $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); return OK; } 1; __END__
$r->allow_ranges
$r->discard_request_body
$r->header_in(field)
$r->header_only
$r->header_out(field,
value)
$r->internal_redirect(uri)
uri
. An actual redirect happens after the Perl handler execution is completed. Redirections to named locations are currently not supported.
$r->log_error(errno,
message)
message
into the error_log. If errno
is non-zero, an error code and its description will be appended to the message. $r->print(text, ...)
$r->request_body
$r->request_body_file
$r->request_method
$r->remote_addr
$r->flush
$r->sendfile(name[,
offset[,
length]])
$r->send_http_header([type])
type
parameter sets the value of the “Content-Type” response header field. If the value is an empty string, the “Content-Type” header field will not be sent. $r->status(code)
$r->sleep(milliseconds,
handler)
$r->variable()
should be used. Example: package hello; use nginx; sub handler { my $r = shift; $r->discard_request_body; $r->variable("var", "OK"); $r->sleep(1000, \&next); return OK; } sub next { my $r = shift; $r->send_http_header; $r->print($r->variable("var")); return OK; } 1; __END__
$r->unescape(text)
$r->uri
$r->variable(name[,
value])
© 2002-2018 Igor Sysoev
© 2011-2018 Nginx, Inc.
Licensed under the BSD License.
https://nginx.org/en/docs/http/ngx_http_perl_module.html