Return to README CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / sapi / litespeed

v 5.4.20

    1: Introduction
    2: ============
    3: 
    4: LiteSpeed SAPI module is a dedicated interface for PHP integration with
    5: LiteSpeed Web Server. LiteSpeed SAPI has similar architecture to the
    6: FastCGI SAPI with there major enhancements: better performance, dynamic 
    7: spawning and PHP configuration modification through web server
    8: configuration and .htaccess files.  
    9: 
   10: Our simple benchmark test ("hello world") shows that PHP with
   11: LiteSpeed SAPI has 30% better performance over PHP with FastCGI SAPI,
   12: which is nearly twice the performance that Apache mod_php can deliver. 
   13:  
   14: A major drawback of FastCGI PHP comparing to Apache mod_php is lacking
   15: the flexibilities in PHP configurations. PHP configurations cannot be 
   16: changed at runtime via configuration files like .htaccess files or web
   17: server's virtual host configuration. In shared hosting environment, 
   18: each hosting account will has its own "open_basedir" overridden in 
   19: server configuration to enhance server security when mod_php is used.
   20: usually, FastCGI PHP is not an option in shared hosting environment 
   21: due to lacking of this flexibility. LiteSpeed SAPI is carefully designed
   22: to address this issue. PHP configurations can be modified the same way 
   23: as that in mod_php with the same configuration directives. 
   24: 
   25: PHP with LiteSpeed SAPI is highly recommended over FastCGI PHP for 
   26: PHP scripting with LiteSpeed web server. 
   27: 
   28: 
   29: Building PHP with LiteSpeed SAPI
   30: ================================
   31: 
   32: You need to add "--with-litespeed" to the configure command to build
   33: PHP with LiteSpeed SAPI, all other SAPI related configure options
   34: should be removed. 
   35: 
   36: For example: 
   37:     ./configure --with-litespeed
   38:     make
   39: 
   40: You should find an executable called 'php' under sapi/litespeed/
   41: directory after the compilation succeeds. Copy it to
   42: 'lsws/fcgi-bin/lsphp' or wherever you prefer, if LiteSpeed web server
   43: has been configured to run PHP with LiteSpeed SAPI already, you just
   44: need to overwrite the old executable with this one and you are all
   45: set. 
   46: 
   47: Start PHP from command line
   48: ===========================
   49: 
   50: Usually, lsphp is managed by LiteSpeed web server in a single server
   51: installation. lsphp can be used in clustered environment with one 
   52: LiteSpeed web server at the front, load balancing lsphp processes 
   53: running on multiple backend servers. In such environment, lsphp can be
   54: start manually from command with option "-b <socket_address>", socket 
   55: address can be IPv4, IPv6 or Unix Domain Socket address. 
   56: for example:
   57: 
   58:     ./lsphp -b [::]:3000
   59: 
   60: have lsphp bind to port 3000 on all IPv4 and IPv6 address,
   61: 
   62:     ./lsphp -b *:3000
   63: 
   64: have lsphp bind to port 300 on all IPv4 address.
   65: 
   66:     ./lsphp -b 192.168.0.2:3000
   67: 
   68: have lsphp bind to address 192.168.0.2:3000.
   69: 
   70:     ./lsphp -b /tmp/lsphp_manual.sock
   71: 
   72: have lsphp accept request on Unix domain socket "/tmp/lsphp_manual.sock"
   73: 
   74: 
   75: Using LiteSpeed PHP with LiteSpeed Web Server
   76: =============================================
   77: 
   78: Detailed information about how to configure LiteSpeed web server with
   79: PHP support is available from our website, at: 
   80: 
   81: http://www.litespeedtech.com/docs/HowTo_QA.html
   82: 
   83: Usually, PHP support has been configured out of box, you don't need to
   84: change it unless you want to change PHP interface from FastCGI to
   85: LiteSpeed SAPI or vice versa. 
   86: 
   87: Brief instructions are as follow:
   88: 
   89: 1) Login to web administration interface, go to 'Server'->'Ext App' tab,
   90:    add an external application of type "LSAPI app", "Command" should be
   91:    set to a shell command that executes the PHP binary you just built. 
   92:    "Instances" should be set to "1". Add "LSAPI_CHILDREN" environment 
   93:    variable to match the value of "Max Connections". More tunable 
   94:    environment variable described below can be added. 
   95: 
   96: 2) Go to 'Server'->'Script Handler' tab, add a script handler
   97:    configuration: set 'suffix' to 'php', 'Handler Type' to 'LiteSpeed
   98:    API', 'Handler Name' should be the name of external application
   99:    just defined. 
  100: 
  101: 
  102: 3) Click 'Apply Changes' link on the top left of the page, then click 
  103:    'graceful restart'. Now PHP is running with LiteSpeed SAPI. 
  104: 
  105: Tunings
  106: -------
  107: 
  108: There are a few environment variables that can be tweaked to control the
  109: behavior of LSAPI application.  
  110: 
  111: * LSAPI_CHILDREN or PHP_LSAPI_CHILDREN  (default: 0)
  112: 
  113: There are two ways to let PHP handle multiple requests concurrently, 
  114: Server Managed Mode and Self Managed Mode. In Server Managed Mode, 
  115: LiteSpeed web server dynamically spawn/stop PHP processes, in this mode
  116: "Instances" should match "Max Connections" configuration for PHP 
  117: external application. To start PHP in Self Managed Mode, "Instances" 
  118: should be set to "1", while "LSAPI_CHILDREN" environment variable should
  119: be set to match the value of "Max Connections" and >1. Web Server will 
  120: start one PHP process, this process will start/stop children PHP processes 
  121: dynamically based on on demand. If "LSAPI_CHILDREN" <=1, PHP will be 
  122: started in server managed mode.
  123: 
  124: Self Managed Mode is preferred because all PHP processes can share one 
  125: shared memory block for the opcode cache.
  126: 
  127: Usually, there is no need to set value of LSAPI_CHILDREN over 100 in
  128: most server environment. 
  129: 
  130: 
  131: * LSAPI_AVOID_FORK              (default: 0)
  132: 
  133: LSAPI_AVOID_FORK specifies the policy of the internal process manager in
  134: "Self Managed Mode". When set to 0, the internal process manager will stop
  135: and start children process on demand to save system resource. This is
  136: preferred in a shared hosting environment. When set to 1, the internal
  137: process manager will try to avoid freqently stopping and starting children
  138: process. This might be preferred in a dedicate hosting environment.
  139: 
  140: 
  141: * LSAPI_EXTRA_CHILDREN          (default: 1/3 of LSAPI_CHILDREN or 0)
  142: 
  143: LSAPI_EXTRA_CHILDREN controls the maximum number of extra children processes
  144: can be started when some or all existing children processes are in
  145: malfunctioning state. Total number of children processes will be reduced to
  146: LSAPI_CHILDREN level as soon as service is back to normal.
  147: When LSAPI_AVOID_FORK is set to 0, the default value is 1/3 of
  148: LSAPI_CHIDLREN, When LSAPI_AVOID_FORK is set to 1, the default value is 0.
  149: 
  150: 
  151: * LSAPI_MAX_REQS or PHP_LSAPI_MAX_REQUESTS (default value: 10000)
  152: 
  153: This controls how many requests each child process will handle before
  154: it exits automatically. Several PHP functions have been identified 
  155: having memory leaks. This parameter can help reducing memory usage 
  156: of leaky PHP functions. 
  157: 
  158: 
  159: * LSAPI_MAX_IDLE                (default value: 300 seconds)
  160: 
  161: In Self Managed Mode, LSAPI_MAX_IDLE controls how long a idle child  
  162: process will wait for a new request before it exits. This option help 
  163: releasing system resources taken by idle processes.
  164: 
  165: 
  166: * LSAPI_MAX_IDLE_CHILDREN
  167:     (default value: 1/3 of LSAPI_CHILDREN or LSAPI_CHILDREN)
  168: 
  169: In Self Managed Mode, LSAI_MAX_IDLE_CHILDREN controls how many idle 
  170: children processes are allowed. Excessive idle children processes
  171: will be killed by the parent process immediately.
  172: When LSAPI_AVOID_FORK is set to 0, the default value is 1/3 of
  173: LSAPI_CHIDLREN, When LSAPI_AVOID_FORK is set to 1, the default value
  174: is LSAPI_CHILDREN.
  175: 
  176: 
  177: * LSAPI_MAX_PROCESS_TIME        (default value: 300 seconds)
  178: 
  179: In Self Managed Mode, LSAPI_MAX_PROCESS_TIME controls the maximum 
  180: processing time allowed when processing a request. If a child process
  181: can not finish processing of a request in the given time period, it 
  182: will be killed by the parent process. This option can help getting rid 
  183: of dead or runaway child process.
  184: 
  185: 
  186: * LSAPI_PGRP_MAX_IDLE           (default value: FOREVER )
  187: 
  188: In Self Managed Mode, LSAPI_PGRP_MAX_IDLE controls how long the parent
  189: process will wait before exiting when there is no child process.
  190: This option help releasing system resources taken by an idle parent 
  191: process.
  192: 
  193: 
  194: * LSAPI_PPID_NO_CHECK
  195: 
  196: By default a LSAPI application check the existence of its parent process
  197: and exits automatically if the parent process died. This is to reduce 
  198: orphan process when web server is restarted. However, it is desirable 
  199: to disable this feature, such as when a LSAPI process was started 
  200: manually from command line. LSAPI_PPID_NO_CHECK should be set when 
  201: you want to disable the checking of existence of parent process.
  202: When PHP started by "-b" option, it is disabled automatically. 
  203: 
  204: 
  205: Compatibility with Apache mod_php
  206: =================================
  207: 
  208: LSAPI PHP supports PHP configuration overridden via web server configuration 
  209: as well as .htaccess. 
  210: Since 4.0 release "apache_response_headers" function is supported.
  211: 
  212: 
  213: 
  214: Contact
  215: =======
  216: 
  217: For support questions, please post to our free support forum, at:
  218: 
  219: http://www.litespeedtech.com/forum/
  220: 
  221: For bug report, please send bug report to bug [at] litespeedtech.com.
  222: 
  223: 
  224: 
  225: