ngx_http_perl_module

Location and variable handlers written in embedded Perl

dynamic moduleBSD-2-Clausesource docs

Overview

ngx_http_perl_module embeds a Perl interpreter in nginx to implement location handlers and variable handlers in Perl and to insert Perl calls into SSI. A handler receives the $r request object, which exposes methods such as header_in, header_out, send_http_header, print, sendfile, internal_redirect and variable.

The module requires Perl 5.6.1 or later and is marked experimental upstream. Perl should be built with -Dusemultiplicity=yes or -Dusethreads=yes so modified modules are recompiled on reconfiguration, and worker memory may grow after each reload. Long-running operations in a handler block every other request on that worker, so the docs recommend only short, predictable work such as local file access.

It is an official nginx module that upstream does not build by default, so it needs the --with-http_perl_module configure parameter. The n.wtf packages build it as a dynamic module shipped in libnginx-mod-http-perl, typically for small custom variables and lightweight request handlers without an external application server.

Key directives

perlSets a Perl handler for a location as module::function or an inline sub; location and limit_except context.

perl_setInstalls a Perl handler that computes the value of the given variable; http context.

perl_modulesAdds a directory to the Perl module search path; http context.

perl_requireNames a module loaded during each reconfiguration; may be repeated.

$r request objectMethods such as uri, args, header_in, header_out, send_http_header, print, sendfile and variable.

SSI perl commandCalls a Perl function from an SSI page with .

Example

nginx.conf

perl_modules /etc/nginx/perl/lib; perl_require hello.pm; # variable handler: flag old MSIE user agents 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 { listen 80; location / { perl hello::handler; } }

Availability

Ships as a dynamic module in libnginx-mod-http-perl, installed with nginx-extras. The package drops a load_module config into /etc/nginx/modules-enabled/, so it loads on start.