How-To

Set up LSPHP in Command Line Mode

Usually, LSPHP(LSAPI + PHP) is managed by LiteSpeed Web Server. In a clustered environment, though, with a single LiteSpeed Web Server or LiteSpeed Web ADC load balancing LSPHP processes running on multiple backend servers, it may be necessary to start LSPHP processes manually. LSPHP is an executable and can be started manually and bound to IPv4, IPv6, or Unix Domain Socket (UDS) addresses with the command line option -b <address>

  1. First step is to start LSPHP with its -b option, this can be accomplished by running the following command in a terminal:

    $ sudo /path/to/lsphp -b <address>
    

    Important

    You will want to run this command on every server that you want to Load Balance LSPHP to.

    • /path/to/lsphp - Path to and including the LSPHP binary.
    • <address> - The address that the LSPHP binary is bound to via IP_ADDRESS:PORT or Unix Domain Socket. If using an IP, a PORT is required and can be any open port on your system. Here are a couple of examples:
      • IPv4 + IPv6: [::]:PORT will bind to every IPv4 and IPv6 IP on your server.
      • IPv4: *:PORT will bind to every IPv4 IP (and only IPv4 IPs) on your server.
      • Specific IP: IP_ADDRESS:PORT will bind to specific IPv4/IPv6 address. (Replace IP_ADDRESS and PORT with the specific IP and port on your system you want LSPHP to run on.)
      • Unix Domain Socket: /var/run/name.sock will bind to the specific Unix Domain Socket. (Replace path+name with where and what you want to call it.)

    Info

    Environment Variables can be added before the LSPHP executable. The PHP_LSAPI_CHILDREN=nn is required when run LSPHP is run as a service to handle concurrent requests. Be sure to replace nn with the value of the Max Connections for the External Application on the frontend LiteSpeed Web Server.

    Here is an example when using Environment Variables:

    $ sudo PHP_LSAPI_MAX_REQUESTS=5000 PHP_LSAPI_CHILDREN=35 /path/to/lsphp -b <address>
    

  2. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.

  3. On the frontend LiteSpeed Web Server you will need to set up an External Application for each server you set up to run LSPHP.

    1. Navigate to Configuration > Server > External Application.
    2. Click Add, then select Type: LSAPI App, and click Next.
    3. While on this page be sure to fill in all the required fields and once done click Save:
      • Set Name to any name you have not used yet for an External Application.
      • Set Address to the IP_ADDRESS:PORT or UDS that LSPHP is listening on.
      • Set Max Connections to what you set PHP_LSAPI_CHILDREN to.
      • Set Initial Request Timeout to 60.
      • Set Retry Timeout to 0.
      • Set Start By Server to No.

    !webadmin-extapp-extphp

  4. Set up LiteSpeed Web Server to load balance these LSPHP External Applications.

    1. Navigate to Configuration > Server > External Application.
    2. Click Add, then select Type: Load Balancer, and click Next.
    3. While on this page be sure to fill in all the required fields and once done click Save:
      • Set Name to any name you have not used yet for an External Application.
      • Set Workers to the EXT_APP_TYPE::EXT_APP_NAME that you set up previously for each of the LSPHP backend servers you have.

    !webadmin-extapp-loadbalancer

  5. Once all the External Applications have been set up, you will need to set up a Script Handler so all .php files are run by the Load Balancer.

    1. Navigate to Configuration > Server > Script Handler.
    2. Click Add, then while on this page be sure to fill in all the required fields and once done click Save:
      • Set Suffixes to php.
      • Set Handler Type to Load Balancer.
      • Set Handler Name to the name of the Load Balancer that you setup.

    !webadmin-extapp-sh-lb

  6. 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.

    !webadmin-restart

Notes

  • When using a load balancing LSPHP backend setup, everything with PHP files needs to be the same. This means the file locations and files need to be the same on both the master and slave servers.
  • For load balancing a backend LSPHP setup, since PHP runs on different servers, a central shared PHP session storage (like memcached, redis, etc) is recommended as LSWS load balancing is not session aware. An ideal set up is using LiteSpeed Web ADC which is session aware in front of LiteSpeed Web Server clusters.

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:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > External Application.
  3. Click Add, then select Type: LSAPI App, and click Next.
  4. 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.
    !webadmin-extapp-lsapi
  5. Navigate to Configuration > Server > Script Handler.
  6. 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.
    !webadmin-extapp-sh
  7. 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.
    !webadmin-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


Last update: August 19, 2020