Installing suPHP on cPanel

I wrote this tutorial a while back and figured it would be good to post because suPHP is growing more popular as an alternative to phpSuExec. The instructions assume that you are on a Linux cPanel server and are familiar with how to install PHP, but do not want to use EasyApache’s suPHP installer in WHM

Note also that these instructions use suPHP 0.6.1 with a cPanel patch that makes it equivalent to 0.6.2. I personally have had issues with the actual 0.6.2 version installing, so I stuck with the patch.

Next, download suPHP and the apply the patch:

tar -xvzf suphp-0.6.1.tar.gz
cd suphp-0.6.1

patch -p1 < suphp-0.6.1-cpanel.patch

Then compile the binary:

./configure –prefix=/usr –sysconfdir=/etc –with-apxs=/usr/local/apache/bin/apxs –with-apache-user=nobody
make && make install

Now locate your PHP binaries for installation. If you previously used EasyApache, you should be able to find them somewhere in your home directory within a directory named ‘cpeasyapache’ or something similar depending on your cPanel version. Otherwise you will need to fetch the PHP sources from if you do not have the original sources you used to compile.

Check the server’s phpinfo file and grab the configure path, then copy and paste it into notepad and remove all the single quotes. You’re basically compiling PHP exactly the same way as it was before, only not as an Apache module.

cd /home/cpapachebuild/buildapache/php-5.2.3
make clean

The only difference is that you need to remove the ‘–with-apxs=’ switch from the configure line. The prefix can stay the same, but it’s recommended to install this in a different directory, like /usr/cgiphp or something.

So technically your configure would look like this:

./configure –prefix=/usr/cgiphp –with-xml –with-mm ………
make install

Now check that the installation was successful (should say cli for this one, but cgi will work as well) :

/usr/cgiphp/bin/php -v

PHP 5.2.3 (cli) (built: Aug 3 2007 07:22:58)
Copyright (c) 1997-2007 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2007 Zend Technologies

Download the suphp.conf into /etc, which is the location you specified during the configuration of suphp:

cd /etc

Now you need to edit /etc/suphp.conf and change the handler paths to (lines 47/48):


Check httpd.conf to see if there is already an suphp module setup in the virtualhost entries. If not, set up the apache template to automatically add it for new accounts:

pico /usr/local/cpanel/etc/httptemplates/apache1/default

Under <IfModule mod_php4.c> (exactly as is) add these lines:

<IfModule mod_suphp.c>
suPHP_UserGroup %user% %user%
suPHP_ConfigPath /home/%user%/php

suPHP_ConfigPath /home/%user%/php specifies the location of the user’s php.ini file, which will be created later. This is completely optional, as it is only necessary if you want to specify where the users’ php.ini files are going to be location (default location is public_html). Recent versions of cPanel already have an suPHP module loader, so you may only have to add the suPHP_ConfigPath line to the suPHP section.

You should do the same for SSL hosts in /usr/local/cpanel/etc/httptemplates/apache1/ssldefault.

Add the following lines to httpd.conf in their appropriate sections:

LoadModule suphp_module libexec/
AddModule mod_suphp.c

<IfModule mod_suphp.c>
suPHP_Engine On
suPHP_ConfigPath /usr/local/Zend/etc
suPHP_AddHandler x-httpd-php5
AddHandler x-httpd-php5 .php5
suPHP_AddHandler x-httpd-php
AddHandler x-httpd-php .php .php3 .php4 .phtml
suPHP_AddHandler x-httpd-php-source
AddHandler x-httpd-php-source .phps
<Files *.php5>
suPHP_ConfigPath /usr/cgiphp/lib

It’s also a good idea at this point to disable the loading of the Apache php module, so they can only run as CGI. Comment out these lines:

#LoadModule php5_module libexec/
#AddModule mod_php5.c

If you do the above, comment out the following lines:

#AddType application/x-httpd-php .php
#AddType application/x-httpd-php .php4
#AddType application/x-httpd-php .php3
#AddType application/x-httpd-php-source .phps
#AddType application/x-httpd-php .phtml

The users that already exist on the system should already have suphp directives in their virtualhost entries. If not, you will need to add them manually:

<IfModule mod_suphp.c>
suPHP_UserGroup user user
suPHP_ConfigPath /home/%user%/php

In this one you actually need to replace ‘user’ with the username and group of the account.

Now you need to fix the first VirtualHost entry as well, which is the website that is displayed when you go to on a shared hosting environment. This is the site that is pulled from /usr/local/apache/htdocs and PHP will not work in this directory, because your suphp.conf file defines the docroot to be /home, meaning that suPHP will not execute PHP that is outside of /home. When you find the VirtualHost container for the main IP add the following into that VirtualHost:

<IfModule mod_suphp.c>
suPHP_UserGroup <user> <user>
<Directory /usr/local/apache/htdocs>
suPHP_GlobalDocRoot /usr/local/apache/htdocs
suPHP_DontCheckVHostDocRoot Yes

For the user, since PHP won’t execute as nobody or root, this needs to be a valid user on the system. Generally it’s best to create a neutral user on the system with no SSH access to be the owner of the htdocs folder. Whatever user you use, you will need to chown the entire htdocs directory to that user (or whatever directory you use as a default. The DontCheckVHostDocRoot part is necessary if you are running this outside of /home.

Last you should create a php folder in /root/cpanel3-skel with a copy of the server’s php.ini file, so new user accounts are created with a php.ini.

The path to the cgi php binary is /usr/local/bin/php, so you want to make sure that it is accessible when called from command line and that suPHP loads the new binary.

ln -s /usr/cgiphp/bin/php-cgi /usr/local/bin/php
ln -s /usr/cgiphp/bin/php-cgi /usr/local/bin/php5
ln -s /usr/cgiphp/bin/php /usr/bin/php
ln -s /usr/cgiphp/bin/php /usr/bin/php5

If you get an error about one already existing, simple delete it and try to link it again.

Now you have to copy the extentions:

cd /usr/cgiphp/lib/php/
mkdir -p extensions/no-debug-non-zts-20060613

pico /usr/local/lib/php.ini

Change the extension_dir value to that of the new folder you created, then copy all the files over:

cp /usr/local/lib/php/extensions/no-debug-non-zts-20060613/* extensions/no-debug-non-zts-2006061/

Depending on the server, the actual extension directory may be different!

Settings for suphp.conf

Suphp.conf lets you control the settings in place for suPHP. The following settings are the recommended in place for shared servers:


The location of the logfile on the server, will be created automatically.


What information to describe in the logs. ‘info’ is very broad, but you can also use ‘warn’ to only show warnings.


What use Apache runs as — this basically indicates what user no php scripts can run as, even ones in htdocs.


The base directory where php scripts have to be located in order to run, which prevents php scripts from executing from system folders. If a user for some reason needs to execute something from outside of home, you need to make a virtualhost directive containing:

<Directory /usr/local/apache/htdocs>
suPHP_GlobalDocRoot /<path to directory>
suPHP_DontCheckVHostDocRoot Yes


This is the most important for security, specifying the allowable permissions of files and folders by other users than the one owning the script.

If your server currently has accounts on it, you’ll need to run these followup scripts:


From /home:

find -perm 777 -exec chmod 755 {} \; -print
find -perm 666 -exec chmod 644 {} \; -print

For the php.ini, you’ll also need to copy it from /usr/bin/php.ini into /home/user/php for all users existing on the machine before the installation of suPHP. New user accounts will automatically have this, as long as it you followed the step of copying it to /root/cpanel3-skel/php

If the server is running Fantastico, make sure you set the config to use phpsuexec.

Categorized as cPanel

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.