Custom PHP Script Handler in LSWS + Control Panel environment

The default installation of LiteSpeed Web Server provides external applications for PHP4 and PHP5. With cPanel and other hosting control panels, though, administrators can provide even more versions of PHP (e.g. PHP 5.2.x or PHP 5.3.x for PHP5). Providing these multiple versions in LiteSpeed requires further customization of your setup. This document details the steps needed to create custom PHP script handlers in the control panel environment (cPanel, DirectAdmin, Plesk, etc) to provide for multiple PHP versions. Enabling multiple PHP versions provides flexibility to suit different end user needs and improves service quality.

When using LSWS with a control panel, users’ web server configurations (httpd.conf files) are managed via the control panel. LSWS can manage server-level settings, but has no control over the the individual user level (the virtual host level). LSWS instead reads these user-specific configurations via the Using Apache Configuration File settings at the server level. Thus, to make multiple PHP versions available to users, soem settings can be set through the WebAdmin console while other settings are changed directly through directives in the appropriate files. The following steps are required:

• Multiple external applications need to be created in LSWS at the server level. Each external application will correspond with a compiled PHP binary (different PHP versions or same version with different extensions).
• Script handlers need to be set up in LSWS at the server level to correspond with each external application created. This step essentially creates MIME types for each php binary built.
• To configure special MIME types at the user level, AddHandler, AddType, or ForceType directives need to be added in httpd.conf or .htaccess files.

1. Compile multiple PHP versions (with needed extensions) for LSWS. You can also make separate PHP binaries each with different extensions but the SAME PHP version.

     PHP 5.3.24 (with GD + Mailparse) : /usr/local/lsws/lsphp5324gm/bin/lsphp
     PHP 5.3.24 (with SOAP) : /usr/local/lsws/lsphp5324soap/bin/lsphp
     PHP 5.4.14 (with SOAP) : /usr/local/lsws/lsphp5414soap/bin/lsphp

Notes:

• Refer to the LSPHP Build and LSPHP Troubleshooting Guide wikis for how to compile and build PHP for LSWS.

• Use the prefix option (’–prefix’) to put each LSPHP build in its own folder (/path/to/prefix/bin/lsphp).

     ./configure '--prefix=/usr/local/lsws/lsphp5324gm' '--with-litespeed' ...
     make
     make install

     ./configure '--prefix=/usr/local/lsws/lsphp5324soap' '--with-litespeed' ...
     make
     make install

     ./configure '--prefix=/usr/local/lsws/lsphp5414soap' '--with-litespeed' ...
     make
     make install

• It is also possible to compile different LSPHP versions from the WebAdmin console (Actions → Compile PHP). Doing so from the WebAdmin console, though, puts each LSPHP build in /usr/local/lsws/fcgi-bin/lsphp-version (i.e. /usr/local/lsws/fcgi-bin/lsphp5414 for LSPHP 5.4.14). Because of this naming convention, you can use the WebAdmin console to compile PHP ONLY IF you do not use PHP builds of the same version but with different extensions. (i.e. The example of 5.3.24 with Soap and 5.3.24 with GD + Mailparse given above is not possible using the WebAdmin console.) /usr/local/lsws/fcgi-bin/lsphp5 is a symlink pointing to the build in use by default.

2. Set up each PHP version binary as an LSAPI type external application (with a unique name) in LSWS at the server level. (LSWS WebAdmin Console → Configuration → Server → External App → Add) Sample settings below:

     lsphp53_1 --> PHP 5.3.24 (with GD + Mailparse)
           Name: lsphp53_1
           Address: uds://tmp/lshttpd/lsphp5324gm.sock 
           Command: /usr/local/lsws/lsphp5324gm/bin/lsphp
           Auto Start: Yes
           Memory Soft Limit(bytes): 200M
           Memory Hard Limit(bytes): 300M
           Process Soft Limit: 200
           Process Hard Limit: 200

     lsphp53_2 --> PHP 5.3.24 (with SOAP)
           Name: lsphp53_2
           Address: uds://tmp/lshttpd/lsphp5324soap.sock 
           Command: /usr/local/lsws/lsphp5324soap/bin/lsphp
           Auto Start: Yes
           Memory Soft Limit(bytes): 200M
           Memory Hard Limit(bytes): 300M
           Process Soft Limit: 200
           Process Hard Limit: 200

     lsphp54 --> PHP 5.4.14 (with SOAP)
           Name: lsphp54
           Address: uds://tmp/lshttpd/lsphp5414soap.sock 
           Command: /usr/local/lsws/lsphp5414soap/bin/lsphp
           Auto Start: Yes
           Memory Soft Limit(bytes): 200M
           Memory Hard Limit(bytes): 300M
           Process Soft Limit: 200
           Process Hard Limit: 200

Note: The socket addresses can be anything, but they must be unique. Memory limits and process limits given are for reference. Modify as needed.

3. Each external application must have script handlers set up at the server level to tell the web server which scripts to send to which application. Script handlers are set up in the LSWS WebAdmin console. (LSWS WebAdmin Console → Configuration → Server → Script Handler → Add) Sample script handler settings are below:

        suffix --> ext app
        ===================
        php5 --> lsphp53_1
        php53 --> lsphp53_2
        php54 --> lsphp54

Creating script handlers automatically creates MIME types for the suffixes you stipulate. (This only happens for the first suffix stipulated in each script handler’s settings. Additional suffixes require that you set up a corresponding MIME type manually in LSWS WebAdmin Console → Configuration → General → MIME Settings.) The MIME types automatically set up for the suffixes stipulated above would be:

 
        application/x-httpd-php5
        application/x-httpd-php53
        application/x-httpd-php54

4. You and your users can now go into your files and change file suffixes so that each script goes to the proper application (and thus the proper version of PHP). You can also use directives (in httpd.conf and .htaccess files) to manipulate how the server translates suffixes into MIME types. It is these MIME types, not the actual suffixes on the file, that the server looks at when assigning scripts to script handlers. Thus the AddType, ForceType, and AddHandler directives can change which script handler a file goes to, even if the actual suffix is not changed. For example, the following in a .htaccess file would cause all .php files in that directory to be run in PHP 5.3.24 (because it would be sent to the lsphp53_1 external application):

          
        AddType application/x-httpd-php5 php

The directive below would also have the same effect:

        AddHandler application/x-httpd-php5 php	

Another way to solve the problem is to use the ForceType directive. ForceType in a .htaccess file changes all files in the directory to a single MIME-type. The following command would cause all files in this directory to be sent to the lsphp53_1 external application:

        ForceType application/x-httpd-php5

If you want to use multiple PHP versions for files in the same directory, you will have to change some suffixes. In the following example we’re using all three versions of PHP for files with different suffixes in the same directory:

        AddType application/x-httpd-php5 php53
        AddType application/x-httpd-php53 php
        AddType application/x-httpd-php54 php54

(The last directive is actually unnecessary, as that suffix-to-MIME type mapping was set when we set up a script handler for the suffix php54.)

Notes:

• Users or host provider can designate PHP versions by location or by suffix, whichever makes more sense to them.
• With PHP suEXEC mode, many MIME types are NOT supported. As of 4.1.12, suEXEC-capable suffixes are: “php, php4, php5, php52, php53, phtml, php54, fastphp”.