.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.26) .\" .\" 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" '' '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 turned on, 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. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Plack::Handler::FCGI 3pm" .TH Plack::Handler::FCGI 3pm "2014-04-05" "perl v5.14.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 \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. .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 .SS "\s-1WEB\s0 \s-1SERVER\s0 \s-1CONFIGURATIONS\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 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 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 \& FcgiPassHeader Authorization .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Plack