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