Help Center/ Huawei Cloud EulerOS/ User Guide/ Migrating an OS/ Migrating an OS to HCE 2.0/ Migrating Procedure
Updated on 2025-07-21 GMT+08:00
View PDF
Share

Migrating Procedure

Before the Migration

1. Read OS migration and change carefully and determine whether to migrate or change an OS. For details about OS change, click here.

2. Test the compatibility of your software and HCE and ensure that they are compatible with each other so that services can still run properly after the migration. The compatibility varies depending on the software version.

3. Back up the OS and data to prevent service loss due to unexpected reasons.

Preparing Dependent Packages

Prepare the software packages required by the migration tool:

  1. Remotely connect to the source OS.

    Remotely log in to the ECS to be migrated and verify that it can be accessed from the Internet. For details, see Login Overview.

  2. Check that the migration tool can access the HCE repository to obtain the dependent packages.
    The migration tool can access the HCE repository in the output of curl https://repo.huaweicloud.com/hce/2.0/os/x86_64/. If information similar to the following is displayed, the repository can be accessed: 
    % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100  3417    0  3417    0     0    373      0 --:--:--  0:00:09 --:--:--   696
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title></title>
<link rel="stylesheet"  href="/repository/static/css/style.css" type="text/css"/>
<style>
* {
font-family: 'Verdana', sans-serif;
margin: 0;
padding: 0;
-webkit-box-sizing: border-box;
-moz-box-sizing: border-box;
box-sizing: border-box;
}
......
  3. Configure the repository of the source OS and ensure that the migration tool can obtain dependent software from this repository.

    The repository address depends on the OS.

  4. Install dependent packages.
    1. Install Python software packages. 
      [root@localhost ~]#  yum install -y python //Run this command in any directory.
    2. (Optional) Create a symbolic link.

      The following steps are only available for CentOS 8 and EulerOS 2.10 and 2.9.

      1. Install Python 3.0 software packages. 
        [root@localhost ~]#  yum install -y python3 //Run this command in any directory.
      2. Check whether any Python symbolic link exists. 
        [root@localhost]# ll /usr/bin/ | grep python
        • If python -> /usr/bin/python3 is returned but python3 -> python3.9 is not, there is a Python symbolic link but it is not linked to Python 3. Run the following command to delete this link and then create a Python symbolic link: 
          [root@localhost]# unlink /usr/bin/python
        • If both python -> /usr/bin/python3 and python3 -> python3.9 are returned, you do not need to create a Python symbolic link. Go to Installing the Migration Tool and Checking Migration Conditions.
        • If neither python -> /usr/bin/python3 or python3 -> python3.9 is returned, there is no Python symbolic link. You need to create a Python symbolic link.
      3. Create a Python symbolic link. 
        [root@localhost]# python
-bash: /usr/bin/python: No such file or directory   //Indicates that the Python symbolic link does not exist.
[root@localhost]# cd /usr/bin/      //Switch to the /usr/bin directory.
[root@localhost bin]# ln -s python3 python   //Create a Python symbolic link.
[root@localhost bin]# python
Python 3.6.8 (default, Apr 16 2020, 01:36:27)
[GCC 8.3.1 20191121 (Red Hat 8.3.1-5)] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>>
//Press Ctrl+D to exit.

Installing the Migration Tool and Checking Migration Conditions

  1. Download tool package centos2hce2-*.rpm of the latest version from the Huawei Cloud open-source image site.
    • If dnf can be used in your OS (for example, CentOS 8.2), run the following command to download the latest tool package: 
      [root@localhost test]# dnf download centos2hce2 --nogpgcheck --repofrom=centos2hce2_repo,https://repo.huaweicloud.com/hce/2.0/updates/x86_64/  // Download centos2hce2-*.rpm.
[root@localhost test]#  ls  // Check whether the download is successful. The software version is an example here.
centos2hce2-1.0.0-0.0.82.hce2.x86_64.rpm
    • If only yum can be used in your OS (for example, CentOS 7.9), run the following command to download the latest tool package: 
      [root@localhost test]# echo -e "[centos2hce2]\nname=centos2hce2_repo\nbaseurl=https://repo.huaweicloud.com/hce/2.0/updates/x86_64/\nenabled=1\ngpgcheck=0" > /etc/yum.repos.d/centos2hce2.repo && yum install centos2hce2 --downloadonly --downloaddir=. && rm -f /etc/yum.repos.d/centos2hce2.repo && yum makecache  // Download centos2hce2-*.rpm.
[root@localhost test]#  ls  // Check whether the download is successful. The software version is an example here.
centos2hce2-1.0.0-0.0.82.hce2.x86_64.rpm
  2. Install the migration tool. 
    [root@localhost test]# rpm -ivh centos2hce2-1.0.0-0.0.82.hce2.x86_64.rpm --nodeps // Replace the version number with the actual one.
warning: centos2hce2-1.0.0-0.0.82.hce2.x86_64.rpm: Header V4 RSA/SHA256 Signature, key ID a8def926: NOKEY
Verifying...                          ################################# [100%]
Preparing...                          ################################# [100%]
Updating / installing...
1:centos2hce2-1.0.0-0.0.6.hce2     ################################# [100%]
  3. Configure the backup directory for the system disk of the source OS.

    Before the OS migration, the migration tool automatically backs up all data of the system software to the backup directory.

    You can run vim /etc/centos2hce2.conf to configure the backup_dir field in the centos2hce2.conf file. The default value of backup_dir is /mnt/sdb/.osbak.

    # backup dir
backup_dir = "/mnt/sdb/.osbak"  #Change the backup directory.
    • To prevent system data from being lost during the migration, configure a backup directory.
    • During OS migration, the migration tool checks the space of the backup directory. To prevent check failures caused by insufficient space, use an independent data disk (for example, /dev/sdb/ mounted to /mnt/sdb/) as the backup directory.
    • Do not use the tmpfs file system (such as /dev and /run) as the backup directory. If such a tmpfs file system is used as the backup directory, files in the file system will be lost after the system is restarted.
  4. Configure the migration parameters.
    1. Set Web migration.

      To perform a Web migration, the system needs to download the RPM package. The network cannot be disconnected during the download.

      In the centos2hce2.conf configuration file, configure the parameters by referring to the parameter descriptions.

      [repo_relation]
.....
# default yum source, val: web or iso
default_yum_source = 'web'
.....
# if web as source, web link config as follow
web_link_dir = "https://repo.huaweicloud.com/hce/2.0/os/x86_64/;https://repo.huaweicloud.com/hce/2.0/updates/x86_64/"
      Table 1 Parameter settings for a Web migration

      Parameter

      Description

      default_yum_source

      Set this parameter to web.

      web_link_dir

      Specifies the addresses of base repository and updates repository for HCE. Separate multiple repositories with semicolons (;).

      This is an example: https://repo.huaweicloud.com/hce/2.0/os/x86_64/;https://repo.huaweicloud.com/hce/2.0/updates/x86_64/.

      The HCE repository will automatically replace the repository of the original OS during the migration. After the migration is complete, the original repository will be restored. So, both the new and old repository files will exist in the system. You are advised to delete the old ones from the /etc/yum.repos.d/ directory and retain only those of HCE.
    2. Configure the isclose_modules parameter, which is required only for CentOS 8.

      CentOS 8 allows you to batch install RPM packages as a module, but HCE does not. Therefore, you need to disable the module function before performing an OS migration.

      • yes (default): The system disables its modules before the migration.
      • no: The system does not disable its modules before the migration. If any module is enabled, the migration is interrupted.
      [system]
# whether close modules, if value is no, system may be not migrate
isclose_modules = "yes"
      • You can run dnf module list to view all running modules.
      • You can run dnf module list | grep '\[e\]' to view enabled modules.
  5. Run centos2hce2.py --check all to check whether the current OS can be migrated.
    • If the message "Environment check passed!" is displayed, continue with the migration.
    • If the message "call migration failed" is displayed, perform step 6 to handle the exceptions. Table 2 provides the error numbers and the corresponding error messages.
      Table 2 Error numbers

      Error Number

      Message

      10001

      When running migration tool commands as a non-root user, you need to switch to user root.

      10002

      The URL is invalid. The web_link_dir and web_link_tar parameters in the /etc/centos2hce2.conf configuration file are configured incorrectly. As a result, the corresponding repo and RPM files cannot be downloaded or connected.

      10003

      Basic commands, such as rpm, yum, and yumdownloader, are missing.

      10004

      The space check failed. The disk space or memory size is insufficient.

      10005

      The source OS does not have a local yum repository or the yum repository is unreachable. You need to reconfigure the yum repository.

      10006

      The yum source configuration of the source OS is incorrect. Check the web_link_dir parameter in the /etc/centos2hce2.conf configuration file.

      10007

      The sut installation failed. Check the web_link_dir parameter in the /etc/centos2hce2.conf configuration file.

      10008

      The sut check failed.

      10009

      The dependency check failed. Run the centos2hce2.py --install all command to install the dependencies.

      10010

      In chroot upgrade, clearing the existing chroot directory failed. Check the chroot_path parameter in the /etc/centos2hce2.conf configuration file.

      10011

      The chroot path is configured incorrectly. Check the chroot_path parameter in the /etc/centos2hce2.conf configuration file.

      10012

      In chroot upgrade where the address for downloading the TAR package in the pre-built environment is configured, decompressing the TAR package failed. Check the web_link_tar parameter in the /etc/centos2hce2.conf configuration file.

      10013

      Checking the /etc/ld.so.conf file failed. Clear the parameters other than include ld.so.conf.d/*.conf in the /etc/ld.so.conf configuration file.

      10014

      The file system is damaged or abnormal and needs to be repaired.

      10015

      The mount directory of the /etc/fstab file does not meet the requirements. You need to mount the file system partitions that are not in the LVM volume format in the /etc/fstab file using UUIDs.

      10016

      After the file attribute check is enabled, files with the Immutable/Append_Only attribute exist in the system. Such files must be added to the exclude_dir parameter in the /etc/centos2hce2.conf configuration file.

      10017

      The /etc/sysconfig/ntpd file contains the -u ntp:ntp configuration. You need to delete the -u ntp:ntp parameter from the /etc/sysconfig/ntpd file.

      10018

      The /etc/ssh/sshd_config configuration file contains algorithms that are not supported by HCE 2.0. Delete these algorithms as prompted.

      10019

      There are duplicate RPM packages in the system. Uninstall the RPM packages of earlier versions that are no longer used and check again. (If you do not want to uninstall duplicate packages, such as kernel and kernel-devel in multi-kernel scenarios, you can set extra_check_switch to false in the /etc/centos2hce2.conf file to skip extra check.)
  6. Install software dependencies for the migration tool.

    Run centos2hce2.py --install all to back up data in the system, install software dependencies, and complete preprocessing.

    If the following information is displayed, the software dependencies have been installed and preprocessing has been completed. You need to perform step 5 again to check the environment.

    2022-08-19 03:12:58,373-INFO-centos2hce2.py-[line:832]: Dependency packages already exist!
2022-08-19 03:12:58,373-INFO-centos2hce2.py-[line:891]: migrate install depend options finished

    Modify the centos2hce2.conf file as follows:

    [check_config]
...
# backup switch before upgrade
backup_avaliable = ""

    backup_avaliable determines whether to perform backup in the installation phase. The default value is an empty string.

    • If backup_avaliable is true or the default value is used, backup will be performed in the installation phase.
    • If backup_avaliable is false, backup will not be performed in the installation phase but performed in the upgrade phase.
    • For CentOS 8.0 or later, centos2hce2.py --install all will back up data and then disable the package management system of CentOS. If you set backup_avaliable to true, the package management system will still be in the disabled state after a rollback to the original OS.
  7. (Optional) Repeat the backup.

Run centos2hce2.py --backup force to back up the files in the system to the directory configured in step 3.

The software dependencies installed in step 6 will also be backed up after this command is executed.

Migrating an OS to HCE

  1. Run centos2hce2.py --upgrade all to migrate an OS to HCE.

    If migrate success is displayed, the OS migration is successful. If the migration fails, perform a rollback by referring to 1.

    Figure 1 Migrating an OS
    Figure 2 Migration succeeded
    • The migration command cannot be executed in the background in Linux.
    • The --simple_name parameter can be added so that the abbreviation of Huawei Cloud EulerOS is displayed in the grub menu after the migration.
    • If an upgrade failed due to network interruption or software package conflicts, run the migration command again.
    • If the error message in Figure 3 is displayed during an upgrade, the upgrade is interrupted due to package conflicts. Handle the conflicts and try the upgrade again. For details about how to handle package conflicts, see Conflicting Packages.
    Figure 3 An error reported when there is a conflict packet
  2. Reboot the server by running reboot. If the reboot command does not respond, run reboot -f instead.

    After the system reboot, run cat /etc/hce-release to view the OS information and run uname -a to view the OS kernel information.

    If Huawei Cloud EulerOS is displayed, the OS migration is successful. Otherwise, the migration failed. Contact technical support.

    Figure 4 Checking the OS and kernel after the migration

    After the OS is migrated to HCE, the name of the original OS is still displayed on the console.

  3. Delete the files of the source OS's components.

    After the OS migration, the target OS's components replace the source OS's components. However, the files of the source OS's components are still stored in the system. You need to run centos2hce2.py --precommit upgrade to delete such files.

    If the message "upgrade precommit success" is displayed, the files have been successfully deleted.

    Figure 5 Deleting component files of the source OS

    The deletion can be performed for multiple times.

  4. (Optional) Modify Cloud-Init configurations.
    • Skip this step if Cloud-Init is running normally in the source OS and Cloud-Init is an RPM package.
    • If Cloud-Init is running normally in the source OS and Cloud-Init is a file (for example, a CentOS 7 file) other than an RPM package, modify /etc/cloud/cloud.cfg as follows:
    1. Enable remote login using the password for user root and allow SSH access to root.

      Set disable_root to 0 to keep root enabled. Set ssh_pwauth to 1 to allow remote login using a password. Set lock_passwd to False to not lock the password.

      users:
 - name: root
   lock_passwd: False

disable_root: 0
ssh_pwauth: 1
    2. Run /usr/bin/cloud-init init --local.
      If there are no errors and the Cloud-Init version is displayed, Cloud-Init has been correctly configured.
      Figure 6 Cloud-Init configured successfully
    3. If Cloud-Init is unavailable after the upgrade, reinstall Cloud-Init. For details, see Installing Cloud-Init.
  5. (Optional) If SELinux service is disabled during the migration but needs to be enabled after the migration, run centos2hce2.py --precommit upg-selinux to enable the SELinux service. This command is executed twice. After each execution, the system restarts.
    1. Run centos2hce2.py --precommit upg-selinux. 
      [root@localhost ~]# centos2hce2.py --precommit upg-selinux
2022-08-21 23:46:23,891-INFO-centos2hce2.py-[line:1239]: precommit migration
2022-08-21 23:46:23,891-INFO-centos2hce2.py-[line:1149]: begin to set selinux
2022-08-21 23:46:23,892-INFO-centos2hce2.py-[line:1157]: grub path is /boot/grub2/grub.cfg
2022-08-21 23:46:23,895-INFO-centos2hce2.py-[line:1162]: sed selinux succeed
2022-08-21 23:46:23,897-INFO-centos2hce2.py-[line:1167]: create autorelabel file succeed
2022-08-21 23:46:23,901-INFO-centos2hce2.py-[line:1172]: modify selinux config succeed
2022-08-21 23:46:23,901-INFO-centos2hce2.py-[line:1174]: create phase 1 flag file succeed
2022-08-21 23:46:23,901-INFO-centos2hce2.py-[line:1184]: selinux has been set, please reboot now
2022-08-21 23:46:23,901-INFO-centos2hce2.py-[line:1206]: upgrade precommit selinux success
[root@localhost ~]# reboot
    2. After the system is restarted, run centos2hce2.py --precommit upg-selinux again. 
      [root@localhost ~]# centos2hce2.py --precommit upg-selinux
2022-08-21 23:57:07,576-INFO-centos2hce2.py-[line:1239]: precommit migration
2022-08-21 23:57:07,576-INFO-centos2hce2.py-[line:1176]: now begin to set selinux phase 2
2022-08-21 23:57:07,580-INFO-centos2hce2.py-[line:1181]: modify selinux config succeed
2022-08-21 23:57:07,580-INFO-centos2hce2.py-[line:1183]: create phase 2 flag file succeed
2022-08-21 23:57:07,580-INFO-centos2hce2.py-[line:1184]: selinux has been set, please reboot now
2022-08-21 23:57:07,580-INFO-centos2hce2.py-[line:1206]: upgrade precommit selinux success
[root@localhost ~]# reboot
    3. After the second restart, run getenforce to check the SELinux status. If it is Enforcing, SELinux has been enabled. 
      [root@localhost ~]# getenforce
Enforcing
  6. (Optional) After the migration is complete, delete the source OS data.

    After the migration, the system data of the source OS is still stored in the new system and occupies a large amount of memory. You can run centos2hce2.py --commit all to clear the data.

    The system will automatically delete the system data of the source OS, including the system data in the backup directory mentioned in step 3.

    After the command is executed, the OS cannot be rolled back.

    [root@localhost ~]# centos2hce2.py --commit all
2022-08-22 04:45:32,601-INFO-centos2hce2.py-[line:1242]: commit migration

Rolling Back the OS

  1. Roll back the OS if needed.
    The migration can be rolled back. You can determine whether to roll back to the original OS as required.
    1. Run centos2hce2.py --rollback all to roll back the system. After the rollback, run reboot to restart the system.
      Figure 7 System rollback and restart
    2. Run centos2hce2.py --precommit rollback to restore the environment.
      Figure 8 Environment restoration
  2. (Optional) If SELinux has been enabled before the migration, the SELinux service will be automatically disabled during the migration. If necessary, manually enable the SELinux status after the rollback.
    1. Run centos2hce2.py --precommit rbk-selinux. 
      [root@localhost ~]# centos2hce2.py --precommit rbk-selinux
2022-09-05 03:58:37,015-INFO-centos2hce2.py-[line:1401]: precommit migration
2022-09-05 03:58:37,047-INFO-centos2hce2.py-[line:1319]: now begin to set selinux
2022-09-05 03:58:37,051-INFO-centos2hce2.py-[line:1324]: modify selinux config succeed
2022-09-05 03:58:37,051-INFO-centos2hce2.py-[line:1325]: selinux has been set, please reboot now
2022-09-05 03:58:37,051-INFO-centos2hce2.py-[line:1340]: set rollback selinux succeed
2022-09-05 03:58:37,051-INFO-centos2hce2.py-[line:1365]: upgrade precommit selinux success
    2. Run reboot to restart the system. 
      [root@localhost ~]# reboot
    3. After the system is restarted, you can see that SELinux is enabled. 
      [root@localhost ~]# getenforce
Enforcing
  3. Clear data from the OS.

    Run centos2hce2.py --commit all to clear the data.

    The system will automatically delete the system data of the source and target OSs, including the system data in the backup directory mentioned in step 3.

    [root@localhost ~]# centos2hce2.py --commit all
2022-08-22 04:45:32,601-INFO-centos2hce2.py-[line:1242]: commit migration