File: //usr/local/share/man/man3/Plack::Handler::FCGI.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Plack::Handler::FCGI 3"
.TH Plack::Handler::FCGI 3 "2020-11-30" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Plack::Handler::FCGI \- FastCGI handler for Plack
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& # Run as a standalone daemon
\& plackup \-s FCGI \-\-listen /tmp/fcgi.sock \-\-daemonize \-\-nproc 10
\&
\& # Run from your web server like mod_fastcgi
\& #!/usr/bin/env plackup \-s FCGI
\& my $app = sub { ... };
\&
\& # Roll your own
\& my $server = Plack::Handler::FCGI\->new(
\& nproc => $num_proc,
\& listen => [ $port_or_socket ],
\& detach => 1,
\& );
\& $server\->run($app);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a handler module to run any \s-1PSGI\s0 application as a standalone
FastCGI daemon or a .fcgi script.
.SS "\s-1OPTIONS\s0"
.IX Subsection "OPTIONS"
.IP "listen" 4
.IX Item "listen"
.Vb 2
\& listen => [ \*(Aq/path/to/socket\*(Aq ]
\& listen => [ \*(Aq:8080\*(Aq ]
.Ve
.Sp
Listen on a socket path, hostname:port, or :port.
.IP "port" 4
.IX Item "port"
listen via \s-1TCP\s0 on port on all interfaces (Same as \f(CW\*(C`listen => ":$port"\*(C'\fR)
.IP "leave-umask" 4
.IX Item "leave-umask"
Set to 1 to disable setting umask to 0 for socket open
.IP "nointr" 4
.IX Item "nointr"
Do not allow the listener to be interrupted by Ctrl+C
.IP "nproc" 4
.IX Item "nproc"
Specify a number of processes for FCGI::ProcManager
.IP "pid" 4
.IX Item "pid"
Specify a filename for the pid file
.IP "manager" 4
.IX Item "manager"
Specify either a FCGI::ProcManager subclass, or an actual FCGI::ProcManager\-compatible object.
If you do not want a FCGI::ProcManager but instead run in a single process, set this to undef.
.Sp
.Vb 4
\& use FCGI::ProcManager::Dynamic;
\& Plack::Handler::FCGI\->new(
\& manager => FCGI::ProcManager::Dynamic\->new(...),
\& );
.Ve
.IP "daemonize" 4
.IX Item "daemonize"
Daemonize the process.
.IP "proc-title" 4
.IX Item "proc-title"
Specify process title
.IP "keep-stderr" 4
.IX Item "keep-stderr"
Send psgi.errors to \s-1STDERR\s0 instead of to the \s-1FCGI\s0 error stream.
.IP "backlog" 4
.IX Item "backlog"
Maximum length of the queue of pending connections, defaults to 100.
.SS "\s-1EXTENSIONS\s0"
.IX Subsection "EXTENSIONS"
Supported PSGI::Extensions.
.IP "psgix.cleanup" 4
.IX Item "psgix.cleanup"
.Vb 2
\& push @{ $env\->{\*(Aqpsgix.cleanup.handlers\*(Aq} }, sub { warn "Did this later" }
\& if $env\->{\*(Aqpsgix.cleanup\*(Aq};
.Ve
.Sp
Supports the \f(CW\*(C`psgix.cleanup\*(C'\fR extension,
in order to use it, just push a callback onto
\&\f(CW\*(C`$env\->{\*(Aqpsgix.cleanup.handlers\*(Aq\*(C'\fR.
These callbacks are run after the \f(CW\*(C`pm_post_dispatch\*(C'\fR hook.
.IP "psgix.harakiri" 4
.IX Item "psgix.harakiri"
.Vb 2
\& $env\->{\*(Aqpsgix.harakiri.commit\*(Aq} = 1
\& if $env\->{\*(Aqpsgix.harakiri\*(Aq};
.Ve
.Sp
If there is a \*(L"manager\*(R", then \f(CW\*(C`psgix.harakiri\*(C'\fR will be enabled
and setting \f(CW\*(C`$env\->{\*(Aqpsgix.harakiri.commit\*(Aq}\*(C'\fR to a true value
will cause \f(CW\*(C`$manager\->pm_exit\*(C'\fR to be called after the
request is finished.
.SS "\s-1WEB SERVER CONFIGURATIONS\s0"
.IX Subsection "WEB SERVER CONFIGURATIONS"
In all cases, you will want to install \s-1FCGI\s0 and FCGI::ProcManager.
You may find it most convenient to simply install Task::Plack which
includes both of these.
.PP
\fInginx\fR
.IX Subsection "nginx"
.PP
This is an example nginx configuration to run your \s-1FCGI\s0 daemon on a
Unix domain socket and run it at the server's root \s-1URL\s0 (/).
.PP
.Vb 10
\& http {
\& server {
\& listen 3001;
\& location / {
\& set $script "";
\& set $path_info $uri;
\& fastcgi_pass unix:/tmp/fastcgi.sock;
\& fastcgi_param SCRIPT_NAME $script;
\& fastcgi_param PATH_INFO $path_info;
\& fastcgi_param QUERY_STRING $query_string;
\& fastcgi_param REQUEST_METHOD $request_method;
\& fastcgi_param CONTENT_TYPE $content_type;
\& fastcgi_param CONTENT_LENGTH $content_length;
\& fastcgi_param REQUEST_URI $request_uri;
\& fastcgi_param SERVER_PROTOCOL $server_protocol;
\& fastcgi_param REMOTE_ADDR $remote_addr;
\& fastcgi_param REMOTE_PORT $remote_port;
\& fastcgi_param SERVER_ADDR $server_addr;
\& fastcgi_param SERVER_PORT $server_port;
\& fastcgi_param SERVER_NAME $server_name;
\& }
\& }
\& }
.Ve
.PP
If you want to host your application in a non-root path, then you
should mangle this configuration to set the path to \f(CW\*(C`SCRIPT_NAME\*(C'\fR and
the rest of the path in \f(CW\*(C`PATH_INFO\*(C'\fR.
.PP
See <http://wiki.nginx.org/NginxFcgiExample> for more details.
.PP
\fIApache mod_fastcgi\fR
.IX Subsection "Apache mod_fastcgi"
.PP
After installing \f(CW\*(C`mod_fastcgi\*(C'\fR, you should add the \f(CW\*(C`FastCgiExternalServer\*(C'\fR
directive to your Apache config:
.PP
.Vb 1
\& FastCgiExternalServer /tmp/myapp.fcgi \-socket /tmp/fcgi.sock
\&
\& ## Then set up the location that you want to be handled by fastcgi:
\&
\& # EITHER from a given path
\& Alias /myapp/ /tmp/myapp.fcgi/
\&
\& # OR at the root
\& Alias / /tmp/myapp.fcgi/
.Ve
.PP
Now you can use plackup to listen to the socket that you've just configured in Apache.
.PP
.Vb 1
\& $ plackup \-s FCGI \-\-listen /tmp/myapp.sock psgi/myapp.psgi
.Ve
.PP
The above describes the \*(L"standalone\*(R" method, which is usually appropriate.
There are other methods, described in more detail at
\&\*(L"Standalone_server_mode\*(R" in Catalyst::Engine::FastCGI (with regards to Catalyst, but which may be set up similarly for Plack).
.PP
See also <http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer>
for more details.
.PP
\fIlighttpd\fR
.IX Subsection "lighttpd"
.PP
To host the app in the root path, you're recommended to use lighttpd
1.4.23 or newer with \f(CW\*(C`fix\-root\-scriptname\*(C'\fR flag like below.
.PP
.Vb 6
\& fastcgi.server = ( "/" =>
\& ((
\& "socket" => "/tmp/fcgi.sock",
\& "check\-local" => "disable",
\& "fix\-root\-scriptname" => "enable",
\& ))
.Ve
.PP
If you use lighttpd older than 1.4.22 where you don't have
\&\f(CW\*(C`fix\-root\-scriptname\*(C'\fR, mounting apps under the root causes wrong
\&\f(CW\*(C`SCRIPT_NAME\*(C'\fR and \f(CW\*(C`PATH_INFO\*(C'\fR set. Also, mounting under the empty
root (\f(CW""\fR) or a path that has a trailing slash would still cause
weird values set even with \f(CW\*(C`fix\-root\-scriptname\*(C'\fR. In such cases you
can use Plack::Middleware::LighttpdScriptNameFix to fix it.
.PP
To mount in the non-root path over \s-1TCP:\s0
.PP
.Vb 6
\& fastcgi.server = ( "/foo" =>
\& ((
\& "host" = "127.0.0.1",
\& "port" = "5000",
\& "check\-local" => "disable",
\& ))
.Ve
.PP
It's recommended that your mount path does \fB\s-1NOT\s0\fR have the trailing
slash. If you \fIreally\fR need to have one, you should consider using
Plack::Middleware::LighttpdScriptNameFix to fix the wrong
\&\fB\s-1PATH_INFO\s0\fR values set by lighttpd.
.SS "Authorization"
.IX Subsection "Authorization"
Most fastcgi configuration does not pass \f(CW\*(C`Authorization\*(C'\fR headers to
\&\f(CW\*(C`HTTP_AUTHORIZATION\*(C'\fR environment variable by default for security
reasons. Authentication middleware such as Plack::Middleware::Auth::Basic or
Catalyst::Authentication::Credential::HTTP requires the variable to
be set up. Plack::Handler::FCGI supports extracting the \f(CW\*(C`Authorization\*(C'\fR environment
variable when it is configured that way.
.PP
Apache2 with mod_fastcgi:
.PP
.Vb 1
\& \-\-pass\-header Authorization
.Ve
.PP
mod_fcgid:
.PP
.Vb 1
\& FcgidPassHeader Authorization
.Ve
.SS "Server::Starter"
.IX Subsection "Server::Starter"
This plack handler supports Server::Starter as a superdaemon.
Simply launch plackup from start_server with a path option.
The listen option is ignored when launched from Server::Starter.
.PP
.Vb 1
\& start_server \-\-path=/tmp/socket \-\- plackup \-s FCGI app.psgi
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Plack