1 package Catalyst::Engine::FastCGI;
4 use base 'Catalyst::Engine::CGI';
6 die "Please install FCGI\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;
26 /path listen via Unix sockets on /path
27 :port listen via TCP on port on all interfaces
28 hostname:port listen via TCP on port bound to hostname
30 Options may also be specified;
33 leave_umask Set to 1 to disable setting umask to 0
35 nointr Do not allow the listener to be
37 nproc Specify a number of processes for
39 pidfile Specify a filename for the pid file
40 manager Specify a FCGI::ProcManager sub-class
41 detach Detach from console
42 keep_stderr Send STDERR to STDOUT instead of the webserver
47 my ( $self, $class, $listen, $options ) = @_;
51 my $old_umask = umask;
52 unless ( $options->{leave_umask} ) {
55 $sock = FCGI::OpenSocket( $listen, 100 )
56 or die "failed to open FastCGI socket; $!";
57 unless ( $options->{leave_umask} ) {
61 elsif ( $^O ne 'MSWin32' ) {
63 or die "STDIN is not a socket; specify a listen location";
69 my $error = \*STDERR; # send STDERR to the web server
70 $error = \*STDOUT # send STDERR to stdout (a logfile)
71 if $options->{keep_stderr}; # (if asked to)
74 FCGI::Request( \*STDIN, \*STDOUT, $error, \%env, $sock,
75 ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ),
81 $options->{manager} ||= "FCGI::ProcManager";
82 $options->{nproc} ||= 1;
84 $self->daemon_fork() if $options->{detach};
86 if ( $options->{manager} ) {
87 eval "use $options->{manager}; 1" or die $@;
89 $proc_manager = $options->{manager}->new(
91 n_processes => $options->{nproc},
92 pid_fname => $options->{pidfile},
96 # detach *before* the ProcManager inits
97 $self->daemon_detach() if $options->{detach};
99 $proc_manager->pm_manage();
101 elsif ( $options->{detach} ) {
102 $self->daemon_detach();
106 while ( $request->Accept >= 0 ) {
107 $proc_manager && $proc_manager->pm_pre_dispatch();
109 # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
110 # http://lists.rawmode.org/pipermail/catalyst/2006-June/008361.html
111 # Thanks to Mark Blythe for this fix
112 if ( $env{SERVER_SOFTWARE} && $env{SERVER_SOFTWARE} =~ /lighttpd/ ) {
113 $env{PATH_INFO} ||= delete $env{SCRIPT_NAME};
116 $class->handle_request( env => \%env );
118 $proc_manager && $proc_manager->pm_post_dispatch();
122 =head2 $self->write($c, $buffer)
127 my ( $self, $c, $buffer ) = @_;
129 unless ( $self->{_prepared_write} ) {
130 $self->prepare_write($c);
131 $self->{_prepared_write} = 1;
134 # FastCGI does not stream data properly if using 'print $handle',
135 # but a syswrite appears to work properly.
136 *STDOUT->syswrite($buffer);
139 =head2 $self->daemon_fork()
141 Performs the first part of daemon initialisation. Specifically,
142 forking. STDERR, etc are still connected to a terminal.
151 =head2 $self->daemon_detach( )
153 Performs the second part of daemon initialisation. Specifically,
154 disassociates from the terminal.
156 However, this does B<not> change the current working directory to "/",
157 as normal daemons do. It also does not close all open file
158 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
165 print "FastCGI daemon started (pid $$)\n";
166 open STDIN, "+</dev/null" or die $!;
167 open STDOUT, ">&STDIN" or die $!;
168 open STDERR, ">&STDIN" or die $!;
175 =head1 WEB SERVER CONFIGURATIONS
177 =head2 Standalone FastCGI Server
179 In server mode the application runs as a standalone server and accepts
180 connections from a web server. The application can be on the same machine as
181 the web server, on a remote machine, or even on multiple remote machines.
182 Advantages of this method include running the Catalyst application as a
183 different user than the web server, and the ability to set up a scalable
186 To start your application in server mode, install the FCGI::ProcManager
187 module and then use the included fastcgi.pl script.
189 $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
191 Command line options for fastcgi.pl include:
193 -d -daemon Daemonize the server.
194 -p -pidfile Write a pidfile with the pid of the process manager.
195 -l -listen Listen on a socket path, hostname:port, or :port.
196 -n -nproc The number of processes started to handle requests.
198 See below for the specific web server configurations for using the external
201 =head2 Apache 1.x, 2.x
203 Apache requires the mod_fastcgi module. The same module supports both
206 There are three ways to run your application under FastCGI on Apache: server,
209 =head3 Standalone server mode
211 FastCgiExternalServer /tmp/myapp -socket /tmp/myapp.socket
212 Alias /myapp/ /tmp/myapp/
214 # Or, run at the root
217 # Optionally, rewrite the path when accessed without a trailing slash
218 RewriteRule ^/myapp$ myapp/ [R]
220 The FastCgiExternalServer directive tells Apache that when serving /tmp/myapp
221 to use the FastCGI application listenting on the socket /tmp/mapp.socket.
222 Note that /tmp/myapp does not need to exist -- it's a virtual file name.
224 It's likely that Apache is not configured to serve files in /tmp, so the
225 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
226 FastCGI application. The trailing slashes are important as their use will
227 correctly set the PATH_INFO environment variable used by Catalyst to
228 determine the request path. If you would like to be able to access your app
229 without a trailing slash (http://server/myapp), you can use the above
230 RewriteRule directive.
234 The term 'static' is misleading, but in static mode Apache uses its own
235 FastCGI Process Manager to start the application processes. This happens at
236 Apache startup time. In this case you do not run your application's
237 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
238 FastCGI script to run your application.
240 FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
241 Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
243 FastCgiServer tells Apache to start three processes of your application at
244 startup. The Alias command maps a path to the FastCGI application. Again,
245 the trailing slashes are important.
249 In FastCGI dynamic mode, Apache will run your application on demand,
250 typically by requesting a file with a specific extension (e.g. .fcgi). ISPs
251 often use this type of setup to provide FastCGI support to many customers.
253 In this mode it is often enough to place or link your *_fastcgi.pl script in
254 your cgi-bin directory with the extension of .fcgi. In dynamic mode Apache
255 must be able to run your application as a CGI script so ExecCGI must be
256 enabled for the directory.
258 AddHandler fastcgi-script .fcgi
260 The above tells Apache to run any .fcgi file as a FastCGI application.
262 Here is a complete example:
265 ServerName www.myapp.com
266 DocumentRoot /path/to/MyApp
268 # Allow CGI script to run
269 <Directory /path/to/MyApp>
273 # Tell Apache this is a FastCGI application
274 <Files myapp_fastcgi.pl>
275 SetHandler fastcgi-script
279 Then a request for /script/myapp_fastcgi.pl will run the
282 For more information on using FastCGI under Apache, visit
283 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
287 These configurations were tested with Lighttpd 1.4.7.
289 =head3 Standalone server mode
291 server.document-root = "/var/www/MyApp/root"
296 "socket" => "/tmp/myapp.socket",
297 "check-local" => "disable"
304 server.document-root = "/var/www/MyApp/root"
309 "socket" => "/tmp/myapp.socket",
310 "check-local" => "disable",
311 "bin-path" => "/var/www/MyApp/script/myapp_fastcgi.pl",
319 Note that in newer versions of lighttpd, the min-procs and idle-timeout
320 values are disabled. The above example would start 5 processes.
322 =head3 Non-root configuration
324 You can also run your application at any non-root location with either of the
335 For more information on using FastCGI under Lighttpd, visit
336 L<http://www.lighttpd.net/documentation/fastcgi.html>
340 It is possible to run Catalyst under IIS with FastCGI, but we do not
341 yet have detailed instructions.
345 L<Catalyst>, L<FCGI>.
349 Sebastian Riedel, <sri@cpan.org>
351 Christian Hansen, <ch@ngmedia.com>
353 Andy Grundman, <andy@hybridized.org>
357 Bill Moseley, for documentation updates and testing.
361 This program is free software, you can redistribute it and/or modify it under
362 the same terms as Perl itself.