.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 3pm"
.TH Plack::Handler::FCGI 3pm 2024-01-20 "perl v5.38.2" "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 PSGI application as a standalone
FastCGI daemon or a .fcgi script.
.SS OPTIONS
.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 TCP 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 STDERR instead of to the FCGI error stream.
.IP backlog 4
.IX Item "backlog"
Maximum length of the queue of pending connections, defaults to 100.
.SS EXTENSIONS
.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 "manager", 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 "WEB SERVER CONFIGURATIONS"
.IX Subsection "WEB SERVER CONFIGURATIONS"
In all cases, you will want to install FCGI 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 FCGI daemon on a
Unix domain socket and run it at the server's root URL (/).
.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 <https://www.nginx.com/resources/wiki/start/topics/examples/fastcgiexample/> 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 "standalone" method, which is usually appropriate.
There are other methods, described in more detail at 
"Standalone_server_mode" 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 TCP:
.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 \fBNOT\fR have the trailing
slash. If you \fIreally\fR need to have one, you should consider using
Plack::Middleware::LighttpdScriptNameFix to fix the wrong
\&\fBPATH_INFO\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