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