README.md
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. Login to 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 freqently 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_CHIDLREN`, 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
