Apache mod_lsapi

Navigation:  »No topics above this level«

Apache mod_lsapi

Previous pageReturn to chapter overviewNext page

Apache mod_lsapi is a module based on LiteSpeed Technologies API for PHP, Ruby and Python. It offers excellent PHP performance, low memory footprint coupled with great security and support for opcode caching.

 

How it works

 

mod_lsapi is a part of Apache;

Apache passes handling for PHP request to mod_lsapi;

mod_lsapi uses liblsapi to transfers request lsphp daemon;

lsphp processes request and return data to mod_lsapi;

Each user has lsphp processes in separate CageFS/LVE;

If there is no requests for lsapi_backend_pgrp_max_idle seconds, lsphp process is terminated;

If no lsphp processes available when new request comes, new lsphp process is created;

lsphp can process lsapi_backend_children requests simultaneously.

 

 

mod_lsapidiagrammNEW

 

What is lsphp

 

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

 

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

 

Requirements

 

CageFS (installed and initialized)

Alt-PHP

Apache with SuExecuUserGroup directive for each user's VirtualHost,

mod_ruid2 disabled

apache itk disabled

 

Configuration Options

 

Options

Description

Level

php_value, php_admin_value, php_flag, php_admin_flag

mod_php emulation

httpd.conf, virtualhost, htaccess

lsapi_engine

Switching mod_lsapi handler on or off

httpd.conf

lsapi_backend_connect_timeout

number of usec to wait while lsPHP starts (if not started on request)

httpd.conf

lsapi_backend_connect_tries

number of retries to connects to lsPHP daemon

httpd.conf

lsapi_terminate_backends_on_exit

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.

httpd.conf

lsapi_backend_children

sets env variable LSAPI_CHILDREN
# lsphp also try to read PHP_LSAPI_CHILDREN var

# Required and should be >0 in order to enter into self-managed mode

# min value is 1; max value is 10000. if var value is more, 10000 will be used.

httpd.conf

lsapi_backend_max_process_time

env variable LSAPI_MAX_PROCESS_TIME
# Optional. Default value is 300

# Timeout to kill runaway processes

httpd.conf

lsapi_backend_pgrp_max_idle

sets evn variable LSAPI_PGRP_MAX_IDLE, in seconds
controls how long an control process will wait for

# a new request before it exits.

# Optional, default value is 0 -> infinite

# export LSAPI_PGRP_MAX_IDLE=0

 

httpd.conf

lsapi_debug

enable debugging for mod_lsapi, acceptable values: on/off

httpd.conf

lsapi_socket_path

 

Path to back end lsphp sockets. By default /tmp/lshttpd

 

httpd.conf

lsapi_per_user

Invoke master lsPHP process not per VirtualHost but per account

httpd.conf

lsapi_phprc

Sets PHPRC env variaable

httpd.conf, virtualhost

lsapi_user_group

Set user & group for requests

 

httpd.conf, virtualhost, directory

 

lsapi_uid_gid

 

Set user id & group id for requests

 

httpd.conf, virtualhost, directory

lsapi_use_default_uid

 

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. Default - Off

 

 

httpd.conf

lsapi_target_perm

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

httpd.conf

lsapi_poll_timeout

By deafult - 0 (infinity). For preventing long running processes which can use EP (limit number of entry processes). In seconds - time to wait response from lsphp daemon.

 

httpd.conf

lsapi_backend_coredump

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

LSAPI_ALLOW_CORE_DUMP

httpd.conf

lsapi_mod_php_behaviour

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

httpd.conf, virtualhost, htaccess

lsapi_with_connection_pool

On/Off - disable enable connect pool, default Off

httpd.conf

lsapi_backend_max_idle

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.

httpd.conf

lsapi_backend_max_reqs

It is relevant only with lsapi_with_connection_pool option switched on. Controls how many requests a worker process will process before it exits.

httpd.conf

lsapi_set_env

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

httpd.conf

lsapi_set_env_path

Change PATH variable in the environment of lsPHP processes.

httpd.conf

lsapi_paranoid

Check or not permissions of target php scripts

httpd.conf

lsapi_check_document_root

Check or not the owner of DOCUMENT ROOT

httpd.conf

lsapi_enable_user_ini

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

httpd.conf

lsapi_criu

Enable/disable CRIU for lsphp freezing. Can be: On/Off. Default: Off

httpd.conf

lsapi_criu_socket_path

Set path to socket for communication with criu service [should be path] - default: /var/run/criu/criu_service.socket

httpd.conf

lsapi_backend_semtimedwait

Enable/disable flag for notification about lsphp started. This method avoid cycles of waiting for lsphp start/ Can be: On/Off. Default: Off

httpd.conf

lsapi_backend_initial_start

Number of request when lsphp should be freezed. Should be [number] - default 0

httpd.conf

lsapi_criu_use_shm

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

httpd.conf

lsapi_criu_imgs_dir_path

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

httpd.conf

 

Example configuration

 

LoadModule lsapi_module modules/mod_lsapi.so
 
<IfModule lsapi_module>
  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>

 

Secret File

 

When installed, liblsapi will automatically create secret file used by mod_lsapi to communicate with backend:

/etc/sysconfig/modlsapi.secret

owner root:root

perms: 400

for making security pass PHPRC and UID|GID on start lsphp

Algorithm of creating:

/bin/dd if=/dev/random of=/etc/sysconfig/modlsapi.secret bs=16 count=1

 

Command Line Tools (cPanel only)

 

Use the following syntax to manage MODLSAPI istall utility:

/usr/bin/switch_mod_lsapi [OPTIONS]

Options:

--setup - setup mod_lsapi configurations for apache

--uninstall - uninstall mod_lsapi from apache

--enable-domain - enable mod_lsapi for individual domain

--disable-domain - disable mod_lsapi for individual domain

--enable-global - sets up mod_lsapi as a default way to serve PHP, making it enabled for all domains. Once that mode is enabled, you cannot disable mod_lsapi for individual domain

--disable-global - disable mod_lsapi  as a default way to serve PHP, disabling mod_lsapi for all domains, including those selected previously using --enable-domain

--build-native-lsphp - build native lsphp for cPanel

 

This tool:

at the moment, works only with cPanel

creates native lsphp (if it doesn't exist) by doing: cp /opt/alt/php54/usr/bin/lsphp /usr/local/bin/

creates /tmp/lshttpd and adds it to /etc/cagefs/cagefs.mp

Removes config template for mod_ruid2

Configures Apache handler application/x-httpd-lsphp

Switch domain to lsphp or enable global lsphp

For cPanel can build native lsphp

 

What commands are available for different control panels:

 

 

No CP

cPanel

DirectAdmin

Plesk

InterWorx

ISPManager

install

+

+

+(no need in manual calling)

+

+

+

uninstall

+

+

-

+

+

+

enable-domain

-

+

-

-

-

-

disable-domain

-

+

-

-

-

-

enable-global

-

+

+/- (custombuild)

-

-

-

disable-global

-

+

-

-

-

-

build-native-lsphp

-

+

+/- (custombuild)

-

-

-

 

Different PHP versions (without PHP Selector)

 

mod_lsapi allows to use different handlers for different php versions. For example, a file with extension .php53 can be handled by php5.3 and a file with extension .php55 handled by php5.5 without PHP Selector.

Here is an extra config file which allows to set handlers and php binaries for these handlers - /etc/container/php.handler. Example of this file:

 

# cat /etc/container/php.handler

application/x-lsphp53 /opt/alt/php53/usr/bin/lsphp

application/x-lsphp55 /opt/alt/php55/usr/bin/lsphp

 

Default handler for lsphp is - application/x-httpd-lsphp, if I set in .htaccess such options:

 

<FilesMatch "\.(php4|php5|php3|php2|php|phtml)$">

SetHandler application/x-httpd-lsphp

</FilesMatch>

<FilesMatch "\.php53$">

SetHandler application/x-lsphp53

</FilesMatch>

 

File index.php53 will be processed by php 5.3, but index.php processed by php standard, placed at /usr/local/bin/lsphp.

 

Important:

 

All custom PHP for phpperdir mechanizm should be located in any place in the directory /opt/alt/, because before start lsphp mod_lsapi checks as follows: /usr/local/bin/lsphp or /opt/alt/*/lsphp. Such location and binary file are allowed to execute. Use the folder /opt/alt/[any path] for installing custom php.

 

For example:

 

/opt/alt/php.perdir/php55/bin/lsphp - it will work with mod_lsapi.

 

But if the server has custom php in another location (for example /usr/local/php55/bin/lsphp), then just make symlink to lsphp:

 

ln -sf /usr/local/php55/bin/lsphp /opt/alt/php.perdir/php55/bin/lsphp

 

and add it to php.handler:

 

myhandler-php55 /opt/alt/php.perdir/php55/bin/lsphp

 

mod_lsapi as suPHP replacement (cPanel)

 

mod_lsapi is a drop in replacement for suPHP. No configuration changes need to be done. To switch from suPHP to mod_lsapi:

 

Switch the whole server (disables suPHP, all domains will be serviced by mod_lsapi):

 

/usr/bin/switch_mod_lsapi --enable-global

 

Switch individual domains:

 

/usr/bin/switch_mod_lsapi --enable-domain test.example.tst - enablesmod_lsapi [only for domain test.example.tst]

 

Manually add mod_lsapi for a particular domain: - add to .htaccess file for the domain:

AddType application/x-httpd-lsphp .php5 .php4 .php .php3 .php2 .phtml

 

Note: This will work only after /usr/bin/switch_mod_lsapi --setup had been called.