lib/Catalyst/Engine/FastCGI.pm

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