How-To¶

Override Auto Detected PHP¶

Starting with LiteSpeed Web Server 5.3, PHP Setup is located in the PHP section of LSWS and can be auto detected in control panel environments. Sometimes, though, you may need to override an auto-detected PHP, and this can easily be set up by configuring an LSAPI External Application and Script Handler for PHP. When setting up an LSAPI External Application and Script Handler for PHP, it will take precedent over the auto detection.

Settings¶

You will need to set up a LiteSpeed SAPI External Application and a Script Handler inside of LiteSpeed Web Server. Here are the various settings to configure that we have for each section.

LiteSpeed SAPI App¶

Title	Value	Description
Name	`lsphp74`	A unique name for this external application.
Address	`uds://tmp/lshttpd/lsphp74.sock`	A unique socket address used by the external application. IPv4/IPv6 sockets and Unix Domain Sockets (UDS) are supported.
Notes	`blank`	Add notes for yourself.
Max Connections	`35`	Specifies the maximum number of concurrent connections that can be established between the server and an external application.
Environment	`PHP_LSAPI_CHILDREN=35`	Specifies extra environment variables for the external application.
Initial Request Timeout	`60`	Specifies the maximum time in seconds the server will wait for the external application to respond to the first request over a new established connection.
Retry Timeout	`0`	Specifies the period of time that the server waits before retrying an external application that had a prior communication problem.
Persistent Connection	`Yes`	Specifies whether to keep the connection open after a request has been processed.
Connection Keepalive Timeout	`Not Set`	Specifies the maximum time in seconds to keep an idle persistent connection open.
Response Buffering	`No`	Specifies whether to buffer responses received from external applications.
Start By Server	`Yes (Through CGI Daemon Async)`	Specifies whether you want the web server to start the application automatically.
Command	`/usr/local/lsws/lsphp74/bin/lsphp`	Specifies the full command line including parameters to execute the external application.
Back Log	`100`	Specifies the backlog of the listening socket. Required if "Start By Server" is enabled.
Instances	`1`	Specifies the maximum instances of the external application the server will create.
Run As User	`Not Set`	The external application will run as this specified user name.
Run As Group	`Not Set`	The external application will run as this specified group name.
umask	`Not Set`	Sets default umask for CGI processes.
Run On Startup	`Yes (Detached mode)`	Specifies whether to start the external application at server start up.
Max Idle Time	`10`	Specifies the maximum idle time before an external application is stopped by the server, freeing idle resources.
Priority	`0`	Specifies priority of the external application process.
Memory Soft Limit	`2047M`	Specifies the memory consumption limit in bytes for an external application process or an external application started by the server.
Memory Hard Limit	`2048M`	Much the same as "Memory Soft Limit (bytes)", except the soft limit can be raised up to the hard limit from within a user process.
Process Soft Limit	`400`	Limits the total number of processes that can be created on behalf of a user.
Process Hard Limit	`500`	Much the same as "Process Soft Limit", except the soft limit can be raised up to the hard limit from within a user process.

Notes

Name and Address need to be unique values.

Max Connections and PHP_LSAPI_CHILDREN values need to match, in this case both need to equal 35.

Anything that is set as Not Set is not a required field.

Script Handler¶

Title	Value	Description
Suffixes	`php`	Specifies the unique script file suffixes that will be handled by this script handler.
Handler Type	`LiteSpeed SAPI`	Specifies the type of external application that processes these script files.
Handler Name	`lsphp74`	Specifies the name of the external application that processes the script files when the handler type is FastCGI, Web Server, LSAPI, Load Balancer, or Servlet Engine.
Notes	`blank`	Add notes for yourself.

Notes

Each Suffixes value needs to be unique from each other.

Notes is not a required field

Set Up¶

GUI¶

The easiest way to set up the external application and script handler is via our WebAdmin Console which gives you a Graphical User Interface ( GUI ) to add all of the settings needed.

Here are the step by step instructions for how to do this via our GUI:

Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
Navigate to Configuration > Server > External Application.
Click Add, then select Type: LSAPI App, and click Next.
While on this page be sure to fill in all the required fields. For default values and recommended values you can hover over the tooltip icon or reference this section here. Once everything is filled out be sure to hit Save.
Navigate to Configuration > Server > Script Handler.
While on this page be sure to fill in all the required fields. For default values and recommended values you can hover over the tooltip icon or reference this section here. Once everything is filled out be sure to hit Save.
Now that everything has been set up, navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.

That is it! The external application and script handler is now fully setup and pages ending in the suffix you put for your script handler will use this external application to process the page.

Command Line¶

It is possible to set up the external application and script handler manually via a terminal. Open /usr/local/lsws/conf/httpd_config.xml with your favorite editor (nano, vim, emacs, etc). An example when using, vi:

$ sudo vi /usr/local/lsws/conf/httpd_config.xml

Then, find the <extProcessorList></extProcessorList> block and add the following to it:

<extProcessor>
  <type>lsapi</type>
  <name>lsphp74</name>
  <address>uds://tmp/lshttpd/lsphp74.sock</address>
  <maxConns>35</maxConns>
  <env>PHP_LSAPI_CHILDREN=35</env>
  <initTimeout>60</initTimeout>
  <retryTimeout>0</retryTimeout>
  <persistConn>1</persistConn>
  <respBuffer>0</respBuffer>
  <autoStart>3</autoStart>
  <path>/usr/local/lsws/lsphp74/bin/lsphp</path>
  <backlog>100</backlog>
  <instances>1</instances>
  <runOnStartUp>3</runOnStartUp>
  <extMaxIdleTime>10</extMaxIdleTime>
  <priority>0</priority>
  <memSoftLimit>2047M</memSoftLimit>
  <memHardLimit>2048M</memHardLimit>
  <procSoftLimit>400</procSoftLimit>
  <procHardLimit>500</procHardLimit>
</extProcessor>

Note

Be sure there is not another <extProcessor></extProcessor> with the same <name></name>. This needs to be unique and can break LiteSpeed Web Server when you restart it.

After the external application has been added, find the <scriptHandlerList></scriptHandlerList> block and add the following to it:

<scriptHandler>
  <suffix>php</suffix>
  <type>lsapi</type>
  <handler>lsphp74</handler>
</scriptHandler>

Note

Be sure there is not another <scriptHandler> with the same suffix. This needs to be unique and can break LiteSpeed Web Server when you restart it.

To have the changes you have just made to /usr/local/lsws/conf/httpd_config.xml take affect inside of LiteSpeed Web Server run the following:

$ sudo touch /usr/local/lsws/admin/tmp/.lsphp_restart.txt
$ sudo systemctl restart lsws