Skip to content

LSPHP Modes

suEXEC Mode

suEXEC is an Apache execution method for CGI and SSI programs which makes executing PHP scripts more secure. It does so by running each PHP process as the owner of a particular account instead of as the user running the web server. This means that even if one user on a server is compromised, PHP scripts running from their accounts will not have access to other users' files. suEXEC has long been a basic feature in shared hosting environments.

LiteSpeed Web Server is capable of using this execution method directly when configured to read Apache configuration files. When running LiteSpeed Web Server in Native mode, a similar implementation, called ExtApp Set UID Mode, is available at the virtual host level. suEXEC-like behavior can also be achieved at the external application level using the Run as User and Run as Group settings.

Native

Here are the steps to enable suEXEC for Native LSWS:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Virtual Hosts and click View/Edit for the Virtual Host you want to enable suEXEC for.
  3. Click Edit under Security.
  4. Follow one of these two processes:
    • Change External App Set UID Mode to Doc Root UID which will inherit the document root's user/group.
    • Change suEXEC User and suEXEC Group to the user/group that you want applications to run as.
      webadmin-vhost-security
  5. Navigate to Actions and press the icons next to Restart Detached PHP Processes, and then Apply Changes / Graceful Restart.
    webadmin-restart

Control Panel

Run PHP suEXEC out of the box

If you run shared hosting services with a control panel, for security reasons, it is necessary to use suEXEC mode. Our LSWS installation scripts will enable PHP suEXEC by default for all control panels, hence LSWS will run PHP suEXEC out of the box. In suEXEC mode, each PHP process will run as the owner of the virtual host's document root. Once suEXEC is set, you generally should not make anymore changes in order to avoid permission problems, since PHP suEXEC generally runs as user:user while non-PHP suEXEC runs as nobody:nobody.

Here are the steps to enable suEXEC for control panels, if not already set:

  1. Go to your WebAdmin console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > General.
  3. Click Edit under Using Apache Configuration File.
  4. Change PHP suEXEC to Yes and PHP suEXEC Max Conn to 10.
    webadmin-general-apache2
  5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.
    webadmin-restart

Customize additional PHP SuEXEC handler

The following list contains the default acceptable SuEXEC handlers:

php,php5,php4,php52,php53,php54,php55,php56,php7,php70,php71,php72,php73,php74,php8,php80,phtml,fastphp

This list should cover most situations, and any other handlers will be run as nobody:nobody and not in PHP suEXEC mode. Though you generally shouldn't need to customize phpSuexecHandlers it is possible to do so.

Simply create a handler mapping, and append the new handler name to the end of the list.

Example

To add a php74ext suEXEC handler, create a mapping with the php74ext suffix, like so:

<phpHandler>
  <id>php74ext</id>
  <command>/usr/local/lsws/lsphp74/bin/lsphp</command>
  <suffixes>php74ext</suffixes>
</phpHandler>
Then append php74ext to the default list, so that it looks like this:
php,php5,php4,php52,php53,php54,php55,php56,php7,php70,php71,php72,php73,php74,php8,php80,phtml,fastphp,php74ext

Process Modes

LiteSpeed Web Server offers a number of different PHP process modes to meet the various needs and goals of shared hosting providers: ProcessGroup mode, Daemon mode, and Worker mode. These process modes take effect regardless of PHP mode (standard vs detached) or execution method used (suEXEC vs non-suEXEC).

Note

As of LiteSpeed Web Server 5.3+, PHP is defaulted to use ProcessGroup Mode. If you wish to use a different mode than ProcessGroup Mode you will need to override PHP and follow the procedure in this document for the mode you want to use.

ProcessGroup Mode

Introduced in PHP LSAPI v6.4, ProcessGroup mode is the default process mode used for Apache virtual host PHP handlers. ProcessGroup mode provisions a parent process for each process group user. When running PHP using a suEXEC execution method, this parent process runs as the owner of the user's document root and spawns new child processes when that user required a PHP process. This allows ProcessGroup mode to spawn processes quickly while allowing for extremely effective per-user opcode caches.

Benefits

ProcessGroup mode enjoys reduced overhead and faster process generation by forking child processes instead of creating new processes for each new request from the same user. Because each process group has its own parent process, ProcessGroup mode is compatible with custom php.ini files and CloudLinux’s PHP Selector.

When running PHP using a suEXEC execution method, ProcessGroup mode will conserve resources by killing parent processes that have been idle too long. This is more efficient than Apache + PHP-FPM, where at least one process is always running in each user's pool.

Like Daemon mode, ProcessGroup mode makes use of opcode caching with the added benefit of having per-user opcode caches while running PHP using a suEXEC execution method. Because Daemon mode forks all processes off of a single parent process, every user on that server will share a single large opcode cache. If there are many users, this opcode cache can fill quickly, pushing other user’s scripts out of the cache. By providing per-user opcode caches, each user's scripts remain in their opcode cache irrespective of what other users are doing.

You can enable ProcessGroup mode at either the server or virtual host level through an httpd.conf file directive. By placing this directive in a virtual host level configuration file, you can decide which users get a personal opcode cache.

Compared to PHP-FPM + suEXEC where each user must have a process pool manually set up for them, ProcessGroup mode can more easily and quickly achieve the same level of security. Simply add the ProcessGroup directive in the server level httpd.conf file while using a suEXEC execution method.

Limitations

ProcessGroup mode keeps one parent process running in addition to all of it's child processes. This creates a lot of extra processes that you wouldn’t have in LiteSpeed’s Worker or Daemon modes. You can control this to some degree with the Max Idle Time setting. This setting informs LiteSpeed Web Server to kill ProcessGroup parent processes that are idle for longer than the time set.

Personal opcode caches must be reasonably large to be of any real use, which almost certainly means setting aside more RAM for opcode caching than you would in Daemon mode. This limits ProcessGroup mode to hosts who are willing to use extra memory to see performance enhancements. Be careful not to portion out too much memory for per-user opcode caches as you could run out of memory.

LiteSpeed Web Server versions 5.2.8 and below will stop all PHP processes when performing a restart. This has the negative effect of resetting the opcode cache. Starting from LSWS v5.3, LSPHP will run in detached mode by default allowing PHP processes to survive LSWS restarts. In this case, the LSPHP parent will follow the Max Idle Time setting.

Setup

ProcessGroup mode is used by default with LiteSpeed Web Server.

To manually change the Process mode, perform the following steps:

  1. Go to your WebAdmin console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > External Application.
  3. Click Edit for the PHP version you want to edit.
  4. Change Start By Server to either Yes, Yes (Through CGI Daemon), or Yes (Through CGI Daemon Async).
  5. Change Instances to 1.
  6. Change LSAPI_CHILDREN to a number greater than 1.
    webadmin-extapp-lsapi
  7. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.
    webadmin-restart

In a control panel environment, you can enable ProcessGroup mode by placing the LSPHP_ProcessGroup on directive in an httpd.conf file. If done in a server level configuration file, all virtual hosts will use ProcessGroup mode. If done in a virtual host level configuration file, only that virtual host will use ProcessGroup mode.

Example configuration for control panel environment:

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

Note

Apache will not understand the two LiteSpeed-specific directives, LSPHP_ProcessGroup and LSPHP_Workers. Apache may crash if it encounters them outside of a <IfModule LiteSpeed> block.

Tips

Setting Start By Server to Yes (Through CGI Daemon) or Yes (Through CGI Daemon Async) may save resources by not starting parent processes for idle process groups at startup.

The Max Idle Time setting under WebAdmin console Configuration > External App > your_external_application will control how long a parent processes can remain idle before being killed. When in ProcessGroup mode, LiteSpeed Web Server will treat a Max Idle Time setting of -1 as a default value of 30 seconds.

Set Run On Start Up to No under WebAdmin console Configuration > External App > your_external_application to start a parent process for each process group only when a user receives traffic. Setting Run On Start Up to Yes may result in errors.

If you use Daemon mode for some users while using ProcessGroup mode for others, change Run On Start Up to Yes (Daemon mode) under WebAdmin console Configuration > External App > your_external_application. ProcessGroup mode can then override Daemon mode by being selectively enabled on virtual hosts that require more powerful opcode caching.

When Run on Start Up is set to Yes or Yes (Daemon mode), the default value of Max Idle Time will be 10 seconds. You can set this to a very large number, such as 3600, to prevent PHP from being stopped by the server too quickly.

You can control the maximum number of child processes that a parent process can spawn with the LSPHP_Workers directive. If set, this will override the PHP suEXEC Max Conn setting under WebAdmin console > Configuration > Server > General > Using Apache Configuration File.

You can set opcode cache size per-user in their php.ini file. The steps to set the size change for each type of opcode cache.

Daemon Mode

Introduced in PHP LSAPI v6.0, Daemon mode forks all processes from a single, constantly running daemon process. This mode makes great use of opcode caching and dynamically spawning processes to reduce resource usage.

Benefits

Daemon mode enjoys reduced overhead and faster process generation by forking child processes instead of creating a new process for each new request from the same user.

When running PHP using a suEXEC execution method, Daemon mode will conserve resources by killing parent processes that have been idle too long. This is more efficient than Apache + PHP-FPM where at least one process is always running in each user's pool. In addition to this, many suEXEC implementations start PHP processes as standalone processes, each with their own opcode cache, leaving only a tiny window of time to take advantage of that process's opcode cache before the process ends. When running in Daemon mode, all PHP processes share the same opcode cache memory, which allows for a larger opcode cache memory block with an improved cache hit rate due to less frequent flushes.

Limitations

Daemon mode does not allow the use of custom per-user php.ini files. As a result, LiteSpeed Web Server will automatically switch to Worker mode at the server level if it detects a custom php.ini file.

Due to it's incompatibility with custom php.ini files, Daemon mode is not compatible with CloudLinux's PHP Selector.

Setup

To set up Daemon mode please perform the following:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > External Application.
  3. Click Edit for the PHP version you want to edit.
  4. Change Start By Server to Yes.
  5. Change Run On Start Up to Yes (Daemon mode).
    webadmin-extapp-lsapi
  6. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.
    webadmin-restart

Worker Mode

Worker mode is standard PHP with LSAPI; it dynamically creates new PHP processes when needed.

Benefits

Worker mode is compatible with custom php.ini files, including CloudLinux’s CageFS php.ini files, allowing the use of CloudLinux's PHP Selector.

Worker mode conserves resources by killing idle processes. When running PHP using a suEXEC execution method, Worker mode is more efficient than Apache + PHP-FPM where at least one process is always running in each user's pool.

Limitations

Worker mode creates a new PHP process when needed, resulting in the process's opcode cache flushing when the processes exits. This makes Worker mode incompatible with opcode and APCu caching. For this reason, you should only use Worker mode if you need custom php.ini files and server resources are too limited for ProcessGroup mode.

Creating a new processes has more overhead than forking child processes. This may cause Worker mode to be slightly slower than Daemon or ProcessGroup mode. This overhead can be greatly reduced by changing the Start By Server value. To do this, follow these instructions:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > External Application.
  3. Click Edit for the PHP version you want to change.
  4. Change Start By Server to either Yes (Through CGI Daemon) or Yes (Through CGI Daemon Async).
    webadmin-extapp-lsapi
  5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.
    webadmin-restart

Setup

LiteSpeed Web Server will use Worker mode when the setting requirements for ProcessGroup mode (default) or Daemon mode are not met. LiteSpeed Web Server may also automatically switch to Worker mode at the server level if it detects a custom php.ini file while running in Daemon mode.

Mode Comparison

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

Detached Mode

PHP Detached mode is a significant feature available in LSWS v5.3 and later. OpenLiteSpeed supports PHP Detached mode starting in version 1.5.6.

In previous versions of LSWS (LSWS v5.2.x and below), all PHP processes were attached to LiteSpeed Web Server processes. As such, when LiteSpeed Web Server restarted, the PHP processes would also. In PHP Detached mode, the PHP processes continue running independently, even when LiteSpeed Web Server restarts.

When you run in PHP ProcessGroup mode, PHP process groups are still started by the LiteSpeed processes. When the first request for a specific PHP process group is received, if PHP is not running the request, it will be started by LiteSpeed. pstree will show that the PHP process is a child of the LiteSpeed process. That's normal. What's new is, as of version 5.3, once the LiteSpeed process exits, the PHP process won't quit. It will become independent.

Note

PHP Detached mode does not mean that PHP will run forever. It will still follow the Max Idle Time setting. If you want to make PHP live longer, just increase Max Idle Time to a large number, such as 3600. Never set it to -1 to indicate “unlimited” since, in ProcessGroup mode, values under 30 will be automatically converted to the default of 30 seconds.

Note

Changes to Detached mode will be effective when the app restarts.

Remember, the Detached mode application isn't started when the server starts up. It only starts when there is traffic hitting the external application. The application will be started on demand, and remain running even if LSWS restarts.

The same applies to the restart. Only if an external application is about to serve a request will it be checked and restarted if needed.

Benefits

PHP Detached mode provides an advantage, especially when hundreds of accounts are hosted on the same shared hosting server, with new accounts being rapidly added to it. In cases like this, there is no need to restart all PHP processes during the web server restart. Also, when a user is heavily relying on opcode to reduce the server load, PHP Detached mode avoids an opcode cache reset during the server restart.

Setup

If you are using a control panel, LSWS v5.3 will enable PHP Detached mode automatically.

If you are using LSWS v5.3 (native), and explicitly configure an external application for each virtual host, you will need to set Run on Startup to Yes (Detached Mode).

Native

Here are the steps to enable Detached mode for an external application:

  1. Go to your WebAdmin Console (https://YOUR_SERVER_IP:7080) and log in.
  2. Navigate to Configuration > Server > External Application.
  3. Click Edit for the PHP version you want to enabled Detached mode for.
  4. Change Run On Startup to Yes (Detached Mode).
    webadmin-extapp-lsapi
  5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful Restart.
    webadmin-restart

Restart

In the past, if there were any php.ini changes, you probably wanted to restart LSWS to apply the changes (since LSWS will restart PHP processes).

Since LiteSpeed Web Server version 5.3, PHP runs in Detached mode and will not be restarted when LSWS restarts. If you want to make php.ini changes effective immediately, there are a few ways to restart PHP processes.

Specific User

To restart detached PHP processes for the account (vhost) level, you can touch a .lsphp_restart.txt file under the user's home directory:

$ touch /path/to/user/home/dir/.lsphp_restart.txt

Once .lsphp_restart.txt is created, the user's PHP will be restarted when the next request comes in. The file .lsphp_restart.txt will not be removed. LSWS will check the timestamp of the file to decide if the user's detached PHP needs to be restarted or not. You can manually remove it if you want to but it's not necessary. Every time you want to restart that user's detached PHP, touch the file again, whether it already exists or not, in order to refresh the timestamp.

To maintain CloudLinux mod_lsapi CRIU feature compatibility, the server will restart PHP if it finds a mod_lsapi_reset_me file as well.

$ touch /path/to/user/home/dir/mod_lsapi_reset_me

The user may also restart detached PHP processes from the Advanced page of the LiteSpeed Web Cache Manager cPanel plugin, which is accessible from within the cPanel dashboard.

Server

To restart detached PHP processes at the server level, you can touch a .lsphp_restart.txt file under the <lsws_server_root>/admin/tmp/ directory. Usually that is /usr/local/lsws/admin/tmp/.

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

This can also be accomplished from the Actions page of the LiteSpeed WebAdmin Console, or by using the 'Restart Detached PHP Processes' button in our control panel plugins.

All running detached PHP processes will be restarted, but not immediately. Instead, they will restart as soon as the server needs to use that PHP handler.

Force

To stop all LSPHP processes immediately, you can manually kill them from the command line:

$ sudo killall lsphp

Last update: August 1, 2023