Documentation for PHP LiteSpeed Server API https://www.litespeedtech.com/images/logos/litespeed/litespeed-logo.png 2018-01-22 19:57:07 Installing, configuring, and using PHP LiteSpeed Server API

PHP LSAPI Documentation

Installing, configuring, and using PHP LSAPI

PHP LSAPI Installation/Upgrade

PHP LSAPI is included in PHP packages 5.3 and up. PHP will automatically be configured for use with LSAPI when you compile PHP using LiteSpeed (WebAdmin console > Actions > Compile PHP).

If a new version of PHP LSAPI comes out, it will be bundled with the latest version of LiteSpeed Web Server. To get this version of LSAPI, simply perform a force-reinstall of the latest version of LSWS (WebAdmin console > Actions > Version Manager) and recompile PHP. If you are using the WHM plugin, you do not need to reinstall LSWS. You can get the latest version of LSAPI by just rebuilding matching PHP in the plugin.

PHP LSAPI Administration

Using LiteSpeed PHP with LiteSpeed Web Server

PHP support has been configured out of box for PHP 4 and PHP 5. Many users will want to compile their own PHP version, though. If you compile PHP using LSWS's Compile PHP feature (WebAdmin console > Actions > Compile PHP), this new PHP will be automatically accessed by the default PHP configurations.

Below are brief instructions for creating new implementations of LSPHP yourself: (More complete guides can be found in our wiki.)

  1. Add an external application: Log into the WebAdmin console. Go to Server > External App. Add an external application of type "LSAPI app". "Command" should be set to the path of the PHP binary. "Instances" should be set to "1". Add an "LSAPI_CHILDREN" environment variable to match the value of "Max Connections". Do not set it to a large value. "20" is a good value to start with.

  2. Create a script handler: Go to Server > Script Handler. Add a script handler and set "suffix" to "php" or "php5", depending on the suffix of your PHP scripts. "Handler Type" should be set to "LiteSpeed SAPI". "Handler Name" should be the name of external application you just added.

  3. Graceful restart to apply changes: (WebAdmin console > Actions > Graceful Restart) Scripts with the suffix you defined in the script handler will now use the external application you created.

Generate formatted PHP source code in html

Since PHP LiteSpeed SAPI 4.3, PHP LSAPI has been capable of generating formatted PHP source code in html. This can be turned on for a process using the command line option -s. If you want LSWS to generate PHP source code for files with certain suffix, "phps" for example, add a dedicated external application with "-s" at the end of the "Command" setting. Then add a script handler for the suffix "phps".

Start LSPHP from the command line

Usually, LSPHP is managed by LiteSpeed Web Server. In a clustered environment, though, with one LiteSpeed Web Server or LiteSpeed Load Balancer at the front 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 addresses with the command line option -b socket_address

Examples:

Have LSPHP bind to port 3000 on all IPv4 and IPv6 addresses:

./lsphp -b [::]:3000

Have LSPHP bind to port 3000 on all IPv4 addresses:

./lsphp -b *:3000

Have LSPHP bind to address 192.168.0.2:3000 :

./lsphp -b 192.168.0.2:3000

Have LSPHP accept requests on Unix domain socket "/tmp/lsphp_manual.sock":

./lsphp -b /tmp/lsphp_manual.sock

PHP LSAPI Configuration

External Application Settings

Much of your LSPHP settings are controlled by your external application settings (WebAdmin console > Configuration > External App). These settings are explained in the LiteSpeed Web Server documentation.

LSAPI setups can be further configured, however, using the directives and environment variables listed below.

LiteSpeed-Specific Directives

Note:
The following directives are LiteSpeed-specific directives. Apache will not understand them and may crash if they are not wrapped in <IfModule>, as in the following example:

<IfModule LiteSpeed>
LSPHP_ProcessGroup on
LSPHP_Workers 15
</IfModule>
LSPHP_Workers

LSPHP_Workers controls the maximum number of worker/child processes per account in shared hosting. This directive can be used at the server level or virtual host level.

LSPHP_ProcessGroup

LSPHP_ProcessGroup turns ProcessGroup mode "on" and "off" when using Apache configs. This directive can be used at the server level or virtual host level.

LSPHP_MaxWaitQ

LSPHP_MaxWaitQ sets a maximum number of processes that can be in the PHP external application wait queue. When this limit is reached, new requests will return a 508 "Resource Limit Reached" error. This directive can be used at the server level or virtual host level.

Environment Variables

LSAPI_CHILDREN or PHP_LSAPI_CHILDREN (default: 35)

PHP LSAPI allows a variety of setups. Two of these setups, Worker and ProcessGroup can be set using this environment variable. (Note: In previous versions of this documentation, Worker was referred to as "server managed mode" and ProcessGroup referred to as "self managed mode".)

Setting LSAPI_CHILDREN to <=1 puts LSWS in Worker mode. In Worker mode, LiteSpeed Web Server dynamically spawns new PHP processes to meet demand and kills finished processes. In this mode, an external application's Instances setting (WebAdmin console > Configuration > External App > your external application) should match the Max Connections setting (WebAdmin console > Configuration > External App > your external application).

Setting LSAPI_CHILDREN to >1 puts LSWS in ProcessGroup mode. In ProcessGroup mode, the web server will start one constantly-running PHP parent process, and this process will fork child PHP processes (as opposed to spawning new processes) to meet demand. ProcessGroup is generally preferred because all PHP processes can then share one memory block for opcode caching. In ProcessGroup mode, Instances should be set to 1, while LSAPI_CHILDREN should be set to match the value of Max Connections. Usually, there is no need to set LSAPI_CHILDREN over 100.

Note:
When using suEXEC set in Apache configs, LSWS's default LSAPI_CHILDREN changes to 0. Thus, the default Apache suEXEC is Worker mode. ProcessGroup can be enabled when using Apache configs by using the directive LSPHP_ProcessGroup listed above.

LSAPI_AVOID_FORK
(default: 0)

LSAPI_AVOID_FORK specifies whether the internal process manager in ProcessGroup mode should try to avoid forking new child processes.

When set to 0, the internal process manager will not try to avoid forking new processes. To save system resources, it will stop processes when they finish and only start child processes when they are needed. This is often preferred in shared hosting.

When set to 1, the internal process manager will try to avoid frequently stopping and starting child processes. This might be preferred in a dedicated hosting environment because it may be faster to recycle existing processes, even if it means running processes when they are unused sometimes.

LSAPI_EXTRA_CHILDREN
(default: 1/3 of LSAPI_CHILDREN or 0)

In ProcessGroup mode, LSAPI_EXTRA_CHILDREN controls the maximum number of extra child processes that can be started when existing child processes are malfunctioning. The total number of child processes will be reduced to the level set in LSAPI_CHILDREN as soon as service is back to normal. When LSAPI_AVOID_FORK is set to 0, the default value of LSAPI_EXTRA_CHILDREN is 1/3 of LSAPI_CHIDLREN. When LSAPI_AVOID_FORK is set to 1, the default value is 0.

LSAPI_MAX_REQS or PHP_LSAPI_MAX_REQUESTS
(default: 10000)

In ProcessGroup mode, this controls how many requests each child process will handle before it exits automatically. Several PHP functions have been identified as having memory leaks. This parameter can help reduce memory usage by leaky PHP functions.

LSAPI_MAX_IDLE
(default: 300 seconds)

In ProcessGroup mode, LSAPI_MAX_IDLE controls how long an idle child process will wait for a new request before it exits. This option helps release system resources taken by idle processes.

LSAPI_MAX_IDLE_CHILDREN
(default: 1/3 of LSAPI_CHILDREN or LSAPI_CHILDREN)

In ProcessGroup mode, LSAPI_MAX_IDLE_CHILDREN controls how many idle child processes are allowed. Extra idle child processes will be killed by the parent process immediately. When LSAPI_AVOID_FORK is set to 0, the default value of LSAPI_MAX_IDLE_CHILDREN is 1/3 of LSAPI_CHIDLREN. When LSAPI_AVOID_FORK is set to 1, the default value of LSAPI_MAX_IDLE_CHILDREN is the same as the value of LSAPI_CHILDREN.

LSAPI_MAX_PROCESS_TIME
(default: 3600 seconds)

In ProcessGroup mode, LSAPI_MAX_PROCESS_TIME controls the maximum processing time allowed when processing a request. If a child process can not finish processing a request in the given time period, it will be killed by the parent process. This option can help get rid of dead or runaway child processes.

LSAPI_PGRP_MAX_IDLE
(default: FOREVER )

In ProcessGroup mode, LSAPI_PGRP_MAX_IDLE controls how long the parent process will wait before exiting when there are no child processes. This option can help release system resources taken up by an idle parent process. This environment variable has the same function as the Max Idle Time setting (WebAdmin console > Configuration > External App).

LSAPI_PPID_NO_CHECK

By default, an LSAPI external application will exit automatically if the parent process dies. This is to reduce orphan processes when the web server is restarted. However, it may be desirable to disable this feature in situations such as when an LSAPI process was started manually from the command line. Adding the LSAPI_PPID_NO_CHECK environment variable (set it to 1) will disable the checking for the existence of a parent process. To turn off this setting, remove the environment variable completely. When PHP is started from the command line using the "-b" option, checking is disabled automatically.

LSAPI_ALLOW_CORE_DUMP

By default, an LSAPI application will not leave a core dump file when it crashes. If you want to have LSPHP dump a core file, you should add this environment variable and set to 1. If set, core files will be created under the current working directory, generally the directory of the PHP script that crashed. To turn off this setting, remove the environment variable completely.

LSAPI_ACCEPT_NOTIFY

By default, an LSAPI application will send back a notification packet whenever a request has been received. Since PHP LSAPI 5.0, it can be changed to only notify the server for newly established connections by setting this environment variable to 1. It is recommended as a way to gain performance in LiteSpeed Web Server 4.1 and later.

LSAPI_SLOW_REQ_MSECS

If set to a non-zero number, LiteSpeed Web Server will log requests into an error log file if a request takes longer than the specified number of milliseconds. This can help identify scripts that are slowing down your server.

Guide to suEXEC Setups

LiteSpeed Web Server offers a number of different PHP suEXEC setups for various shared hosters' needs and goals. The following table is offered as a simple guide to choosing the PHP setup right for you and your users.

All of the following setups give you suEXEC security (each PHP process running as the owner of the virtual host's document root). More detailed information on these setups can be found in each setup's documentation.

Setup Description Recommended for
suEXEC Worker Standard suEXEC PHP with LSAPI. Creates new processes when needed. Shared hosting providers with limited resources that want custom php.ini files.
suEXEC Daemon All processes forked from constantly running daemon process for speed and efficiency. All shared hosting providers who do not need custom php.ini files.
suEXEC ProcessGroup Each user account gets a separate process group with a constantly running parent process forking child processes when needed. Shared hosting providers who want to leverage extra RAM into more powerful opcode caching and thus better PHP performance.

Detailed feature comparison

  suEXEC Worker suEXEC Daemon suEXEC ProcessGroup
Forks processes instead of spawning new processes No Yes Yes
Number of parent processes 0 1 One for each process group (each user)
Customize number of processes per account? Yes Yes Yes
Can be enabled only for certain virtual hosts? No No Yes
Custom php.ini supported?
(Including CageFS custom php.ini)
Yes No Yes
Opcode caching No Shared throughout server Dedicated per-user

PHP LSAPI suEXEC Worker Mode

PHP LSAPI's default suEXEC setup, allowing for customizable, resource efficient shared hosting PHP.

What is suEXEC?

suEXEC makes PHP more secure by running each PHP process as the owner of a particular account and not as the web server user. This means that even if one user on a server is compromised, PHP scripts run from their account will not have access to other users' files. suEXEC has long been a basic feature of shared hosting.

What is suEXEC Worker mode?

suEXEC Worker is LiteSpeed's default suEXEC setup. suEXEC Worker spawns new processes whenever PHP is needed. It controls system resource usage by killing processes when they finish.

Benefits

Efficient resource usage

Because Worker mode only starts new processes when PHP is needed and kills processes when they finish, it leaves fewer idle processes.

Allows custom php.ini files

PHP suEXEC Worker is compatible with custom php.ini files, including CloudLinux’s CageFS php.ini files, and thus allows the use of CloudLinux's PHP Selector.

Comparison to other setups

Apache/nginx setups

vs. suPHP

suPHP is the standard suEXEC setup for Apache.

  • All LiteSpeed suEXEC modes (Worker, Daemon, and WorkerGroup) are far faster than suPHP because suPHP uses CGI. CGI is much, much slower than LiteSpeed's LSAPI.
vs. PHP-FPM Pools

PHP-FPM was created for Apache and other servers to make use of FastCGI with PHP.

  • FastCGI is a speedier than CGI, but, our benchmarks show, LSAPI is still about 20% faster than FCGI.
  • To get security similar to suEXEC from PHP-FPM, you have to manually set up pools of processes for each user (though, once set up, PHP FPM does allow opcode caching).
  • These pools always leave at least one process in each pool running, meaning wasted system resources even when a particular site is not being used. This is especially a problem for servers with many users and thus many pools.
  • suEXEC Worker is set up by default and spawns processes dynamically, using resources when and where you need them.

Other LiteSpeed setups

Consult our guide to different LiteSpeed suEXEC setups

Limitations

Because each process in suEXEC Worker is created as a new process, opcode cache is flushed each time one of these processes exits. Thus suEXEC Worker is incompatible with opcode caching. For this reason, we recommend suEXEC Worker only for hosts who need custom php.ini files and whose resources are too limited for suEXEC ProcessGroup.

Creating brand new processes has more overhead than forking child processes. This may cause suEXEC Worker to be slightly slower than sueEXEC Daemon or WorkerGroup modes. Setting PHP processes to be started by the CGI Daemon (WebAdmin console > Configuration > External App > your external application > Auto Start) greatly reduces this overhead, though.

Configuration

suEXEC Worker is enabled by default when PHP suEXEC is configured in your Apache configs.

PHP LSAPI suEXEC Daemon Mode

PHP LSAPI 6.0 introduced one of LSAPI's most important advances — suEXEC Daemon mode. suEXEC Daemon mode allows for faster, more efficient PHP processing in shared hosting.

What is suEXEC?

suEXEC makes PHP more secure by running each PHP process as the owner of a particular account and not as the web server user. This means that even if one user on a server is compromised, PHP scripts run from their account will not have access to other users' files. suEXEC has long been a basic feature of shared hosting.

What is suEXEC Daemon mode?

suEXEC Daemon mode keeps all the security of suEXEC, but improves performance by forking new processes from a constantly running parent process as opposed to creating completely new processes.

Benefits

Faster process generation

Forking child processes is faster than creating new processes because it has less overhead.

Effective opcode caching

Opcode cache stores compiled PHP scripts and variables, allowing for faster PHP response. But opcode cache memory can only be shared among child processes forked off the same parent process and it is flushed when the process ends. Because many suEXEC implementations start PHP processes as standalone processes, each standalone process is allocated its own opcode cache memory, giving only a tiny window for caching before the memory flushes. In suEXEC Daemon mode, opcode cache memory is shared by all PHP processes and won’t be flushed. This allows for a larger opcode cache memory block which is flushed less frequently, leading to a far improved cache hit rate.

Comparison to other setups

Apache/nginx setups

vs. suPHP

suPHP is the standard suEXEC setup for Apache.

  • All LiteSpeed suEXEC modes (Worker, Daemon, and ProcessGroup) are far faster than suPHP because suPHP uses CGI. CGI is much, much slower than LiteSpeed's LSAPI.
  • suPHP creates a new standalone process for each PHP process. As explained above, creating these new processes requires overhead, is time-consuming, and prevents the effective use of opcode cache.
vs. PHP-FPM Pools

PHP-FPM was created for Apache and other web servers to make use of FastCGI with PHP.

  • FastCGI is speedier than CGI, but, our benchmarks show, LSAPI is still about 20% faster than FCGI.
  • To get security similar to suEXEC from PHP-FPM, you have to manually set up pools of processes for each user.
  • These pools always leave at least one process in each pool running, meaning wasted system resources even when a particular user's sites are not being accessed. This is especially a problem for servers with many users and thus many pools.
  • suEXEC Daemon mode is automatically set up to run processes as the site owner, makes great use of opcode caching, and spawns processes dynamically, using resources when and where you need them.

Other LiteSpeed setups

Consult our guide to different LiteSpeed suEXEC setups

Limitations

suEXEC Daemon mode does not allow a customized per-user php.ini. If a user has a customized php.ini, LiteSpeed Web Server will automatically switch to suEXEC Worker mode (LiteSpeed's default suEXEC setup) at the server level.

Because of the incompatibility with custom php.ini's, suEXEC Daemon mode is not compatible with CloudLinux's PHP Selector.

Configuration

To set up suEXEC Daemon mode, you need only adjust your server-level LSPHP external application settings in the WebAdmin Console > Configuration > External App > your LSPHP external application:

  1. Set Auto Start to "Yes".
  2. Set Run On Start Up to "suEXEC Daemon".

PHP LSAPI suEXEC ProcessGroup

PHP LSAPI 6.4 introduced the new suEXEC ProcessGroup mode. ProcessGroup allows shared hosting providers with extra memory to get better PHP performance through per-user opcode caching. It also allows custom php.ini files, and thus CloudLinux’s PHP Selector.

What is suEXEC?

suEXEC makes PHP more secure by running each PHP process as the owner of a particular account and not as the web server user. This means that even if one user on a server is compromised, PHP scripts run from their account will not have access to other users' files. suEXEC has long been a basic feature of shared hosting.

What is suEXEC ProcessGroup?

suEXEC ProcessGroup is set up similarly to PHP-FPM pools. ProcessGroup provisions a parent process for each ProcessGroup user. This parent process runs as the owner of the user’s document root and spawns new child processes when that user needs a PHP process. Forking child processes this way requires less overhead than creating brand new processes and these processes can share an opcode cache. ProcessGroup thus maintains the security of suEXEC, but spawns processes faster and allows for extremely effective per-user opcode caches.

Benefits

Faster process generation

Forking child processes is faster than creating new processes because it has less overhead.

LiteSpeed's most powerful suEXEC opcode caching

ProcessGroup allows for LiteSpeed's most powerful suEXEC opcode caching. Opcode cache stores compiled PHP scripts and variables, allowing for faster PHP response. But opcode cache memory can only be shared among child processes forked off the same parent process and it is flushed if the parent process ends. In suEXEC Worker (LiteSpeed's default suEXEC mode), all processes are standalone and opcode cache memory is flushed every time a PHP process ends. Because, in ProcessGroup, child processes are forked off a continuous parent process, each user's cache is not flushed and their scripts can be used many times. (See vs. suEXEC Daemon mode section for why this is more effective than Daemon mode opcode caching.)

Custom php.ini files

Because each process group has its own parent process, this means PHP suEXEC ProcessGroup is compatible with custom php.ini files. A custom php.ini allows the use of CloudLinux’s PHP Selector.

Can be set at the server or vhost level

ProcessGroup is set through a directive in your httpd.conf files at either the server or virtual host level. (See the Configuration section.) Putting this directive at the virtual host level allows you to decide which users get a personal opcode cache.

Comparison to other setups

Apache/nginx setups

vs. suPHP

suPHP is the standard suEXEC setup for Apache.

  • All LSWS suEXEC modes (Worker, Daemon, and ProcessGroup) are far faster than suPHP because suPHP uses CGI. CGI is much, much slower than LiteSpeed's LSAPI.
  • suPHP creates a new standalone process for each PHP process. As explained above, creating these new processes requires overhead, is time-consuming, and prevents the effective use of opcode cache.
vs. PHP-FPM pools

PHP-FPM was created for Apache and other web servers to make use of FastCGI with PHP.

  • FastCGI is a speedier than CGI, but, our benchmarks show, LSAPI is still about 20% faster than FCGI.
  • To get security similar to suEXEC from PHP-FPM, you have to manually set up pools of processes for each user. ProcessGroup can be automatically set up for the whole server by adding the ProcessGroup directive in the server-level httpd.conf file.
  • PHP-FPM's pools always leave at least one process in each pool running, meaning wasted system resources even when a particular site is not being used. This is especially a problem for servers with many users and thus many pools. The ProcessGroup parent process, however, will be killed when it has been idle for too long.

Other LiteSpeed setups

vs. suEXEC daemon mode

LiteSpeed's suEXEC daemon mode forks all processes from one constantly running daemon process.

  • Because suEXEC Daemon mode forks all processes off one parent process, everyone on that server shares one large opcode cache. If there are many users, this opcode cache can fill up and each user’s scripts may get bumped off the cache before they’re accessed very much. By allowing per-user opcode caches, ProcessGroup allows for more effective opcode caching — each user's scripts stay in the cache to be accessed many times irrespective of what other users do.
  • Daemon mode does not allow custom php.ini files. ProcessGroup does, which also allows for the use of CloudLinux's PHP Selector.
  • ProcessGroup can require more resources than suEXEC Daemon mode: Each ProcessGroup must have its own parent process in addition to other processes. Giving each user a per-user opcode cache should mean more memory for opcode caching than having everyone share one opcode cache.
  • ProcessGroup can be used in conjunction with Daemon mode by setting up Daemon mode at the server level and enabling ProcessGroup on certain virtual hosts that require more powerful opcode caching.
See our comparison of suEXEC setups for more information

Limitations

ProcessGroup keeps one parent process running in addition to all their child processes. This creates a lot of extra processes that you wouldn’t have in LiteSpeed’s suEXEC Worker or Daemon mode. (This can be controlled to some degree with the Max Idle Time setting described below. This causes LSWS to kill ProcessGroup parent processes when they’ve been idle for a certain amount of time.)

Personal opcode caches must be reasonably large in order to be of any use. This almost certainly means setting aside more RAM for opcode caching than you would with suEXEC Daemon mode. ProcessGroup is thus meant for hosts that are willing to use extra memory to see performance enhancements. You must be careful, though. If you portion out too much memory for per-user opcode caches, you could run out of memory.

Configuration

Prerequisites

  • Auto Start (WebAdmin Console > Configuration > External App > your external application) must be set to "Yes" or "Through CGI Daemon". Setting Auto Start to "Through CGI Daemon" may save resources by not starting parent processes for idle process groups at startup.
  • If you wish to use suEXEC Daemon mode for some users while using ProcessGroup for others, change Run On Start Up (WebAdmin console > Configuration > External App > your external application) to "suEXEC Daemon". If Run On Start Up is set to "suEXEC Daemon", ProcessGroup will override Daemon mode wherever ProcessGroup is enabled.
  • If Run On Start Up (WebAdmin Console > Configuration > External App > your external application) is set to "No", LSWS will start a parent process for each process group only when traffic is coming in to that user. This is recommended. Setting Run On Start Up to "Yes" may result in errors.

Enabling ProcessGroup

ProcessGroup is enabled by placing the directive LSPHP_ProcessGroup in an httpd.conf file. This can be done at the server or virtual host level. If done at the server level, all virtual hosts will use ProcessGroup. If done at the virtual host level, only that virtual host will use ProcessGroup.

Example configuration:

<IfModule LiteSpeed>
LSPHP_ProcessGroup on
LSPHP_Workers 15
</IfModule>
Note the <IfModule LiteSpeed> . The two directives, LSPHP_ProcessGroup and LSPHP_Workers, are LiteSpeed-specific directives. Apache will not understand them and may crash if they are not protected.

Additional configurations

  • LSPHP_Workers sets the maximum number of child processes that the parent process can spawn. It is optional. If set, it will override the PHP suEXEC Max Conn setting (WebAdmin console > Configuration > Server > General > Using Apache Configuration File).
  • Per-user opcode cache size is set in your php.ini file. How to set this depends on what opcode cache you’re using.
  • The Max Idle Time setting (WebAdmin console > Configuration > External App > your external application) will control how long before idle parent processes are killed.

Special notes for use with cPanel

  • The ProcessGroup directive should be put in an include file, otherwise it will be overwritten when you upgrade WHM.
  • When configuring ProcessGroup at the server level, the directive should be placed in /usr/local/apache/conf/includes/pre_virtualhost_global.conf
  • When configuring ProcessGroup at the virtual host level, the directive should be placed in a virtual host-level include file.
  • Guides for adding include files can be found on this page from cPanel's site.