Advanced¶

Set up 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.
   

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.
   

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.
   

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.

   

Unmanaged Process Groups¶

To connect an unmanaged PHP handler via a socket address defined within the LiteSpeed PHP handler configuration, add the LSPHP_ProcessGroup unmanaged directive to the Apache configuration at the server level or at the virtual host level, like so:

<IfModule LiteSpeed>
LSPHP_ProcessGroup unmanaged
</IfModule>

This is useful in a situation where you want to use LSPHP command-line mode with some variables in a LiteSpeed external app template, like so:

<extProcessorList>
  <extProcessor>
    <type>lsapi</type>
    <name>extapp-php</name>
    <address>uds://tmp/lsphp-$VH_USER.sock</address>
    <maxConns>35</maxConns>
    <initTimeout>60</initTimeout>
    <retryTimeout>0</retryTimeout>
    <respBuffer>0</respBuffer>
    <autoStart>0</autoStart>
  </extProcessor>
</extProcessorList>

If you are defining a UNIX socket by using $VH_USER or $VH_NAME variables in the <address> path of the external app, like in the example above, the LSPHP_ProcessGroup unmanaged directive makes sure that the variable is applied.