We have a new documentation site for cPanel & WHM! You can find our new documentation site at docs.cpanel.net.
We will continue to maintain our API documentation on this server.
EasyApache is software that installs, modifies, and validates your Apache web server, PHP, Tomcat, and other components of your web server. WHM's EasyApache 3 interface (Home >> Software >> EasyApache 3) provides an interface that allows you to select which components you want EasyApache to install.
You do not have to use EasyApache, but it provides a convenient and easy method to modify your web server. Your cPanel & WHM license includes the EasyApache software.
For more information about EasyApache, read our EasyApache documentation.
EasyApache provides the following benefits:
We recommend that you run EasyApache whenever there is an update to software that you use. For example, if you use PHP on your server, run EasyApache each time that PHP releases an update.
/scripts/upcpscript as the
To run EasyApache via the WHM interface, use WHM's EasyApache 3 interface (Home >> Software >> EasyApache 3).
To run EasyApache via the command line, run the
/scripts/easyapache script as the
When you configure EasyApache, the following terms in the WHM interface describe a product or feature's state of development:
If you manually modified your Apache, PHP or Tomcat configurations, we recommend that you perform the following actions before you run EasyApache:
Use the procedures in our EasyApache - Development documentation to modify the configuration files to restore the necessary parts of your custom configuration.
EasyApache will automatically remove changes to the configuration if they are not in the correct files. Read our EasyApache - Development documentation for more information.
The EasyApache options that you select will determine what EasyApache builds into your web server. As a general rule, do not select an option unless you need it. For each option that you select, make certain that you understand the functionality of the option and any security vulnerabilities that may come with it.
We strongly recommend that you do not use options marked DEPRECATED or NOT SUPPORTED. They may introduce security vulnerabilities or instability to your server.
EasyApache provides a mechanism that allows you to add options to EasyApache via custom modules. For example, you can add PHP or Apache modules, or PHP versions.
For more information on custom modules, read our Custom Modules documentation.
This option allows Apache to serve files which are located inside of the virtual host's document root. For example:
If you enable symlinks via
FollowSymlinks, Apache will only serve content via a symlink when the owner of the symlink matches the owner of the file (For example, the user
bob links to a file that
bob owns). However, Apache's documentation for symlinks states that a potential race condition with symlinks exists and the directive will affect server performance.
Apache performs a test for symlinks as it turns a URL into a file path on disk. Apache handlers expect to operate on the file path rather than on an open file handle. So, a race condition exists titled time of check time of use (TOCTOU) between the step where Apache validates the path and when a content handler accesses the symlinked file.
The Rack911 patch turns the Apache
FollowSymlinks directive into the Apache '
FollowSymlinks' + '
SymLinksIfOwnerMatch' directive. This provides a quick way to activate both of these directives in the
httpd.conf file at the same time.
The Rack911 patch itself does not protect against the race condition. Instead, this patch changes the Apache
Options FollowSymlinks directive into a shortcut for the Apache
Options FollowSymlinks SymLinksIfOwnerMatch directive. If you use this patch, your users cannot turn off both the Apache
SymLinksIfOwnerMatch directive and symlinks. Because Apache does not provide a detailed ACL approach for these options, this solution provides a quick way to enable and disable symlinks at a system-wide level within the
The Bluehost.com patch modifies Apache and APR so that Apache cannot access certain files. However, the Bluehost.com patch only affects requests that Apache's default handler processes (for example, static files such as
.html files). The Bluehost patch does not affect requests that application content handlers such as
Traditionally, systems administrators assign content handlers to the content that they want to serve. For example, the
mod_php handler serves PHP scripts, and the
mod_cgi hander serves arbitrary CGI scripts. When Apache cannot find a content handler associated with an incoming request, Apache resorts to the
default_handler reads in the contents of a file and displays it as-is to the requestor (for example,
cat file.txt > requestor).
A problem occurs when an application runs as the
nobody user. The application will create files on the server that the user
nobody owns, which does not match the owner. Because the patch prevents access to static content that does not match the owner, the user cannot view these files.
If your applications run as a specific user, then the files the application writes will possess the correct ownership.
The Bluehost.com patch compares the UID of the requested file to the owner of the document root. If the owners do not match, Apache returns the following error code:
Finally, the system writes a warning to the
/usr/local/apache/error_log file that will resemble the following example:
When EasyApache builds, it creates a log file that contains all of the EasyApache process's output. EasyApache stores the build log files in the
If EasyApache fails to build successfully, EasyApache provides a general statement of the error near the end of the log file, and then a more specific failure error. If you see any of the following text in the EasyApache log file, look further down in the log file to determine the cause:
Could not ensure pkglist
Syntax error on line
Failed to generate a syntactically correct Apache configuration
Configuration problem detected on line ... of file ...
This error message indicates that your system detects another instance of EasyApache and will not proceed until that instance completes. You cannot run multiple instances of EasyApache at the same time. Some common causes of this error include the following situations:
/scripts/easyapache) to run via the command line. The issue will resolve after the other instance of EasyApache completes.
The first thing that EasyApache does is check to see if there are any updates available. The most common causes of this issue relate to network connectivity. The EasyApache software requires access to our update servers, and will retry repeatedly if it cannot reach them.
In rarer cases, you may experience this issue when we are in the process of an EasyApache release. If you are certain that there is no connectivity issue, then we recommend that you wait up to one hour and then run EasyApache to receive the update.
The most common cause of this issue is that the new EasyApache configuration uses a different PHP version than the previous EasyApache configuration used.
The EasyApache build may have changed your PHP version from one minor version to another. For example, code written for PHP version 5.3 may not be compatible with PHP version 5.4. EasyApache will not automatically change the version unless you select a default profile, or if your last EasyApache build contained a version of PHP that we no longer support.
Updates to minor revisions of PHP do not usually affect compatibility. For example, code written for PHP version 5.4.28 should still function correctly with PHP version 5.4.29.
To resolve the issue, select the correct PHP version and rebuild EasyApache. If the version of PHP is not available, the developer of the incompatible code will need to either modify the code or you will need to use a custom module for the necessary PHP version.
We strongly recommend that you do not use a version of PHP that has reached End of Life (EOL) or that we mark as DEPRECATED or NOT SUPPORTED. They may introduce security vulnerabilities or instability to your server.
This issue may also happen if you do not select a PHP handler after you run EasyApache. Use WHM's Configure PHP and suEXEC interface (Home >> Service Configuration >> Configure PHP and suEXEC) to select a PHP handler.
If you include options that have different file permissions or security settings than your previous build, you may need to make additional adjustments. For example, the modules suPHP and ModRuid2 require specific file permissions to work correctly.
Before you can resolve the issue, you will need to determine what the root cause of the issue is. If the Apache error that the web browser displays is not clear, review the following sources of information:
.htaccessfiles — For information about
.htaccessfiles, view Apache's Apache HTTP Server Tutorial: .htaccess files documentation for Apache version 2.4, or Apache's Apache HTTPD Server Tutorial: .htaccess files documentation for Apache version 2.2.
The full error that you receive will look similar to the following text, but the file names in the error may be different:
This error message means that EasyApache was unable to locate, access, or load the file that is in the error. This following issues can cause this error:
To resolve the error message, correct all locations where the issue occurs in the Apache configuration.
The ModSecurity software firewall can cause a variety of different errors if the configuration is not correct.
For example, the following error indicates that a rule in the configuration uses a DEPRECATED ModSecurity feature.
The following error indicates that the configuration has two or more rules with the same ID:
This error indicates the following situation:
multilib) package that it cannot modify.
To correct this issue, the system administrator needs to update the
multilib package to the version that EasyApache requires. In some cases, the command
yum update will resolve the issue.
The actual error message that you receive may vary. The following is an example error message that is related to the
SymLinksIfOwnerMatch Apache option:
To resolve this issue, correct the options that are in your Apache configuration files. For more information on the syntax and options that are available for your Apache configuration, view Apache's Directive Quick Reference documentation for Apache version 2.2, or Apache's Directive Quick Reference documentation for Apache version 2.4.
This error indicates that after EasyApache completes the build process, the Apache process (
httpd) did not start correctly. This may happen if you install additional web server software, such as Litespeed. If Litespeed is the cause of the issue, the full error message will include the following output:
To resolve this issue, perform the following steps:
This error indicates that the yum repository list on your server contains a URL that does not resolve to a server correctly. If the other entries in your yum repository list work correctly, this should not cause EasyApache to fail.
To resolve the issue, correct the issues in your yum repository list. For more information on your yum repository list, read your operating system documentation.
This error indicates that your server does not have enough memory to run EasyApache. The more options that you select in EasyApache, the more memory EasyApache requires to build successfully. You must increase the available memory on the server to at least 512 MB of RAM before you run EasyApache.
This error indicates that your server was unable to unpack an RPM that EasyApache requires. The full error message may look similar to the following example:
This may be due to an issue with the package that is in the error. In some cases, the
yum update command will resolve the issue.
A disk space error indicates that your server does not have the disk space to unpack all of the packages that EasyApache requires. The specific error message you receive may vary. The following is an example of a disk space error message:
To resolve the issue, the system administrator must increase the amount of available disk space or inodes on the server.
This error indicates that the yum update system experienced an error. Many problems could cause this issue.
For example, yum may fail for any of the following reasons:
To troubleshoot this error, run the following command:
During the update process, yum checks all of your packages for issues. The error or errors that this command produces will identify the source of the problem.
The most common reason for this error is multilib problems with the