1 package Catalyst::Engine::FastCGI;
4 use base 'Catalyst::Engine::CGI';
6 die "Please install FCGI\n" if $@;
10 Catalyst::Engine::FastCGI - FastCGI Engine
14 This is the FastCGI engine.
16 =head1 OVERLOADED METHODS
18 This class overloads some methods from C<Catalyst::Engine::CGI>.
20 =head2 $self->run($c, $listen, { option => value, ... })
22 Starts the FastCGI server. If C<$listen> is set, then it specifies a
23 location to listen for FastCGI requests;
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
30 Options may also be specified;
33 leave_umask Set to 1 to disable setting umask to 0
35 nointr Do not allow the listener to be
37 nproc Specify a number of processes for
39 pidfile Specify a filename for the pid file
40 manager Specify a FCGI::ProcManager sub-class
41 detach Detach from console
46 my ( $self, $class, $listen, $options ) = @_;
50 my $old_umask = umask;
51 unless ( $options->{leave_umask} ) {
54 $sock = FCGI::OpenSocket( $listen, 100 )
55 or die "failed to open FastCGI socket; $!";
56 unless ( $options->{leave_umask} ) {
62 or die "STDIN is not a socket; specify a listen location";
70 FCGI::Request( \*STDIN, \*STDOUT, \*STDERR, \%env, $sock,
71 ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ),
77 $options->{manager} ||= "FCGI::ProcManager";
78 $options->{nproc} ||= 1;
80 $self->daemon_fork() if $options->{detach};
82 if ( $options->{manager} ) {
83 eval "use $options->{manager}; 1" or die $@;
85 $proc_manager = $options->{manager}->new(
87 n_processes => $options->{nproc},
88 pid_fname => $options->{pidfile},
92 # detach *before* the ProcManager inits
93 $self->daemon_detach() if $options->{detach};
95 $proc_manager->pm_manage();
97 elsif ( $options->{detach} ) {
98 $self->daemon_detach();
102 while ( $request->Accept >= 0 ) {
103 $proc_manager && $proc_manager->pm_pre_dispatch();
104 $class->handle_request( env => \%env );
105 $proc_manager && $proc_manager->pm_pre_dispatch();
109 =head2 $self->write($c, $buffer)
114 my ( $self, $c, $buffer ) = @_;
116 unless ( $self->{_prepared_write} ) {
117 $self->prepare_write($c);
118 $self->{_prepared_write} = 1;
121 # FastCGI does not stream data properly if using 'print $handle',
122 # but a syswrite appears to work properly.
123 *STDOUT->syswrite($buffer);
126 =head2 $self->daemon_fork()
128 Performs the first part of daemon initialisation. Specifically,
129 forking. STDERR, etc are still connected to a terminal.
138 =head2 $self->daemon_detach( )
140 Performs the second part of daemon initialisation. Specifically,
141 disassociates from the terminal.
143 However, this does B<not> change the current working directory to "/",
144 as normal daemons do. It also does not close all open file
145 descriptors (except STDIN, STDOUT and STDERR, which are re-opened from
152 print "FastCGI daemon started (pid $$)\n";
153 open STDIN, "+</dev/null" or die $!;
154 open STDOUT, ">&STDIN" or die $!;
155 open STDERR, ">&STDIN" or die $!;
162 =head1 WEB SERVER CONFIGURATIONS
164 =head2 Apache 1.x, 2.x
166 Apache requires the mod_fastcgi module. The following config will let Apache
167 control the running of your FastCGI processes.
169 # Launch the FastCGI processes
171 FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -idle-timeout 300 -processes 5
174 ScriptAlias / /var/www/MyApp/script/myapp_fastcgi.pl/
177 You can also tell Apache to connect to an external FastCGI server:
179 # Start the external server (requires FCGI::ProcManager)
180 $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
182 # Note that the path used in FastCgiExternalServer can be any path
184 FastCgiExternalServer /tmp/myapp_fastcgi.pl -socket /tmp/myapp.socket
187 ScriptAlias / /tmp/myapp_fastcgi.pl/
190 For more information on using FastCGI under Apache, visit
191 L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html>
195 This configuration was tested with Lighttpd 1.4.7.
197 server.document-root = "/var/www/MyApp/root"
202 "socket" => "/tmp/myapp.socket",
203 "check-local" => "disable",
204 "bin-path" => "/var/www/MyApp/script/myapp_fastcgi.pl",
212 You can also run your application at any non-root location.
222 You can also use an external server:
224 # Start the external server (requires FCGI::ProcManager)
225 $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5
227 server.document-root = "/var/www/MyApp/root"
232 "socket" => "/tmp/myapp.socket",
233 "check-local" => "disable"
238 For more information on using FastCGI under Lighttpd, visit
239 L<http://www.lighttpd.net/documentation/fastcgi.html>
243 It is possible to run Catalyst under IIS with FastCGI, but we do not
244 yet have detailed instructions.
248 L<Catalyst>, L<FCGI>.
252 Sebastian Riedel, <sri@cpan.org>
254 Christian Hansen, <ch@ngmedia.com>
256 Andy Grundman, <andy@hybridized.org>
260 This program is free software, you can redistribute it and/or modify it under
261 the same terms as Perl itself.