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