Commit | Line | Data |
3fea05b9 |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3 |
2 | .\" |
3 | .\" Standard preamble: |
4 | .\" ======================================================================== |
5 | .de Sh \" Subsection heading |
6 | .br |
7 | .if t .Sp |
8 | .ne 5 |
9 | .PP |
10 | \fB\\$1\fR |
11 | .PP |
12 | .. |
13 | .de Sp \" Vertical space (when we can't use .PP) |
14 | .if t .sp .5v |
15 | .if n .sp |
16 | .. |
17 | .de Vb \" Begin verbatim text |
18 | .ft CW |
19 | .nf |
20 | .ne \\$1 |
21 | .. |
22 | .de Ve \" End verbatim text |
23 | .ft R |
24 | .fi |
25 | .. |
26 | .\" Set up some character translations and predefined strings. \*(-- will |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. |
32 | .tr \(*W-|\(bv\*(Tr |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
34 | .ie n \{\ |
35 | . ds -- \(*W- |
36 | . ds PI pi |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
39 | . ds L" "" |
40 | . ds R" "" |
41 | . ds C` "" |
42 | . ds C' "" |
43 | 'br\} |
44 | .el\{\ |
45 | . ds -- \|\(em\| |
46 | . ds PI \(*p |
47 | . ds L" `` |
48 | . ds R" '' |
49 | 'br\} |
50 | .\" |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the |
54 | .\" output yourself in some meaningful fashion. |
55 | .if \nF \{\ |
56 | . de IX |
57 | . tm Index:\\$1\t\\n%\t"\\$2" |
58 | .. |
59 | . nr % 0 |
60 | . rr F |
61 | .\} |
62 | .\" |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
64 | .\" way too many mistakes in technical documents. |
65 | .hy 0 |
66 | .if n .na |
67 | .\" |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. |
70 | . \" fudge factors for nroff and troff |
71 | .if n \{\ |
72 | . ds #H 0 |
73 | . ds #V .8m |
74 | . ds #F .3m |
75 | . ds #[ \f1 |
76 | . ds #] \fP |
77 | .\} |
78 | .if t \{\ |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
80 | . ds #V .6m |
81 | . ds #F 0 |
82 | . ds #[ \& |
83 | . ds #] \& |
84 | .\} |
85 | . \" simple accents for nroff and troff |
86 | .if n \{\ |
87 | . ds ' \& |
88 | . ds ` \& |
89 | . ds ^ \& |
90 | . ds , \& |
91 | . ds ~ ~ |
92 | . ds / |
93 | .\} |
94 | .if t \{\ |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
101 | .\} |
102 | . \" troff and (daisy-wheel) nroff accents |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
110 | .ds ae a\h'-(\w'a'u*4/10)'e |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E |
112 | . \" corrections for vroff |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
115 | . \" for low resolution devices (crt and lpr) |
116 | .if \n(.H>23 .if \n(.V>19 \ |
117 | \{\ |
118 | . ds : e |
119 | . ds 8 ss |
120 | . ds o a |
121 | . ds d- d\h'-1'\(ga |
122 | . ds D- D\h'-1'\(hy |
123 | . ds th \o'bp' |
124 | . ds Th \o'LP' |
125 | . ds ae ae |
126 | . ds Ae AE |
127 | .\} |
128 | .rm #[ #] #H #V #F C |
129 | .\" ======================================================================== |
130 | .\" |
131 | .IX Title "Catalyst::Engine::FastCGI 3" |
132 | .TH Catalyst::Engine::FastCGI 3 "2009-12-02" "perl v5.8.7" "User Contributed Perl Documentation" |
133 | .SH "NAME" |
134 | Catalyst::Engine::FastCGI \- FastCGI Engine |
135 | .SH "DESCRIPTION" |
136 | .IX Header "DESCRIPTION" |
137 | This is the FastCGI engine. |
138 | .SH "OVERLOADED METHODS" |
139 | .IX Header "OVERLOADED METHODS" |
140 | This class overloads some methods from \f(CW\*(C`Catalyst::Engine::CGI\*(C'\fR. |
141 | .ie n .Sh "$self\->run($c, $listen, { option => value, ... })" |
142 | .el .Sh "$self\->run($c, \f(CW$listen\fP, { option => value, ... })" |
143 | .IX Subsection "$self->run($c, $listen, { option => value, ... })" |
144 | Starts the FastCGI server. If \f(CW$listen\fR is set, then it specifies a |
145 | location to listen for FastCGI requests; |
146 | .IP "/path" 4 |
147 | .IX Item "/path" |
148 | listen via Unix sockets on /path |
149 | .IP ":port" 4 |
150 | .IX Item ":port" |
151 | listen via \s-1TCP\s0 on port on all interfaces |
152 | .IP "hostname:port" 4 |
153 | .IX Item "hostname:port" |
154 | listen via \s-1TCP\s0 on port bound to hostname |
155 | .PP |
156 | Options may also be specified; |
157 | .IP "leave_umask" 4 |
158 | .IX Item "leave_umask" |
159 | Set to 1 to disable setting umask to 0 for socket open |
160 | .IP "nointr" 4 |
161 | .IX Item "nointr" |
162 | Do not allow the listener to be interrupted by Ctrl+C |
163 | .IP "nproc" 4 |
164 | .IX Item "nproc" |
165 | Specify a number of processes for FCGI::ProcManager |
166 | .IP "pidfile" 4 |
167 | .IX Item "pidfile" |
168 | Specify a filename for the pid file |
169 | .IP "manager" 4 |
170 | .IX Item "manager" |
171 | Specify a FCGI::ProcManager sub-class |
172 | .IP "detach" 4 |
173 | .IX Item "detach" |
174 | Detach from console |
175 | .IP "keep_stderr" 4 |
176 | .IX Item "keep_stderr" |
177 | Send \s-1STDERR\s0 to \s-1STDOUT\s0 instead of the webserver |
178 | .ie n .Sh "$self\->write($c, $buffer)" |
179 | .el .Sh "$self\->write($c, \f(CW$buffer\fP)" |
180 | .IX Subsection "$self->write($c, $buffer)" |
181 | .Sh "$self\->\fIdaemon_fork()\fP" |
182 | .IX Subsection "$self->daemon_fork()" |
183 | Performs the first part of daemon initialisation. Specifically, |
184 | forking. \s-1STDERR\s0, etc are still connected to a terminal. |
185 | .Sh "$self\->daemon_detach( )" |
186 | .IX Subsection "$self->daemon_detach( )" |
187 | Performs the second part of daemon initialisation. Specifically, |
188 | disassociates from the terminal. |
189 | .PP |
190 | However, this does \fBnot\fR change the current working directory to \*(L"/\*(R", |
191 | as normal daemons do. It also does not close all open file |
192 | descriptors (except \s-1STDIN\s0, \s-1STDOUT\s0 and \s-1STDERR\s0, which are re-opened from |
193 | \&\fI/dev/null\fR). |
194 | .ie n .Sh "$self\->_fix_env( $env )" |
195 | .el .Sh "$self\->_fix_env( \f(CW$env\fP )" |
196 | .IX Subsection "$self->_fix_env( $env )" |
197 | Adjusts the environment variables when necessary. |
198 | .SH "WEB SERVER CONFIGURATIONS" |
199 | .IX Header "WEB SERVER CONFIGURATIONS" |
200 | .Sh "Standalone FastCGI Server" |
201 | .IX Subsection "Standalone FastCGI Server" |
202 | In server mode the application runs as a standalone server and accepts |
203 | connections from a web server. The application can be on the same machine as |
204 | the web server, on a remote machine, or even on multiple remote machines. |
205 | Advantages of this method include running the Catalyst application as a |
206 | different user than the web server, and the ability to set up a scalable |
207 | server farm. |
208 | .PP |
209 | To start your application in server mode, install the FCGI::ProcManager |
210 | module and then use the included fastcgi.pl script. |
211 | .PP |
212 | .Vb 1 |
213 | \& $ script/myapp_fastcgi.pl \-l /tmp/myapp.socket \-n 5 |
214 | .Ve |
215 | .PP |
216 | Command line options for fastcgi.pl include: |
217 | .PP |
218 | .Vb 4 |
219 | \& \-d \-daemon Daemonize the server. |
220 | \& \-p \-pidfile Write a pidfile with the pid of the process manager. |
221 | \& \-l \-listen Listen on a socket path, hostname:port, or :port. |
222 | \& \-n \-nproc The number of processes started to handle requests. |
223 | .Ve |
224 | .PP |
225 | See below for the specific web server configurations for using the external |
226 | server. |
227 | .Sh "Apache 1.x, 2.x" |
228 | .IX Subsection "Apache 1.x, 2.x" |
229 | Apache requires the mod_fastcgi module. The same module supports both |
230 | Apache 1 and 2. |
231 | .PP |
232 | There are three ways to run your application under FastCGI on Apache: server, |
233 | static, and dynamic. |
234 | .PP |
235 | \fIStandalone server mode\fR |
236 | .IX Subsection "Standalone server mode" |
237 | .PP |
238 | .Vb 2 |
239 | \& FastCgiExternalServer /tmp/myapp.fcgi \-socket /tmp/myapp.socket |
240 | \& Alias /myapp/ /tmp/myapp/myapp.fcgi/ |
241 | .Ve |
242 | .PP |
243 | .Vb 2 |
244 | \& # Or, run at the root |
245 | \& Alias / /tmp/myapp.fcgi/ |
246 | .Ve |
247 | .PP |
248 | .Vb 2 |
249 | \& # Optionally, rewrite the path when accessed without a trailing slash |
250 | \& RewriteRule ^/myapp$ myapp/ [R] |
251 | .Ve |
252 | .PP |
253 | The FastCgiExternalServer directive tells Apache that when serving |
254 | /tmp/myapp to use the FastCGI application listenting on the socket |
255 | /tmp/mapp.socket. Note that /tmp/myapp.fcgi \fB\s-1MUST\s0 \s-1NOT\s0\fR exist \*(-- |
256 | it's a virtual file name. With some versions of \f(CW\*(C`mod_fastcgi\*(C'\fR or |
257 | \&\f(CW\*(C`mod_fcgid\*(C'\fR, you can use any name you like, but some require that the |
258 | virtual filename end in \f(CW\*(C`.fcgi\*(C'\fR. |
259 | .PP |
260 | It's likely that Apache is not configured to serve files in /tmp, so the |
261 | Alias directive maps the url path /myapp/ to the (virtual) file that runs the |
262 | FastCGI application. The trailing slashes are important as their use will |
263 | correctly set the \s-1PATH_INFO\s0 environment variable used by Catalyst to |
264 | determine the request path. If you would like to be able to access your app |
265 | without a trailing slash (http://server/myapp), you can use the above |
266 | RewriteRule directive. |
267 | .PP |
268 | \fIStatic mode\fR |
269 | .IX Subsection "Static mode" |
270 | .PP |
271 | The term 'static' is misleading, but in static mode Apache uses its own |
272 | FastCGI Process Manager to start the application processes. This happens at |
273 | Apache startup time. In this case you do not run your application's |
274 | fastcgi.pl script \*(-- that is done by Apache. Apache then maps URIs to the |
275 | FastCGI script to run your application. |
276 | .PP |
277 | .Vb 2 |
278 | \& FastCgiServer /path/to/myapp/script/myapp_fastcgi.pl \-processes 3 |
279 | \& Alias /myapp/ /path/to/myapp/script/myapp_fastcgi.pl/ |
280 | .Ve |
281 | .PP |
282 | FastCgiServer tells Apache to start three processes of your application at |
283 | startup. The Alias command maps a path to the FastCGI application. Again, |
284 | the trailing slashes are important. |
285 | .PP |
286 | \fIDynamic mode\fR |
287 | .IX Subsection "Dynamic mode" |
288 | .PP |
289 | In FastCGI dynamic mode, Apache will run your application on demand, |
290 | typically by requesting a file with a specific extension (e.g. .fcgi). ISPs |
291 | often use this type of setup to provide FastCGI support to many customers. |
292 | .PP |
293 | In this mode it is often enough to place or link your *_fastcgi.pl script in |
294 | your cgi-bin directory with the extension of .fcgi. In dynamic mode Apache |
295 | must be able to run your application as a \s-1CGI\s0 script so ExecCGI must be |
296 | enabled for the directory. |
297 | .PP |
298 | .Vb 1 |
299 | \& AddHandler fastcgi\-script .fcgi |
300 | .Ve |
301 | .PP |
302 | The above tells Apache to run any .fcgi file as a FastCGI application. |
303 | .PP |
304 | Here is a complete example: |
305 | .PP |
306 | .Vb 3 |
307 | \& <VirtualHost *:80> |
308 | \& ServerName www.myapp.com |
309 | \& DocumentRoot /path/to/MyApp |
310 | .Ve |
311 | .PP |
312 | .Vb 4 |
313 | \& # Allow CGI script to run |
314 | \& <Directory /path/to/MyApp> |
315 | \& Options +ExecCGI |
316 | \& </Directory> |
317 | .Ve |
318 | .PP |
319 | .Vb 5 |
320 | \& # Tell Apache this is a FastCGI application |
321 | \& <Files myapp_fastcgi.pl> |
322 | \& SetHandler fastcgi\-script |
323 | \& </Files> |
324 | \& </VirtualHost> |
325 | .Ve |
326 | .PP |
327 | Then a request for /script/myapp_fastcgi.pl will run the |
328 | application. |
329 | .PP |
330 | For more information on using FastCGI under Apache, visit |
331 | <http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html> |
332 | .PP |
333 | \fIAuthorization header with mod_fastcgi or mod_cgi\fR |
334 | .IX Subsection "Authorization header with mod_fastcgi or mod_cgi" |
335 | .PP |
336 | By default, mod_fastcgi/mod_cgi do not pass along the Authorization header, |
337 | so modules like \f(CW\*(C`Catalyst::Plugin::Authentication::Credential::HTTP\*(C'\fR will |
338 | not work. To enable pass-through of this header, add the following |
339 | mod_rewrite directives: |
340 | .PP |
341 | .Vb 2 |
342 | \& RewriteCond %{HTTP:Authorization} ^(.+) |
343 | \& RewriteRule ^(.*)$ $1 [E=HTTP_AUTHORIZATION:%1,PT] |
344 | .Ve |
345 | .Sh "Lighttpd" |
346 | .IX Subsection "Lighttpd" |
347 | These configurations were tested with Lighttpd 1.4.7. |
348 | .PP |
349 | \fIStandalone server mode\fR |
350 | .IX Subsection "Standalone server mode" |
351 | .PP |
352 | .Vb 1 |
353 | \& server.document\-root = "/var/www/MyApp/root" |
354 | .Ve |
355 | .PP |
356 | .Vb 8 |
357 | \& fastcgi.server = ( |
358 | \& "" => ( |
359 | \& "MyApp" => ( |
360 | \& "socket" => "/tmp/myapp.socket", |
361 | \& "check\-local" => "disable" |
362 | \& ) |
363 | \& ) |
364 | \& ) |
365 | .Ve |
366 | .PP |
367 | \fIStatic mode\fR |
368 | .IX Subsection "Static mode" |
369 | .PP |
370 | .Vb 1 |
371 | \& server.document\-root = "/var/www/MyApp/root" |
372 | .Ve |
373 | .PP |
374 | .Vb 12 |
375 | \& fastcgi.server = ( |
376 | \& "" => ( |
377 | \& "MyApp" => ( |
378 | \& "socket" => "/tmp/myapp.socket", |
379 | \& "check\-local" => "disable", |
380 | \& "bin\-path" => "/var/www/MyApp/script/myapp_fastcgi.pl", |
381 | \& "min\-procs" => 2, |
382 | \& "max\-procs" => 5, |
383 | \& "idle\-timeout" => 20 |
384 | \& ) |
385 | \& ) |
386 | \& ) |
387 | .Ve |
388 | .PP |
389 | Note that in newer versions of lighttpd, the min-procs and idle-timeout |
390 | values are disabled. The above example would start 5 processes. |
391 | .PP |
392 | \fINon-root configuration\fR |
393 | .IX Subsection "Non-root configuration" |
394 | .PP |
395 | You can also run your application at any non-root location with either of the |
396 | above modes. Note the required mod_rewrite rule. |
397 | .PP |
398 | .Vb 8 |
399 | \& url.rewrite = ( "myapp\e$" => "myapp/" ) |
400 | \& fastcgi.server = ( |
401 | \& "/myapp" => ( |
402 | \& "MyApp" => ( |
403 | \& # same as above |
404 | \& ) |
405 | \& ) |
406 | \& ) |
407 | .Ve |
408 | .PP |
409 | For more information on using FastCGI under Lighttpd, visit |
410 | <http://www.lighttpd.net/documentation/fastcgi.html> |
411 | .Sh "nginx" |
412 | .IX Subsection "nginx" |
413 | Catalyst runs under nginx via FastCGI in a similar fashion as the lighttpd |
414 | standalone server as described above. |
415 | .PP |
416 | nginx does not have its own internal FastCGI process manager, so you must run |
417 | the FastCGI service separately. |
418 | .PP |
419 | \fIConfiguration\fR |
420 | .IX Subsection "Configuration" |
421 | .PP |
422 | To configure nginx, you must configure the FastCGI parameters and also the |
423 | socket your FastCGI daemon is listening on. It can be either a \s-1TCP\s0 socket |
424 | or a Unix file socket. |
425 | .PP |
426 | The server configuration block should look roughly like: |
427 | .PP |
428 | .Vb 2 |
429 | \& server { |
430 | \& listen $port; |
431 | .Ve |
432 | .PP |
433 | .Vb 5 |
434 | \& location / { |
435 | \& fastcgi_param QUERY_STRING $query_string; |
436 | \& fastcgi_param REQUEST_METHOD $request_method; |
437 | \& fastcgi_param CONTENT_TYPE $content_type; |
438 | \& fastcgi_param CONTENT_LENGTH $content_length; |
439 | .Ve |
440 | .PP |
441 | .Vb 6 |
442 | \& fastcgi_param SCRIPT_NAME /; |
443 | \& fastcgi_param PATH_INFO $fastcgi_script_name; |
444 | \& fastcgi_param REQUEST_URI $request_uri; |
445 | \& fastcgi_param DOCUMENT_URI $document_uri; |
446 | \& fastcgi_param DOCUMENT_ROOT $document_root; |
447 | \& fastcgi_param SERVER_PROTOCOL $server_protocol; |
448 | .Ve |
449 | .PP |
450 | .Vb 2 |
451 | \& fastcgi_param GATEWAY_INTERFACE CGI/1.1; |
452 | \& fastcgi_param SERVER_SOFTWARE nginx/$nginx_version; |
453 | .Ve |
454 | .PP |
455 | .Vb 5 |
456 | \& fastcgi_param REMOTE_ADDR $remote_addr; |
457 | \& fastcgi_param REMOTE_PORT $remote_port; |
458 | \& fastcgi_param SERVER_ADDR $server_addr; |
459 | \& fastcgi_param SERVER_PORT $server_port; |
460 | \& fastcgi_param SERVER_NAME $server_name; |
461 | .Ve |
462 | .PP |
463 | .Vb 4 |
464 | \& # Adjust the socket for your applications! |
465 | \& fastcgi_pass unix:$docroot/myapp.socket; |
466 | \& } |
467 | \& } |
468 | .Ve |
469 | .PP |
470 | It is the standard convention of nginx to include the fastcgi_params in a |
471 | separate file (usually something like \f(CW\*(C`/etc/nginx/fastcgi_params\*(C'\fR) and |
472 | simply include that file. |
473 | .PP |
474 | \fINon-root configuration\fR |
475 | .IX Subsection "Non-root configuration" |
476 | .PP |
477 | If you properly specify the \s-1PATH_INFO\s0 and \s-1SCRIPT_NAME\s0 parameters your |
478 | application will be accessible at any path. The \s-1SCRIPT_NAME\s0 variable is the |
479 | prefix of your application, and \s-1PATH_INFO\s0 would be everything in addition. |
480 | .PP |
481 | As an example, if your application is rooted at /myapp, you would configure: |
482 | .PP |
483 | .Vb 2 |
484 | \& fastcgi_param SCRIPT_NAME /myapp/; |
485 | \& fastcgi_param PATH_INFO $fastcgi_script_name; |
486 | .Ve |
487 | .PP |
488 | \&\f(CW$fastcgi_script_name\fR would be \*(L"/myapp/path/of/the/action\*(R". Catalyst will |
489 | process this accordingly and setup the application base as expected. |
490 | .PP |
491 | This behavior is somewhat different than Apache and Lighttpd, but is still |
492 | functional. |
493 | .PP |
494 | For more information on nginx, visit: |
495 | <http://nginx.net> |
496 | .Sh "Microsoft \s-1IIS\s0" |
497 | .IX Subsection "Microsoft IIS" |
498 | It is possible to run Catalyst under \s-1IIS\s0 with FastCGI, but only on \s-1IIS\s0 6.0 |
499 | (Microsoft Windows 2003), \s-1IIS\s0 7.0 (Microsoft Windows 2008 and Vista) and |
500 | hopefully its successors. |
501 | .PP |
502 | Even if it is declared that FastCGI is supported on \s-1IIS\s0 5.1 (Windows \s-1XP\s0) it |
503 | does not support some features (specifically: wildcard mappings) that prevents |
504 | running Catalyst application. |
505 | .PP |
506 | Let us assume that our server has the following layout: |
507 | .PP |
508 | .Vb 3 |
509 | \& d:\eWWW\eWebApp\e path to our Catalyst application |
510 | \& d:\estrawberry\eperl\ebin\eperl.exe path to perl interpreter (with Catalyst installed) |
511 | \& c:\ewindows Windows directory |
512 | .Ve |
513 | .PP |
514 | \fISetup \s-1IIS\s0 6.0 (Windows 2003)\fR |
515 | .IX Subsection "Setup IIS 6.0 (Windows 2003)" |
516 | .IP "Install FastCGI extension for \s-1IIS\s0 6.0" 4 |
517 | .IX Item "Install FastCGI extension for IIS 6.0" |
518 | FastCGI is not a standard part of \s-1IIS\s0 6 \- you have to install it separately. For |
519 | more info and download go to <http://www.iis.net/extensions/FastCGI>. Choose |
520 | approptiate version (32\-bit/64\-bit), installation is quite simple |
521 | (in fact no questions, no options). |
522 | .IP "Create a new website" 4 |
523 | .IX Item "Create a new website" |
524 | Open \*(L"Control Panel\*(R" > \*(L"Administrative Tools\*(R" > \*(L"Internet Information Services Manager\*(R". |
525 | Click \*(L"Action\*(R" > \*(L"New\*(R" > \*(L"Web Site\*(R". After you finish the installation wizard |
526 | you need to go to the new website's properties. |
527 | .IP "Set website properties" 4 |
528 | .IX Item "Set website properties" |
529 | On tab \*(L"Web site\*(R" set proper values for: |
530 | Site Description, \s-1IP\s0 Address, \s-1TCP\s0 Port, \s-1SSL\s0 Port etc. |
531 | .Sp |
532 | On tab \*(L"Home Directory\*(R" set the following: |
533 | .Sp |
534 | .Vb 3 |
535 | \& Local path: "d:\eWWW\eWebApp\eroot" |
536 | \& Local path permission flags: check only "Read" + "Log visits" |
537 | \& Execute permitions: "Scripts only" |
538 | .Ve |
539 | .Sp |
540 | Click \*(L"Configuration\*(R" button (still on Home Directory tab) then click \*(L"Insert\*(R" |
541 | the wildcard application mapping and in the next dialog set: |
542 | .Sp |
543 | .Vb 2 |
544 | \& Executable: "c:\ewindows\esystem32\einetsrv\efcgiext.dll" |
545 | \& Uncheck: "Verify that file exists" |
546 | .Ve |
547 | .Sp |
548 | Close all dialogs with \*(L"\s-1OK\s0\*(R". |
549 | .IP "Edit fcgiext.ini" 4 |
550 | .IX Item "Edit fcgiext.ini" |
551 | Put the following lines into c:\ewindows\esystem32\einetsrv\efcgiext.ini (on 64\-bit |
552 | system c:\ewindows\esyswow64\einetsrv\efcgiext.ini): |
553 | .Sp |
554 | .Vb 12 |
555 | \& [Types] |
556 | \& *:8=CatalystApp |
557 | \& ;replace 8 with the identification number of the newly created website |
558 | \& ;it is not so easy to get this number: |
559 | \& ; \- you can use utility "c:\einetpub\eadminscripts\eadsutil.vbs" |
560 | \& ; to list websites: "cscript adsutil.vbs ENUM /P /W3SVC" |
561 | \& ; to get site name: "cscript adsutil.vbs GET /W3SVC/<number>/ServerComment" |
562 | \& ; to get all details: "cscript adsutil.vbs GET /W3SVC/<number>" |
563 | \& ; \- or look where are the logs located: |
564 | \& ; c:\eWINDOWS\eSYSTEM32\eLogfiles\eW3SVC7\ewhatever.log |
565 | \& ; means that the corresponding number is "7" |
566 | \& ;if you are running just one website using FastCGI you can use '*=CatalystApp' |
567 | .Ve |
568 | .Sp |
569 | .Vb 3 |
570 | \& [CatalystApp] |
571 | \& ExePath=d:\estrawberry\eperl\ebin\eperl.exe |
572 | \& Arguments="d:\eWWW\eWebApp\escript\ewebapp_fastcgi.pl \-e" |
573 | .Ve |
574 | .Sp |
575 | .Vb 3 |
576 | \& ;by setting this you can instruct IIS to serve Catalyst static files |
577 | \& ;directly not via FastCGI (in case of any problems try 1) |
578 | \& IgnoreExistingFiles=0 |
579 | .Ve |
580 | .Sp |
581 | .Vb 3 |
582 | \& ;do not be fooled by Microsoft doc talking about "IgnoreExistingDirectories" |
583 | \& ;that does not work and use "IgnoreDirectories" instead |
584 | \& IgnoreDirectories=1 |
585 | .Ve |
586 | .PP |
587 | \fISetup \s-1IIS\s0 7.0 (Windows 2008 and Vista)\fR |
588 | .IX Subsection "Setup IIS 7.0 (Windows 2008 and Vista)" |
589 | .PP |
590 | Microsoft \s-1IIS\s0 7.0 has built-in support for FastCGI so you do not have to install |
591 | any addons. |
592 | .IP "Necessary steps during \s-1IIS7\s0 installation" 4 |
593 | .IX Item "Necessary steps during IIS7 installation" |
594 | During \s-1IIS7\s0 installation after you have added role \*(L"Web Server (\s-1IIS\s0)\*(R" |
595 | you need to check to install role feature \*(L"\s-1CGI\s0\*(R" (do not be nervous that it is |
596 | not FastCGI). If you already have \s-1IIS7\s0 installed you can add \*(L"\s-1CGI\s0\*(R" role feature |
597 | through \*(L"Control panel\*(R" > \*(L"Programs and Features\*(R". |
598 | .IP "Create a new website" 4 |
599 | .IX Item "Create a new website" |
600 | Open \*(L"Control Panel\*(R" > \*(L"Administrative Tools\*(R" > \*(L"Internet Information Services Manager\*(R" |
601 | > \*(L"Add Web Site\*(R". |
602 | .Sp |
603 | .Vb 3 |
604 | \& site name: "CatalystSite" |
605 | \& content directory: "d:\eWWW\eWebApp\eroot" |
606 | \& binding: set proper IP address, port etc. |
607 | .Ve |
608 | .IP "Configure FastCGI" 4 |
609 | .IX Item "Configure FastCGI" |
610 | You can configure FastCGI extension using commandline utility |
611 | \&\*(L"c:\ewindows\esystem32\einetsrv\eappcmd.exe\*(R" |
612 | .RS 4 |
613 | .ie n .IP "Configuring section ""fastCgi"" (it is a global setting)" 4 |
614 | .el .IP "Configuring section ``fastCgi'' (it is a global setting)" 4 |
615 | .IX Item "Configuring section fastCgi (it is a global setting)" |
616 | .Vb 1 |
617 | \& appcmd.exe set config \-section:system.webServer/fastCgi /+"[fullPath='d:\estrawberry\eperl\ebin\eperl.exe',arguments='d:\ewww\eWebApp\escript\ewebapp_fastcgi.pl \-e',maxInstances='4',idleTimeout='300',activityTimeout='30',requestTimeout='90',instanceMaxRequests='1000',protocol='NamedPipe',flushNamedPipe='False']" /commit:apphost |
618 | .Ve |
619 | .IP "Configuring proper handler (it is a site related setting)" 4 |
620 | .IX Item "Configuring proper handler (it is a site related setting)" |
621 | .Vb 1 |
622 | \& appcmd.exe set config "CatalystSite" \-section:system.webServer/handlers /+"[name='CatalystFastCGI',path='*',verb='GET,HEAD,POST',modules='FastCgiModule',scriptProcessor='d:\estrawberry\eperl\ebin\eperl.exe|d:\ewww\eWebApp\escript\ewebapp_fastcgi.pl \-e',resourceType='Unspecified',requireAccess='Script']" /commit:apphost |
623 | .Ve |
624 | .Sp |
625 | Note: before launching the commands above do not forget to change site |
626 | name and paths to values relevant for your server setup. |
627 | .RE |
628 | .RS 4 |
629 | .RE |
630 | .SH "SEE ALSO" |
631 | .IX Header "SEE ALSO" |
632 | Catalyst, \s-1FCGI\s0. |
633 | .SH "AUTHORS" |
634 | .IX Header "AUTHORS" |
635 | Catalyst Contributors, see Catalyst.pm |
636 | .SH "THANKS" |
637 | .IX Header "THANKS" |
638 | Bill Moseley, for documentation updates and testing. |
639 | .SH "COPYRIGHT" |
640 | .IX Header "COPYRIGHT" |
641 | This library is free software. You can redistribute it and/or modify it under |
642 | the same terms as Perl itself. |