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.
5. Navigate to Actions and press the icons next to Restart Detached PHP Processes, and then Apply Changes / Graceful 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.
5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful 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.

<phpHandler>
  <id>php74ext</id>
  <command>/usr/local/lsws/lsphp74/bin/lsphp</command>
  <suffixes>php74ext</suffixes>
</phpHandler>

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

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.
7. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful 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>

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).
6. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful 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).
5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful 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¶

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.

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).
5. Navigate to Actions and press the icons next to Restart Detached PHP Processes and then Apply Changes / Graceful 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