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 (you stubborn bitches)

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.

Be Sociable, Share!

12 thoughts on “Installing suPHP on cPanel

  1. Hi Vanessa..

    I have a problem with suphp and apache nobody user ..

    All files created my php have user as nobody and not the user

    get his error when uploading image inside wordpress..

    The uploaded file could not be moved permission denied

  2. That means that PHP is running through Apache, as Apache runs as ‘nobody’ so PHP will follow that ownership. You need to make sure that PHP is running as CGI, which can usually be verified by checking your phpinfo file and seeing if it says ‘apache’ or ‘cgi’ as the server API.

  3. Thanks so much for pointing that m8 ! I actually moved a site from a shared hosting to a vps .. only now im comparing the phpinfo output for both the servers and see the diff !!

    I m rebuilding php and apache now !! First time on a vps .. God save me

  4. Hi Vanessa,
    i have got a problem with my suphp.
    Last tuesday the server stops working and shows me an error 500 on all my php files. I check the config and the logs and i only find this problem in the suphp log.
    [Mon Aug 25 11:48:22 2008] [warn] Directory / is not owned by username1
    It happens for all the users in the server, but there is one username1 that is working when the others dont.
    [Mon Aug 25 11:48:17 2008] [info] Executing “/home/username2/public_html/index.php” as UID 32047, GID 32049

    As one of them is working, i understand that suphp is fine, but… i have read a lot in the Internet and i dont know where to find the problem for the server. could you help me?

  5. hello, i am wondering if suPHP can be enabled/disabled per virtual host account (eg. my hosting company is worried about installing it on the shared server that i am on, as it might affect the other sites/accounts on that server… isn’t there a way to limit suPHP to just my account? running cpanel on a linux box). thanks!

  6. @T.F Well, they can install two instances of PHP and have them load in Apache side by side, but you would need to make sure your .htaccess contains Apache handlers for .php to associate with SuPHP.

    FYI – Any host that is going to make a change like this on a shared server, esp. at the request of one customer, should be ditched. This is why so many people leave iPower…

  7. Hi guys,

    I just got a Dedicated Server running cPanel/WHM from Heart Internet.

    I have managed to set up Packages, and I have set up an account as well, and everything SEEMED to be working fine.

    I have found that when the client uploads files to his account, they are all accessible as long as they are directly under the public_html folder.

    However, if the user creates a subdirectory under public_html, then any files under that directory are inaccessible via the browser, and the browser throws a 500 error.

    I can assume that this is a permissions problem?
    Any help would be greatly appreciated!

  8. You are awesome, you have just made my week. Thank you so much my cart is back up and selling because of you!

Leave a Reply

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