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