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 "Please install FCGI\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 -socket /tmp/myapp.socket
 241     Alias /myapp/ /tmp/myapp/
 242
 243     # Or, run at the root
 244     Alias / /tmp/myapp/
 245
 246     # Optionally, rewrite the path when accessed without a trailing slash
 247     RewriteRule ^/myapp$ myapp/ [R]
 248
 249 The FastCgiExternalServer directive tells Apache that when serving /tmp/myapp
 250 to use the FastCGI application listenting on the socket /tmp/mapp.socket.
 251 Note that /tmp/myapp does not need to exist -- it's a virtual file name.
 252
 253 It's likely that Apache is not configured to serve files in /tmp, so the
 254 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
 255 FastCGI application. The trailing slashes are important as their use will
 256 correctly set the PATH_INFO environment variable used by Catalyst to
 257 determine the request path.  If you would like to be able to access your app
 258 without a trailing slash (http://server/myapp), you can use the above
 259 RewriteRule directive.
 260
 261 =head3 Static mode
 262
 263 The term 'static' is misleading, but in static mode Apache uses its own
 264 FastCGI Process Manager to start the application processes.  This happens at
 265 Apache startup time.  In this case you do not run your application's
 266 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
 267 FastCGI script to run your application.
 268
 269     FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
 270     Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
 271
 272 FastCgiServer tells Apache to start three processes of your application at
 273 startup.  The Alias command maps a path to the FastCGI application. Again,
 274 the trailing slashes are important.
 275
 276 =head3 Dynamic mode
 277
 278 In FastCGI dynamic mode, Apache will run your application on demand,
 279 typically by requesting a file with a specific extension (e.g. .fcgi).  ISPs
 280 often use this type of setup to provide FastCGI support to many customers.
 281
 282 In this mode it is often enough to place or link your *_fastcgi.pl script in
 283 your cgi-bin directory with the extension of .fcgi.  In dynamic mode Apache
 284 must be able to run your application as a CGI script so ExecCGI must be
 285 enabled for the directory.
 286
 287     AddHandler fastcgi-script .fcgi
 288
 289 The above tells Apache to run any .fcgi file as a FastCGI application.
 290
 291 Here is a complete example:
 292
 293     <VirtualHost *:80>
 294         ServerName www.myapp.com
 295         DocumentRoot /path/to/MyApp
 296
 297         # Allow CGI script to run
 298         <Directory /path/to/MyApp>
 299             Options +ExecCGI
 300         </Directory>
 301
 302         # Tell Apache this is a FastCGI application
 303         <Files myapp_fastcgi.pl>
 304             SetHandler fastcgi-script
 305         </Files>
 306     </VirtualHost>
 307
 308 Then a request for /script/myapp_fastcgi.pl will run the
 309 application.
 310
 311 For more information on using FastCGI under Apache, visit
 312 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
 313
 314 =head2 Lighttpd
 315
 316 These configurations were tested with Lighttpd 1.4.7.
 317
 318 =head3 Standalone server mode
 319
 320     server.document-root = "/var/www/MyApp/root"
 321
 322     fastcgi.server = (
 323         "" => (
 324             "MyApp" => (
 325                 "socket"      => "/tmp/myapp.socket",
 326                 "check-local" => "disable"
 327             )
 328         )
 329     )
 330
 331 =head3 Static mode
 332
 333     server.document-root = "/var/www/MyApp/root"
 334
 335     fastcgi.server = (
 336         "" => (
 337             "MyApp" => (
 338                 "socket"       => "/tmp/myapp.socket",
 339                 "check-local"  => "disable",
 340                 "bin-path"     => "/var/www/MyApp/script/myapp_fastcgi.pl",
 341                 "min-procs"    => 2,
 342                 "max-procs"    => 5,
 343                 "idle-timeout" => 20
 344             )
 345         )
 346     )
 347
 348 Note that in newer versions of lighttpd, the min-procs and idle-timeout
 349 values are disabled.  The above example would start 5 processes.
 350
 351 =head3 Non-root configuration
 352
 353 You can also run your application at any non-root location with either of the
 354 above modes.
 355
 356     fastcgi.server = (
 357         "/myapp" => (
 358             "MyApp" => (
 359                 # same as above
 360             )
 361         )
 362     )
 363
 364 For more information on using FastCGI under Lighttpd, visit
 365 L<http://www.lighttpd.net/documentation/fastcgi.html>
 366
 367 =head2 IIS
 368
 369 It is possible to run Catalyst under IIS with FastCGI, but we do not
 370 yet have detailed instructions.
 371
 372 =head1 SEE ALSO
 373
 374 L<Catalyst>, L<FCGI>.
 375
 376 =head1 AUTHORS
 377
 378 Sebastian Riedel, <sri@cpan.org>
 379
 380 Christian Hansen, <ch@ngmedia.com>
 381
 382 Andy Grundman, <andy@hybridized.org>
 383
 384 =head1 THANKS
 385
 386 Bill Moseley, for documentation updates and testing.
 387
 388 =head1 COPYRIGHT
 389
 390 This program is free software, you can redistribute it and/or modify it under
 391 the same terms as Perl itself.
 392
 393 =cut