SuPHP is an Apache module that enhances security on your server by running PHP scripts under the ownership of the individual cPanel user account rather than the default Apache web server user (often nobody). This guide will walk you through understanding, installing, and managing SuPHP on your cPanel server using EasyApache 4, along with troubleshooting common permission issues and customizing PHP settings.

What is SuPHP?

SuPHP (Single user PHP) is an Apache module for executing PHP scripts with the permissions of their owners. When you use PHP, by default, scripts might run as a generic web server user. If one site running under this generic user is compromised, it could potentially affect other sites on the same server. SuPHP mitigates this risk by ensuring that each PHP script executes under the specific cPanel user who owns the website files. This isolates processes and enhances the overall security of a shared hosting environment.

SuPHP works as a CGI handler, meaning PHP scripts are executed as CGI processes. While this provides strong security, it’s important to be aware of its strict permission requirements, which we’ll cover in detail.

Installing SuPHP with EasyApache 4

If SuPHP is not already active on your server, you can install it via WHM’s EasyApache 4 interface. You’ll need root access to WHM to perform these steps.

Log in to WHM as the root user.
Navigate to Software > EasyApache 4.
In the “Currently Installed Packages” section, click the Customize button.
Go to the Apache Modules section. Type “suphp” in the search box. Find mod_suphp and toggle the switch to mark it for installation.
Next, go to the PHP Handlers section. Here, you will see a list of your installed PHP versions. For each PHP version where you want to use SuPHP, select suPHP from the dropdown menu as the handler. Note: SuPHP requires PHP to be compiled as CGI. EasyApache 4 typically handles this automatically when you select SuPHP as the handler.
Click on Review. Check the list of packages to be installed and changes to be made.
If everything looks correct, click the Provision button and wait for the process to complete.
Once provisioning is complete, SuPHP will be active for the selected PHP versions. You can verify this in WHM’s MultiPHP Manager by checking the PHP Handler for your websites.

SuPHP file permission requirements

SuPHP is very strict about file and directory permissions for security reasons. If permissions are not set correctly, SuPHP will refuse to execute the scripts, often resulting in a 500 Internal Server Error. Here’s what you need to know:

Ownership

All PHP scripts and the directories containing them must be owned by the cPanel user account that owns the website. They should not be owned by root or nobody.

Permissions

PHP Files (e.g., .php):
- Recommended: 644 (-rw-r--r--). This means the owner can read and write, while the group and others can only read.
- Never use 777, 666, or 664. SuPHP will refuse to execute files with such permissive settings, especially group or world writability.
- PHP files should not have the execute bit set (e.g., 755 for a file is incorrect).
Directories (e.g., public_html and subdirectories):
- Recommended: 755 (drwxr-xr-x). This means the owner can read, write, and execute (For a directory, execute means entering and listing contents), while the group and others can read and execute.
- Directories should not be world-writable (777) or group-writable (775 can sometimes cause issues depending on SuPHP’s strictness settings, though 755 is safest).

Incorrect permissions are the most common cause of issues when using SuPHP.

Troubleshooting SuPHP permission errors

If your website displays a “500 Internal Server Error” after enabling SuPHP or when trying to access PHP scripts, the first place to check is the SuPHP log.

The SuPHP log file is typically located at:

/var/log/apache2/suphp_log

You can view this log via SSH using commands like tail, less, or cat:

tail -f /var/log/apache2/suphp_log

Common error messages in suphp_log and how to fix them:

SecurityException: Group writable directory /home/username/public_html/somedir or SecurityException: File /home/username/public_html/script.php is writable by group
- Cause: The directory or file has group write permissions (e.g., 775 for a directory, 664 for a file).
- Fix: Change permissions. For directories: chmod 755 /home/username/public_html/somedir. For files: chmod 644 /home/username/public_html/script.php.
SecurityException: World writable directory /home/username/public_html/somedir or SecurityException: File /home/username/public_html/script.php is writable by others
- Cause: The directory or file has world write permissions (e.g., 777, 647).
- Fix: Change permissions as above (755 for directories, 644 for files).
SoftException in Application.cpp:XXX: UID of script "/home/username/public_html/script.php" is NNN, should be MMM or SoftException in Application.cpp:XXX: Mismatch between target UID (XXX, username) and UID (YYY, owner) of file /home/username/public_html/script.php or SecurityException: UID of script NNN does not match UID of file MMMM
- Cause: The PHP script is not owned by the correct cPanel user. The UID (User ID) of the script’s owner does not match the UID SuPHP expects for that virtual host.
- Fix: Change the ownership of the file to the correct cPanel user: chown username:username /home/username/public_html/script.php. Ensure parent directories are also correctly owned.
SoftException in Application.cpp:XXX: File "/home/username/public_html/script.php" is not executable
- Cause: This usually implies an issue with how SuPHP is trying to execute a script, often stemming from incorrect handler configuration or internal SuPHP setup. However, remember PHP files themselves usually do not need the execute bit (x). This error could point to deeper configuration issues or trying to execute a non-PHP file as PHP. For directories, they *do* need the execute bit to be accessible.
- Fix: Ensure directories leading to the script have 755 permissions. Verify your PHP handler settings in WHM MultiPHP Manager.

When troubleshooting, always check the permissions and ownership of the script itself, as well as all parent directories up to the user’s public_html or document root.

You can check current permissions and ownership using: ls -ld /path/to/file_or_directory

Custom PHP settings with .user.ini

When using SuPHP (or other CGI/FPM handlers), you can customize PHP settings on a per-directory basis using .user.ini files. This is different from using php_value directives in .htaccess files, which typically only work with DSO (mod_php).

How .user.ini works with SuPHP:

Create a file named .user.ini (note the leading dot) in the directory where you want the custom PHP settings to apply. Usually, this is your website’s document root (e.g., /home/username/public_html/).
Settings in a .user.ini file affect the directory it resides in and all subdirectories.
The syntax is the same as a regular php.ini file.

Example .user.ini content:


memory_limit = 256M
upload_max_filesize = 64M
post_max_size = 64M
max_execution_time = 120
display_errors = On
error_log = /home/username/logs/php_errors.log

Important considerations:

Permissions: The .user.ini file itself should be owned by the cPanel user and have permissions like 644. It should not be writable by group or others.
Directive Scope: You can only change PHP directives that have a mode of PHP_INI_PERDIR or PHP_INI_USER. Directives with PHP_INI_SYSTEM mode cannot be changed in .user.ini. You can check the mode of a directive on the official PHP documentation website (php.net).
Caching: PHP caches these files for performance. Changes might not take effect immediately due to the user_ini.cache_ttl setting in PHP (Time To Live, defaults to 300 seconds / 5 minutes). You might need to wait or, if you have appropriate access and know-how, restart the PHP-FPM service associated with the user/domain (if FPM is used in conjunction with SuPHP, though SuPHP itself doesn’t have a separate service to restart for this purpose). For SuPHP as a pure CGI handler, the changes are typically picked up on the next script execution after the cache TTL expires.
Security: cPanel’s default Apache configuration usually includes rules to prevent direct web access to .user.ini files, so they cannot be viewed through a browser.

Using .user.ini files provides a flexible way to tailor PHP behavior for specific sites or applications without needing server-wide configuration changes.

By understanding these aspects of SuPHP, you can maintain a more secure and customizable PHP environment for your websites hosted on a cPanel server.

Was this article helpful?

Thank you for your input.

Thank you for your feedback.