Using PHP4 with the Zeus Web Server ----------------------------------- Zeus fully supports running PHP in combination with our webserver. A significant improvement in PHP 4 is that you can now run PHP as an ISAPI module, giving great performance benefits over traditional CGI code. Note that you will need to be running at least version 3.3.6 of the webserver. If you are running an earlier version, please see our website (http://www.zeus.com) for upgrade instructions. To build the ISAPI version of PHP, start the configuration with: ./configure --with-zeus=/usr/local/zeus Obviously, replace /usr/local/zeus with the location of where you have installed Zeus on your machine. For PHP to build successfully, you need to have 3.3.6 already installed, because the code relies on the presence of header files provided with the latest version. You may have to adjust the environment variable LDFLAGS and EXTRA_LIBS in order to link in extra libraries. This depends on the platform on which you are building and also on the compiler used (see below). A standard GNU/Linux install with GCC should build fine with no changes. Configuring the webserver ------------------------- After running 'make' and 'make install', you will have a 'libphp4.so' file. Copy this file into a directory reserved for ISAPI binaries. Now, perform the following steps for each virtual server that you wish to run PHP on: 1) On the Admin server, go to 'edit server->path mapping' 2) Add an alias to the directory with libphp4.so in it, mapped to /isapi/ (or a location of your choice). Make sure you set the alias type to ISAPI. 3) Click 'update' 4) Add a handler for file extension 'php' to be run by /isapi/libphp4.so 5) Click 'update', then go back to the previous page. 6) Click on the 'module configuration' button, ensure that ISAPI support is ticked. 7) Click on the ISAPI link. At the bottom of the page, click the checkbox for running ISAPI extensions 'out of process'. 8) Click 'update'. Then restart the virtual server. Done! Troubleshooting --------------- *) Why does the compile fail at Zend/zend-scanner-cc.cc or Zend/zend-parser.c ? These source files are auto-generated from the corresponding .y files. The default distribution of PHP contains pre-generated versions of these files that have caused problems for some people. The simplest solution is to delete the files. They will then be rebuilt correctly. You must have the following GNU tools to do this: bison 1.28 or later flex 2.5.4 or later *) Why does my PHP library fail to load? After configuring Zeus, if you get a '502 Bad Gateway' error when accessing a PHP page, there are problems loading the PHP library. Check the error log ($ZEUSHOME/web/log/errors) for errors. Failing to load the PHP ISAPI module is likely to be due to unresolved symbols in the module. A way to check for this is to visit our support page at http://support.zeus.com/faq/entries/isapi_error.html and run the program there on your libphp4.so. It will list any unresolved symbols. *) My libphp4.so has unresolved symbols. How do I fix this? You must ensure that the PHP build process links in the appropriate libraries that contain these symbols! The libraries required will depend on the platform you are running PHP on. You may need to set one or two environment variables before running the 'configure' program to set up PHP; LDFLAGS and EXTRA_LIBS. Make sure that you also export these variables to the build process. (Type 'export LDFLAGS EXTRA_LIBS' in the shell to do this.) If you are using 3rd party tools and libraries which are installed in non-standard locations, you may need to set the environment variable LD_LIBRARY_PATH to point to the library's location, prior to running the Zeus Web Server. For example, if you have compiled external MySQL support, and mysql is installed in /usr/local/mysql, you should set LD_LIBRARY_PATH to '/usr/local/mysql/lib/mysql' and then 'export LD_LIBRARY_PATH'. For convenience, you should add this to the 'start-zeus' script provided. Yet another method of ensuring the linked libraries are found is to set the environment variable LD_RUN_PATH before compiling PHP. This works in a similar way to LD_LIBRARY_PATH, but at compile-time. Libraries produced with this envrionment variable set will have its value 'burned' into the resultant binary, specifying a runtime search pth to locate other required libraries such as MySQL. On Linux, you can also tell the dynamic linker where to find the libraries, by adding '/usr/local/mysql/lib/mysql' to the file /etc/ld.so.conf - after editting this file, run 'ldconfig' as root, to use the changes. Specific examples: Solaris + gcc: Ensure you run ./configure with the `--enable-libgcc' parameter. You may need to set LDFLAGS to '-L/usr/local/egcs/lib' (path depends on your gcc installation) FreeBSD 4: Some people may find they need to run ./configure with the '--enable-libgcc' compile option too. Performance issues ================== To make PHP run fast under Zeus, check the following points: 1) Run PHP as an ISAPI module, not a CGI - compile it with the --with-zeus=... flag! 2) Tune the ISAPI runner to your required workload. There are several tuneables that can be given. These are set by adding the appropriate lines to the $ZEUSHOME/web/global.cfg file. Changes to this file will only be picked up after the web server is restarted (run stop-zeus ; start-zeus) tuning!modules!isapi!external!maxthreads xxx - Sets the maximum number of threads that the ISAPI runner will spawn. If further PHP page requests arrive, they will be queued until a current page is finished. For busy websites, we suggest increasing this value (defaults to 16). Replace the 'xxx' in the above line with the required number of threads. Note that the threads are equally shared between ISAPI extensions and filters, so if you want to handle 100 concurrent PHP page requests, set this tuneable to 200. tuning!modules!isapi!external!minthreads xxx - Sets the minimum number of threads. Idle threads will be kept in a pool, which avoids costly thread creation/deletion. For more information and help with Zeus, please visit our website: http://support.zeus.com