Plack::Handler::FCGI(3pm)

1Plack::Handler::FCGI(3)User Contributed Perl DocumentatioPnlack::Handler::FCGI(3)
2
3
4

NAME

6       Plack::Handler::FCGI - FastCGI handler for Plack
7

SYNOPSIS

9         # Run as a standalone daemon
10         plackup -s FCGI --listen /tmp/fcgi.sock --daemonize --nproc 10
11
12         # Run from your web server like mod_fastcgi
13         #!/usr/bin/env plackup -s FCGI
14         my $app = sub { ... };
15
16         # Roll your own
17         my $server = Plack::Handler::FCGI->new(
18             nproc  => $num_proc,
19             listen => [ $port_or_socket ],
20             detach => 1,
21         );
22         $server->run($app);
23

DESCRIPTION

25       This is a handler module to run any PSGI application as a standalone
26       FastCGI daemon or a .fcgi script.
27
28   OPTIONS
29       listen
30               listen => [ '/path/to/socket' ]
31               listen => [ ':8080' ]
32
33           Listen on a socket path, hostname:port, or :port.
34
35       port
36           listen via TCP on port on all interfaces (Same as "listen =>
37           ":$port"")
38
39       leave-umask
40           Set to 1 to disable setting umask to 0 for socket open
41
42       nointr
43           Do not allow the listener to be interrupted by Ctrl+C
44
45       nproc
46           Specify a number of processes for FCGI::ProcManager
47
48       pid Specify a filename for the pid file
49
50       manager
51           Specify either a FCGI::ProcManager subclass, or an actual
52           FCGI::ProcManager-compatible object.  If you do not want a
53           FCGI::ProcManager but instead run in a single process, set this to
54           undef.
55
56             use FCGI::ProcManager::Dynamic;
57             Plack::Handler::FCGI->new(
58                 manager => FCGI::ProcManager::Dynamic->new(...),
59             );
60
61       daemonize
62           Daemonize the process.
63
64       proc-title
65           Specify process title
66
67       keep-stderr
68           Send psgi.errors to STDERR instead of to the FCGI error stream.
69
70       backlog
71           Maximum length of the queue of pending connections, defaults to
72           100.
73
74   EXTENSIONS
75       Supported PSGI::Extensions.
76
77       psgix.cleanup
78               push @{ $env->{'psgix.cleanup.handlers'} }, sub { warn "Did this later" }
79                   if $env->{'psgix.cleanup'};
80
81           Supports the "psgix.cleanup" extension, in order to use it, just
82           push a callback onto "$env->{'psgix.cleanup.handlers'".  These
83           callbacks are run after the "pm_post_dispatch" hook.
84
85       psgix.harakiri
86               $env->{'psgix.harakiri.commit'} = 1
87                   if $env->{'psgix.harakiri'};
88
89           If there is a "manager", then "psgix.harakiri" will be enabled and
90           setting "$env->{'psgix.harakiri.commit'}" to a true value will
91           cause "$manager->pm_exit" to be called after the request is
92           finished.
93
94   WEB SERVER CONFIGURATIONS
95       In all cases, you will want to install FCGI and FCGI::ProcManager.  You
96       may find it most convenient to simply install Task::Plack which
97       includes both of these.
98
99       nginx
100
101       This is an example nginx configuration to run your FCGI daemon on a
102       Unix domain socket and run it at the server's root URL (/).
103
104         http {
105           server {
106             listen 3001;
107             location / {
108               set $script "";
109               set $path_info $uri;
110               fastcgi_pass unix:/tmp/fastcgi.sock;
111               fastcgi_param  SCRIPT_NAME      $script;
112               fastcgi_param  PATH_INFO        $path_info;
113               fastcgi_param  QUERY_STRING     $query_string;
114               fastcgi_param  REQUEST_METHOD   $request_method;
115               fastcgi_param  CONTENT_TYPE     $content_type;
116               fastcgi_param  CONTENT_LENGTH   $content_length;
117               fastcgi_param  REQUEST_URI      $request_uri;
118               fastcgi_param  SERVER_PROTOCOL  $server_protocol;
119               fastcgi_param  REMOTE_ADDR      $remote_addr;
120               fastcgi_param  REMOTE_PORT      $remote_port;
121               fastcgi_param  SERVER_ADDR      $server_addr;
122               fastcgi_param  SERVER_PORT      $server_port;
123               fastcgi_param  SERVER_NAME      $server_name;
124             }
125           }
126         }
127
128       If you want to host your application in a non-root path, then you
129       should mangle this configuration to set the path to "SCRIPT_NAME" and
130       the rest of the path in "PATH_INFO".
131
132       See <http://wiki.nginx.org/NginxFcgiExample> for more details.
133
134       Apache mod_fastcgi
135
136       After installing "mod_fastcgi", you should add the
137       "FastCgiExternalServer" directive to your Apache config:
138
139         FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/fcgi.sock
140
141         ## Then set up the location that you want to be handled by fastcgi:
142
143         # EITHER from a given path
144         Alias /myapp/ /tmp/myapp.fcgi/
145
146         # OR at the root
147         Alias / /tmp/myapp.fcgi/
148
149       Now you can use plackup to listen to the socket that you've just
150       configured in Apache.
151
152         $  plackup -s FCGI --listen /tmp/myapp.sock psgi/myapp.psgi
153
154       The above describes the "standalone" method, which is usually
155       appropriate.  There are other methods, described in more detail at
156       "Standalone_server_mode" in Catalyst::Engine::FastCGI (with regards to
157       Catalyst, but which may be set up similarly for Plack).
158
159       See also
160       <http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer>
161       for more details.
162
163       lighttpd
164
165       To host the app in the root path, you're recommended to use lighttpd
166       1.4.23 or newer with "fix-root-scriptname" flag like below.
167
168         fastcgi.server = ( "/" =>
169            ((
170              "socket" => "/tmp/fcgi.sock",
171              "check-local" => "disable",
172              "fix-root-scriptname" => "enable",
173            ))
174
175       If you use lighttpd older than 1.4.22 where you don't have
176       "fix-root-scriptname", mounting apps under the root causes wrong
177       "SCRIPT_NAME" and "PATH_INFO" set. Also, mounting under the empty root
178       ("") or a path that has a trailing slash would still cause weird values
179       set even with "fix-root-scriptname". In such cases you can use
180       Plack::Middleware::LighttpdScriptNameFix to fix it.
181
182       To mount in the non-root path over TCP:
183
184         fastcgi.server = ( "/foo" =>
185            ((
186              "host" = "127.0.0.1",
187              "port" = "5000",
188              "check-local" => "disable",
189            ))
190
191       It's recommended that your mount path does NOT have the trailing slash.
192       If you really need to have one, you should consider using
193       Plack::Middleware::LighttpdScriptNameFix to fix the wrong PATH_INFO
194       values set by lighttpd.
195
196   Authorization
197       Most fastcgi configuration does not pass "Authorization" headers to
198       "HTTP_AUTHORIZATION" environment variable by default for security
199       reasons. Authentication middleware such as
200       Plack::Middleware::Auth::Basic or
201       Catalyst::Authentication::Credential::HTTP requires the variable to be
202       set up. Plack::Handler::FCGI supports extracting the "Authorization"
203       environment variable when it is configured that way.
204
205       Apache2 with mod_fastcgi:
206
207         --pass-header Authorization
208
209       mod_fcgid:
210
211         FcgidPassHeader Authorization
212
213   Server::Starter
214       This plack handler supports Server::Starter as a superdaemon.  Simply
215       launch plackup from start_server with a path option.  The listen option
216       is ignored when launched from Server::Starter.
217
218         start_server --path=/tmp/socket -- plackup -s FCGI app.psgi
219

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO