lib/Catalyst/Engine/FastCGI.pm

   1 package Catalyst::Engine::FastCGI;
   2
   3 use strict;
   4 use base 'Catalyst::Engine::CGI';
   5 eval "use FCGI";
   6 die "Unable to load the FCGI module, you may need to install it:\n$@\n" if $@;
   7
   8 =head1 NAME
   9
  10 Catalyst::Engine::FastCGI - FastCGI Engine
  11
  12 =head1 DESCRIPTION
  13
  14 This is the FastCGI engine.
  15
  16 =head1 OVERLOADED METHODS
  17
  18 This class overloads some methods from C<Catalyst::Engine::CGI>.
  19
  20 =head2 $self->run($c, $listen, { option => value, ... })
  21
  22 Starts the FastCGI server.  If C<$listen> is set, then it specifies a
  23 location to listen for FastCGI requests;
  24
  25 =over 4
  26
  27 =item /path
  28
  29 listen via Unix sockets on /path
  30
  31 =item :port
  32
  33 listen via TCP on port on all interfaces
  34
  35 =item hostname:port
  36
  37 listen via TCP on port bound to hostname
  38
  39 =back
  40
  41 Options may also be specified;
  42
  43 =over 4
  44
  45 =item leave_umask
  46
  47 Set to 1 to disable setting umask to 0 for socket open =item nointr
  48
  49 Do not allow the listener to be interrupted by Ctrl+C
  50
  51 =item nproc
  52
  53 Specify a number of processes for FCGI::ProcManager
  54
  55 =item pidfile
  56
  57 Specify a filename for the pid file
  58
  59 =item manager
  60
  61 Specify a FCGI::ProcManager sub-class
  62
  63 =item detach
  64
  65 Detach from console
  66
  67 =item keep_stderr
  68
  69 Send STDERR to STDOUT instead of the webserver
  70
  71 =back
  72
  73 =cut
  74
  75 sub run {
  76     my ( $self, $class, $listen, $options ) = @_;
  77
  78     my $sock = 0;
  79     if ($listen) {
  80         my $old_umask = umask;
  81         unless ( $options->{leave_umask} ) {
  82             umask(0);
  83         }
  84         $sock = FCGI::OpenSocket( $listen, 100 )
  85           or die "failed to open FastCGI socket; $!";
  86         unless ( $options->{leave_umask} ) {
  87             umask($old_umask);
  88         }
  89     }
  90     elsif ( $^O ne 'MSWin32' ) {
  91         -S STDIN
  92           or die "STDIN is not a socket; specify a listen location";
  93     }
  94
  95     $options ||= {};
  96
  97     my %env;
  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)
 101
 102     my $request =
 103       FCGI::Request( \*STDIN, \*STDOUT, $error, \%env, $sock,
 104         ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ),
 105       );
 106
 107     my $proc_manager;
 108
 109     if ($listen) {
 110         $options->{manager} ||= "FCGI::ProcManager";
 111         $options->{nproc}   ||= 1;
 112
 113         $self->daemon_fork() if $options->{detach};
 114
 115         if ( $options->{manager} ) {
 116             eval "use $options->{manager}; 1" or die $@;
 117
 118             $proc_manager = $options->{manager}->new(
 119                 {
 120                     n_processes => $options->{nproc},
 121                     pid_fname   => $options->{pidfile},
 122                 }
 123             );
 124
 125             # detach *before* the ProcManager inits
 126             $self->daemon_detach() if $options->{detach};
 127
 128             $proc_manager->pm_manage();
 129         }
 130         elsif ( $options->{detach} ) {
 131             $self->daemon_detach();
 132         }
 133     }
 134
 135     while ( $request->Accept >= 0 ) {
 136         $proc_manager && $proc_manager->pm_pre_dispatch();
 137
 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};
 143         }
 144
 145         $class->handle_request( env => \%env );
 146
 147         $proc_manager && $proc_manager->pm_post_dispatch();
 148     }
 149 }
 150
 151 =head2 $self->write($c, $buffer)
 152
 153 =cut
 154
 155 sub write {
 156     my ( $self, $c, $buffer ) = @_;
 157
 158     unless ( $self->{_prepared_write} ) {
 159         $self->prepare_write($c);
 160         $self->{_prepared_write} = 1;
 161     }
 162
 163     # FastCGI does not stream data properly if using 'print $handle',
 164     # but a syswrite appears to work properly.
 165     *STDOUT->syswrite($buffer);
 166 }
 167
 168 =head2 $self->daemon_fork()
 169
 170 Performs the first part of daemon initialisation.  Specifically,
 171 forking.  STDERR, etc are still connected to a terminal.
 172
 173 =cut
 174
 175 sub daemon_fork {
 176     require POSIX;
 177     fork && exit;
 178 }
 179
 180 =head2 $self->daemon_detach( )
 181
 182 Performs the second part of daemon initialisation.  Specifically,
 183 disassociates from the terminal.
 184
 185 However, this does B<not> change the current working directory to "/",
 186 as normal daemons do.  It also does not close all open file
 187 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
 188 F</dev/null>).
 189
 190 =cut
 191
 192 sub daemon_detach {
 193     my $self = shift;
 194     print "FastCGI daemon started (pid $$)\n";
 195     open STDIN,  "+</dev/null" or die $!;
 196     open STDOUT, ">&STDIN"     or die $!;
 197     open STDERR, ">&STDIN"     or die $!;
 198     POSIX::setsid();
 199 }
 200
 201 1;
 202 __END__
 203
 204 =head1 WEB SERVER CONFIGURATIONS
 205
 206 =head2 Standalone FastCGI Server
 207
 208 In server mode the application runs as a standalone server and accepts
 209 connections from a web server.  The application can be on the same machine as
 210 the web server, on a remote machine, or even on multiple remote machines.
 211 Advantages of this method include running the Catalyst application as a
 212 different user than the web server, and the ability to set up a scalable
 213 server farm.
 214
 215 To start your application in server mode, install the FCGI::ProcManager
 216 module and then use the included fastcgi.pl script.
 217
 218     $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
 219
 220 Command line options for fastcgi.pl include:
 221
 222     -d -daemon     Daemonize the server.
 223     -p -pidfile    Write a pidfile with the pid of the process manager.
 224     -l -listen     Listen on a socket path, hostname:port, or :port.
 225     -n -nproc      The number of processes started to handle requests.
 226
 227 See below for the specific web server configurations for using the external
 228 server.
 229
 230 =head2 Apache 1.x, 2.x
 231
 232 Apache requires the mod_fastcgi module.  The same module supports both
 233 Apache 1 and 2.
 234
 235 There are three ways to run your application under FastCGI on Apache: server,
 236 static, and dynamic.
 237
 238 =head3 Standalone server mode
 239
 240     FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket
 241     Alias /myapp/ /tmp/myapp/myapp.fcgi/
 242
 243     # Or, run at the root
 244     Alias / /tmp/myapp.fcgi/
 245
 246     # Optionally, rewrite the path when accessed without a trailing slash
 247     RewriteRule ^/myapp$ myapp/ [R]
 248
 249
 250 The FastCgiExternalServer directive tells Apache that when serving
 251 /tmp/myapp to use the FastCGI application listenting on the socket
 252 /tmp/mapp.socket.  Note that /tmp/myapp.fcgi does not need to exist --
 253 it's a virtual file name.  With some versions of C<mod_fastcgi> or
 254 C<mod_fcgid>, you can use any name you like, but most require that the
 255 virtual filename end in C<.fcgi>.
 256
 257 It's likely that Apache is not configured to serve files in /tmp, so the
 258 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
 259 FastCGI application. The trailing slashes are important as their use will
 260 correctly set the PATH_INFO environment variable used by Catalyst to
 261 determine the request path.  If you would like to be able to access your app
 262 without a trailing slash (http://server/myapp), you can use the above
 263 RewriteRule directive.
 264
 265 =head3 Static mode
 266
 267 The term 'static' is misleading, but in static mode Apache uses its own
 268 FastCGI Process Manager to start the application processes.  This happens at
 269 Apache startup time.  In this case you do not run your application's
 270 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
 271 FastCGI script to run your application.
 272
 273     FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
 274     Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
 275
 276 FastCgiServer tells Apache to start three processes of your application at
 277 startup.  The Alias command maps a path to the FastCGI application. Again,
 278 the trailing slashes are important.
 279
 280 =head3 Dynamic mode
 281
 282 In FastCGI dynamic mode, Apache will run your application on demand,
 283 typically by requesting a file with a specific extension (e.g. .fcgi).  ISPs
 284 often use this type of setup to provide FastCGI support to many customers.
 285
 286 In this mode it is often enough to place or link your *_fastcgi.pl script in
 287 your cgi-bin directory with the extension of .fcgi.  In dynamic mode Apache
 288 must be able to run your application as a CGI script so ExecCGI must be
 289 enabled for the directory.
 290
 291     AddHandler fastcgi-script .fcgi
 292
 293 The above tells Apache to run any .fcgi file as a FastCGI application.
 294
 295 Here is a complete example:
 296
 297     <VirtualHost *:80>
 298         ServerName www.myapp.com
 299         DocumentRoot /path/to/MyApp
 300
 301         # Allow CGI script to run
 302         <Directory /path/to/MyApp>
 303             Options +ExecCGI
 304         </Directory>
 305
 306         # Tell Apache this is a FastCGI application
 307         <Files myapp_fastcgi.pl>
 308             SetHandler fastcgi-script
 309         </Files>
 310     </VirtualHost>
 311
 312 Then a request for /script/myapp_fastcgi.pl will run the
 313 application.
 314
 315 For more information on using FastCGI under Apache, visit
 316 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
 317
 318 =head2 Lighttpd
 319
 320 These configurations were tested with Lighttpd 1.4.7.
 321
 322 =head3 Standalone server mode
 323
 324     server.document-root = "/var/www/MyApp/root"
 325
 326     fastcgi.server = (
 327         "" => (
 328             "MyApp" => (
 329                 "socket"      => "/tmp/myapp.socket",
 330                 "check-local" => "disable"
 331             )
 332         )
 333     )
 334
 335 =head3 Static mode
 336
 337     server.document-root = "/var/www/MyApp/root"
 338
 339     fastcgi.server = (
 340         "" => (
 341             "MyApp" => (
 342                 "socket"       => "/tmp/myapp.socket",
 343                 "check-local"  => "disable",
 344                 "bin-path"     => "/var/www/MyApp/script/myapp_fastcgi.pl",
 345                 "min-procs"    => 2,
 346                 "max-procs"    => 5,
 347                 "idle-timeout" => 20
 348             )
 349         )
 350     )
 351
 352 Note that in newer versions of lighttpd, the min-procs and idle-timeout
 353 values are disabled.  The above example would start 5 processes.
 354
 355 =head3 Non-root configuration
 356
 357 You can also run your application at any non-root location with either of the
 358 above modes.
 359
 360     fastcgi.server = (
 361         "/myapp" => (
 362             "MyApp" => (
 363                 # same as above
 364             )
 365         )
 366     )
 367
 368 For more information on using FastCGI under Lighttpd, visit
 369 L<http://www.lighttpd.net/documentation/fastcgi.html>
 370
 371 =head2 IIS
 372
 373 It is possible to run Catalyst under IIS with FastCGI, but we do not
 374 yet have detailed instructions.
 375
 376 =head1 SEE ALSO
 377
 378 L<Catalyst>, L<FCGI>.
 379
 380 =head1 AUTHORS
 381
 382 Sebastian Riedel, <sri@cpan.org>
 383
 384 Christian Hansen, <ch@ngmedia.com>
 385
 386 Andy Grundman, <andy@hybridized.org>
 387
 388 =head1 THANKS
 389
 390 Bill Moseley, for documentation updates and testing.
 391
 392 =head1 COPYRIGHT
 393
 394 This program is free software, you can redistribute it and/or modify it under
 395 the same terms as Perl itself.
 396
 397 =cut