php-src/sapi/cgi/README.FastCGI

Credits:
Ben Mansell, Stephen Landamore, Daniel Silverstone, Shane Caraveo

Building PHP
------------

You must add '--enable-fastcgi' to the configure command on Linux or
OSX based systems to get fastcgi support in the php-cgi binary.  You
also must not use '--enable-discard-path'.

Running the FastCGI PHP module
------------------------------

There are two ways to run the resulting 'php' binary after the fastcgi
version has been built:

1) Configure your web server to run the PHP binary itself.

This is the simplest method, obviously you will have to configure your
web server appropriately. Some web servers may also not support this method,
or may not be as efficient.

2) Run PHP separately from the web server.

In this setup, PHP is started as a separate process entirely from the web
server. It will listen on a socket for new FastCGI requests, and deliver
PHP pages as appropriate. This is the recommended way of running PHP-FastCGI.
To run this way, you must start the PHP binary running by giving it an IP
and a port number to listen to on the command line, e.g.:

    ./php -b 127.0.0.1:8002

The above line is the recommended way of running FastCGI.  You usually
want the FastCGI server to provide services to the localhost, not
everyone on the Internet.

If your web server sits on a remote host, you can make FastCGI listen
on all interfaces:

    ./php -b :8002
    ./php -b "*:8002"

Note that hostnames are not supported.

You must also configure your web server to connect to the appropriate port
in order to talk to the PHP FastCGI process.

The advantage of running PHP in this way is that it entirely separates the
web server and PHP process, so that one cannot disrupt the other. It also
allows PHP to be on an entirely separate machine from the web server if need
be, you could even have several web servers utilising the same running PHP
process if required!


Using FastCGI PHP with Apache
=============================

First of all, you may well ask 'Why?'. After all, Apache already has mod_php.
However, there are advantages to running PHP with FastCGI. Separating the
PHP code from the web server removes 'bloat' from the main server, and should
improve the performance of non-PHP requests. Secondly, having one permanent
PHP process as opposed to one per apache process means that shared resources
like persistent database connections are used more efficiently.

First of all, make sure that the FastCGI module is enabled. You should have
a line in your config like:

    LoadModule fastcgi_module /usr/lib/apache/2.0/mod_fastcgi.so

Don't load mod_php, by the way. Make sure it is commented out!

    #LoadModule php5_module /usr/lib/apache/2.0/libphp5.so

Now, we'll create a fcgi-bin directory, just like you would do with normal
CGI scripts. You'll need to create a directory somewhere to store your
FastCGI binaries. We'll use /space/fcgi-bin/ for this example. Remember to
copy the FastCGI-PHP binary in there. (named 'php-cgi')  This sets up
php to run under mod_fastcgi as a dynamic server.

    ScriptAlias /fcgi-bin/ /space/fcgi-bin/
    <Location /fcgi-bin/>
        Options ExecCGI
        SetHandler fastcgi-script
    </Location>

To setup a specific static configuration for php, you have to use
the FastCgiServer configuration for mod_fastcgi.  For this, do not
use the above configuration, but rather the following.
(see mod_fastcgi docs for more configuration information):

    Alias /fcgi-bin/ /space/fcgi-bin/
    FastCgiServer /path/to/php-cgi -processes 5

For either of the above configurations,  we need to tell Apache to 
use the FastCGI binary /fcgi-bin/php to deliver PHP pages. 
All that is needed is:

    AddType application/x-httpd-fastphp .php
    Action application/x-httpd-fastphp /fcgi-bin/php-cgi

Now, if you restart Apache, php pages should now be delivered!

Using FastCGI PHP with IIS or iPlanet
=====================================

FastCGI server plugins are available at www.caraveo.com/fastcgi/
Documentation on these are sparse.  iPlanet is not very tested,
and no makefile exists yet for unix based iPlanet servers.


Security
--------

Be sure to run the php binary as an appropriate userid. Also, firewall out
the port that PHP is listening on. In addition, you can set the environment
variable FCGI_WEB_SERVER_ADDRS to control who can connect to the FastCGI.
Set it to a comma separated list of IP addresses, e.g.:

export FCGI_WEB_SERVER_ADDRS=199.170.183.28,199.170.183.71


Tuning
------

There are a few tuning parameters that can be tweaked to control the
performance of FastCGI PHP. The following are environment variables that can
be set before running the PHP binary:

PHP_FCGI_CHILDREN  (default value: 0)

This controls how many child processes the PHP process spawns. When the
fastcgi starts, it creates a number of child processes which handle one
page request at a time. Value 0 means that PHP willnot start additional
processes and main process will handle FastCGI requests by itself. Note that
this process may die (because of PHP_FCGI_MAX_REQUESTS) and it willnot
respawned automatic. Values 1 and above force PHP start additioanl processes
those will handle requests. The main process will restart children in case of
their death. So by default, you will be able to handle 1 concurrent PHP page
requests. Further requests will be queued. Increasing this number will allow
for better concurrency, especially if you have pages that take a significant
time to create, or supply a lot of data (e.g. downloading huge files via PHP).
On the other hand, having more processes running will use more RAM, and letting
too many PHP pages be generated concurrently will mean that each request will
be slow.

PHP_FCGI_MAX_REQUESTS (default value: 500)

This controls how many requests each child process will handle before
exitting. When one process exits, another will be created. This tuning is
necessary because several PHP functions are known to have memory leaks. If the
PHP processes were left around forever, they would be become very inefficient.