The EasyApache 3 to EasyApache 4 Migration Process
Last modified: July 11, 2022
Overview
This document lists the changes that EasyApache 4 makes to your system when you migrate from EasyApache 3, as well as any necessary manual changes. For more information, read our Current Status of EasyApache 4 documentation.
Initial actions
In cPanel & WHM version 60 and higher, the script performs a preflight check to confirm that the system configuration will properly migrate.
When you run the migration script, it checks to ensure the availability of your system’s current version of PHP. If EasyApache 4 does not support the system’s current PHP version, the script issues a warning and prompts you to confirm that you want to continue the migration.
- If your system uses a version of PHP that EasyApache 4 does not support, websites that depend on that version of PHP may no longer function.
- If your system runs CloudLinux™ and you experience difficulty with the conversion, you may need to run the CloudLinux conversion script to migrate your system.
Profile changes
The script attempts to convert the currently installed EasyApache 3 profile, /var/cpanel/easy/apache/profile/_main.yaml
, into an EasyApache 4 profile. It copies the profile to the following location:
/etc/cpanel/ea4/profiles/custom/ea3_state_at_migration-$time.json
If the profile converts successfully, the system installs the converted EasyApache 3 profile. If it does not convert successfully, the system installs the cPanel Default profile, located in the /etc/cpanel/ea4/profiles/cpanel/default.json
file.
RPM changes
The script automatically removes the following RPMs from your system, if they exist:
httpd
httpd-tools
php-cli
The script installs the following required EasyApache 4 RPMs:
yum-plugin-tsflags
yum-plugin-universal-hooks
ea-profiles-cpanel
ea-cpanel-tools
The script attempts to match your EasyApache 3 modules to the EasyApache 4 RPMs. If the script cannot match a module with an RPM, the script pauses and prompts you to either continue or abort the conversion. Some modules are not compatible with EasyApache 4.
Apache changes
EasyApache 4 only supports Apache 2.4. Any profile that contains an older version of Apache will require an upgraded version of Apache.
The script backs up your /usr/local/apache
directory to the /usr/local/apache.ea3
directory.
Post-migration changes
After your system successfully builds EasyApache 4, the system moves the data from the /usr/local/apache.ea3/conf/userdata/
directory to the /etc/apache2/conf.d/userdata/
directory.
user
represents a user name and domain
represents a domain name.
The data structure remains the same in the new directory. For example, the /usr/local/apache/conf/userdata/ssl/2_4/user/domain
directory will move to the /etc/apache2/conf.d/userdata/ssl/2_4/user/domain
directory.
The following exceptions exist:
- If a directory that specifies the current EasyApache 3 Apache version does not exist, but the
/usr/local/apache.ea3 /conf/userdata/std/2/
directory exists, the system moves and uses that directory instead. - If a directory that specifies the current EasyApache 3 Apache version does not exist, but the
/usr/local/apache.ea3 /conf/userdata/ssl/2/
directory exists, the system moves and uses that directory instead. - If the system has not previously migrated the
cp_bw_all_limit.conf
file, the system moves the following files:- The
/usr/local/apache.ea3/conf/userdata/std/2/user/domain/cp_bw_all_limit.conf
file moves to the/etc/apache2/conf.d/userdata/std/user/domain/cp_bw_all_limit.conf
file. - The
/usr/local/apache.ea3/conf/userdata/ssl/2/user/domain/cp_bw_all_limit.conf
file moves to the/etc/apache2/conf.d/userdata/ssl/user/domain/cp_bw_all_limit.conf
file.
- The
- The system does not migrate include files with names that include an underscore (
_
) number.conf
naming convention. For example, a file namedpost_virtualhost_1.conf
will not migrate. - The system checks the syntax of each file for EasyApache 4 compatibility after it moves it. If the file is not compatible, then the system deletes it from the EasyApache 4 destination directory and continues the move process.
For more information, read our Modify Apache Virtual Hosts with Include Files documentation.
PHP changes
With the introduction of MultiPHP, we made significant changes in how the system handles your PHP files.
Default charset
In PHP 5.6 and above, PHP’s default charset changed to UTF-8
. This may break the encoding on some websites. For more information, read PHP’s documentation.
SuPHP and migration to EasyApache 4
In cPanel & WHM version 60 and above, EasyApache 4 attempts to migrate the php.ini
files on the system to an EasyApache 4 compatible format. In order for a user’s php.ini
file to migrate successfully, all of the following must be true:
- The system is attempting to migrate from EasyApache 3 to EasyApache 4.
- The system’s default PHP version must use the suPHP handler.
- One or more
.htaccess
files must exist in the user’s home directory. - Each
.htaccess
file must contain a properly configuredsuPHP_ConfigPath
directive. - The
suPHP_ConfigPath
directory must contain aphp.ini
file. - The
php.ini
file specified in thesuPHP_ConfigPath
directive must exist in the user’s home directory.
If the migration completes successfully, the system renames the original php.ini
file to php.ini.ea3.bak
. Comments in the original php.ini
file are not retained in the converted file.