Documentation
Installation
Software and Hardware Requirements:
- Atleast 500 Mb free space on your drive containing /opt (usually /)
- Cpanel version 11.31 or greater
- Incron
- bzip2
- Devel packages to compile PHP from source
The installer will install nginX from the official nginX yum repo and incron from the EPEL repo . PHP and cpXstack files will be installed to /opt/pifpm directory
cpXstack will take some time to install depending on your hardware
and other factors like number of accounts . It is strongly advised that
you perform the install in a screen session
screen -S cpXstack wget http://sysally.net/pifpm/cpxstack.sh chmod a+x cpxstack.sh ./cpxstack.sh install
Troubleshooting
cpXstack works on filesystem events generated by cpanel software.
The first thing to check if you notice a problem will be the status of
incron .
root@cpanel2 [/opt/pifpm/scripts]# ps aux|grep incron|grep -v grep root 6817 0.0 0.0 14080 724 ? Ss 08:52 0:00 incrond
At any time you can regenerate a users config files by running the following command from the commandline
cd /opt/pifpm/scripts ./looper.sh <USERNAME>
Where USERNAME is the cpanel username
For any domain that has nginX+PHP-FPM enabled . Additional nginX configuration can be added by the root user at
/opt/pifpm/nginx.include.d/<DOMAINNAME>.autoinclude
where DOMAINNAME is the domain .Ensure that the configuration you are adding to .autoinclude files are error proof ;otherwise nginX will fail to start
PHP-FPM custom pool file edits in /opt/pifpm/phpfpm.pool.d/ will be preserved . The cpXstack upgrade process preserves custom changes made to php.ini files as well
PHP-FPM process manager
cpXstack use the ondemand process manager by default as it is meant to be used in mass hosting environments . You can ofcourse change the processmanager by editing the PHP-FPM pool configuration per cpanel user . The other process managers available are.
static - a fixed number (pm.max_children) of child processes; dynamic - the number of child processes are set dynamically . With this process management, there will be always at least 1 children.
The maximum number of child processes which can be forked by each user can be set from the WHM panel by the root user .This works with all process managers .It is advised that you edit this value from WHM as any value set in WHM will overwrite the original value set .WHM cpXstack plugin also provides you privilege to change multiple cpanel users value at once. Which can home handy if for example you wish to edit the maxprocess for all users under one reseller.
PHP-FPM access log
By default this is not enabled .But you can enable it by editing the
pool config file (eg:
/opt/pifpm/phpfpm.pool.d/picdn.php-fpm.pool.conf ) and uncommenting the
following values
;access.log = /home/CPANELUSER/$pool.access.log
;access.format = "%R - %u %t \"%m %r%Q%q\" %s %f %{mili}d %{kilo}M %C%%"
This can sometimes come handy in troubleshooting php fastcgi behaviour
Slow PHP process logging
This feature comes very handy in troubleshooting buggy/slow php scripts in user accounts.The following setting must be enabled
; The log file for slow requests ; Default Value: not set ; Note: slowlog is mandatory if request_slowlog_timeout is set ;slowlog = /home/CPANELUSER/$pool.slow.log ; The timeout for serving a single request after which a PHP backtrace will be ; dumped to the 'slowlog' file. A value of '0s' means 'off'. ; Available units: s(econds)(default), m(inutes), h(ours), or d(ays) ; Default Value: 0 ;request_slowlog_timeout = 0
Additional php.ini defines per pool
; Additional php.ini defines, specific to this pool of workers. These settings ; overwrite the values previously defined in the php.ini. The directives are the ; same as the PHP SAPI: ; php_value/php_flag - you can set classic ini defines which can ; be overwritten from PHP call 'ini_set'. ; php_admin_value/php_admin_flag - these directives won't be overwritten by ; PHP call 'ini_set' ; For php_*flag, valid values are on, off, 1, 0, true, false, yes or no. ; Defining 'extension' will load the corresponding shared extension from ; extension_dir. Defining 'disable_functions' or 'disable_classes' will not ; overwrite previously defined php.ini values, but will append the new value ; instead. ; Note: path INI options can be relative and will be expanded with the prefix ; (pool, global or /opt/pifpm/php-PHPVERSION)
Adding a PHP opcode cache
You can add any PHP opcode cache to the available php versions
.Example here shows adding APC to the php-5.3.20 version installed
root@cpanel1 [~]# /opt/pifpm/php-5.3.20/bin/pecl install APC
Build process completed successfully Installing '/opt/pifpm/php-5.3.20/lib/php/extensions/no-debug-non-zts-20090626/apc.so' Installing '/opt/pifpm/php-5.3.20/include/php/ext/apc/apc_serializer.h' install ok: channel://pecl.php.net/APC-3.1.9
This can be enabled per cpanel user by editing the fpm pool config file for the user as given by the example below
vi /opt/pifpm/phpfpm.pool.d/picdn.php-fpm.pool.conf
php_admin_value[extension] = /opt/pifpm/php-5.3.20/lib/php/extensions/no-debug-non-zts-20090626/apc.so
Please note that the apc.shm_size cannot be set in the pool configuration - http://forum.nginx.org/read.php?3,122844
OR
The module can be loaded in the php.ini file ;which then gets enabled for all users
vi /opt/pifpm/php-5.3.20/lib/php.ini
extension = /opt/pifpm/php-5.3.20/lib/php/extensions/no-debug-non-zts-20090626/apc.so
Read this too if you are keen on enabling opcode caching : https://bugs.php.net/bug.php?id=57825
Adding ioncube loaders
Download ioncube loaders matching your OS and arch
wget http://downloads2.ioncube.com/loader_downloads/ioncube_loaders_lin_x86-64.tar.gz tar -xvzf ioncube_loaders_lin_x86-64.tar.gz
I needed it installed for the PHP 5.4.11 version ;so
mv ioncube/ioncube_loader_lin_5.4.so /opt/pifpm/php-5.4.11/lib/
and edit the php.ini file /opt/pifpm/php-5.4.11/lib/php.ini and add line below towards the end
zend_extension = /opt/pifpm/php-5.4.11/lib/ioncube_loader_lin_5.4.so
Restart the PHP-FPM daemon for the PHP version
/etc/init.d/php-fpm-5.4.11 restart
Thats it. You can try enabling this extension on a per pool basis too.
Recompile php
Download the respective php source from php.net
wget http://us2.php.net/distributions/php-5.3.21.tar.bz2 tar -xvjf php-5.3.21.tar.bz2 cd php-5.3.21 php_configure_args="`php-cli -i|grep configure |cut -d'>' -f2 | sed "s/'//g;s/prefix=\/usr\/local/prefix=/;s/--with-apxs2=\/usr\/local\/apache\/bin\/apxs//;s/--with-apxs=\/usr\/local\/apache\/bin\/apxs//"` --enable-fpm" echo $php_configure_args > current_config
Edit the file current_config and change --prefix= line so that it looks like
--prefix=/opt/pifpm/php-5.3.21
Change the prefix according to the php version you are recompiling! and add any extra configure arguments to the file .
Thats it recompile php with the correct args
root@cpanel1 [~/php-5.3.21]# `cat current_config ` make make install
Please note that cpXstack will upgrade your php as soon as a new version is available at php.net ;so you either have to add the new modules to cpanel installed system php or recompile php-fpm again as mentioned above.
Microcaching
We are yet to try this out .But searching the web shows a lot of custom configurations
http://alchemi.st/nginx-wordpress-network-and-fastcgi-cache-the-ultimate-guide/
http://fennb.com/microcaching-speed-your-app-up-250x-with-no-n
http://daan.kortenba.ch/wordpress-nginx-tutorials/
http://www.howtoforge.com/configuring-your-lemp-system-linux-nginx-mysql-php-fpm-for-maximum-performance
The file /etc/nginx/fastcgi_params gets included in
location ~ \.php$
