Annotation of embedaddon/lighttpd/doc/outdated/fastcgi.txt, revision 1.1.1.1
1.1 misho 1: =====================
2: the FastCGI Interface
3: =====================
4:
5: -------------------
6: Module: mod_fastcgi
7: -------------------
8:
9: :Author: Jan Kneschke
10: :Date: $Date: 2004/11/03 22:26:05 $
11: :Revision: $Revision: 1.3 $
12:
13: :abstract:
14: The FastCGI interface is the fastest and most secure way
15: to interface external process-handlers like Perl, PHP and
16: your self-written applications.
17:
18: .. meta::
19: :keywords: lighttpd, FastCGI
20:
21: .. contents:: Table of Contents
22:
23: Description
24: ===========
25:
26: lighttpd provides an interface to a external programs that
27: support the FastCGI interface. The FastCGI Interface is
28: defined by http://www.fastcgi.com/ and is a
29: platform-independent and server independent interface between
30: a web-application and a webserver.
31:
32: This means that FastCGI programs that run with the Apache
33: Webserver will run seamlessly with lighttpd and vice versa.
34:
35:
36: FastCGI
37: -------
38:
39: FastCGI is removes a lot of the limitations of CGI programs.
40: CGI programs have the problem that they have to be restarted
41: by the webserver for every request which leads to really bad
42: performance values.
43:
44: FastCGI removes this limitation by keeping the process running
45: and handling the requests by this always running process. This
46: removes the time used for the fork() and the overall startup
47: and cleanup time which is necessary to create and destroy a
48: process.
49:
50: While CGI programs communicate to the server over pipes,
51: FastCGI processes use Unix-Domain-Sockets or TCP/IP to talk
52: with the webserver. This gives you the second advantage over
53: simple CGI programs: FastCGI don't have to run on the Webserver
54: itself but everywhere in the network.
55:
56: lighttpd takes it a little bit further by providing a internal
57: FastCGI load-balancer which can be used to balance the load
58: over multiple FastCGI Servers. In contrast to other solutions
59: only the FastCGI process has to be on the cluster and not the
60: whole webserver. That gives the FastCGI process more resources
61: than a e.g. load-balancer+apache+mod_php solution.
62:
63: If you compare FastCGI against a apache+mod_php solution you
64: should note that FastCGI provides additional security as the
65: FastCGI process can be run under different permissions that
66: the webserver and can also live a chroot which might be
67: different than the one the webserver is running in.
68:
69: Options
70: =======
71:
72: lighttpd provides the FastCGI support via the fastcgi-module
73: (mod_fastcgi) which provides 2 options in the config-file:
74:
75: fastcgi.debug
76: a value between 0 and 65535 to set the debug-level in the
77: FastCGI module. Currently only 0 and 1 are used. Use 1 to
78: enable some debug output, 0 to disable it.
79:
80: fastcgi.map-extensions
81: map multiple extensions to the same fastcgi server
82:
83: Example: ::
84:
85: fastcgi.map-extensions = ( ".php3" => ".php" )
86:
87: fastcgi.server
88: tell the module where to send FastCGI requests to. Every
89: file-extension can have it own handler. Load-Balancing is
90: done by specifying multiple handles for the same extension.
91:
92: structure of fastcgi.server section: ::
93:
94: ( <extension> =>
95: (
96: ( "host" => <string> ,
97: "port" => <integer> ,
98: "socket" => <string>, # either socket
99: # or host+port
100: "bin-path" => <string>, # OPTIONAL
101: "bin-environment" => <array>, # OPTIONAL
102: "bin-copy-environment" => <array>, # OPTIONAL
103: "mode" => <string>, # OPTIONAL
104: "docroot" => <string> , # OPTIONAL if "mode"
105: # is not "authorizer"
106: "check-local" => <string>, # OPTIONAL
107: "max-procs" => <integer>, # OPTIONAL
108: "broken-scriptfilename" => <boolean>, # OPTIONAL
109: "disable-time" => <integer>, # optional
110: "allow-x-send-file" => <boolean>, # optional
111: "kill-signal" => <integer>, # OPTIONAL
112: "fix-root-scriptname" => <boolean>,
113: # OPTIONAL
114: ( "host" => ...
115: )
116: )
117: )
118:
119: :<extension>: is the file-extension or prefix
120: (if started with "/")
121: :"host": is hostname/ip of the FastCGI process
122: :"port": is tcp-port on the "host" used by the FastCGI
123: process
124: :"bin-path": path to the local FastCGI binary which should be
125: started if no local FastCGI is running
126: :"socket": path to the unix-domain socket
127: :"mode": is the FastCGI protocol mode.
128: Default is "responder", also "authorizer"
129: mode is implemented.
130: :"docroot": is optional and is the docroot on the remote
131: host for default "responder" mode. For
132: "authorizer" mode it is MANDATORY and it points
133: to docroot for authorized requests. For security
134: reasons it is recommended to keep this docroot
135: outside of server.document-root tree.
136: :"check-local": is optional and may be "enable" (default) or
137: "disable". If enabled the server first check
138: for a file in local server.document-root tree
139: and return 404 (Not Found) if no such file.
140: If disabled, the server forward request to
141: FastCGI interface without this check.
142: :"broken-scriptfilename": breaks SCRIPT_FILENAME in a wat that
143: PHP can extract PATH_INFO from it (default: disabled)
144: :"disable-time": time to wait before a disabled backend is checked
145: again
146: :"allow-x-send-file": controls if X-LIGHTTPD-send-file headers
147: are allowed
148: :"fix-root-scriptname": fix broken path-info split for "/" extension ("prefix")
149:
150: If bin-path is set:
151:
152: :"max-procs": the upper limit of the processess to start
153: :"bin-environment": put an entry into the environment of
154: the started process
155: :"bin-copy-environement": clean up the environment and copy
156: only the specified entries into the fresh
157: environment of the spawn process
158: :"kill-signal": signal to terminate the FastCGI process with,
159: defauls to SIGTERM
160:
161: Examples
162: --------
163:
164: Multiple extensions for the same host ::
165:
166: fastcgi.server = ( ".php" =>
167: (( "host" => "127.0.0.1",
168: "port" => 1026,
169: "bin-path" => "/usr/local/bin/php"
170: )),
171: ".php4" =>
172: (( "host" => "127.0.0.1",
173: "port" => 1026
174: ))
175: )
176:
177: Example with prefix: ::
178:
179: fastcgi.server = ( "/remote_scripts/" =>
180: (( "host" => "192.168.0.3",
181: "port" => 9000,
182: "check-local" => "disable",
183: "docroot" => "/" # remote server may use
184: # it's own docroot
185: ))
186: )
187:
188: The request `http://my.host.com/remote_scripts/test.cgi` will
189: be forwarded to fastcgi server at 192.168.0.3 and the value
190: "/remote_scripts/test.cgi" will be used for the SCRIPT_NAME
191: variable. Remote server may prepend it with its own
192: document root. The handling of index files is also the
193: resposibility of remote server for this case.
194:
195: In the case that the prefix is not terminated with a slash
196: the prefix will be handled as file and /test.cgi would become
197: a PATH_INFO instead of part of SCRIPT_NAME.
198:
199:
200: Example for "authorizer" mode: ::
201:
202: fastcgi.server = ( "/remote_scripts/" =>
203: (( "host" => "10.0.0.2",
204: "port" => 9000,
205: "docroot" => "/path_to_private_docs",
206: "mode" => "authorizer"
207: ))
208: )
209:
210: Note that if "docroot" is specified then its value will be
211: used in DOCUMENT_ROOT and SCRIPT_FILENAME variables passed
212: to FastCGI server.
213:
214: Load-Balancing
215: ==============
216:
217: The FastCGI plugin provides automaticly a load-balancing between
218: multiple FastCGI servers. ::
219:
220: fastcgi.server = ( ".php" =>
221: (( "host" => "10.0.0.2", "port" => 1030 ),
222: ( "host" => "10.0.0.3", "port" => 1030 ))
223: )
224:
225:
226: To understand how the load-balancing works you can enable the
227: fastcgi.debug option and will get a similar output as here: ::
228:
229: proc: 127.0.0.1 1031 1 1 1 31454
230: proc: 127.0.0.1 1028 1 1 1 31442
231: proc: 127.0.0.1 1030 1 1 1 31449
232: proc: 127.0.0.1 1029 1 1 2 31447
233: proc: 127.0.0.1 1026 1 1 2 31438
234: got proc: 34 31454
235: release proc: 40 31438
236: proc: 127.0.0.1 1026 1 1 1 31438
237: proc: 127.0.0.1 1028 1 1 1 31442
238: proc: 127.0.0.1 1030 1 1 1 31449
239: proc: 127.0.0.1 1031 1 1 2 31454
240: proc: 127.0.0.1 1029 1 1 2 31447
241:
242: Even if this for multiple FastCGI children on the local machine
243: the following explaination is valid for remote connections too.
244:
245: The output shows:
246:
247: - IP, port, unix-socket (is empty here)
248: - is-local, state (0 - unset, 1 - running, ... )
249: - active connections (load)
250: - PID
251:
252: As you can see the list is always sorted by the load field.
253:
254: Whenever a new connection is requested, the first entry (the one
255: with the lowest load) is selected, the load is increased (got proc: ...)
256: and the list is sorted again.
257:
258: If a FastCGI request is done or the connection is dropped, the load on the
259: FastCGI proc decreases and the list is sorted again (release proc: ...)
260:
261: This behaviour is very light-weight in code and still very efficient
262: as it keeps the fastcgi-servers equally loaded even if they have different
263: CPUs.
264:
265: Adaptive Process Spawning
266: =========================
267:
268: .. note:: This feature is disabled in 1.3.14 again. min-procs is
269: ignored in that release
270:
271: Starting with 1.3.8 lighttpd can spawn processes on demand if
272: a bin-path is specified and the FastCGI process runs locally.
273:
274: If you want to have a least one FastCGI process running and
275: more of the number of requests increases you can use min-procs
276: and max-procs.
277:
278: A new process is spawned as soon as the average number of
279: requests waiting to be handle by a single process increases the
280: max-load-per-proc setting.
281:
282: The idle-timeout specifies how long a fastcgi-process should wait
283: for a new request before it kills itself.
284:
285: Example
286: -------
287: ::
288:
289: fastcgi.server = ( ".php" =>
290: (( "socket" => "/tmp/php.socket",
291: "bin-path" => "/usr/local/bin/php",
292: "min-procs" => 1,
293: "max-procs" => 32,
294: "max-load-per-proc" => 4,
295: "idle-timeout" => 20
296: ))
297: )
298:
299: Disabling Adaptive Spawning
300: ---------------------------
301:
302: Adaptive Spawning is a quite new feature and it might misbehave
303: for your setup. There are several ways to control how the spawing
304: is done:
305:
306: 1. ``"max-load-per-proc" => 1``
307: if that works for you, great.
308:
309: 2. If not set ``min-procs == max-procs``.
310:
311: 3. For PHP you can also use: ::
312:
313: $ PHP_FCGI_CHILDREN=384 ./lighttpd -f ./lighttpd.conf
314:
315: fastcgi.server = ( ".php" =>
316: (( "socket" => "/tmp/php.socket",
317: "bin-path" => "/usr/local/bin/php",
318: "min-procs" => 1,
319: "max-procs" => 1,
320: "max-load-per-proc" => 4,
321: "idle-timeout" => 20
322: ))
323: )
324:
325: It will create one socket and let's PHP create the 384 processes itself.
326:
327: 4. If you don't want lighttpd to manage the fastcgi processes, remove the
328: bin-path and use spawn-fcgi to spawn them itself.
329:
330:
331: FastCGI and Programming Languages
332: =================================
333:
334: Preparing PHP as a FastCGI program
335: ----------------------------------
336:
337: One of the most important application that has a FastCGI
338: interface is php which can be downloaded from
339: http://www.php.net/ . You have to recompile the php from
340: source to enable the FastCGI interface as it is normally
341: not enabled by default in the distributions.
342:
343: If you already have a working installation of PHP on a
344: webserver execute a small script which just contains ::
345:
346: <?php phpinfo(); ?>
347:
348: and search for the line in that contains the configure call.
349: You can use it as the base for the compilation.
350:
351: You have to remove all occurences of `--with-apxs`, `--with-apxs2`
352: and the like which would build PHP with Apache support. Add the
353: next three switches to compile PHP with FastCGI support::
354:
355: $ ./configure \
356: --enable-fastcgi \
357: --enable-force-cgi-redirect \
358: ...
359:
360: After compilation and installation check that your PHP
361: binary contains FastCGI support by calling: ::
362:
363: $ php -v
364: PHP 4.3.3RC2-dev (cgi-fcgi) (built: Oct 19 2003 23:19:17)
365:
366: The important part is the (cgi-fcgi).
367:
368:
369: Starting a FastCGI-PHP
370: ----------------------
371:
372: Starting with version 1.3.6 lighttpd can spawn the FastCGI
373: processes locally itself if necessary: ::
374:
375: fastcgi.server = ( ".php" =>
376: (( "socket" => "/tmp/php-fastcgi.socket",
377: "bin-path" => "/usr/local/bin/php"
378: ))
379: )
380:
381: PHP provides 2 special environment variables which control the number of
382: spawned workes under the control of a single watching process
383: (PHP_FCGI_CHILDREN) and the number of requests what a single worker
384: handles before it kills itself. ::
385:
386: fastcgi.server = ( ".php" =>
387: (( "socket" => "/tmp/php-fastcgi.socket",
388: "bin-path" => "/usr/local/bin/php",
389: "bin-environment" => (
390: "PHP_FCGI_CHILDREN" => "16",
391: "PHP_FCGI_MAX_REQUESTS" => "10000"
392: )
393: ))
394: )
395:
396: To increase the security of the started process you should only pass
397: the necessary environment variables to the FastCGI process. ::
398:
399: fastcgi.server = ( ".php" =>
400: (( "socket" => "/tmp/php-fastcgi.socket",
401: "bin-path" => "/usr/local/bin/php",
402: "bin-environment" => (
403: "PHP_FCGI_CHILDREN" => "16",
404: "PHP_FCGI_MAX_REQUESTS" => "10000" ),
405: "bin-copy-environment" => (
406: "PATH", "SHELL", "USER" )
407: ))
408: )
409:
410: Configuring PHP
411: ---------------
412:
413: If you want to use PATH_INFO and PHP_SELF in you PHP scripts you have to
414: configure php and lighttpd. The php.ini needs the option: ::
415:
416: cgi.fix_pathinfo = 1
417:
418: and the option ``broken-scriptfilename`` in your fastcgi.server config: ::
419:
420: fastcgi.server = ( ".php" =>
421: (( "socket" => "/tmp/php-fastcgi.socket",
422: "bin-path" => "/usr/local/bin/php",
423: "bin-environment" => (
424: "PHP_FCGI_CHILDREN" => "16",
425: "PHP_FCGI_MAX_REQUESTS" => "10000" ),
426: "bin-copy-environment" => (
427: "PATH", "SHELL", "USER" ),
428: "broken-scriptfilename" => "enable"
429: ))
430: )
431:
432: Why this ? the ``cgi.fix_pathinfo = 0`` would give you a working ``PATH_INFO``
433: but no ``PHP_SELF``. If you enable it, it turns around. To fix the
434: ``PATH_INFO`` `--enable-discard-path` needs a SCRIPT_FILENAME which is against the CGI spec, a
435: broken-scriptfilename. With ``cgi.fix_pathinfo = 1`` in php.ini and
436: ``broken-scriptfilename => "enable"`` you get both.
437:
438:
439: External Spawning
440: -----------------
441:
442: Spawning FastCGI processes directly in the webserver has some
443: disadvantages like
444:
445: - FastCGI process can only run locally
446: - has the same permissions as the webserver
447: - has the same base-dir as the webserver
448:
449: As soon as you are using a seperate FastCGI Server to
450: take off some load from the webserver you have to control
451: the FastCGI process by a external program like spawn-fcgi.
452:
453: spawn-fcgi is used to start a FastCGI process in its own
454: environment and set the user-id, group-id and change to
455: another root-directory (chroot).
456:
457: For convenience a wrapper script should be used which takes
458: care of all the necessary option. Such a script in included
459: in the lighttpd distribution and is call spawn-php.sh.
460:
461: The script has a set of config variables you should take
462: a look at: ::
463:
464: ## ABSOLUTE path to the spawn-fcgi binary
465: SPAWNFCGI="/usr/local/sbin/spawn-fcgi"
466:
467: ## ABSOLUTE path to the PHP binary
468: FCGIPROGRAM="/usr/local/bin/php"
469:
470: ## bind to tcp-port on localhost
471: FCGIPORT="1026"
472:
473: ## bind to unix domain socket
474: # FCGISOCKET="/tmp/php.sock"
475:
476: ## number of PHP childs to spawn
477: PHP_FCGI_CHILDREN=10
478:
479: ## number of request server by a single php-process until
480: ## is will be restarted
481: PHP_FCGI_MAX_REQUESTS=1000
482:
483: ## IP adresses where PHP should access server connections
484: ## from
485: FCGI_WEB_SERVER_ADDRS="127.0.0.1,192.168.0.1"
486:
487: # allowed environment variables sperated by spaces
488: ALLOWED_ENV="ORACLE_HOME PATH USER"
489:
490: ## if this script is run as root switch to the following user
491: USERID=wwwrun
492: GROUPID=wwwrun
493:
494: If you have set the variables to values that fit to your
495: setup you can start it by calling: ::
496:
497: $ spawn-php.sh
498: spawn-fcgi.c.136: child spawned successfully: PID: 6925
499:
500: If you get "child spawned successfully: PID:" the php
501: processes could be started successfully. You should see them
502: in your processlist: ::
503:
504: $ ps ax | grep php
505: 6925 ? S 0:00 /usr/local/bin/php
506: 6928 ? S 0:00 /usr/local/bin/php
507: ...
508:
509: The number of processes should be PHP_FCGI_CHILDREN + 1.
510: Here the process 6925 is the master of the slaves which
511: handle the work in parallel. Number of parallel workers can
512: be set by PHP_FCGI_CHILDREN. A worker dies automaticly of
513: handling PHP_FCGI_MAX_REQUESTS requests as PHP might have
514: memory leaks.
515:
516: If you start the script as user root php processes will be
517: running as the user USERID and group GROUPID to drop the
518: root permissions. Otherwise the php processes will run as
519: the user you started script as.
520:
521: As the script might be started from a unknown stage or even
522: directly from the command-line it cleans the environment
523: before starting the processes. ALLOWED_ENV contains all
524: the external environement variables that should be available
525: to the php-process.
526:
527:
528: Perl
529: ----
530:
531: For Perl you have to install the FCGI module from CPAN.
532:
533: Skeleton for remote authorizer
534: ==============================
535:
536: The basic functionality of authorizer is as follows (see
537: http://www.fastcgi.com/devkit/doc/fcgi-spec.html, 6.3 for
538: details). ::
539:
540: #include <fcgi_stdio.h>
541: #include <stdlib.h>
542: #include <unistd.h>
543: int main () {
544: char* p;
545:
546: while (FCGI_Accept() >= 0) {
547: /* wait for fastcgi authorizer request */
548:
549: printf("Content-type: text/html\r\n");
550:
551: if ((p = getenv("QUERY_STRING")) == NULL) ||
552: <QUERY_STRING is unauthorized>)
553: printf("Status: 403 Forbidden\r\n\r\n");
554:
555: else printf("\r\n");
556: /* default Status is 200 - allow access */
557: }
558:
559: return 0;
560: }
561:
562: It is possible to use any other variables provided by
563: FastCGI interface for authorization check. Here is only an
564: example.
565:
566:
567: Troubleshooting
568: ===============
569:
570: fastcgi.debug should be enabled for troubleshooting.
571:
572: If you get: ::
573:
574: (fcgi.c.274) connect delayed: 8
575: (fcgi.c.289) connect succeeded: 8
576: (fcgi.c.745) unexpected end-of-file (perhaps the fastcgi
577: process died): 8
578:
579: the fastcgi process accepted the connection but closed it
580: right away. This happens if FCGI_WEB_SERVER_ADDRS doesn't
581: include the host where you are connection from.
582:
583: If you get ::
584:
585: (fcgi.c.274) connect delayed: 7
586: (fcgi.c.1107) error: unexpected close of fastcgi connection
587: for /peterp/seite1.php (no fastcgi process on host/port ?)
588: (fcgi.c.1015) emergency exit: fastcgi: connection-fd: 5
589: fcgi-fd: 7
590:
591: the fastcgi process is not running on the host/port you are
592: connection to. Check your configuration.
593:
594: If you get ::
595:
596: (fcgi.c.274) connect delayed: 7
597: (fcgi.c.289) connect succeeded: 7
598:
599: everything is fine. The connect() call just was delayed a
600: little bit and is completly normal.
601:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to fastcgi.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated