PHP: Hypertext Preprocessor

Contents

• PHP integration methods with Zeus Web Server
• Obtaining a copy of FastCGI/PHP
• Compiling and Installing FastCGI/PHP
• Configuring Zeus Web Server to use FastCGI/PHP
• Tuning FastCGI/PHP and the Operating Systemi
• Building and Installing CGI/PHP
• Authentication with FastCGI/PHP

More resources

PHP integration methods with Zeus Web Server

There are a number of ways to integrate PHP with Zeus Web Server. Our preferred method is to use FastCGI with Remote Responders. A description of all the methods along with their advantages and disadvantages are discussed below.

1. Just use the built-in PHP binary

   Zeus Web Server now ships with a fully-functional PHP binary. You can simply enable this from the PHP page in the user interface. This will configure your site to run PHP in a simple and efficient manner. This should be suitable for most sites. You really only need to configure and set up PHP manually if you want to compile special options into PHP.

2. PHP/FastCGI using Local Responders

   This is the method employed through the Zeus Web Server Administration Server. Although easy to setup, it relies on Unix Domain Sockets which are known to have problems sustaining high connection rates on some platforms such as Solaris and HPUX. For this reason we recommened the use of Remote Responders which use the superior TCP sockets. FastCGI using Local Responders can however be a quick way to test the operation of your PHP binary prior to setting up Remote Responders.

3. PHP/FastCGI using Remote Responders

   This is the recommended way of configuring PHP with Zeus Web Server. TCP sockets are used to provide a more reliable mechanism than Unix Domain Sockets. Although perhaps counter intuative, it is possible to run remote responders locally. There are two choices therefore:

   • To run your PHP processes on the same box as the webserver i.e. using a remote connection method (TCP sockets) but running the service locally.
   • To run your PHP processes on their own machine, separate from the Zeus Web Server. This approach is preferred for high traffic sites and has the additional advantage of being able to segregate machine load away from the web server machines.

   Further instructions can be found in the Compiling and Installing FastCGI/PHP and Configuring Zeus Web Server to use FastCGI/PHP sections of this document

4. PHP/CGI

   Running PHP as a CGI is recommended when you have a requirement to control process limits/security on a per user-basis. The PHP interpreter must be loaded for every request which can have a negative impact on performance compared to the other methods listed above. CGI/PHP also allows users to have individual php.ini files.

   Further instructions can be found in the Building and Installing CGI/PHP section at the end of this document.

5. PHP/ISAPI

   Although PHP4 (released on 22nd May 2000) contains native Zeus ISAPI support, Zeus strongly recommend using the FastCGI interface to PHP instead. Extensive stability and performance testing has shown the FastCGI interface to be superior.

Obtaining a copy of FastCGI/PHP

Choose either to compile from source or use a pre-compiled binary.

1. Download the PHP source code from the official PHP website.

   The FastCGI modifications to PHP were initially released as part of PHP 4.0.5. It is recommended that you download the latest source code directly from PHP (downloads can be found at http://www.php.net/downloads.php).

   Please note that Zeus Technology are not responsible for maintaining the PHP code base or documentation. Any compilation instructions given here are provided purely for convienience and should not be considered as a replacement for reading the official PHP documentation.

Compiling and Installing FastCGI/PHP

Step 1 - Compiling FastCGI/PHP from source.

Extract the package and compile as follows:

    ./configure --enable-fastcgi
    make 

You may want to pass additional options to the PHP configure script e.g. --with-mysql. The illustration above shows the minimum neccessary. Please consult the PHP documentation for more information regarding extra compile time options.

Note:

• The configure option --enable-discard-path should not be set, as this prevents correct operation of PHP with Zeus.
  It is necessary to ensure that this option is not set even if building from vendor-provided source (such as a source-rpm, or deb).
  Please contact your vendor if you are unsure as to how to verify or change the options of their source packages - Zeus Technologies are unable to provide advice on the choices of specific vendors.

  It is know that Fedora Core 1 & 2 distributions have the --enable-discard-path option set in their source RPMs, and therefore these cannot be used without modification.

After compilation finishes, you will be left with an executable program called php. The binary will be found in the sapi/cgi directory of your PHP installation directory.

You may optionally want to execute the following command to install the php binary to /usr/local/bin

    make install 

Step 2 - Testing the PHP binary

Before configuring Zeus to use the PHP binary, it is neccessary to check that the binary has been built successfully. This can be done by testing that the binary can process PHP commands when run as a CGI.

From the PHP installation sapi/cgi directory execute the following command:

    ./php  

Note: If you have a recent version of PHP, the binary may be called php-cgi.

You will now need to type in the following:

<? phpinfo(); ?>

Now signify the end of input with <ctrl-d>

You should see a page of html displayed which is the output from the phpinfo() command. If this does not happen, consult the official PHP documentation from either the PHP installation directory or from the PHP website

Configuring Zeus Web Server to use FastCGI/PHP

Step 1 - Place the PHP binary

If you have decided to configure FastCGI/PHP by using the Local Responder method and are using Zeus Web Server 4.2 or later, you can setup PHP very easily.

If you aren't using Zeus Web Server 4.3 or above (which already include PHP configured as below), then perform the following steps:

• Simply create a $ZEUSHOME/php directory on each web server machine:
  

      mkdir $ZEUSHOME/php 

  and copy the php binary into it but renamed to php.fcgi:

      cp $PHP_DOWNLOAD_DIR/sapi/cgi/php $ZEUSHOME/php/php.fcgi 

  In recent versions of PHP, the binary is called php-cgi, so use the following instead:

      cp $PHP_DOWNLOAD_DIR/sapi/cgi/php-cgi $ZEUSHOME/php/php.fcgi 

To activate PHP for a virtual server, enable PHP in the Third Party configuration section of the Administration Server.

No further configuration is required when using this method. Instructions later in this document describe how to test that your configuration is working correctly.

If you are not using Zeus Web Server 4.2, or would like to run PHP as a Remote Responder (recommended for high-traffic sites), you will need to configure PHP manually, as follows:

1. Enable FastCGI

   Using the Admin Server, go to the FastCGI configuration page located under API support in the menu bar. Ensure that FastCGI support is enabled by checking the radio button and apply your changes.

2. Configure FastCGI

   On the FastCGI page, under Add FastCGI Remote Responders, add:

    
   Remote FastCGI
   Docroot path 	/fcgi-bin/php
   Remote machine 	localhost:8002
   

   The 'Docroot path' entry does not need to physically exist on the filesystem. It is merely a stub which the handler (see below) uses to connect requests for files with a php extension to the remote FastCGI application(in this case PHP).

   In this example we are configuring the virtual server to pass PHP requests onto the PHP Responder running on the local machine on port 8002. Note that the Responder has not yet been started.

   Now Click Apply.

3. Setup alias for PHP

   Add the following mapping from the URL Handling->Handlers section of the Admin Server:

         Add handler
         File extension 	php
         Handler 	/fcgi-bin/php
   

   Note: The docroot path virtual mapping in the previous point and the handler mentioned here must always point to the same location.

4. Apply these changes and commit them for this Virtual Server

Now that your Zeus Web Server FastCGI/PHP on the local machine configuration is complete, it is time to move on to tuning the PHP and then operating system.

If you wish to use Remote Reponders on a separate machine. Perform the following steps:

1. Instead of specifiying 'localhost' as in the example above for the 'Remote machine', provide the name of the machine on which the responder will run.

2. Create a $ZEUSHOME directory on the remote machine with the minimum set of files neccessary to run the fcgirunner.pl script:

         $ZEUSHOME/web/bin/fcgirunner.pl
         $ZEUSHOME/perl/miniperl
         $ZEUSHOME/perl/ZeusOS.pm
       

3. Export $ZEUSHOME to the enviroment that you will run the script from.

4. Ensure that your document root is available to the PHP processes e.g. exported via NFS.

Step 2 - Start PHP as a FastCGI runner

Before we start the runner, it is neccessary to set to enviroment variables. Default values will be used for now but please see the Tuning section later in this document to determine the most appropriate values for your system.

export PHP_FCGI_CHILDREN=8

export PHP_FCGI_MAX_REQUESTS=500

Now start the FastCGI runner as follows:

$ZEUSHOME/web/bin/fcgirunner 8002 <path to php binary>

Substitute the appropriate values for $ZEUSHOME and <path to php binary>; also substitute for 8002 the port you chose above. Note that the FastCGI service will now be listening on the specified port, and should be subject to standard security policies.

Please note that in Zeus 3.3.8, the 'fcgirunner' program requires perl to be installed. Further, it searches for perl in /usr/local/bin/perl. If it is not found there, you will see a 'file not found' error message. To correct this, put a symlink in /usr/local/bin to the real location of perl:

ln -s /usr/bin/perl /usr/local/bin/perl

To stop the fcgirunner you will need to manually kill the running PHP processes. (Use ps and kill). Since the web server is configured to use a 'remote' FastCGI runner, the web server itself will not be aware of what PHP processes are running.

The following example script written for linux will stop the FastCGI runner:

ps -efl | grep <path to php binary> | grep -v grep | awk '{print $4}' | xargs kill

Starting and stopping the FastCGI runner can be performed at the same time as the Zeus Web Server. You can do this using an executable SysV init script, placed in $ZEUSHOME/rc.d/S50external_php.

Note: You should avoid editing $ZEUSHOME/stop-zeus and $ZEUSHOME/start-zeus as these files are overwritten during product upgrades. You can download an example script for Linux only. This script must be modified as indicated to use the paths appropriate for your installation.

Whilst the "fcgirunner" script must be started by the root user, the FastCGI runner itself should execute as a non-root user - especially if you start the runner from your rc script. To do this, ensure that you specify an alternative non-privileged username and group that the fcgirunner script should through the use of the --user and --group flags. We advise against running FastCGI programs as root.

 $ZEUSHOME/web/bin/fcgirunner --user=$USERNAME --group=$GROUP --pidfile=$PIDFILE 8002 $FPHPBIN

The process ID of the fastcgi process will be stored in $PIDFILE (eg. /var/run/fcgiphp.pid). Please chmod this file to 666 so the script has the correct read+write permissions. Now, you can cleanly shut the process down using:

 kill -TERM -`cat $PIDFILE`

Use 'fcgirunner --help' or view the manpages for more information.

Step 3 - Test the installation

Create a file $DOCROOT/info.php containing the single line:

<? phpinfo(); ?>

From a browser, verify that fetching this file gives a valid page

If the above file can be displayed without error then, congratulations, you now have a basic working FastCGI/PHP installation. It is now neccessary ensure that there are enough PHP processes to handle the incomming connections.

Tuning FastCGI/PHP and the Operating System

Tuning FastCGI/PHP

When you start PHP, it will pre-fork a given number of child processes to handle incoming PHP requests. Each process will handle a given number of requests before exiting (and being replaced by a newly forked process). You can control these two parameters by setting the following environment variables BEFORE starting the FastCGI runner:

• PHP_FCGI_CHILDREN - the number of child processes to pre-fork. If not set, defaults to 8 (PHP versions below 4.3.0) or 0 (PHP versions 4.3.0 and above) - see below.
• PHP_FCGI_MAX_REQUESTS - the number of requests each PHP child process handles before exiting. If not set, defaults to 500.

If you are running PHP as a FastCGI, you can set these values in the FastCGI pages of the Admin Server under the section entitled 'Configuring Additional FastCGI Enviroment Variables'.

Note: When using PHP 4.3.0 and above, the default setting for PHP_FCGI_CHILDREN is "0". If you fail to set this variable to a higher value than the default, the PHP binary will not fork resulting in only one PHP request being processed at a time.

To choose suitable values for PHP_FCGI_CHILDREN and PHP_FCGI_MAX_REQUEST, we recommend you use a load testing program, e.g. ApacheBench, to exercise the web server whilst measuring the server system utilization (with e.g. top or vmstat). If, by increasing the load offered up by ApacheBench, you are not able to drive the server to 100% utilization, you will probably need to increase PHP_FCGI_CHILDREN. (An example would be, if a PHP script is blocked for a long time waiting for a response to a backend database, the server will be unable to handle more than PHP_FCGI_CHILDREN concurrent requests).

Tuning the Operating System

If you are running FastCGI/PHP as a Remote Responder and are expecting substantial PHP load when the site is deployed, it is likely that you will want to raise the number of ephemeral ports available on your server due to the number of TCP TIME_WAIT states that will accrue. Please consult the relevant documentation for your OS e.g. under Linux you will need to:

echo 1024 65000 > /proc/sys/net/ipv4/ip_local_port_range

You may also need to raise the number of file descriptors available, bothper-process and system-wide. Again, please consult the relevant documentation for your OS along with the Support FAQ on dealing with file descriptor shortages.

Ensuring the suitability of the tuning values

It is recommended that you load test you FastCGI/PHP responders on a test platform prior to releasing on a live site. This will highlight any Operating Sytem resource limitations issues. Benchmarking programs can be used to simulate load which will help you to determine the optimum tuning values. Zeus Technology have Performance engineers who are experienced in this field and can offer advice on getting the most out of your system. Please contact sales@zeus.com for more information.

Building and Installing CGI/PHP

It is also possible to run PHP as a CGI. We would recommend this when you are allowing customers to run their own scripts on the system and you need to enforce access control or process limits on those scripts.

1. Download the PHP source code and compile it with the required options. This will produce a php binary.

   Note: the configure option --enable-discard-path should not be used, as this prevents correct operation of PHP/CGI with Zeus.

2. From the 'URL Mapping' section of your virtual server, create a CGI script alias directory:

         Map requests for(relative to document root): 	/cgi-bin/
         Map requests to(filesystem path): 	/filesystem_path/cgi-bin/
   

   ... where, for security, filesystem_path should reside outside of any Virtual Server's document root directory.

   The rest of the example assumes that PHP is accessible via the URL /cgi-bin/php.

3. From the 'Handlers' section of the virtual server, set up a handler for files with the extension php to be processed by /cgi-bin/php.

         File Extension: 	*.php
         Specify the path and filename of the handler relative to the document root: 	/cgi-bin/php
   

4. Any file you now put in your docroot with the extension .php should now automatically be processed by PHP.

Authentication with PHP

By default, authentication information is not passed on to content generators such as PHP. If you wish your PHP scripts to check usernames and passwords using HTTP's Basic authentication, you must turn this on manually.

To do this, ensure that htaccess is enabled on the virtual server. The appropriate .htaccess file(s) (such as the global htaccess file) should contain the directive 'passenvauthorization on'.

Content Manager [Administrator] 08 November 2005   1 comment