--- title: "SuPHP on cPanel" source: "https://docs.nexcess.com/hosting/control-panel/whm/cpanel/suphp-on-cpanel/" description: "Learn to install SuPHP on cPanel via EasyApache 4, manage file permissions, troubleshoot 500 errors using suphp_log, and set custom PHP options with .user.ini." vertical: "Hosting" date: "2025-05-29" last_modified: "2026-08-04" --- # SuPHP on cPanel 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. 1. Log in to **[WHM](https://docs.nexcess.com/hosting/control-panel/whm/logging-into-whm/)** as the root user. 2. Navigate to **Software** > **EasyApache 4**. 3. In the “Currently Installed Packages” section, click the **Customize** button. 4. Go to the **Apache Modules** section. Type “suphp” in the search box. Find `mod_suphp` and toggle the switch to mark it for installation. 5. 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.* 6. Click on **Review**. Check the list of packages to be installed and changes to be made. 7. If everything looks correct, click the **Provision** button and wait for the process to complete. 8. 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.