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