====== PHP 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|ProcessGroup mode]], [[#daemon_mode|Daemon mode]], and [[#worker_mode|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 needs 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|Daemon mode]], ProcessGroup mode makes use of opcode caching with the added benefit of having per-user opcode caches when running PHP using a suEXEC execution method. Because [[#daemon_mode|Daemon mode]] forks all processes off 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_mode|Worker]] or [[#daemon_mode|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|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.

==== Setup ====
To use ProcessGroup mode, **Start By Server** must be set to ''Yes'', ''Yes (Through CGI Daemon)'', or ''Yes (Through CGI Daemon Async)'' under **WebAdmin Console > Configuration > External App > your_external_application**.

In a LiteSpeed Web Server (native) environment, you can enable ProcessGroup mode by setting **Instances** to ''1'' and ''[[litespeed_wiki:php:lsapi-environment-variables#lsapi_children_or_php_lsapi_children|LSAPI_CHILDREN]]'' to a number greater than ''1''.

In a control panel environment, you can enable ProcessGroup mode by placing the ''[[litespeed_wiki:php:lsapi-environment-variables#lsphp_processgroup|LSPHP_ProcessGroup]] on'' directive in an httpd.conf file. If done in a Server level conf file, all Virtual Hosts will use ProcessGroup mode. If done in a Virtual Host level conf file, only that Virtual Host will use ProcessGroup mode.

Example configuration for control panel environment:
<code>
<IfModule LiteSpeed>
LSPHP_ProcessGroup on
LSPHP_Workers 15
</IfModule>
</code>

Note the two LiteSpeed-specific directives ''[[litespeed_wiki:php:lsapi-environment-variables#lsphp_processgroup|LSPHP_ProcessGroup]]'' and ''[[litespeed_wiki:php:lsapi-environment-variables#lsphp_workers|LSPHP_Workers]]''. Apache will not understand these directives and may crash if it encounters them outside of by an ''<IfModule LiteSpeed>'' block.

==== Configuration 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 wish to use [[#daemon_mode|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|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 like ''3600'' to prevent PHP from being stopped by the server too quickly.

==== Additional configurations ====

  * You can control the maximum number of child processes that a parent process can spawn with the ''[[litespeed_wiki:php:lsapi-environment-variables#lsphp_workers|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 this depends on which opcode cache you’re using.


==== Special notes for use with cPanel ====

  * Place the ''ProcessGroup'' directive in an include file to avoid it being overwritten during WHM upgrades. When configuring ''ProcessGroup'' at the Server level, place the directive in ''/usr/local/apache/conf/includes/pre_virtualhost_global.conf''. When configuring ''ProcessGroup'' at the Virtual Host level, place the directive in a [[https://confluence2.cpanel.net/display/EA/Modify+Virtualhost+Containers+With+Include+Files|Virtual Host level include file]].
  * 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 5.3, LSPHP will run in detached mode by default allowing PHP processes to survive LSWS restarts. The LSPHP parent will follow the **[[https://www.litespeedtech.com/docs/webserver/config/extapps/lsapi#extMaxIdleTime|Max Idle Time]]** setting in this case.

===== Daemon Mode =====

Introduced in PHP LSAPI v6.0, Daemon mode forks all process 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 new processes 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. This leaves only a tiny window 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. This 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|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, set **Start By Server** to ''Yes'' and **Run On Start Up** to ''Yes (Daemon mode)'' under **WebAdmin console > Configuration > External App > your_external_application**.

===== Worker Mode =====

Standard PHP with LSAPI. Worker Mode 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, this 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|ProcessGroup mode]].
  * Creating a new processes has more overhead than forking child processes. This may cause Worker mode to be slightly slower than [[#daemon_mode|Daemon]] or [[#processgroup_mode|ProcessGroup]] modes. This overhead can be greatly reduced by running in [[#daemon_mode|Daemon mode]] by setting **Start By Server** to ''Yes (Through CGI Daemon)'' or ''Yes (Through CGI Daemon Async)'' under **Configuration > External App > your_external_application**.

==== Setup ====
LiteSpeed Web Server will use Worker mode when none of the setting requirements for [[#processgroup_mode|ProcessGroup mode]] (default) or [[#daemon_mode|Daemon mode]] have been 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|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  |
^ 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  |