LSPHP Options¶

There are multiple different configuration options that LSPHP can use depending on the setup. There are directives which are meant to be used when configuring Apache configurations and there are environment variables which are used inside of LiteSpeed Web Server specifically.

Directives¶

Directives are meant to be used when using LiteSpeed Web Server with Apache configurations. These directives can be used on either the Server or Virtual Host level of Apache.

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

LSPHP_Workers¶

The LSPHP_Workers directive controls the maximum number of worker/child processes per account in a shared hosting environment. This directive can allow you to set a higher concurrency for certain Virtual Hosts on your shared hosting environment.

LSPHP_ProcessGroup¶

The LSPHP_ProcessGroup directive turns ProcessGroup mode on and off when using Apache configuration files. By default this is already turned on.

LSPHP_MaxWaitQ¶

The LSPHP_MaxWaitQ directive sets the 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 is the same WaitQ that can be monitored inside the WebAdmin Console under Actions > Real-Time Stats.

Variables¶

Variables are meant to be used when settings need to be set globally on LiteSpeed Web Server. These can be set in the PHP section of LiteSpeed Web Server under Environment.

LSAPI_CHILDREN¶

Default Value: 35

LSAPI_CHILDREN can also be referenced as PHP_LSAPI_CHILDREN.

PHP LSAPI allows a variety of process modes. Two of these modes, Worker and ProcessGroup, can be set using this environment variable.

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 in the WebAdmin Console under Configuration > External App > your_external_application should match the Max Connections setting in the same location.

Setting LSAPI_CHILDREN to a number larger than 1 puts LSWS in ProcessGroup mode. In ProcessGroup mode, the web server will start one constantly-running PHP parent process. This process will then fork child PHP processes (as opposed to spawning new processes) to meet demand. ProcessGroup mode 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.

LSAPI_AVOID_FORK¶

Default Value: 0

The LSAPI_AVOID_FORK environment variable 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 sometimes running unused processes.

However, if your server has less than 1 GB available memory, just setting LSAPI_AVOID_FORK=1 will not work, since LSPHP will only keep the child processes if there is enough available memory which by default is set to 1 GB, If your server has less available memory than that, set it with a limit by replacing it with LSAPI_AVOID_FORK=100M. This will set a limit for the LSAPI_AVOID_FORK variable and will run as expected.

LSAPI_EXTRA_CHILDREN¶

Default Values:

• If LSAPI_AVOID_FORK is set to 0: LSAPI_CHILDREN / 3
• If LSAPI_AVOID_FORK is set to 1: 0

In ProcessGroup mode, the LSAPI_EXTRA_CHILDREN environment variable 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.

LSAPI_MAX_REQS¶

Default Value: 10000

LSAPI_MAX_REQS can also be referenced as PHP_LSAPI_MAX_REQUESTS.

In ProcessGroup mode, this environment variable controls the number of requests each child process will handle before exiting 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 Value: 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 Values:

• If LSAPI_AVOID_FORK is set to 0: $\frac{LSAPI-CHILDREN}{3}$
• If LSAPI_AVOID_FORK is set to 1: 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.

LSAPI_MAX_PROCESS_TIME¶

Default Value: 3600 seconds

The LSAPI_MAX_PROCESS_TIME environment variable controls the total time that a PHP process can spend processing a request. It is only effective in ProcessGroup or Daemon mode. The parent process will kill child processes spending more time than this threshold.

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 frame, 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 Value: FOREVER

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

LSAPI_PPID_NO_CHECK¶

Default Value: 0

By default, an LSAPI external application will exit automatically when 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 certain situations, such as when an LSAPI process was started manually from the command line.

Adding the LSAPI_PPID_NO_CHECK environment variable and setting it to 1 will disable the check for the existence of a parent process. To turn this setting off, remove the environment variable completely. When PHP is started from the command line using the -b option, this check is disabled automatically.

LSAPI_ALLOW_CORE_DUMP¶

Default Value: 0

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 to 1, 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¶

Default Value: 0

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

LSAPI_SLOW_REQ_MSECS¶

Default Value: 0

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.

LSAPI_CLEAN_SHUTDOWN¶

Default Value:

• If PHP Version is greater than 5.6: 1
• If PHP Version is 5.6 or lower: 0

Available as of PHP LSAPI v7.6, the LSAPI_CLEAN_SHUTDOWN environment variable can be used to instruct LSPHP to automatically perform a clean shutdown. A clean shutdown refers to performing cleanup after a PHP crash or abnormal exit (such as manually killing the process). Setting LSAPI_CLEAN_SHUTDOWN to 0 will disable the clean shutdown feature while setting LSAPI_CLEAN_SHUTDOWN to 1 will enable it.

LS_OOM_SCORE_ADJ¶

As of LiteSpeed Web Server v6.0.12 build 2, the external application environment variable LS_OOM_SCORE_ADJ can be used to apply oom_score_adj values for PHP processes, independent of the value set for the parent LSWS process. The assigned value will be applied to external applications that are started by the web server.

Usage: LS_OOM_SCORE_ADJ=<desired_value> where "desired_value" is an integer in the -1000 to 1000 range. The lower the value, the lower the chance that the process will be killed.

To illustrate why you might want to use this, let's look at a common scenario:

Your server becomes low on free memory and an OOM killer is invoked. You want to ensure that processes are sacrificed according to importance, so you have set oom_score_adj accordingly. The problem is that setting oom_score_adj for the litespeed process also sets this for litespeed's children, including lsphp processes. While it's highly desirable that LiteSpeed Web Server is protected from an OOM killer, it is conversely desirable that lsphp processes are sacrificed to free up memory.

In this scenario, you use oom_score_adj to set the priority for the litespeed process as usual. In your WebAdmin Console, add the LS_OOM_SCORE_ADJ environment variable to the PHP tab. You may also choose to add the variable to the configuration for a dedicated individual PHP application, if it should have a different priority than PHP in general.