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