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