PHP FastCGI

From DreamHost

The following instructions will help you get a persistent PHP interpretor to run your applications through. It is not completely tested, however it seems to work with all of the one click installs which support PHP5. This will not work with PHP4. The PHP FastCGI support does not appear to be as robust as the Perl/Ruby support, yet, however that could change in the future. This setup is for the semi-poweruser.

Contents 1 Web Panel Setup 2 Make a FastCGI wrapper 3 Custom php cgi and Custom PHP.ini 4 Make an .htaccess file 5 Check your work 6 Troubleshooting 7 See Also

Web Panel Setup

This step is not strictly required, however it helps us know what customers are using!

Go to the Domains::Manage Domains section of the web panel. Click the Edit link next to the domain you would like to set up. Select the PHP 5 radio button and check the FastCGI box, then press save. Continue on to the next step while the web panel thinks and configures your site.

Make a FastCGI wrapper

Required

You need to make a file for the FastCGI process manager to run and hook up to. We will call it "php5-wrapper.fcgi". The contents of this file are as follows:

#!/bin/sh
export PHP_FCGI_CHILDREN=2
exec /dh/cgi-system/php5.cgi

see user comment in "Discussion"

There have been reports of problems when there are blank lines in this file. If the file contains Windows Line endings (CRLF), the file will have problems with blank lines. Make sure to convert the file to Unix line endings (CR) and everything will work properly.

We are still testing the PHP_FCGI_CHILDREN number, however you should not currently put it above 3. 2 is likely all you need for most websites. Set this file to be executable:

chmod u+x php5-wrapper.fcgi

Warning: FCGI processes use more memory than usual CGI ones. Due to this, FCGI-enabled application may be killed by process watchdog due to high memory usage. To prevent this, it's recommended (by DreamHost support) to rename wrapper script to dispatch.fcgi. This way it will be allowed to use more memory.

Custom php cgi and Custom PHP.ini

NOTE: Unsupported by DreamHost

If you have created own cgi'd php or you have copied the /usr/local/dh/cgi-system/php5.cgi then simply replace the exec target below to the php5.cgi you created.

To use a custom php.ini file with FastCGI and php, export the directory that contains your php.ini file in the PHPRC variable.

#!/bin/sh
export PHPRC=/home/username/domain.tld/inc
export PHP_FCGI_CHILDREN=2
exec /home/username/domain.tld/cgi-bin/php5.cgi

Please DO NOT use the -c command line option of php5.cgi to specify your php.ini file!

Make an .htaccess file

Required

You will need to make a ".htaccess" file, or edit your current one. Add these lines at the top:

AddHandler fastcgi-script fcg fcgi fpl
AddHandler php5-fastcgi .php
Action php5-fastcgi /php5-wrapper.fcgi

This file points all PHP scripts in the current directory and any directories below it towards your wrapper.fcgi script. This means they are all now running PHP5. If you put this .htaccess file in your home directory, and a copy of the php5-wrapper.fcgi file in each domain directory, they will all be switched!

You also need to make sure that your root allows execution of CGIs, by adding the following to your .htaccess at the root of your server:

Options +ExecCGI

Check your work

Required!

Make sure your files are all there, and have the proper permissions:

-rw-r--r--   1 user pg15734      242 2006-04-28 14:43 .htaccess*
-rwxr--r--   1 user pg15734      144 2006-05-01 15:04 php5-wrapper.fcgi*

Then load up your (Hopefully!) completely working FastCGI enabled website. You can then check via the shell if your processes are running:

[dinar]$ ps aux
USER       PID %CPU %MEM   VSZ  RSS TTY      STAT START   TIME COMMAND
user    682  0.0  0.1 17180 6148 ?        Ss   15:27   0:00 /dh/cgi-system/php5.cgi
user  21117  0.1  0.3 23872 11924 ?       S    15:27   0:00 /dh/cgi-system/php5.cgi
user   7576  0.0  0.3 23872 11920 ?       S    15:27   0:00 /dh/cgi-system/php5.cgi
user  23783  0.5  0.0  2632 1500 pts/7    S    15:30   0:00 -bash
user  20840  0.0  0.0  2488  860 pts/7    R+   15:30   0:00 ps aux

If things are broken, you can revert everything by just removing the lines added to your .htaccess file.

Troubleshooting

Hopefully not required

Problem -- The browser shows the proper result (the page looks correct), but when looking in the ps output, "php5.cgi" instead of "/dh/cgi-system/php5.cgi" appears.

this means that the modifications to the .htaccess file have take effect. Make sure you have entered the information into your ".htaccess" file from Make an .htaccess file properly.

Problem -- the browser sees no response from the server, and the following lines are seen in the http error log after a minute or so

[Fri Jun 01 15:36:11 2007] [error] [client 207.111.236.2] FastCGI: comm with (dynamic) \
        server "<path> /php5-wrapper.fcgi" aborted: (first read) idle timeout (60 sec)

[Fri Jun 01 15:36:11 2007] [error] [client 207.111.236.2] FastCGI: incomplete headers \
        (0 bytes) received from server "<path>/php5-wrapper.fcgi"

This means that the fast cgi process did not get started or was killed. As a bonus, this error means that the .htaccess modifications have been read.

If you do a ps, and DO NOT see any php5.cgi processes running (unqualified "php.cgi", nor any full path php5.cgi "/dh/cgi-system/php5.cgi" processes, it means that the process is not running). Try touch php5-wrapper.fcgi. this will cause the apache handler to realize that a change has been made to the file and it needs to be re-read.

NOTE: Do not kill -9 the php5.cgi processes as the Apache dispatchers will not realize the processes is dead (and you will certainly cause the errors shown above). This note was gleaned from the webpage http://www.nabble.com/Dreamhost-Application-Errors-t3733692.html (towards the bottom of the page):

Another tip: Unless you are hung badly, avoid using killall -9
dispatch.fcgi: Apache is set on a very long timer (5minutes+) for
timeout on the dispatchers, and you will be pulling your hair out trying
to figure out what Apache is not bringing the dispatchers back up.
Always use touch dispatch.fcgi unless that is not working; Touch will
work in most cases unless you have a major issue. 

More troubleshooting tips:

• Check your permissions, CGI (this includes FastCGI!) files cannot be world writable:

chmod o-w *.php *.fcgi *.cgi

• If you're getting the infamous "500 Server Error", there may be many issues. One solution is try try naming the files exactly as shown in this article.

TODO: Add more troubleshooting tips here.

See Also

• Advanced PHP configuration