Long-Term Supported Versions

    2openEuler Failed to Upgrade the OS


    After the upgrade is complete, the OS cannot be accessed and the source OS cannot be restored through a rollback. In this case, you can use an ISO image to enter the rescue mode.

    Handling Procedure

    The x86_64 OS is used as an example.

    1. Obtain the standard ISO image. (For example, openEuler-20.03-LTS-SP1-everthing-x86_64-dvd.iso).

    2. Mount the ISO image to the CD-ROM drive, restart the machine, and boot the machine from the CD-ROM drive.

    3. Enter the rescue mode from the GRUB menu.

      • UEFI boot

        1. Select Troubleshooting.

          Figure 1 UEFI GRUB menu

        2. Select Rescue a openEuler system.

          Figure 2 Selecting rescue mode

      • Legacy boot

        1. Select Troubleshooting.

          Figure 3 Legacy GRUB menu

        2. Select Rescue a openEuler system.

          Figure 4 Selecting rescue mode

    4. After entering the rescue mode, press 1 to select Continue.

      Figure 5 Rescue mode

      Press Enter. The Rescue Shell is opened.

      Figure 6 Rescue Shell

    5. Run the following command to check whether the x2openEuler-upgrade software package exists in the current environment. If yes, go to 7

      find / -name x2openEuler-upgrade

      Figure 7 Checking the x2openEuler-upgrade software package

    6. Configure an available IP address for the current environment.

      Figure 8 Configuring an available IP address

    7. Run the following commands to enable the SSH service and upload the x2openEuler-upgrade software package to the /root directory:

      mv /etc/ssh/sshd_config.anaconda /etc/ssh/sshd_config
      systemctl restart sshd
      scp root@xxx.xxx.xxx.xxx:/xxx/x2oepnEuler-upgrade* /root/ 

      Figure 9 Enabling the SSH service

      Figure 10 Uploading the x2openEuler software package to the /root directory

    8. Run the following commands to install the x2openEuler-upgrade software package:

      ln -s /usr/bin/python3 /usr/bin/python
      rpm -ivh /root/x2openEuler-upgrade-* --nodeps
      source /root/.bashrc

      Figure 11 Installing the x2openEuler-upgrade software package

    9. Run the following command to modify the x2openEuler-upgrade configuration file so that the /run/install directory will not be rolled back:

      vim /mnt/sysroot/etc/sut/sut.conf 

      Figure 12 Modifying the x2openEuler-upgrade configuration file

    10. Run the following command to rescue the OS:

      x2openEuler rescue -p /mnt/sysroot/

      Figure 13 OS rescue

    11. After the OS rescue is complete, run the following command to restart the system:


      After the system is restarted, SELinux performs the relabel operation, which may take a long time on a physical machine. After the relabel operation is complete, the system automatically restarts. Then, the rollback to the source OS is completely finished.

    12. Run the following command to verify the rescue:

      cat /etc/os-release

      Figure 14 Rescue verification


      • After the rescue is complete, you can run a command of the source OS for verification.
      • You can restore services or adapt scripts based on service requirements.

    Some Commands Cannot Be Executed After the Upgrade


    After the upgrade is complete, some commands of the target OS cannot be executed properly. An error message is displayed, indicating that a symbolic link is not found.

    Possible Causes

    If the dynamic dependency library of a later version is configured before the upgrade, conflicts will occur after the upgrade.

    Handling Procedure

    Check whether the /etc/ld.so.conf.d directory contains configurations that conflict with the .so files in the OS directories.

    Upgrade Failed Due to DNF Upgrade Errors


    The upgrade failed. The logs show that errors are reported during software upgrade using DNF.

    Possible Causes

    Check the repository configuration and the number of software packages to be upgraded. In normal cases, 90% of the software packages can be upgraded. If the number of software packages to be upgraded is small, check whether the configured repositories are correct and complete.

    Handling Procedure

    Configure the everything, epol, and update repositories completely.

    Upgrade Takes Too Long


    The upgrade from the source OS to the target OS takes too long.

    Possible Causes

    Big files exist in the backup sources.

    Handling Procedure

    1. Run the following command to query the file systems of the node to be upgraded. Check whether big files exist in the backup sources.

      df -h
    2. If necessary, add some of the directories to excluded directories.

    GRUB2 Version Does Not Meet the Requirements


    The pre-upgrade check report shows that the GRUB2 version does not meet requirements.

    Handling Procedure

    If the target OS is openEuler 20.03 LTS SP1, mount the update repository.

    An Error Is Reported during the Pre-upgrade Check


    The following error is reported during the pre-upgrade check:

    Abnormal exit,error:/etc/x2openEuler/database_2.0.0.630/centos7.4/x86_64/primary not exist

    Handling Procedure

    1. Visit OEPKGS and obtain the database support packages of the corresponding OS version based on the error information. For example, if the database support package of CentOS 7.4 does not exist, you need to install x2openEuler-database-centos7.4- and x2openEuler-database-centos7.4-openEuler20.03-LTS-SP1-

    2. Upload the obtained database support packages to the environment where x2openEuler is deployed and use an SSH remote management tool to log in to the environment.

    3. Run the following commands to install the software packages. CentOS 7.4 is used as an example.

      rpm -ivh x2openEuler-database-centos7.4-
      rpm -ivh x2openEuler-database-centos7.4-openEuler20.03-LTS-SP1-
    4. Go to the upgrade task and start the pre-upgrade check again.

    QEMU-Related Issues

    Symptom 1

    qemu-kvm is uninstalled after the OS is upgraded.

    Handling Procedure

    Run the following command to install QEMU and start a VM again:

    yum install qemu

    Symptom 2

    After the system is upgraded and QEMU is installed, the following error message is displayed when a VM is started:

    Process exited prior to exec: libvirt: QEMU Driver error : Unable to get devmapper targets for /data1/var/lib/scevm/instances/xxxxxxx/disk.qcow2: Success

    Handling Procedure

    The fault occurs because dm_mod.ko is not loaded on the host. You can run the modprobe dm_mod command to rectify the fault.

    modprobe dm_mod

    Symptom 3

    After the upgrade is complete and a VM is started, a message is displayed indicating that machine does not match.

    Handling Procedure

    After the upgrade, the machine does not match. Run the following command to query the machine types supported by openEuler:

    qemu-kvm -machine help

    Change the value of the machine parameter of the VM to a value supported by openEuler and start the VM again:

    virsh edit

    Web Service of x2openEuler Failed to Be Started with a Message "MariaDB Is Not Installed"


    MariaDB has been built and installed from source code before x2openEuler is installed. After x2openEuler is installed, the following information is displayed when you start the web service of x2openEuler:

    Figure 15 Output information when the web service is started

    Possible Causes

    x2openEuler cannot connect to MariaDB through mysql.sock.

    Handling Procedure

    1. Run the following command to query the MariaDB process ID (PID):

      ps -ef | grep mariadb

      After obtaining the PID, run the following command to stop the process:

      kill -9 PID
    2. Comment out the socket parameter in the /etc/my.cnf file.

      1. Run the following command to open the my.cnf file and press i to enter the insert mode:

        vi /etc/my.cnf
      2. Comment out the socket parameter in the [mysqld] section.

        # socket=/var/lib/mysql/mysql.sock
      3. Press Esc, type :wq, and press Enter to save the change and exit.

    3. Run the following command to restart the MariaDB service:

      systemctl start mariadb.service
    4. Restart the web service of x2openEuler.

    Bug Catching

    Buggy Content

    Bug Description

    Submit As Issue

    It's a little complicated....

    I'd like to ask someone.


    Just a small problem.

    I can fix it online!

    Bug Type
    Specifications and Common Mistakes

    ● Misspellings or punctuation mistakes;

    ● Incorrect links, empty cells, or wrong formats;

    ● Chinese characters in English context;

    ● Minor inconsistencies between the UI and descriptions;

    ● Low writing fluency that does not affect understanding;

    ● Incorrect version numbers, including software package names and version numbers on the UI.


    ● Incorrect or missing key steps;

    ● Missing prerequisites or precautions;

    ● Ambiguous figures, tables, or texts;

    ● Unclear logic, such as missing classifications, items, and steps.


    ● Technical principles, function descriptions, or specifications inconsistent with those of the software;

    ● Incorrect schematic or architecture diagrams;

    ● Incorrect commands or command parameters;

    ● Incorrect code;

    ● Commands inconsistent with the functions;

    ● Wrong screenshots.

    Risk Warnings

    ● Lack of risk warnings for operations that may damage the system or important data.

    Content Compliance

    ● Contents that may violate applicable laws and regulations or geo-cultural context-sensitive words and expressions;

    ● Copyright infringement.

    How satisfied are you with this document

    Not satisfied at all
    Very satisfied
    Click to create an issue. An issue template will be automatically generated based on your feedback.
    Bug Catching
    编组 3备份