Return to README.FastCGI CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / sapi / cgi

Annotation of embedaddon/php/sapi/cgi/README.FastCGI, revision 1.1.1.1

1.1       misho       1: Credits:
                      2: Ben Mansell, Stephen Landamore, Daniel Silverstone, Shane Caraveo
                      3: 
                      4: Building PHP
                      5: ------------
                      6: 
                      7: You must add '--enable-fastcgi' to the configure command on Linux or
                      8: OSX based systems to get fastcgi support in the php-cgi binary.  You
                      9: also must not use '--enable-discard-path'.
                     10: 
                     11: Running the FastCGI PHP module
                     12: ------------------------------
                     13: 
                     14: There are two ways to run the resulting 'php' binary after the fastcgi
                     15: version has been built:
                     16: 
                     17: 1) Configure your web server to run the PHP binary itself.
                     18: 
                     19: This is the simplest method, obviously you will have to configure your
                     20: web server appropriately. Some web servers may also not support this method,
                     21: or may not be as efficient.
                     22: 
                     23: 2) Run PHP separately from the web server.
                     24: 
                     25: In this setup, PHP is started as a separate process entirely from the web
                     26: server. It will listen on a socket for new FastCGI requests, and deliver
                     27: PHP pages as appropriate. This is the recommended way of running PHP-FastCGI.
                     28: To run this way, you must start the PHP binary running by giving it an IP
                     29: and a port number to listen to on the command line, e.g.:
                     30: 
                     31:     ./php -b 127.0.0.1:8002
                     32: 
                     33: The above line is the recommended way of running FastCGI.  You usually
                     34: want the FastCGI server to provide services to the localhost, not
                     35: everyone on the Internet.
                     36: 
                     37: If your web server sits on a remote host, you can make FastCGI listen
                     38: on all interfaces:
                     39: 
                     40:     ./php -b :8002
                     41:     ./php -b "*:8002"
                     42: 
                     43: Note that hostnames are not supported.
                     44: 
                     45: You must also configure your web server to connect to the appropriate port
                     46: in order to talk to the PHP FastCGI process.
                     47: 
                     48: The advantage of running PHP in this way is that it entirely separates the
                     49: web server and PHP process, so that one cannot disrupt the other. It also
                     50: allows PHP to be on an entirely separate machine from the web server if need
                     51: be, you could even have several web servers utilising the same running PHP
                     52: process if required!
                     53: 
                     54: 
                     55: Using FastCGI PHP with Apache
                     56: =============================
                     57: 
                     58: First of all, you may well ask 'Why?'. After all, Apache already has mod_php.
                     59: However, there are advantages to running PHP with FastCGI. Separating the
                     60: PHP code from the web server removes 'bloat' from the main server, and should
                     61: improve the performance of non-PHP requests. Secondly, having one permanent
                     62: PHP process as opposed to one per apache process means that shared resources
                     63: like persistent database connections are used more efficiently.
                     64: 
                     65: First of all, make sure that the FastCGI module is enabled. You should have
                     66: a line in your config like:
                     67: 
                     68:     LoadModule fastcgi_module /usr/lib/apache/2.0/mod_fastcgi.so
                     69: 
                     70: Don't load mod_php, by the way. Make sure it is commented out!
                     71: 
                     72:     #LoadModule php5_module /usr/lib/apache/2.0/libphp5.so
                     73: 
                     74: Now, we'll create a fcgi-bin directory, just like you would do with normal
                     75: CGI scripts. You'll need to create a directory somewhere to store your
                     76: FastCGI binaries. We'll use /space/fcgi-bin/ for this example. Remember to
                     77: copy the FastCGI-PHP binary in there. (named 'php-cgi')  This sets up
                     78: php to run under mod_fastcgi as a dynamic server.
                     79: 
                     80:     ScriptAlias /fcgi-bin/ /space/fcgi-bin/
                     81:     <Location /fcgi-bin/>
                     82:         Options ExecCGI
                     83:         SetHandler fastcgi-script
                     84:     </Location>
                     85: 
                     86: To setup a specific static configuration for php, you have to use
                     87: the FastCgiServer configuration for mod_fastcgi.  For this, do not
                     88: use the above configuration, but rather the following.
                     89: (see mod_fastcgi docs for more configuration information):
                     90: 
                     91:     Alias /fcgi-bin/ /space/fcgi-bin/
                     92:     FastCgiServer /path/to/php-cgi -processes 5
                     93: 
                     94: For either of the above configurations,  we need to tell Apache to 
                     95: use the FastCGI binary /fcgi-bin/php to deliver PHP pages. 
                     96: All that is needed is:
                     97: 
                     98:     AddType application/x-httpd-fastphp .php
                     99:     Action application/x-httpd-fastphp /fcgi-bin/php-cgi
                    100: 
                    101: Now, if you restart Apache, php pages should now be delivered!
                    102: 
                    103: Using FastCGI PHP with IIS or iPlanet
                    104: =====================================
                    105: 
                    106: FastCGI server plugins are available at www.caraveo.com/fastcgi/
                    107: Documentation on these are sparse.  iPlanet is not very tested,
                    108: and no makefile exists yet for unix based iPlanet servers.
                    109: 
                    110: 
                    111: Security
                    112: --------
                    113: 
                    114: Be sure to run the php binary as an appropriate userid. Also, firewall out
                    115: the port that PHP is listening on. In addition, you can set the environment
                    116: variable FCGI_WEB_SERVER_ADDRS to control who can connect to the FastCGI.
                    117: Set it to a comma separated list of IP addresses, e.g.:
                    118: 
                    119: export FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71
                    120: 
                    121: 
                    122: Tuning
                    123: ------
                    124: 
                    125: There are a few tuning parameters that can be tweaked to control the
                    126: performance of FastCGI PHP. The following are environment variables that can
                    127: be set before running the PHP binary:
                    128: 
                    129: PHP_FCGI_CHILDREN  (default value: 0)
                    130: 
                    131: This controls how many child processes the PHP process spawns. When the
                    132: fastcgi starts, it creates a number of child processes which handle one
                    133: page request at a time. Value 0 means that PHP willnot start additional
                    134: processes and main process will handle FastCGI requests by itself. Note that
                    135: this process may die (because of PHP_FCGI_MAX_REQUESTS) and it willnot
                    136: respawned automatic. Values 1 and above force PHP start additioanl processes
                    137: those will handle requests. The main process will restart children in case of
                    138: their death. So by default, you will be able to handle 1 concurrent PHP page
                    139: requests. Further requests will be queued. Increasing this number will allow
                    140: for better concurrency, especially if you have pages that take a significant
                    141: time to create, or supply a lot of data (e.g. downloading huge files via PHP).
                    142: On the other hand, having more processes running will use more RAM, and letting
                    143: too many PHP pages be generated concurrently will mean that each request will
                    144: be slow.
                    145: 
                    146: PHP_FCGI_MAX_REQUESTS (default value: 500)
                    147: 
                    148: This controls how many requests each child process will handle before
                    149: exitting. When one process exits, another will be created. This tuning is
                    150: necessary because several PHP functions are known to have memory leaks. If the
                    151: PHP processes were left around forever, they would be become very inefficient.