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         $options->{proc_title} ||= "perl-fcgi-pm [$class]";
 117
 118         $self->daemon_fork() if $options->{detach};
 119
 120         if ( $options->{manager} ) {
 121             eval "use $options->{manager}; 1" or die $@;
 122
 123             $proc_manager = $options->{manager}->new(
 124                 {
 125                     n_processes => $options->{nproc},
 126                     pid_fname   => $options->{pidfile},
 127                     pm_title => $options->{proc_title},
 128                 }
 129             );
 130
 131             # detach *before* the ProcManager inits
 132             $self->daemon_detach() if $options->{detach};
 133
 134             $proc_manager->pm_manage();
 135
 136             # Give each child its own RNG state.
 137             srand;
 138         }
 139         elsif ( $options->{detach} ) {
 140             $self->daemon_detach();
 141         }
 142     }
 143
 144     while ( $request->Accept >= 0 ) {
 145         $proc_manager && $proc_manager->pm_pre_dispatch();
 146
 147         $self->_fix_env( \%env );
 148
 149         $class->handle_request( env => \%env );
 150
 151         $proc_manager && $proc_manager->pm_post_dispatch();
 152     }
 153 }
 154
 155 =head2 $self->write($c, $buffer)
 156
 157 =cut
 158
 159 sub write {
 160     my ( $self, $c, $buffer ) = @_;
 161
 162     unless ( $self->_prepared_write ) {
 163         $self->prepare_write($c);
 164         $self->_prepared_write(1);
 165     }
 166
 167     # XXX: We can't use Engine's write() method because syswrite
 168     # appears to return bogus values instead of the number of bytes
 169     # written: http://www.fastcgi.com/om_archive/mail-archive/0128.html
 170
 171     # Prepend the headers if they have not yet been sent
 172     if ( $self->_has_header_buf ) {
 173         $buffer = $self->_clear_header_buf . $buffer;
 174     }
 175
 176     # FastCGI does not stream data properly if using 'print $handle',
 177     # but a syswrite appears to work properly.
 178     *STDOUT->syswrite($buffer);
 179 }
 180
 181 =head2 $self->daemon_fork()
 182
 183 Performs the first part of daemon initialisation.  Specifically,
 184 forking.  STDERR, etc are still connected to a terminal.
 185
 186 =cut
 187
 188 sub daemon_fork {
 189     require POSIX;
 190     fork && exit;
 191 }
 192
 193 =head2 $self->daemon_detach( )
 194
 195 Performs the second part of daemon initialisation.  Specifically,
 196 disassociates from the terminal.
 197
 198 However, this does B<not> change the current working directory to "/",
 199 as normal daemons do.  It also does not close all open file
 200 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
 201 F</dev/null>).
 202
 203 =cut
 204
 205 sub daemon_detach {
 206     my $self = shift;
 207     print "FastCGI daemon started (pid $$)\n";
 208     open STDIN,  "+</dev/null" or die $!;
 209     open STDOUT, ">&STDIN"     or die $!;
 210     open STDERR, ">&STDIN"     or die $!;
 211     POSIX::setsid();
 212 }
 213
 214 =head2 $self->_fix_env( $env )
 215
 216 Adjusts the environment variables when necessary.
 217
 218 =cut
 219
 220 sub _fix_env
 221 {
 222     my $self = shift;
 223     my $env = shift;
 224
 225     # we are gonna add variables from current system environment %ENV to %env
 226     # that contains at this moment just variables taken from FastCGI request
 227     foreach my $k (keys(%ENV)) {
 228       $env->{$k} = $ENV{$k} unless defined($env->{$k});
 229     }
 230
 231     return unless ( $env->{SERVER_SOFTWARE} );
 232
 233     # If we're running under Lighttpd, swap PATH_INFO and SCRIPT_NAME
 234     # http://lists.scsys.co.uk/pipermail/catalyst/2006-June/008361.html
 235     # Thanks to Mark Blythe for this fix
 236     if ( $env->{SERVER_SOFTWARE} =~ /lighttpd/ ) {
 237         $env->{PATH_INFO} ||= delete $env->{SCRIPT_NAME};
 238     }
 239     elsif ( $env->{SERVER_SOFTWARE} =~ /^nginx/ ) {
 240         my $script_name = $env->{SCRIPT_NAME};
 241         $env->{PATH_INFO} =~ s/^$script_name//g;
 242     }
 243     # Fix the environment variables PATH_INFO and SCRIPT_NAME when running
 244     # under IIS
 245     elsif ( $env->{SERVER_SOFTWARE} =~ /IIS\/[6-9]\.[0-9]/ ) {
 246         my @script_name = split(m!/!, $env->{PATH_INFO});
 247         my @path_translated = split(m!/|\\\\?!, $env->{PATH_TRANSLATED});
 248         my @path_info;
 249
 250         while ($script_name[$#script_name] eq $path_translated[$#path_translated]) {
 251             pop(@path_translated);
 252             unshift(@path_info, pop(@script_name));
 253         }
 254
 255         unshift(@path_info, '', '');
 256
 257         $env->{PATH_INFO} = join('/', @path_info);
 258         $env->{SCRIPT_NAME} = join('/', @script_name);
 259     }
 260 }
 261
 262 1;
 263 __END__
 264
 265 =head1 WEB SERVER CONFIGURATIONS
 266
 267 =head2 Standalone FastCGI Server
 268
 269 In server mode the application runs as a standalone server and accepts
 270 connections from a web server.  The application can be on the same machine as
 271 the web server, on a remote machine, or even on multiple remote machines.
 272 Advantages of this method include running the Catalyst application as a
 273 different user than the web server, and the ability to set up a scalable
 274 server farm.
 275
 276 To start your application in server mode, install the FCGI::ProcManager
 277 module and then use the included fastcgi.pl script.
 278
 279     $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
 280
 281 Command line options for fastcgi.pl include:
 282
 283     -d -daemon     Daemonize the server.
 284     -p -pidfile    Write a pidfile with the pid of the process manager.
 285     -l -listen     Listen on a socket path, hostname:port, or :port.
 286     -n -nproc      The number of processes started to handle requests.
 287
 288 See below for the specific web server configurations for using the external
 289 server.
 290
 291 =head2 Apache 1.x, 2.x
 292
 293 Apache requires the mod_fastcgi module.  The same module supports both
 294 Apache 1 and 2.
 295
 296 There are three ways to run your application under FastCGI on Apache: server,
 297 static, and dynamic.
 298
 299 =head3 Standalone server mode
 300
 301     FastCgiExternalServer /tmp/myapp.fcgi -socket /tmp/myapp.socket
 302     Alias /myapp/ /tmp/myapp.fcgi/
 303
 304     # Or, run at the root
 305     Alias / /tmp/myapp.fcgi/
 306
 307     # Optionally, rewrite the path when accessed without a trailing slash
 308     RewriteRule ^/myapp$ myapp/ [R]
 309
 310
 311 The FastCgiExternalServer directive tells Apache that when serving
 312 /tmp/myapp to use the FastCGI application listenting on the socket
 313 /tmp/mapp.socket.  Note that /tmp/myapp.fcgi B<MUST NOT> exist --
 314 it's a virtual file name.  With some versions of C<mod_fastcgi> or
 315 C<mod_fcgid>, you can use any name you like, but some require that the
 316 virtual filename end in C<.fcgi>.
 317
 318 It's likely that Apache is not configured to serve files in /tmp, so the
 319 Alias directive maps the url path /myapp/ to the (virtual) file that runs the
 320 FastCGI application. The trailing slashes are important as their use will
 321 correctly set the PATH_INFO environment variable used by Catalyst to
 322 determine the request path.  If you would like to be able to access your app
 323 without a trailing slash (http://server/myapp), you can use the above
 324 RewriteRule directive.
 325
 326 =head3 Static mode
 327
 328 The term 'static' is misleading, but in static mode Apache uses its own
 329 FastCGI Process Manager to start the application processes.  This happens at
 330 Apache startup time.  In this case you do not run your application's
 331 fastcgi.pl script -- that is done by Apache. Apache then maps URIs to the
 332 FastCGI script to run your application.
 333
 334     FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl -processes 3
 335     Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/
 336
 337 FastCgiServer tells Apache to start three processes of your application at
 338 startup.  The Alias command maps a path to the FastCGI application. Again,
 339 the trailing slashes are important.
 340
 341 =head3 Dynamic mode
 342
 343 In FastCGI dynamic mode, Apache will run your application on demand,
 344 typically by requesting a file with a specific extension (e.g. .fcgi).  ISPs
 345 often use this type of setup to provide FastCGI support to many customers.
 346
 347 In this mode it is often enough to place or link your *_fastcgi.pl script in
 348 your cgi-bin directory with the extension of .fcgi.  In dynamic mode Apache
 349 must be able to run your application as a CGI script so ExecCGI must be
 350 enabled for the directory.
 351
 352     AddHandler fastcgi-script .fcgi
 353
 354 The above tells Apache to run any .fcgi file as a FastCGI application.
 355
 356 Here is a complete example:
 357
 358     <VirtualHost *:80>
 359         ServerName www.myapp.com
 360         DocumentRoot /path/to/MyApp
 361
 362         # Allow CGI script to run
 363         <Directory /path/to/MyApp>
 364             Options +ExecCGI
 365         </Directory>
 366
 367         # Tell Apache this is a FastCGI application
 368         <Files myapp_fastcgi.pl>
 369             SetHandler fastcgi-script
 370         </Files>
 371     </VirtualHost>
 372
 373 Then a request for /script/myapp_fastcgi.pl will run the
 374 application.
 375
 376 For more information on using FastCGI under Apache, visit
 377 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
 378
 379 =head3 Authorization header with mod_fastcgi or mod_cgi
 380
 381 By default, mod_fastcgi/mod_cgi do not pass along the Authorization header,
 382 so modules like C<Catalyst::Plugin::Authentication::Credential::HTTP> will
 383 not work.  To enable pass-through of this header, add the following
 384 mod_rewrite directives:
 385
 386     RewriteCond %{HTTP:Authorization} ^(.+)
 387     RewriteRule ^(.*)$ $1 [E=HTTP_AUTHORIZATION:%1,PT]
 388
 389 =head2 Lighttpd
 390
 391 These configurations were tested with Lighttpd 1.4.7.
 392
 393 =head3 Standalone server 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             )
 403         )
 404     )
 405
 406 =head3 Static mode
 407
 408     server.document-root = "/var/www/MyApp/root"
 409
 410     fastcgi.server = (
 411         "" => (
 412             "MyApp" => (
 413                 "socket"       => "/tmp/myapp.socket",
 414                 "check-local"  => "disable",
 415                 "bin-path"     => "/var/www/MyApp/script/myapp_fastcgi.pl",
 416                 "min-procs"    => 2,
 417                 "max-procs"    => 5,
 418                 "idle-timeout" => 20
 419             )
 420         )
 421     )
 422
 423 Note that in newer versions of lighttpd, the min-procs and idle-timeout
 424 values are disabled.  The above example would start 5 processes.
 425
 426 =head3 Non-root configuration
 427
 428 You can also run your application at any non-root location with either of the
 429 above modes.  Note the required mod_rewrite rule.
 430
 431     url.rewrite = ( "myapp\$" => "myapp/" )
 432     fastcgi.server = (
 433         "/myapp" => (
 434             "MyApp" => (
 435                 # same as above
 436             )
 437         )
 438     )
 439
 440 For more information on using FastCGI under Lighttpd, visit
 441 L<http://www.lighttpd.net/documentation/fastcgi.html>
 442
 443 =head2 nginx
 444
 445 Catalyst runs under nginx via FastCGI in a similar fashion as the lighttpd
 446 standalone server as described above.
 447
 448 nginx does not have its own internal FastCGI process manager, so you must run
 449 the FastCGI service separately.
 450
 451 =head3 Configuration
 452
 453 To configure nginx, you must configure the FastCGI parameters and also the
 454 socket your FastCGI daemon is listening on.  It can be either a TCP socket
 455 or a Unix file socket.
 456
 457 The server configuration block should look roughly like:
 458
 459     server {
 460         listen $port;
 461
 462         location / {
 463             fastcgi_param  QUERY_STRING       $query_string;
 464             fastcgi_param  REQUEST_METHOD     $request_method;
 465             fastcgi_param  CONTENT_TYPE       $content_type;
 466             fastcgi_param  CONTENT_LENGTH     $content_length;
 467
 468             fastcgi_param  SCRIPT_NAME        /;
 469             fastcgi_param  PATH_INFO          $fastcgi_script_name;
 470             fastcgi_param  REQUEST_URI        $request_uri;
 471             fastcgi_param  DOCUMENT_URI       $document_uri;
 472             fastcgi_param  DOCUMENT_ROOT      $document_root;
 473             fastcgi_param  SERVER_PROTOCOL    $server_protocol;
 474
 475             fastcgi_param  GATEWAY_INTERFACE  CGI/1.1;
 476             fastcgi_param  SERVER_SOFTWARE    nginx/$nginx_version;
 477
 478             fastcgi_param  REMOTE_ADDR        $remote_addr;
 479             fastcgi_param  REMOTE_PORT        $remote_port;
 480             fastcgi_param  SERVER_ADDR        $server_addr;
 481             fastcgi_param  SERVER_PORT        $server_port;
 482             fastcgi_param  SERVER_NAME        $server_name;
 483
 484             # Adjust the socket for your applications!
 485             fastcgi_pass   unix:$docroot/myapp.socket;
 486         }
 487     }
 488
 489 It is the standard convention of nginx to include the fastcgi_params in a
 490 separate file (usually something like C</etc/nginx/fastcgi_params>) and
 491 simply include that file.
 492
 493 =head3  Non-root configuration
 494
 495 If you properly specify the PATH_INFO and SCRIPT_NAME parameters your
 496 application will be accessible at any path. The SCRIPT_NAME variable is the
 497 prefix of your application, and PATH_INFO would be everything in addition.
 498
 499 As an example, if your application is rooted at /myapp, you would configure:
 500
 501     fastcgi_param  SCRIPT_NAME /myapp/;
 502     fastcgi_param  PATH_INFO   $fastcgi_script_name;
 503
 504 C<$fastcgi_script_name> would be "/myapp/path/of/the/action".  Catalyst will
 505 process this accordingly and setup the application base as expected.
 506
 507 This behavior is somewhat different than Apache and Lighttpd, but is still
 508 functional.
 509
 510 For more information on nginx, visit:
 511 L<http://nginx.net>
 512
 513 =head2 Microsoft IIS
 514
 515 It is possible to run Catalyst under IIS with FastCGI, but only on IIS 6.0
 516 (Microsoft Windows 2003), IIS 7.0 (Microsoft Windows 2008 and Vista) and
 517 hopefully its successors.
 518
 519 Even if it is declared that FastCGI is supported on IIS 5.1 (Windows XP) it
 520 does not support some features (specifically: wildcard mappings) that prevents
 521 running Catalyst application.
 522
 523 Let us assume that our server has the following layout:
 524
 525     d:\WWW\WebApp\                   path to our Catalyst application
 526     d:\strawberry\perl\bin\perl.exe  path to perl interpreter (with Catalyst installed)
 527     c:\windows                       Windows directory
 528
 529 =head3 Setup IIS 6.0 (Windows 2003)
 530
 531 =over 4
 532
 533 =item Install FastCGI extension for IIS 6.0
 534
 535 FastCGI is not a standard part of IIS 6 - you have to install it separately. For
 536 more info and download go to L<http://www.iis.net/extensions/FastCGI>. Choose
 537 approptiate version (32-bit/64-bit), installation is quite simple
 538 (in fact no questions, no options).
 539
 540 =item Create a new website
 541
 542 Open "Control Panel" > "Administrative Tools" > "Internet Information Services Manager".
 543 Click "Action" > "New" > "Web Site". After you finish the installation wizard
 544 you need to go to the new website's properties.
 545
 546 =item Set website properties
 547
 548 On tab "Web site" set proper values for:
 549 Site Description, IP Address, TCP Port, SSL Port etc.
 550
 551 On tab "Home Directory" set the following:
 552
 553     Local path: "d:\WWW\WebApp\root"
 554     Local path permission flags: check only "Read" + "Log visits"
 555     Execute permitions: "Scripts only"
 556
 557 Click "Configuration" button (still on Home Directory tab) then click "Insert"
 558 the wildcard application mapping and in the next dialog set:
 559
 560     Executable: "c:\windows\system32\inetsrv\fcgiext.dll"
 561     Uncheck: "Verify that file exists"
 562
 563 Close all dialogs with "OK".
 564
 565 =item Edit fcgiext.ini
 566
 567 Put the following lines into c:\windows\system32\inetsrv\fcgiext.ini (on 64-bit
 568 system c:\windows\syswow64\inetsrv\fcgiext.ini):
 569
 570     [Types]
 571     *:8=CatalystApp
 572     ;replace 8 with the identification number of the newly created website
 573     ;it is not so easy to get this number:
 574     ; - you can use utility "c:\inetpub\adminscripts\adsutil.vbs"
 575     ;   to list websites:   "cscript adsutil.vbs ENUM /P /W3SVC"
 576     ;   to get site name:   "cscript adsutil.vbs GET /W3SVC/<number>/ServerComment"
 577     ;   to get all details: "cscript adsutil.vbs GET /W3SVC/<number>"
 578     ; - or look where are the logs located:
 579     ;   c:\WINDOWS\SYSTEM32\Logfiles\W3SVC7\whatever.log
 580     ;   means that the corresponding number is "7"
 581     ;if you are running just one website using FastCGI you can use '*=CatalystApp'
 582
 583     [CatalystApp]
 584     ExePath=d:\strawberry\perl\bin\perl.exe
 585     Arguments="d:\WWW\WebApp\script\webapp_fastcgi.pl -e"
 586
 587     ;by setting this you can instruct IIS to serve Catalyst static files
 588     ;directly not via FastCGI (in case of any problems try 1)
 589     IgnoreExistingFiles=0
 590
 591     ;do not be fooled by Microsoft doc talking about "IgnoreExistingDirectories"
 592     ;that does not work and use "IgnoreDirectories" instead
 593     IgnoreDirectories=1
 594
 595 =back
 596
 597 =head3 Setup IIS 7.0 (Windows 2008 and Vista)
 598
 599 Microsoft IIS 7.0 has built-in support for FastCGI so you do not have to install
 600 any addons.
 601
 602 =over 4
 603
 604 =item Necessary steps during IIS7 installation
 605
 606 During IIS7 installation after you have added role "Web Server (IIS)"
 607 you need to check to install role feature "CGI" (do not be nervous that it is
 608 not FastCGI). If you already have IIS7 installed you can add "CGI" role feature
 609 through "Control panel" > "Programs and Features".
 610
 611 =item Create a new website
 612
 613 Open "Control Panel" > "Administrative Tools" > "Internet Information Services Manager"
 614 > "Add Web Site".
 615
 616     site name: "CatalystSite"
 617     content directory: "d:\WWW\WebApp\root"
 618     binding: set proper IP address, port etc.
 619
 620 =item Configure FastCGI
 621
 622 You can configure FastCGI extension using commandline utility
 623 "c:\windows\system32\inetsrv\appcmd.exe"
 624
 625 =over 4
 626
 627 =item Configuring section "fastCgi" (it is a global setting)
 628
 629   appcmd.exe set config -section:system.webServer/fastCgi /+"[fullPath='d:\strawberry\perl\bin\perl.exe',arguments='d:\www\WebApp\script\webapp_fastcgi.pl -e',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='1000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost
 630
 631 =item Configuring proper handler (it is a site related setting)
 632
 633   appcmd.exe set config "CatalystSite" -section:system.webServer/handlers /+"[name='CatalystFastCGI',path='*',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='d:\strawberry\perl\bin\perl.exe|d:\www\WebApp\script\webapp_fastcgi.pl -e',resourceType='Unspecified',requireAccess='Script']" /commit:apphost
 634
 635 Note: before launching the commands above do not forget to change site
 636 name and paths to values relevant for your server setup.
 637
 638 =back
 639
 640 =back
 641
 642 =head1 SEE ALSO
 643
 644 L<Catalyst>, L<FCGI>.
 645
 646 =head1 AUTHORS
 647
 648 Catalyst Contributors, see Catalyst.pm
 649
 650 =head1 THANKS
 651
 652 Bill Moseley, for documentation updates and testing.
 653
 654 =head1 COPYRIGHT
 655
 656 This library is free software. You can redistribute it and/or modify it under
 657 the same terms as Perl itself.
 658
 659 =cut