The EasyApache 3 to EasyApache 4 Migration Process

Last modified: January 19, 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.

Note:

This document is not comprehensive. It only provides an overview of the changes that the migration script attempts.

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.

Warning:

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.

Warning:

The system does not convert custom modules or any EasyApache 3 customizations handled by pre or post scripts.

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.

Note:

In the following examples, 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.

Important:

The system does not migrate include files with names that include an underscore (_) number .conf naming convention. For example, a file named post_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 configured suPHP_ConfigPath directive.
The suPHP_ConfigPath directory must contain a php.ini file.
The php.ini file specified in the suPHP_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.