mod_lsapi PRO is an Apache HTTP Server module based on LiteSpeed Technologies API . It serves to execute PHP scripts on a web-server by analogy with other modules like mod_suphp, php-fpm, mod_php. However, mod_lsapi PRO usage offers excellent PHP performance, low memory footprint coupled with great security and support for opcode caching.

How does it work?

1. Apache passes handling for PHP request to mod_lsapi PRO;
2. mod_lsapi PRO use liblsapi to transfer request to lsphp parent process;
3. lsphp is forking child process which executes the request and returns data to mod_lsapi PRO;
   mod_lsapi PRO integrates with Apache, allows to handle concurrent requests and manages the lsphp processes

• If there are no requests for lsapi_backend_pgrp_max_idle seconds, lsphp parent process will be  terminated;
• If there are no lsphp child processes available when a new request comes, the new lsphp child process will be created;
• lsphp childs process concurrent requests simultaneously;
• The maximum number of simultaneously running lsphp child processes can be set by the lsapi_backend_children directive.

What is lsphp?

lsphp - PHP + LSAPI. What is PHP LSAPI? LiteSpeed Server Application Programming Interface (LSAPI) is designed specifically for seamless, optimized communication between LiteSpeed Web Server and third-party web applications. Now with mod_lsapi PRO this protocol is available for Apache 2.2/2.4.

Using mod_lsapi PRO, we have seen the higher performance than Apache with mod_php, easier installation than php-fpm and easier integration with any control panel. mod_lsapi PRO means faster and more stable dynamic web pages.

Requirements

Currently, the mod_lsapi is not compatible with:

• Apache mod_ruid2 - should be disabled;
• Apache mod_itk - should be disabled;
• PHP-FPM - should be disabled because PHP-FPM is also a PHP Handler just as mod_lsapi.

Optional requirements

• Configured LVE containers for end-users ( recommended - higher security level );
• Installed and configured mod_hostinglimits for Apache ( recommended - higher security level );
• Installed mod_suexec for Apache and configured SuExecUserGroup directive for each virtual host ( recommended - higher security level );
• Enabled CageFS for end-users ( recommended - higher security level );
• PHP Selector with alt-php - an easy way to select different PHP versions for each end-user provided by CloudLinux;
• ea-php - alternative to alt-php provided by cPanel (for cPanel only).

Configuring mod_lsapi PRO

In order to get mod_lsapi PRO work properly, you'll need to configure Apache. To do this, we use a separate lsapi.conf file.

First of all, for the mod_lsapi PRO work, you need to ensure that the module is loaded. In your lsapi.conf you need to make sure the LoadModule directive has not been commented out. A correctly configured directive may look like this:

LoadModule lsapi_module modules/mod_lsapi.so

In order to enable the module to process requests, you need to add the lsapi_engine directive to your lsapi.conf file as follows:

lsapi_engine On

The mod_lsapi PRO handler can be enabled using the AddType directive. The AddType directive tells Apache that a given filename extension should be handled by mod_lsapi PRO. Apache will assume that and will attempt to execute it when that particular resource is requested by a client.

AddType application/x-httpd-lsphp .php

If no handler is explicitly set for a request, the specified content type will be used as the handler name, therefore, please disable php.conf or any other PHP handler for using mod_lsapi PRO. In this example application/x-httpd-lsphp is a default handler by which mod_lsapi PRO process requests with lsphp binary from /usr/local/bin/ directory.

The final lsapi.conf configuration might look like this:

LoadModule lsapi_module modules/mod_lsapi.so


<IfModule lsapi_module>      
	lsapi_engine On      
	AddType application/x-httpd-lsphp .php      
	lsapi_backend_connect_timeout 100000
	lsapi_backend_connect_tries 10
	lsapi_backend_children 20
	lsapi_backend_pgrp_max_idle 30
	lsapi_backend_max_process_time 300
	lsapi_debug Off
</IfModule>

In order to mod_lsapi PRO work lsapi.conf should be loaded to Apache through Include directive.

For more detailed description of the module directives please visit Configuration reference.
For installation guide mod_lsapi PRO please visit Installation .

mod_lsapi customization:

• lsapi_engine
• lsapi_socket_path
• lsapi_poll_timeout
• lsapi_per_user
• lsapi_output_buffering
• lsapi_disable_reject_mode
• lsapi_terminate_backends_on_exit
• lsapi_avoid_zombies
• lsapi_use_req_hostname
• lsapi_debug

Tuning LSPHP backend:

• lsapi_set_env
• lsapi_set_env_path
• lsapi_backend_children
• lsapi_backend_connect_tries
• lsapi_backend_connect_timeout
• lsapi_backend_max_process_time
• lsapi_backend_pgrp_max_idle
• lsapi_backend_use_own_log
• lsapi_backend_common_own_log
• lsapi_backend_coredump
• lsapi_backend_accept_notify

Connection pool mode:

• lsapi_with_connection_pool
• lsapi_backend_max_idle
• lsapi_backend_max_reqs

CRIU support (CloudLinux 7 only):

• lsapi_criu
• lsapi_criu_socket_path
• lsapi_criu_imgs_dir_path
• lsapi_backend_initial_start
• lsapi_criu_use_shm
• lsapi_backend_semtimedwait
• lsapi_reset_criu_on_apache_restart

PHP configuration management:

• lsapi_process_phpini
• lsapi_phpini
• lsapi_phprc
• lsapi_tmpdir
• lsapi_enable_user_ini
• lsapi_user_ini_homedir
• lsapi_keep_http200
• lsapi_mod_php_behaviour
• php_value, php_admin_value, php_flag, php_admin_flag

Security:

• lsapi_use_suexec
• lsapi_user_group
• lsapi_uid_gid
• lsapi_use_default_uid
• lsapi_target_perm
• lsapi_paranoid
• lsapi_check_document_root
• lsapi_disable_forced_pwd_var
• lsapi_max_resend_buffer

Syntax : lsapi_engine on/off
Default : lsapi_engine off
Context : httpd.conf, htaccess

Description :
Switching mod_lsapi handler on or off.

Syntax : lsapi_socket_path [path] Default : lsapi_socket_path /var/run/mod_lsapi
Context : httpd.conf

Description:
Path to backend lsphp sockets. By default /var/run/mod_lsapi

Syntax : lsapi_poll_timeout [number]
Default : lsapi_poll_timeout 300
Context : httpd.conf, htaccess

Description :
Time to wait for response from the lsphp daemon, in seconds. 0 stands for infinity. For preventing long running processes which can use EP (limit number of entry processes). Default value is 300. Should be more or equal to 0. In the case of wrong format, the default value will be used.

Syntax : lsapi_per_user On/Off
Default : lsapi_per_user Off
Context : httpd.conf

Description :
Invoke master lsPHP process not per VirtualHost but per account. When On, invoke backend not per VirtualHost but per account. Default value is Off. It is possible, for example, to set it to On in global config file and to Off in config files of some particular Virtual Hosts. Then these Virtual Hosts will have a dedicated backend process, while others will have backend processes shared on account basis.

Syntax : lsapi_output_buffering On/Off
Default : lsapi_output_buffering On
Context : httpd.conf, virtualhost, htaccess

Description :
Enable or disable output buffering on Apache level. Default value is On.

Syntax : lsapi_disable_reject_mode On/Off
Default : lsapi_disable_reject_mode Off
Context : httpd.conf, virtualhost

Description :
If a new HTTP request is coming to LSPHP daemon when all LSPHP workers are still busy, it can process this situation in two different ways. In REJECT mode LSPHP daemon will reject such request immediately. Otherwise, in legacy mode, LSPHP daemon will put this request into infinite queue, until one or more LSPHP daemon becomes free. When HTTP request is rejected in REJECT mode, mod_lsapi will write into Apache error_log the following message: Connect to backend rejected, and the client will receive 507 HTTP response. By default LSPHP daemon in CloudLinux uses REJECT mode. It can be switched off with this option.

Syntax : lsapi_terminate_backends_on_exit On/Off
Default : lsapi_terminate_backends_on_exit On
Context : httpd.conf

Description :
httpd.conf, On - stop lsphp services on apache restart, Off - leave live started lsphp services on apache restart (for php+opcache). The lsphp will not restart, even if Apache gets restarted.

Syntax : lsapi_avoid_zombies On/Off
Default : lsapi_avoid_zombies Off
Context : httpd.conf, virtualhost

Description :
Enable or disable a mechanism to avoid creation of zombie processes by lsphp. Default value is Off.

Syntax : lsapi_use_req_hostname On/Off
Default : lsapi_use_req_hostname Off
Context : httpd.conf, virtualhosts

Description :
By default, we are using hostname from the server_rec structure (off), it means that mod_lsapi takes hostname from the VirtualHost section of the configuration file. Using hostname from the request_rec structure (On) means that mod_lsapi takes hostname from the HOST section of the request. It could be useful for those who use dynamically generated configs for virtual hosts for example with mod_lua.

Syntax : lsapi_sentry On/Off
Default : lsapi_sentry On
Context : httpd.conf

Description :
When this option is enabled, errors that occur in the operation of the mod_lsapi will be sent to the remote sentry server. You can see the error messages that were sent to the sentry server in the directory /var/log/mod_lsapi. If you do not want to send error notifications from your server, you can disable this directive in lsapi.conf.

Syntax : lsapi_debug On/Off
Default : lsapi_debug Off
Context : httpd.conf, virtualhost

Description :
Extended debug logging.

Syntax : lsapi_set_env VAR_NAME [VAR_VALUE]
Default : -
Context : httpd.conf

Description :
Pass env variable to lsphp. By default lsphp environment have only TEMP, TMP and PATH variables set.
Example: lsapi_set_env TMP "/var/lsphp-tmp"
Note: PATH env var default "/usr/local/bin:/usr/bin:/bin" cannot be changed because of security reasons.
To change it, use explicitly lsapi_set_env_path option.

Syntax : lsapi_set_env_path [path(s)]
Default : lsapi_set_env_path /usr/local/bin:/usr/bin:/bin
Context : httpd.conf

Description :
Change PATH variable in the environment of lsPHP processes. Default path /usr/local/bin:/usr/bin:/bin will be used if not set.

Syntax : lsapi_backend_children [number]
Default : lsapi_backend_children [EP]
Context : httpd.conf

Description :
Sets env variable LSAPI_CHILDREN
Maximum number of simultaneously running child backend processes.
Optional, a default value is equal to EP.
min value is 2; max value is 10000. If var value is more, 10000 will be used.

Syntax : lsapi_backend_connect_tries [number]
Default : lsapi_backend_connect_tries 20
Context : httpd.conf

Description :
Number of retries to connects to lsPHP daemon.

Syntax : lsapi_backend_connect_timeout [number]
Default : lsapi_backend_connect_timeout 500000
Context : httpd.conf

Description :
Number of usec to wait while lsPHP starts (if not started on request).

Syntax : lsapi_backend_max_process_time [number]
Default : lsapi_backend_max_process_time 300
Context : httpd.conf

Description :
Sets env variable LSAPI_MAX_PROCESS_TIME
Optional. Default value is 300.
Timeout to kill runaway processes.

Syntax : lsapi_backend_pgrp_max_idle [number]
Default : lsapi_backend_pgrp_max_idle 30
Context : httpd.conf

Description :
Sets env variable LSAPI_PGRP_MAX_IDLE, in seconds.
Controls how long a control process will wait for a new request before it exits. # 0 stands for infinite.
Optional, default value is 30.
Should be more or equal to 0.

Syntax : lsapi_backend_use_own_log On/Off
Default : lsapi_backend_use_own_log Off
Context : httpd.conf, virtualhost, htaccess

Description :
Redirecting log output of backend processes from Apache error_log to dedicated log file or files, depending on value of lsapi_backend_common_own_log option. If Off, use Apache error log file for backend output, or separate file otherwise.

Syntax : lsapi_backend_common_own_log On/Off
Default : lsapi_backend_common_own_log Off
Context : httpd.conf, virtualhost, htaccess

Description :
It will be used only when lsapi_backend_use_own_log set to On. On - backend processes of the all virtual hosts will share the common log file. Off - every virtual host will have its own backend log file.

Syntax : lsapi_backend_coredump On/Off
Default : lsapi_backend_coredump Off
Context : httpd.conf, htaccess

Description :
env variable LSAPI_ALLOW_CORE_DUMP (On or Off). Pass LSAPI_ALLOW_CORE_DUMP to lsphp or not. If it will be passed - core dump on lsphp crash will be created.
Off by default.
By default LSAPI application will not leave a core dump file when crashed. If you want to have LSAPI PHP dump a core file, you should set this environment variable. If set, regardless the value has been set to, core files will be created under the directory that the PHP script in.

Syntax : lsapi_backend_accept_notify On/Off
Default : lsapi_backend_accept_notify On
Context : httpd.conf, virtualhost

Description :
Switch LSAPI_ACCEPT_NOTIFY mode for lsphp. This option can be used both in Global and VirtualHost scopes.This mode is incompatible with PHP 4.4.

Syntax : lsapi_with_connection_pool On/Off
Default : lsapi_with_connection_pool Off
Context : httpd.conf

Description :
On/Off - disable enable connect pool, default is Off.

Syntax : lsapi_backend_max_idle [number]
Default : lsapi_backend_max_idle 300
Context : httpd.conf

Description :
It is relevant only with lsapi_with_connection_pool option switched on. Controls how long a worker process will wait for a new request before it exits. 0 stands for infinite. Should be more or equal to 0. In the case of wrong format default value will be used. Optional, default value is 300.

Syntax : lsapi_backend_max_reqs [number]
Default : lsapi_backend_max_reqs 10000
Context : httpd.conf

Description :
It is relevant only with lsapi_with_connection_pool option switched on. Controls how many requests a worker process will process before it exits. Should be more than 0. In the case of wrong format default value will be used. Optional, default value is 10000.

Syntax : lsapi_criu On/Off
Default : lsapi_criu Off
Context : httpd.conf

Description :
Enable/disable CRIU for lsphp freezing. Default: Off.

Syntax : lsapi_criu_socket_path [path]
Default : lsapi_criu_socket_path /var/run/criu/criu_service.socket
Context : httpd.conf

Description :
Set path to socket for communication with criu service. Default: /var/run/criu/criu_service.socket.

Syntax : lsapi_criu_imgs_dir_path [path]
Default : lsapi_criu_imgs_dir_path /var/run/mod_lsapi/
Context : httpd.conf

Description :
Path to folder where images of freezed PHP will be stored. Should be path. Default: /var/run/mod_lsapi/

Syntax : lsapi_backend_initial_start [number]
Default : lsapi_backend_initial_start 0
Context : httpd.conf

Description :
Number of requests to virtualhost, when lsphp will be freezed. Default: 0 - means disable freezing.

Syntax : lsapi_criu_use_shm Off/Signals
Default : lsapi_criu_use_shm Off
Context : httpd.conf

Description :
Method of requests counting. Off - use shared memory. Signals - use signals from child processes to parent. Default: Off

Syntax : lsapi_backend_semtimedwait On/Off
Default : lsapi_backend_semtimedwait On
Context : httpd.conf

Description :
Use semaphore for checking when lsphp process will be started. Speed of start lsphp increased with semaphore using. This method avoid cycles of waiting for lsphp start. Default: On.

Syntax : lsapi_reset_criu_on_apache_restart On/Off
Default : lsapi_reset_criu_on_apache_restart Off
Context : httpd.conf, virtualhost

Description :
This option allows cleaning all CRIU images on Apache restart.
Setting lsapi_reset_criu_on_apache_restart to On means that on each Apache restart the CRIU images which are stored in directory specified by lsapi_criu_imgs_dir_path directive will be recreated on new request to domain(only after restart).
If this option set to Off then CRIU images won’t be recreated on Apache restart.

Syntax : lsapi_process_phpini On/Off
Default : lsapi_process_phpini Off
Context : httpd.conf, virtualhost, directory

Description :
Enable or disable phpini_* directive processing. Default value is Off.

Syntax : lsapi_phpini [path]
Default : lsapi_phpini -
Context : httpd.conf, virtualhost, htaccess

Description :
When lsapi_process_phpini option switched to Off, these values will be silently ignored. lsapi_phpini values with absolute filename of php.ini file can be inserted into .htaccess files in order to set custom php.ini which will override/complement settings from system default php.ini.

Syntax : lsapi_phprc [No | Env | Auto | DocRoot]
Default : lsapi_phprc No
Context : httpd.conf, virtualhost

Description : The value of PHPRC env variable.
Special values are "No", "Env", "Auto" and "DocRoot".
Default value is "No" - without PHPRC at all.
"Auto" value stands for php.ini from DocumentRoot of the corresponding VirtualHost if it is present, or from user's home directory otherwise "DocRoot" value stands for php.ini from DocumentRoot of the corresponding VirtualHost.
"Env" value for using PHPRC from the environment, to set it with SetEnv config option, for example
lsapi_phprc No
lsapi_phprc Auto
lsapi_phprc DocRoot
lsapi_phprc Env
lsapi_phprc /etc/

Syntax : lsapi_tmpdir [path]
Default : lsapi_tmpdir /tmp
Context : httpd.conf, virtualhost

Description :
Set alternate request body temporary files directory.

Syntax : lsapi_enable_user_ini On/Off
Default : lsapi_enable_user_ini Off
Context : httpd.conf, virtualhost

Description :
Enable .user.ini files for backend. Same as suphp, php-fpm and fcgid mechanism of .user.ini. Default value is Off.

Syntax : lsapi_user_ini_homedir On/Off
Default : lsapi_user_ini_homedir Off
Context : httpd.conf, virtualhost

Description :
If lsapi_enable_user_ini option is set to On, then enable/disable processing .user.ini file in home directory also. Default value is Off.

Syntax : lsapi_keep_http200 On/Off
Default : lsapi_keep_http200 Off
Context : httpd.conf, .htaccess

Description :
If set to On, always keep backend's response status as mod_php do. If set to Off, response status can be overridden by Apache as suphp do (in case of call via ErrorDocument directive).

Syntax : lsapi_mod_php_behaviour On/Off
Default : lsapi_mod_php_behaviour On
Context : httpd.conf, virtualhost, directory

Description :
On/Off - disable php_* directives, default On.

Syntax : [php_value|php_admin_value|php_flag|php_admin_flag]
Default :
Context : httpd.conf, virtualhost, htaccess

Description :
mod_php emulation.

Syntax : lsapi_use_suexec On/Off
Default : lsapi_use_suexec On
Context : httpd.conf

Description :
Use or not suexec to a target user.

Syntax : lsapi_user_group [user_name] [group_name]
Default : -
Context : httpd.conf, virtualhost, directory

Description :
Set user & group for requests.

Syntax : lsapi_uid_gid [uid] [gid]
Default : -
Context : httpd.conf, virtualhost, directory

Description :
Set user & group for request.

Syntax : lsapi_use_default_uid On/Off
Default : lsapi_use_default_uid On
Context : httpd.conf

Description :
Use default Apache UID/GID if no uid/gid set. Values: On/Off. If Off, and no UID/GID set, error 503 will be returned.

Syntax : lsapi_target_perm On/Off
Default : lsapi_target_perm Off
Context : httpd.conf

Description :
Check target PHP script permissions. If set to On, lsapi will check that script is owned by the same user, as user under which it is being executed. Return 503 error if they don't match. Default: Off.

Syntax : lsapi_paranoid On/Off
Default : lsapi_paranoid Off
Context : httpd.conf

Description :
Check or not permissions of target php scripts. Optional, default value is Off.

Syntax : lsapi_check_document_root On/Off
Default : lsapi_check_document_root On
Context : httpd.conf

Description :
Check or not owner of DOCUMENT_ROOT. Optional, default value is On.

Syntax : lsapi_disable_forced_pwd_var On/Off
Default : lsapi_disable_forced_pwd_var Off
Context : httpd.conf, virtualhost

Description :
To disable addition of PWD variable. Default value is Off. If set to On, the PWD variable will not be added into a backend environment.

Syntax : lsapi_max_resend_buffer [number]tmp
Default : lsapi_max_resend_buffer 200
Context : httpd.conf, virtualhost

Description :
Maximum buffer in KiB to resend for request that has a body (like POST request body).

mod_lsapi PRO can be installed through YUM package manager, however, the installation process varies depending on the control panel.

Select the control panel you are using:

• cPanel
• Plesk
• DirectAdmin
• No control panel

Installing on cPanel servers with EasyApache 4

Install mod_lsapi PRO and related packages through YUM package manager as follows:

$ yum install liblsapi liblsapi-devel
$ yum install ea-apache24-mod_lsapi

$ /usr/bin/switch_mod_lsapi --setup

$ service httpd restart

For more details about swith_mod_lsapi, please visit switch_mod_lsapi tool .

Installing on Plesk servers

Install mod_lsapi PRO and related packages through YUM package manager as follows:

$ yum install liblsapi liblsapi-devel
$ yum install mod_lsapi

$ /usr/bin/switch_mod_lsapi --setup

Now, when the module is installed, restart Apache to ensure that mod_lsapi PRO is enabled:

$ service httpd restart

Now LSPHPXY alt-php PHP handlers are available for managing through Plesk PHP Settings.

For more details about swith_mod_lsapi, please visit switch_mod_lsapi tool .

Installing on DirectAdmin servers

Installation process is done with custombuild script:

$ cd /usr/local/directadmin/custombuild
$ ./build update
$ ./build set php1_mode lsphp
$ ./build php n
$ ./build apache

$ service httpd restart

Installing on servers with no control panel

Install mod_lsapi PRO and related packages through YUM package manager as follows:

$ yum install liblsapi liblsapi-devel
$ yum install mod_lsapi

$ /usr/bin/switch_mod_lsapi --setup

$ service httpd restart

If you are using an alternative Apache - httpd24 , then install mod_lsapi as follows:

$ yum install liblsapi liblsapi-devel
$ yum install httpd24-mod_lsapi

$ /usr/bin/switch_mod_lsapi --setup

$ service httpd24 restart

For more details about swith_mod_lsapi, please visit switch_mod_lsapi tool .

Uninstall mod_lsapi PRO is performed depending on your control panel.

Select the control panel you are using:

• cPanel
• Plesk
• DirectAdmin
• No control panel

Uninstall procedure for cPanel servers with EasyApache 4

To remove lsapi handler from cPanel MultiPHP Manager and uninstall mod_lsapi PRO, run a command:

$ /usr/bin/switch_mod_lsapi --uninstall

$ yum erase liblsapi liblsapi-devel ea-apache24-mod_lsapi

$ service httpd restart

Uninstall procedure for Plesk servers

To unregister LSPHP handlers and uninstall mod_lsapi PRO, run the command:

$ /usr/bin/switch_mod_lsapi --uninstall

$ yum erase liblsapi liblsapi-devel mod_lsapi

$ service httpd restart

Uninstall procedure for DirectAdmin servers

Uninstall is done with custombuild script:

$ cd /usr/local/directadmin/custombuild
$ ./build update
$ ./build set php1_release [any other php mode]
$ ./build php n
$ ./build apache

• mod_php
• fastcgi
• php-fpm
• suphp

Restart Apache afterwards:

$ service httpd restart

Uninstall procedure for servers with no control panel

To uninstall mod_lsapi PRO, run the command:

$ /usr/bin/switch_mod_lsapi --uninstall

$ yum erase liblsapi liblsapi-devel mod_lsapi
$ rm [path to mod_lsapi.conf]

$ service httpd restart

If you are using an alternative Apache: - httpd24 , then uninstall mod_lsapi PRO as follows:

$ /usr/bin/switch_mod_lsapi --uninstall

$ yum erase liblsapi liblsapi-devel httpd24-mod_lsapi
$ rm [path to mod_lsapi.conf]

$ service httpd24 restart

switch_mod_lsapi is the command line tool used to manage mod_lsapi PRO.

It has the following syntax:

/usr/bin/switch_mod_lsapi [OPTIONS]

[OPTIONS] can be the main and an additional (for usage together with any other main option).

Main options

Additional options

The following table presents which [OPTIONS] are supported for various panels:

Debugging mod_lsapi issues: error_log & sulsphp_log

mod_lsapi errors will be located in error_log and sulsphp_log. Note that errors can appear in both logs at the same time, and you might need to refer to both of them to solve the issue.

See next table for more details:

Non-standard apache user

If apache runs under a username other than "apache" or "nobody" , you should rebuild sulsphp (where username is built in for security reasons) with corresponding username:

$ yum install liblsapi liblsapi-devel   
$ cd ~$ wget [http://repo.cloudlinux.com/cloudlinux/sources/da/mod_lsapi.tar.gz](http://repo.cloudlinux.com/cloudlinux/sources/da/mod_lsapi.tar.gz)  
$ tar zxvf mod_lsapi.tar.gz  
$ cd mod-lsapi-0.1-37  
$ cmake -DHTTPD_USER=<new user name> .  
$ make
$ make install

lsphp started under user apache/nobody

Check if SuExecUserGroup specified for virtual hosts. This parameter is used by mod_lsapi for user identification.

Could not connect to lsphp backend: connect(/tmp/lshttpd/lsapi_application-x-httpd-lsphp_XXX.sock) failed: 111 Connection refused

• Switch in lsapi.conf or mod_lsapi.conf value to: lsapi_terminate_backends_on_exit Off

• Check if empty: cat /etc/cron.d/kill_orphaned_php-cron | grep lsphp , then run:

yum install lve-utils

Running PHP for users with UID < 99

If you need to run PHP using mod_lsapi using users with UID < 99, you would need to re-compile sulsphp:

$ yum install liblsapi liblsapi-devel
$ cd ~
$ wget [http://repo.cloudlinux.com/cloudlinux/sources/da/mod_lsapi.tar.gz](http://repo.cloudlinux.com/cloudlinux/sources/da/mod_lsapi.tar.gz)
$ tar zxvf mod_lsapi.tar.gz
$ cd mod-lsapi-0.1-XX
$ cmake -DUID_MIN=80 -DGID_MIN=80 .
$ make
$ make install

Apache binary called not httpd (httpd.event, httpd.worker)

$ yum install liblsapi liblsapi-devel 
$ cd ~
$ wget http://repo.cloudlinux.com/cloudlinux/sources/da/mod_lsapi.tar.gz        
$ tar zxvf mod_lsapi.tar.gz
$ cd mod-lsapi-0.1-XX
$ cmake -DPARENT_NAME="<apache binary name>".
$ make
$ make install

WHMCS Status page not accessible after installing CL and mod_lsapi (cPanel).

• add user: useradd userstat
• add to file (to the end of file before ) /usr/local/apache/conf/conf.d/lsapi.conf: <Directory /usr/local/apache/htdocs/> lsapi_user_group userstat userstat

This is safe solution for easyapache rebuilding and cpanel-mod-lsapi updating.

PHP page with Suhosin return 503 error

Make php.ini for suhosin as recommended below:

[suhosin]
suhosin.simulation = Off
suhosin.mail.protect = 1
suhosin.cookie.disallow_nul = Off
suhosin.cookie.max_array_depth = 1000
suhosin.cookie.max_array_index_length = 500
suhosin.cookie.max_name_length = 500
suhosin.cookie.max_totalname_length = 500
suhosin.cookie.max_value_length = 200000
suhosin.cookie.max_vars = 16384
suhosin.get.disallow_nul = Off
suhosin.get.max_array_depth = 1000
suhosin.get.max_array_index_length = 500
suhosin.get.max_name_length = 500
suhosin.get.max_totalname_length = 500
suhosin.get.max_value_length = 1000000
suhosin.get.max_vars = 16384
suhosin.post.disallow_nul = Off
suhosin.post.max_array_depth = 1000
suhosin.post.max_array_index_length = 500
suhosin.post.max_name_length = 500
suhosin.post.max_totalname_length = 500
suhosin.post.max_value_length = 1000000
suhosin.post.max_vars = 16384
suhosin.request.disallow_nul = Off
suhosin.request.max_array_depth = 1000
suhosin.request.max_array_index_length = 500
suhosin.request.max_totalname_length = 500
suhosin.request.max_value_length = 1000000
suhosin.request.max_vars = 16384
suhosin.request.max_varname_length = 524288
suhosin.upload.max_uploads = 300
suhosin.upload.disallow_elf = Off
suhosin.session.cryptua = Off
suhosin.session.encrypt = Off
suhosin.session.max_id_length = 1024
suhosin.executor.allow_symlink = Off
suhosin.executor.disable_eval = Off
suhosin.executor.disable_emodifier = Off
suhosin.executor.include.max_traversal = 8

PHP page with APC return 503 error

Make php.ini for APC as recommended below:

[apc]...apc.shm_segments=1apc.shm_size=32...

Messages appearing in error_log: Child process with pid: XXXXX was killed by signal: 11, core dump: 0

This means that lsphp was crashed. The solution is:

• Check if apc for user enabled. Tune its options as described in previous slide.
• Check if suhosin is enabled for user. Tune its options as described in this article.
• If previous items do not help, contact us at https://helpdesk.cloudlinux.com/

How to get lsphp core dump on crash

• Configure mod_lsapi to allow lsphp to generate core dumps. In mod_lsapi.conf:

lsapi_backend_coredump On

• Enable core file generation in sysctl:

sysctl -w ‘kernel.core_uses_pid=1’
sysctl -w ‘kernel.core_pattern=core.%p’

• Configure system to change max size of core files. In /etc/security/limits.conf add:

user1 soft core unlimited
user1 hard core unlimited

• If /etc/profile.d/limits.sh exists, look up for the following lines:

if [ "$LIMITUSER" != "root" ]; then
ulimit -n 100 -u 35 -m 200000 -d 200000 -s 8192 -c 200000 -v unlimited 2>/dev/null

• Add line into ulimit -c unlimited into apachectl script just after another invokes of the ulimit command.

• Do cold restart of Apache with the command like this:

service httpd stop; sleep 2; killall lsphp; service httpd start

• You can make sure that ulimit for lsphp is changed to unlimited successfully with the following command:

cat /proc/PID/limits | grep ‘Max core file size’

where PID is a pid of any lsphp process. ps -u user1 | grep lsphp

• Core dump of lsphp will be created in the DocumentRoot of the corresponding virtual server. On cPanel server it should map to

mod_lsapi is not included in output of httpd -M after installation and setup command for cPanel EasyApache 3

1. Check if the file /usr/local/apache/conf/conf.d/lsapi.conf exists and not empty;

2. Check if output of the command

cat /usr/local/apache/conf/httpd.conf | grep "/usr/local/apache/conf/conf.d/\*\.conf"

If it is empty:

1. Add to "include" section of /var/cpanel/conf/apache/main string:

"include": '"/usr/local/apache/conf/conf.d/*.conf"'
 "include":
 "directive": 'include'
 "items":
 ...
 -
 "include": '"/usr/local/apache/conf/conf.d/*.conf"' 
 "listen":

2. Do:

mkdir -p /usr/local/apache/conf/conf.d/;                                                                                 
cp /usr/share/lve/modlscapi/confs/lsapi.conf /usr/local/apache/conf/conf.d/lsapi.conf

3. Call:

/scripts/rebuildhttpdconf/scripts/restartsrv_httpd

You can find FAQ here.

:::tip Note CloudLinux 7 only :::

CRIU is Checkpoint/Restore In Userspace , (pronounced kree-oo ), is a software tool for Linux operating system. Using this tool, you can freeze a running application (or part of it) and checkpoint it as a collection of files on disk. You can then use the files to restore the application and run it exactly as it was during the time of freeze (more information on the link https://criu.org/Main_Page ).

mod_lsapi-1.1-1 is the first beta version with freezing PHP implemented. mod_lsapi now supports the following parameters:

Example:

lsapi_criu On
lsapi_criu_socket_path /var/run/criu/criu_service.socket
lsapi_backend_semtimedwait On
lsapi_backend_initial_start 15
lsapi_criu_use_shm Off
lsapi_criu_debug Off

When Apache module mod_lsapi detects CRIU enabled (lsapi_criu On) it prepares a directory for images (on the first request of virtualhost) to store ( lsapi_criu_imgs_dir_path /var/run/mod_lsapi/[dir_name] ), and starts lsphp process. Lsphp increases counter ( lsapi_criu_use_shm Off|Signals ) via shared memory or signals, when counter reaches limit ( lsapi_backend_initial_start 15 ), lsphp sends the request to CRIU for freezing. CRIU service makes images of requested processes. Lsphp will not be frozen if counter has not reached the limit. The next time when lsphp will be stopped, it will be unfrozen from the images.

The images of the processes will be saved even if Apache is restarted. But all images will be deleted after server restart by default configuration. This can be modified by setting the new path lsapi_criu_imgs_dir_path .

Important! If php.ini or configuration file from php.d is changed, the images must be deleted manually.

Note that CRIU (version lower than criu-lve-3.6-1) can't correctly freeze lsphp with PrivateTmp enabled. For correct work, PrivateTmp must be false in httpd.service file . For disabling:

Copy httpd.service to /etc/systemd/system and change there PrivateTmp:  

# cat httpd.service
[Unit]
Description=Apache web server managed by cPanel Easy
ApacheConditionPathExists=!/etc/httpddisable
ConditionPathExists=!/etc/apachedisable
ConditionPathExists=!/etc/httpdisable

[Service]Type=forking
ExecStart=/usr/local/cpanel/scripts/restartsrv_httpd --no-verbose
PIDFile=/var/run/apache2/httpd.pid
PrivateTmp=false 

[Install]
WantedBy=multi-user.target 

http://www.freedesktop.org/software/systemd/man/systemd.unit.html

mkdir /etc/systemd/system/httpd.service.d
echo "[Service]" >  /etc/systemd/system/httpd.service.d/nopt.conf
echo "PrivateTmp=false" >> /etc/systemd/system/httpd.service.d/nopt.conf

and

# systemctl daemon-reload

Installation

Criu is installed with dependency to mod_lsapi-1.1 package. To activate it:

1. Enable service and start it:

systemctl enable criu
systemctl start criu

2. Edit lsapi.conf file, turn CRIU On and set some defaults:

lsapi_criu On
lsapi_criu_socket_path /var/run/criu/criu_service.socket
lsapi_backend_semtimedwait On
lsapi_backend_initial_start 15
lsapi_criu_use_shm Off

3. Restart apache:

service httpd restart

1. An option added to the Apache configuration for cleaning all the images earlier saved by CRIU.

On the next restart of Apache all of the images will be cleaned.

It can be enabled by writing lsapi_reset_criu_on_apache_restart On in lsapi.conf (Virtual Host and .htaccess do not allow to use this option).

Note that this option works only if lsapi_terminate_backends_on_exit is On (default value is On , it is set in lsapi.conf too).

2. If you need to clean CRIU images for one user you can simply add file to the user's directory with CRIU images (default /var/run/mod_lsapi/lsapi * criu_imgs ). On the next restart of lsphp the images will be cleaned.

3. Global reset flag for cleaning all earlier saved images by CRIU.

Current mod_lsapi allows cleaning all images only with one flag file.

Create /usr/share/criu/mod_lsapi/lsphp.criu.reset file. Also don't forget to set such permissions [nobody:nobody] (or [apache:apache] for non cPanel) and access mode [700] to the /usr/share/criu/mod_lsapi directory.

Steps to do :

mkdir /usr/share/criumkdir /usr/share/criu/mod_lsapi
chown nobody:nobody /usr/share/criu/mod_lsapi
touch /usr/share/criu/mod_lsapi/lsphp.criu.reset

On the next requests to all virtual hosts images will be recreated (deleted first and created again later - it depends on lsapi_backend_initial_start value).

4. Аdded possibility to clean CRIU images from user space.

If a user needs to clean CRIU images for lsphp, he should create a file: ~/mod_lsapi_reset_me_[vhost_name] . Where [vhost_name] is a ServerName from the VirtualHost block in the configuration file. On the next restart of lsphp, the images will be cleaned.

Example:

cd; touch mod_lsapi_reset_me_criu.test.com

where vhost.conf contains:
ServerName criu.test.com

This mode is enabled by default and creates a separate lsphp process for each virtual host.

mod_lsapi_reset_me[vhost_name] flag will not work for a user when lsapi_per_user option is On .

5. There is (default off) option in mod_lsapi that creates only one lsphp process for a user, regardless of the number of his virtual hosts. We don't recommend to use this option with CRIU, but if you use it, make sure that your virtual hosts (under the same user) have the same environment configurations. If they are not the same, this may cause undesirable lsphp process operation.