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
133       <https://www.nginx.com/resources/wiki/start/topics/examples/fastcgiexample/>
134       for more details.
135
136       Apache mod_fastcgi
137
138       After installing "mod_fastcgi", you should add the
139       "FastCgiExternalServer" directive to your Apache config:
140
141         FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/fcgi.sock
142
143         ## Then set up the location that you want to be handled by fastcgi:
144
145         # EITHER from a given path
146         Alias /myapp/ /tmp/myapp.fcgi/
147
148         # OR at the root
149         Alias / /tmp/myapp.fcgi/
150
151       Now you can use plackup to listen to the socket that you've just
152       configured in Apache.
153
154         $  plackup -s FCGI --listen /tmp/myapp.sock psgi/myapp.psgi
155
156       The above describes the "standalone" method, which is usually
157       appropriate.  There are other methods, described in more detail at
158       "Standalone_server_mode" in Catalyst::Engine::FastCGI (with regards to
159       Catalyst, but which may be set up similarly for Plack).
160
161       See also
162       <http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer>
163       for more details.
164
165       lighttpd
166
167       To host the app in the root path, you're recommended to use lighttpd
168       1.4.23 or newer with "fix-root-scriptname" flag like below.
169
170         fastcgi.server = ( "/" =>
171            ((
172              "socket" => "/tmp/fcgi.sock",
173              "check-local" => "disable",
174              "fix-root-scriptname" => "enable",
175            ))
176
177       If you use lighttpd older than 1.4.22 where you don't have
178       "fix-root-scriptname", mounting apps under the root causes wrong
179       "SCRIPT_NAME" and "PATH_INFO" set. Also, mounting under the empty root
180       ("") or a path that has a trailing slash would still cause weird values
181       set even with "fix-root-scriptname". In such cases you can use
182       Plack::Middleware::LighttpdScriptNameFix to fix it.
183
184       To mount in the non-root path over TCP:
185
186         fastcgi.server = ( "/foo" =>
187            ((
188              "host" = "127.0.0.1",
189              "port" = "5000",
190              "check-local" => "disable",
191            ))
192
193       It's recommended that your mount path does NOT have the trailing slash.
194       If you really need to have one, you should consider using
195       Plack::Middleware::LighttpdScriptNameFix to fix the wrong PATH_INFO
196       values set by lighttpd.
197
198   Authorization
199       Most fastcgi configuration does not pass "Authorization" headers to
200       "HTTP_AUTHORIZATION" environment variable by default for security
201       reasons. Authentication middleware such as
202       Plack::Middleware::Auth::Basic or
203       Catalyst::Authentication::Credential::HTTP requires the variable to be
204       set up. Plack::Handler::FCGI supports extracting the "Authorization"
205       environment variable when it is configured that way.
206
207       Apache2 with mod_fastcgi:
208
209         --pass-header Authorization
210
211       mod_fcgid:
212
213         FcgidPassHeader Authorization
214
215   Server::Starter
216       This plack handler supports Server::Starter as a superdaemon.  Simply
217       launch plackup from start_server with a path option.  The listen option
218       is ignored when launched from Server::Starter.
219
220         start_server --path=/tmp/socket -- plackup -s FCGI app.psgi
221

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO