Commit | Line | Data |
d1d9793f |
1 | package Catalyst::Engine::FastCGI; |
ffb41d94 |
2 | |
3 | use strict; |
fbcc39ad |
4 | use base 'Catalyst::Engine::CGI'; |
6f409682 |
5 | eval "use FCGI"; |
6 | die "Please install FCGI\n" if $@; |
ffb41d94 |
7 | |
8 | =head1 NAME |
9 | |
fbcc39ad |
10 | Catalyst::Engine::FastCGI - FastCGI Engine |
ffb41d94 |
11 | |
12 | =head1 DESCRIPTION |
13 | |
fbcc39ad |
14 | This is the FastCGI engine. |
ffb41d94 |
15 | |
e2fd5b5f |
16 | =head1 OVERLOADED METHODS |
17 | |
fbcc39ad |
18 | This class overloads some methods from C<Catalyst::Engine::CGI>. |
e2fd5b5f |
19 | |
20 | =over 4 |
21 | |
5898abae |
22 | =item $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 | Form Meaning |
28 | /path listen via Unix sockets on /path |
29 | :port listen via TCP on port on all interfaces |
30 | hostname:port listen via TCP on port bound to hostname |
31 | |
32 | Options may also be specified; |
33 | |
34 | Option Meaning |
35 | leave_umask Set to 1 to disable setting umask to 0 |
36 | for socket open |
37 | nointr Do not allow the listener to be |
38 | interrupted by Ctrl+C |
39 | nproc Specify a number of processes for |
40 | FCGI::ProcManager |
dc2fc680 |
41 | pidfile Specify a filename for the pid file |
526b698a |
42 | manager Specify a FCGI::ProcManager sub-class |
43 | detach Detach from console |
e2fd5b5f |
44 | |
45 | =cut |
46 | |
fbcc39ad |
47 | sub run { |
5898abae |
48 | my ( $self, $class, $listen, $options ) = @_; |
49 | |
50 | my $sock; |
51 | if ($listen) { |
52 | my $old_umask = umask; |
53 | unless ( $options->{leave_umask} ) { |
54 | umask(0); |
55 | } |
56 | $sock = FCGI::OpenSocket( $listen, 100 ) |
57 | or die "failed to open FastCGI socket; $!"; |
58 | unless ( $options->{leave_umask} ) { |
59 | umask($old_umask); |
60 | } |
61 | } |
62 | else { |
63 | -S STDIN |
64 | or die "STDIN is not a socket; specify a listen location"; |
65 | } |
66 | |
67 | $options ||= {}; |
6f409682 |
68 | |
84528885 |
69 | my %env; |
e2fd5b5f |
70 | |
5898abae |
71 | my $request = |
84528885 |
72 | FCGI::Request( \*STDIN, \*STDOUT, \*STDERR, \%env, $sock, |
5898abae |
73 | ( $options->{nointr} ? 0 : &FCGI::FAIL_ACCEPT_ON_INTR ), |
74 | ); |
75 | |
76 | my $proc_manager; |
6f409682 |
77 | |
78 | if ($listen) { |
526b698a |
79 | $options->{manager} ||= "FCGI::ProcManager"; |
80 | $options->{nproc} ||= 1; |
81 | |
82 | $self->daemon_fork() if $options->{detach}; |
83 | |
84 | if ( $options->{manager} ) { |
85 | eval "use $options->{manager}; 1" or die $@; |
86 | |
87 | $proc_manager |
88 | = $options->{manager}->new( { |
89 | n_processes => $options->{nproc}, |
90 | pid_fname => $options->{pidfile}, |
91 | } ); |
92 | |
93 | # detach *before* the ProcManager inits |
94 | $self->daemon_detach() if $options->{detach}; |
95 | |
96 | $proc_manager->pm_manage(); |
dc2fc680 |
97 | } |
526b698a |
98 | elsif ( $options->{detach} ) { |
99 | $self->daemon_detach(); |
100 | } |
5898abae |
101 | } |
e2fd5b5f |
102 | |
fbcc39ad |
103 | while ( $request->Accept >= 0 ) { |
5898abae |
104 | $proc_manager && $proc_manager->pm_pre_dispatch(); |
84528885 |
105 | $class->handle_request( env => \%env ); |
5898abae |
106 | $proc_manager && $proc_manager->pm_pre_dispatch(); |
fbcc39ad |
107 | } |
e2fd5b5f |
108 | } |
109 | |
fbcc39ad |
110 | =item $self->write($c, $buffer) |
e2fd5b5f |
111 | |
112 | =cut |
113 | |
fbcc39ad |
114 | sub write { |
115 | my ( $self, $c, $buffer ) = @_; |
4f5ebacd |
116 | |
fbcc39ad |
117 | unless ( $self->{_prepared_write} ) { |
4f5ebacd |
118 | $self->prepare_write($c); |
fbcc39ad |
119 | $self->{_prepared_write} = 1; |
120 | } |
4f5ebacd |
121 | |
fbcc39ad |
122 | # FastCGI does not stream data properly if using 'print $handle', |
123 | # but a syswrite appears to work properly. |
4f5ebacd |
124 | *STDOUT->syswrite($buffer); |
e2fd5b5f |
125 | } |
126 | |
526b698a |
127 | =item $self->daemon_fork() |
128 | |
129 | Performs the first part of daemon initialisation. Specifically, |
130 | forking. STDERR, etc are still connected to a terminal. |
131 | |
132 | =cut |
133 | |
134 | sub daemon_fork { |
135 | require POSIX; |
136 | fork && exit; |
137 | } |
138 | |
139 | =item $self->daemon_detach( ) |
140 | |
141 | Performs the second part of daemon initialisation. Specifically, |
142 | disassociates from the terminal. |
143 | |
144 | However, this does B<not> change the current working directory to "/", |
145 | as normal daemons do. It also does not close all open file |
146 | descriptors (except STDIN, STDOUT and STDERR, which are re-opened from |
147 | F</dev/null>). |
148 | |
149 | =cut |
150 | |
151 | sub daemon_detach { |
152 | my $self = shift; |
153 | print "FastCGI daemon started (pid $$)\n"; |
154 | open STDIN, "+</dev/null" or die $!; |
155 | open STDOUT, ">&STDIN" or die $!; |
156 | open STDERR, ">&STDIN" or die $!; |
157 | POSIX::setsid(); |
158 | } |
159 | |
198b0efa |
160 | 1; |
161 | __END__ |
162 | |
fbcc39ad |
163 | =back |
e2fd5b5f |
164 | |
198b0efa |
165 | =head1 WEB SERVER CONFIGURATIONS |
166 | |
167 | =head2 Apache 1.x, 2.x |
168 | |
169 | Apache requires the mod_fastcgi module. The following config will let Apache |
170 | control the running of your FastCGI processes. |
171 | |
172 | # Launch the FastCGI processes |
173 | FastCgiIpcDir /tmp |
8f753f10 |
174 | FastCgiServer /var/www/MyApp/script/myapp_fastcgi.pl -idle-timeout 300 -processes 5 |
198b0efa |
175 | |
176 | <VirtualHost *> |
177 | ScriptAlias / /var/www/MyApp/script/myapp_fastcgi.pl/ |
178 | </VirtualHost> |
179 | |
180 | You can also tell Apache to connect to an external FastCGI server: |
181 | |
182 | # Start the external server (requires FCGI::ProcManager) |
183 | $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 |
184 | |
185 | # Note that the path used in FastCgiExternalServer can be any path |
186 | FastCgiIpcDir /tmp |
187 | FastCgiExternalServer /tmp/myapp_fastcgi.pl -socket /tmp/myapp.socket |
188 | |
189 | <VirtualHost *> |
190 | ScriptAlias / /tmp/myapp_fastcgi.pl/ |
191 | </VirtualHost> |
192 | |
193 | For more information on using FastCGI under Apache, visit |
194 | L<http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html> |
195 | |
196 | =head2 Lighttpd |
197 | |
198 | This configuration was tested with Lighttpd 1.4.7. |
199 | |
200 | server.document-root = "/var/www/MyApp/root" |
201 | |
202 | fastcgi.server = ( |
203 | "" => ( |
204 | "MyApp" => ( |
205 | "socket" => "/tmp/myapp.socket", |
206 | "check-local" => "disable", |
207 | "bin-path" => "/var/www/MyApp/script/myapp_fastcgi.pl", |
208 | "min-procs" => 2, |
209 | "max-procs" => 5, |
210 | "idle-timeout" => 20 |
211 | ) |
212 | ) |
213 | ) |
214 | |
25810c41 |
215 | You can also run your application at any non-root location. |
216 | |
217 | fastcgi.server = ( |
218 | "/myapp" => ( |
219 | "MyApp" => ( |
220 | # same as above |
221 | ) |
222 | ) |
223 | ) |
224 | |
225 | You can also use an external server: |
198b0efa |
226 | |
227 | # Start the external server (requires FCGI::ProcManager) |
228 | $ script/myapp_fastcgi.pl -l /tmp/myapp.socket -n 5 |
229 | |
230 | server.document-root = "/var/www/MyApp/root" |
231 | |
232 | fastcgi.server = ( |
233 | "" => ( |
234 | "MyApp" => ( |
235 | "socket" => "/tmp/myapp.socket", |
236 | "check-local" => "disable" |
237 | ) |
238 | ) |
239 | ) |
240 | |
241 | For more information on using FastCGI under Lighttpd, visit |
242 | L<http://www.lighttpd.net/documentation/fastcgi.html> |
243 | |
244 | =head2 IIS |
245 | |
246 | It is possible to run Catalyst under IIS with FastCGI, but we do not |
247 | yet have detailed instructions. |
248 | |
fbcc39ad |
249 | =head1 SEE ALSO |
e2fd5b5f |
250 | |
fbcc39ad |
251 | L<Catalyst>, L<FCGI>. |
cd3bb248 |
252 | |
fbcc39ad |
253 | =head1 AUTHORS |
ffb41d94 |
254 | |
fbcc39ad |
255 | Sebastian Riedel, <sri@cpan.org> |
ffb41d94 |
256 | |
fbcc39ad |
257 | Christian Hansen, <ch@ngmedia.com> |
ffb41d94 |
258 | |
fbcc39ad |
259 | Andy Grundman, <andy@hybridized.org> |
ffb41d94 |
260 | |
261 | =head1 COPYRIGHT |
262 | |
263 | This program is free software, you can redistribute it and/or modify it under |
264 | the same terms as Perl itself. |
265 | |
266 | =cut |