1 package Catalyst::Engine::FastCGI;
4 use base 'Catalyst::Engine::CGI';
6 die "Unable to load the FCGI module, you may need to install it:\n$@\n" if $@;
10 Catalyst::Engine::FastCGI - FastCGI Engine
14 This is the FastCGI engine.
16 =head1 OVERLOADED METHODS
18 This class overloads some methods from C<Catalyst::Engine::CGI>.
20 =head2 $self->run($c, $listen, { option => value, ... })
22 Starts the FastCGI server. If C<$listen> is set, then it specifies a
23 location to listen for FastCGI requests;
29 listen via Unix sockets on /path
33 listen via TCP on port on all interfaces
37 listen via TCP on port bound to hostname
41 Options may also be specified;
47 Set to 1 to disable setting umask to 0 for socket open =item nointr
49 Do not allow the listener to be interrupted by Ctrl+C
53 Specify a number of processes for FCGI::ProcManager
57 Specify a filename for the pid file
61 Specify a FCGI::ProcManager sub-class
69 Send STDERR to STDOUT instead of the webserver
76 my ( $self, $class, $listen, $options ) = @_;
80 my $old_umask = umask;
81 unless ( $options->{leave_umask} ) {
84 $sock = FCGI::OpenSocket( $listen, 100 )
85 or die "failed to open FastCGI socket; $!";
86 unless ( $options->{leave_umask} ) {
90 elsif ( $^O ne 'MSWin32' ) {
92 or die "STDIN is not a socket; specify a listen location";
98 my $error = \*STDERR; # send STDERR to the web server
99 $error = \*STDOUT # send STDERR to stdout (a logfile)
100 if $options->{keep_stderr}; # (if asked to)
103 FCGI::Request( \*STDIN, \*STDOUT, $error, \%env, $sock,
104 ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ),
110 $options->{manager} ||= "FCGI::ProcManager";
111 $options->{nproc} ||= 1;
113 $self->daemon_fork() if $options->{detach};
115 if ( $options->{manager} ) {
116 eval "use $options->{manager}; 1" or die $@;
118 $proc_manager = $options->{manager}->new(
120 n_processes => $options->{nproc},
121 pid_fname => $options->{pidfile},
125 # detach *before* the ProcManager inits
126 $self->daemon_detach() if $options->{detach};
128 $proc_manager->pm_manage();
130 elsif ( $options->{detach} ) {
131 $self->daemon_detach();
135 while ( $request->Accept >= 0 ) {
136 $proc_manager && $proc_manager->pm_pre_dispatch();
138 # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
139 # http://lists.rawmode.org/pipermail/catalyst/2006-June/008361.html
140 # Thanks to Mark Blythe for this fix
141 if ( $env{SERVER_SOFTWARE} && $env{SERVER_SOFTWARE} =~ /lighttpd/ ) {
142 $env{PATH_INFO} ||= delete $env{SCRIPT_NAME};
145 $class->handle_request( env => \%env );
147 $proc_manager && $proc_manager->pm_post_dispatch();
151 =head2 $self->write($c, $buffer)
156 my ( $self, $c, $buffer ) = @_;
158 unless ( $self->{_prepared_write} ) {
159 $self->prepare_write($c);
160 $self->{_prepared_write} = 1;
163 # XXX: We can't use Engine's write() method because syswrite
164 # appears to return bogus values instead of the number of bytes
165 # written: http://www.fastcgi.com/om_archive/mail-archive/0128.html
167 # Prepend the headers if they have not yet been sent
168 if ( my $headers = delete $self->{_header_buf} ) {
169 $buffer = $headers . $buffer;
172 # FastCGI does not stream data properly if using 'print $handle',
173 # but a syswrite appears to work properly.
174 *STDOUT->syswrite($buffer);
177 =head2 $self->daemon_fork()
179 Performs the first part of daemon initialisation. Specifically,
180 forking. STDERR, etc are still connected to a terminal.
189 =head2 $self->daemon_detach( )
191 Performs the second part of daemon initialisation. Specifically,
192 disassociates from the terminal.
194 However, this does B<not> change the current working directory to "/",
195 as normal daemons do. It also does not close all open file
196 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
203 print "FastCGI daemon started (pid $$)\n";
204 open STDIN, "+</dev/null" or die $!;
205 open STDOUT, ">&STDIN" or die $!;
206 open STDERR, ">&STDIN" or die $!;
213 =head1 WEB SERVER CONFIGURATIONS
215 =head2 Standalone FastCGI Server
217 In server mode the application runs as a standalone server and accepts
218 connections from a web server. The application can be on the same machine as
219 the web server, on a remote machine, or even on multiple remote machines.
220 Advantages of this method include running the Catalyst application as a
221 different user than the web server, and the ability to set up a scalable
224 To start your application in server mode, install the FCGI::ProcManager
225 module and then use the included fastcgi.pl script.
227 $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
229 Command line options for fastcgi.pl include:
231 -d -daemon Daemonize the server.
232 -p -pidfile Write a pidfile with the pid of the process manager.
233 -l -listen Listen on a socket path, hostname:port, or :port.
234 -n -nproc The number of processes started to handle requests.
236 See below for the specific web server configurations for using the external
239 =head2 Apache 1.x, 2.x
241 Apache requires the mod_fastcgi module. The same module supports both
244 There are three ways to run your application under FastCGI on Apache: server,
247 =head3 Standalone server mode
249 FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket
250 Alias /myapp/ /tmp/myapp/myapp.fcgi/
252 # Or, run at the root
253 Alias / /tmp/myapp.fcgi/
255 # Optionally, rewrite the path when accessed without a trailing slash
256 RewriteRule ^/myapp$ myapp/ [R]
259 The FastCgiExternalServer directive tells Apache that when serving
260 /tmp/myapp to use the FastCGI application listenting on the socket
261 /tmp/mapp.socket. Note that /tmp/myapp.fcgi does not need to exist --
262 it's a virtual file name. With some versions of C<mod_fastcgi> or
263 C<mod_fcgid>, you can use any name you like, but most require that the
264 virtual filename end in C<.fcgi>.
266 It's likely that Apache is not configured to serve files in /tmp, so the
267 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
268 FastCGI application. The trailing slashes are important as their use will
269 correctly set the PATH_INFO environment variable used by Catalyst to
270 determine the request path. If you would like to be able to access your app
271 without a trailing slash (http://server/myapp), you can use the above
272 RewriteRule directive.
276 The term 'static' is misleading, but in static mode Apache uses its own
277 FastCGI Process Manager to start the application processes. This happens at
278 Apache startup time. In this case you do not run your application's
279 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
280 FastCGI script to run your application.
282 FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
283 Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
285 FastCgiServer tells Apache to start three processes of your application at
286 startup. The Alias command maps a path to the FastCGI application. Again,
287 the trailing slashes are important.
291 In FastCGI dynamic mode, Apache will run your application on demand,
292 typically by requesting a file with a specific extension (e.g. .fcgi). ISPs
293 often use this type of setup to provide FastCGI support to many customers.
295 In this mode it is often enough to place or link your *_fastcgi.pl script in
296 your cgi-bin directory with the extension of .fcgi. In dynamic mode Apache
297 must be able to run your application as a CGI script so ExecCGI must be
298 enabled for the directory.
300 AddHandler fastcgi-script .fcgi
302 The above tells Apache to run any .fcgi file as a FastCGI application.
304 Here is a complete example:
307 ServerName www.myapp.com
308 DocumentRoot /path/to/MyApp
310 # Allow CGI script to run
311 <Directory /path/to/MyApp>
315 # Tell Apache this is a FastCGI application
316 <Files myapp_fastcgi.pl>
317 SetHandler fastcgi-script
321 Then a request for /script/myapp_fastcgi.pl will run the
324 For more information on using FastCGI under Apache, visit
325 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
329 These configurations were tested with Lighttpd 1.4.7.
331 =head3 Standalone server mode
333 server.document-root = "/var/www/MyApp/root"
338 "socket" => "/tmp/myapp.socket",
339 "check-local" => "disable"
346 server.document-root = "/var/www/MyApp/root"
351 "socket" => "/tmp/myapp.socket",
352 "check-local" => "disable",
353 "bin-path" => "/var/www/MyApp/script/myapp_fastcgi.pl",
361 Note that in newer versions of lighttpd, the min-procs and idle-timeout
362 values are disabled. The above example would start 5 processes.
364 =head3 Non-root configuration
366 You can also run your application at any non-root location with either of the
377 For more information on using FastCGI under Lighttpd, visit
378 L<http://www.lighttpd.net/documentation/fastcgi.html>
382 It is possible to run Catalyst under IIS with FastCGI, but we do not
383 yet have detailed instructions.
387 L<Catalyst>, L<FCGI>.
391 Sebastian Riedel, <sri@cpan.org>
393 Christian Hansen, <ch@ngmedia.com>
395 Andy Grundman, <andy@hybridized.org>
399 Bill Moseley, for documentation updates and testing.
403 This program is free software, you can redistribute it and/or modify it under
404 the same terms as Perl itself.