Environment Requirements

OS Requirements

• Table 1 describes the x2openEuler WebUI deployment requirements.

  Table 1 OS requirements

  Deployment Environment	Description
  CentOS 7.6 or openEuler 20.03-LTS-SPx	The node must be connected to the internal network where the node to be upgraded is located. The OS software packages must be updated to the latest version. Security policies must be set on the OS firewall. It is recommended that the deployment environment be a non-production environment. The OS password must comply with the password complexity requirements and be updated periodically.

• x2openEuler CLI deployment requirements (The CLI is automatically deployed with the WebUI.)

  NOTE
  The environment to be upgraded must be compatible with openEuler 20.03 LTS SP1.

• Table 2 describes the OS requirements of the node to be upgraded.

  Table 2 OS requirements

  OS to Be Upgraded	Target OS
  CentOS 7.x	openEuler 20.03-LTS-SPx
  	openEuler 22.03-LTS
  CentOS 8.x	openEuler 22.03-LTS

  NOTE
  By default, x2openEuler upgrades CentOS 7.6 to openEuler 20.03 LTS SP1. You can install OS database support packages to support more OSs

Hardware Requirements

Table 3 lists the hardware requirements for deploying the x2openEuler WebUI.

Table 3 Hardware requirements

NOTE
There are no special hardware requirements for the node to be upgraded. However, the available memory of the node must be greater than or equal to 2 GB. Otherwise, the upgrade will fail due to insufficient memory.

Obtaining the Software Package

Table 4 lists the required software package.

Table 4 Software package

NOTE

• 软件包名称中的“x.x.x”表示版本号。
• 软件包中包含有针对待升级节点的分析工具接口。

Verifying the Digital Signature

To prevent a software package from being maliciously tampered with during transfer or storage, download also the corresponding digital signature file for integrity verification while downloading the software package.

After the software package is downloaded from the community website, verify its PGP digital signature. For details, see the OpenPGP Signature Verification Guide. If the verification fails, do not use the software package. Obtain the software package from the community website again.

The verification is also required before the installation or update of the software package.

For carrier customers, visit PGP Verify.

For enterprise customers, visit PGP Verify.

Installing x2openEuler

Prerequisites

• You have obtained the x2openEuler software package.
• An SSH remote login tool, such as Xshell, MobaXterm, or PuTTY, has been installed.
• The sftp tool has been installed.
• The environment to be upgraded can access the locally configured CentOS Yum repository through the network.
• The port used by x2openEuler has been enabled in the x2openEuler installation environment.

Procedure

1. The following describes how to install x2openEuler in the x86 environment. Use the sftp tool to upload the x2openEuler software package x2openEuler-core-x.x.x-xx.x86_64.rpm to the /root directory on the remote server.

2. Use the SSH remote management tool to log in to the CLI of the remote server.

3. (Optional) If the firewall of the server OS is enabled, perform the following operations to enable the port on the firewall. (If the firewall of the server OS is disabled, skip this step.)

   NOTE

   • Port 18082 in the following commands is the default HTTPS port number for the web service. Change it as required.
   • If the hardware firewall is enabled, contact the network administrator to configure the hardware firewall and enable the ports that will be accessed.

   1. Check whether the firewall is enabled.

      systemctl status firewalld
      

      If the firewall status is inactive, the firewall is not enabled. Skip the following steps in this case.

   2. Check whether the port is enabled.

      firewall-cmd --query-port=18082/tcp
      

      If "no" is displayed, the port is not enabled.

   3. Enable the port permanently.

      firewall-cmd --add-port=18082/tcp --permanent
      

      If "success" is displayed, the port is enabled successfully.

   4. Reload the configuration.

      firewall-cmd --reload
      

   5. Check whether the port is enabled.

      firewall-cmd --query-port=18082/tcp
      

      If "yes" is displayed, the port is enabled.

      NOTE
      To remove a port, run the following command:

      firewall-cmd --permanent --remove-port=18082/tcp
      

      If "success" is displayed, the port is successfully removed. After the port is removed, run the following command to reload the configuration:

      firewall-cmd --reload
      

4. Install x2openEuler.

   yum install -y /root/x2openEuler-core-x.x.x-xx.x86_64.rpm
   

5. After the software package is successfully installed, run the following commands to start the web service:

   NOTE

   • If the web service cannot run properly due to the SELinux policy, modify the SELinux policy or perform Disabling SELinux.
   • For details about how to stop or restart the web service, see Starting, Stopping, or Restarting the x2openEuler Service.
   • When starting the service for the first time, you need to configure the password of the MariaDB user. The password must meet the following complexity requirements:
     • Contain 8 to 32 characters.
     • Contain at least two types of the uppercase letters, lowercase letters, digits, and special characters (`~!@#$%^&*()-_=+|[{}];:'",<.>/?).
     • Cannot contain any space.
     • Cannot be the same as the user name.
     • Cannot be a password in the weak password dictionary.
   • You are advised to periodically change the password of the database user x2openEuler to ensure secure service running.
   • If a local MariaDB database exists, you are advised to update MariaDB to the latest version and disable remote access to the database.

   cd /usr/local/x2openEuler/portal/service
   bash service_init.sh
   

   Complete the service startup configuration based on the command output.

   1. Configure the database.

      Start MariaDB customize configure
      MariaDB is active.
      
      NOTE: RUNNING ALL PARTS OF THIS SCRIPT IS RECOMMENDED FOR ALL MariaDB
            SERVERS IN PRODUCTION USE!  PLEASE READ EACH STEP CAREFULLY!
      
      In order to log into MariaDB to secure it, we'll need the current
      password for the root user.  If you've just installed MariaDB, and
      you haven't set the root password yet, the password will be blank,
      so you should just press enter here.
      
      Enter current password for root (enter for none):
      OK, successfully used password, moving on...
      
      Setting the root password ensures that nobody can log into the MariaDB
      root user without the proper authorisation.
      
      You already have a root password set, so you can safely answer 'n'.
      
      Change the root password? [Y/n] n
       ... skipping.
      
      By default, a MariaDB installation has an anonymous user, allowing anyone
      to log into MariaDB without having to have a user account created for
      them.  This is intended only for testing, and to make the installation
      go a bit smoother.  You should remove them before moving into a
      production environment.
      
      Remove anonymous users? [Y/n] y
       ... Success!
      
      Normally, root should only be allowed to connect from 'localhost'.  This
      ensures that someone cannot guess at the root password from the network.
      
      Disallow root login remotely? [Y/n] y
       ... Success!
      
      By default, MariaDB comes with a database named 'test' that anyone can
      access.  This is also intended only for testing, and should be removed
      before moving into a production environment.
      
      Remove test database and access to it? [Y/n] y
       - Dropping test database...
       ... Success!
       - Removing privileges on test database...
       ... Success!
      
      Reloading the privilege tables will ensure that all changes made so far
      will take effect immediately.
      
      Reload privilege tables now? [Y/n] y
       ... Success!
      
      Cleaning up...
      
      All done!  If you've completed all of the above steps, your MariaDB
      installation should now be secure.
      
      Thanks for using MariaDB!
      

   2. Configure the x2openEuler service.

      • Set the password for the database user x2openEuler.
      • Configure whether to enable SSH authentication.
      • Set the web server IP address.
      • Set the HTTPS port number, which is 18082 by default.
      • Set the Gunicorn port number, which is 18080 by default

      Enter the password of the root user of the MariaDB again:
      Set the password of the x2openEuler user for MariaDB:
      If the selected database already exists, it will be overwritten.
      Use default x2openEulerDb database? [Y/n]y
      MariaDB is configured successfully.
      
      If authentication is enabled, the SSH connection fails after the fingerprint of the machine changes.
      Please confirm whether public key authentication is not required for SSH connection(y/n default: n):
      Use default x2openEuler database? [Y/n]y
      MariaDB is configured successfully.
      If authentication is enabled, the SSH connection fails after the fingerprint of the machine changes.
      Please confirm whether public key authentication is not required for SSH connection(y/n default: n):y
      Start Nginx service and Gunicorn service
      Ip address list:
      sequence_number         ip_address              device
      [1]                     x.x.x.x                 enp1s0
      Enter the sequence number of listed ip as web server ip(default: 1): 1
      Set the web server IP address x.x.x.x
      Please enter HTTPS port(default: 18082):
      The HTTPS port 18082 is valid.  Set the HTTPS port to 18082 (y/n default: y):
      Set the HTTPS port 18082
      Please enter gunicorn port(default: 18080):
      The GUNICORN port 18080 is valid.  Set the GUNICORN port to 18080 (y/n default: y):
      Set the GUNICORN port 18080
      The Nginx and Gunicorn ports are set up successfully.
      Installing the django dependent environment.
      The django dependency environment is installed successfully.
      Generating the Django secret key.
      Generate the Django secret key successfully.
      Migrations for 'certificatemanager':
        /usr/local/x2openEuler/portal/src/certificatemanager/migrations/0001_initial.py
          - Create model CertificateInfo
          - Create model CertPathConfig
          - Create model ScheduleTask
      Migrations for 'config':
        /usr/local/x2openEuler/portal/src/config/migrations/0001_initial.py
          - Create model RollbackFilterConfig
          - Create model UserConfig
      ...
      Running migrations:
        Applying contenttypes.0001_initial... OK
        Applying contenttypes.0002_remove_content_type_name... OK
        Applying auth.0001_initial... OK
        Applying auth.0002_alter_permission_name_max_length... OK
        Applying auth.0003_alter_user_email_max_length... OK
      ...
      Installed 1 object(s) from 1 fixture(s)
      Installed 1 object(s) from 1 fixture(s)
      Installed 13 object(s) from 1 fixture(s)
      Installed 52 object(s) from 1 fixture(s)
      Installed 2 object(s) from 1 fixture(s)
      Encrypting phase successfully.
      It may take a few minutes to generate the certificate, please wait...
      Certificate generated successfully. You can import the root certificate to the browser to mask security alarms when you access the tool. The root certificate is stored in /usr/local/x2openEuler/portal/thirdapp/nginx-install/webui/ca.crt.
      Web console is now running, go to: https://x.x.x.x:18082/x2openEuler/#/login
      

Verifying the Installation

Verifying the Installation Through the WebUI

Log in to the x2openEuler WebUI. For details, see Logging In to the x2openEuler WebUI. If the login is successful, x2openEuler is installed successfully.

Verifying the Installation Through the CLI

1. Use an SSH tool to remotely log in to the CLI of the node to be upgraded.

2. Query the x2openEuler version.

   rpm -qa x2openEuler-core
   

   If the following information is displayed, the installation is successful. In the information, x.x.x-x indicates the version.

   x2openEuler-core-x.x.x-x.x86_64
   

Upgrading and Rolling Back

Upgrading x2openEuler

Version Support

Currently, x2openEuler 3.0.RC1 can be upgraded to later versions.

Prerequisites

• You have downloaded the x2openEuler software package of the target version to the local PC and confirmed that the target version is compatible with the server hardware platform.

  You have verified that the software package is consistent with that on the website. For details, see Verifying the Digital Signature.

• x2openEuler can be used properly. Unfinished tasks have been initialized using the WebUI.

• The x2openEuler installation directory (/usr/local/x2openEuler by default) has sufficient free space.

• For versions earlier than 3.0.RC1, upgrade them to 3.0.RC1 by following the instructions provided in Upgrading x2openEuler Using a Script.

Procedure

1. Use an SSH tool to remotely log in to the Linux CLI.

2. Upload the x2openEuler software package to a custom directory on the server and run the following commands to perform the upgrade:

   cd custom_directory
   rpm -Uvh x2openEuler-core-x.x.x-xx.x86_64.rpm
   

3. After the upgrade is complete, run the following commands to start the x2openEuler service:

   systemctl start nginx_x2openEuler.service
   systemctl start gunicorn_x2openEuler.service
   

Upgrading x2openEuler Using a Script

Earlier versions of x2openEuler can be upgraded to 3.0.RC1 using a script.

Prerequisites

• You have saved the x2openEuler 3.0.RC1 software package to the local PC and confirmed that the software package is compatible with the server hardware platform. You have verified that the software package is consistent with that on the website. For details, see Verifying the Digital Signature.
• x2openEuler can be used properly

Procedure

须知：

• The upgrade cannot be performed when an assessment or upgrade task is being performed. Ensure that no task is running during the upgrade.
• Dot not press Ctrl+Z, Ctrl+C, or restart the OS during the upgrade.

1. Use an SSH tool to remotely log in to the Linux CLI and upload the x2openEuler 3.0.RC1 software package.

2. Run the following commands to decompress the software package and obtain the db_migrate.sh file from the decompressed directory:

   rpm2cpio x2openEuler-core-3.0.0-xxx.rpm | cpio -id ./usr/local/x2openEuler/portal/src/db_migrate.sh 
   

3. Go to the directory where the software package is stored and run the following command as the root user to migrate the x2openEuler database of an earlier version:

   bash ./usr/local/x2openEuler/portal/src/db_migrate.sh
   

   The command output is as follows:

   The data is backed up successfully. You can uninstall the old version.
   

   Uninstall x2openEuler of the earlier version after the migration is complete.

   NOTE
   After the backup is complete, ensure that the /opt/back_up directory contains files such as db.sqlite3, output.tar.gz, x2openEuler-upgrade.tar.gz, and the x2openEuler directory.

4. Install x2openEuler 3.0.RC1 by referring to Installing x2openEuler. After the installation is complete, run the following command to execute db_migrate.sh:

   bash /usr/local/x2openEuler/portal/src/db_migrate.sh
   

5. After the database file migration is complete, log in to the x2openEuler WebUI again and check whether the services, data, and status of the tool of the earlier version are normal.

Rolling Back x2openEuler after the Upgrade

Roll back x2openEuler 3.0.RC1 to the source version.

Prerequisites

• x2openEuler has been upgraded to 3.0.RC1 from an earlier version.
• The /opt/back_up backup file exists.
• You have obtained the software package of the source version.

Procedure

NOTE
If a passed environment check task exists before the rollback, uninstall the x2openEuler-upgrade package (for example, x2openEuler-upgrade-x.x.x.x86_64) on the node to be upgraded after the rollback.

1. Use an SSH tool to remotely log in to the Linux CLI.

2. Run the following command to copy the db_migrate.sh file to a custom directory: (The /home directory is used as an example.)

   cp /usr/local/x2openEuler/portal/src/db_migrate.sh /home/
   

3. Uninstall x2openEuler 3.0.RC1. For details, see Uninstalling x2openEuler.

4. Install the x2openEuler software package of the earlier version. For details, see Installing x2openEuler.

5. Go to the directory where db_migrate.sh is stored and run the following command to perform the rollback:

   bash db_migrate.sh rollback
   

   If the following information is displayed, the rollback is complete.

   System rollback succeeded.
   

Uninstalling x2openEuler

Prerequisites

No tasks are running.

Procedure

1. Use an SSH tool to remotely log in to the Linux CLI.

2. Run the following command to uninstall x2openEuler:

   yum -y remove x2openEuler-core-x.x.x-x.x86_64
   

   NOTE

   • Before you run the uninstallation command, terminate any task in progress or wait until the task is complete. Otherwise, the task in progress will be stopped.
   • Before you run the uninstallation command, ensure that you are the only user who is operating x2openEuler on the remote server through a client. Otherwise, x2openEuler may fail to be uninstalled due to the failure to delete the x2openEuler user.
   • After the uninstallation is complete, the x2openEuler user and related directories (/home/x2openEuler and /var/spool/mail/x2openEuler) are automatically removed to ensure system environment security.

3. Delete the x2openEuler database.

   1. Run the following command to log in to the MariaDB database. Enter the password as prompted.

      mysql -u root -p
      

   2. Run the following SQL statement to delete the database of x2openEuler. The following describes how to delete the database named x2openEulerDb.

      DROP DATABASE IF EXISTS x2openEulerDb;
      

   3. Run the following SQL statements to delete the database user of x2openEuler.

      DELETE FROM mysql.user WHERE User='x2openEuler';
      DELETE FROM mysql.db WHERE User='x2openEuler';
      

   4. Run the following SQL statements to check whether the database and user of x2openEuler have been deleted:

      show databases;
      SELECT Host,User,Password FROM mysql.user;
      

4. (Optional) Uninstall MariaDB.

   NOTICE
   Before uninstalling MariaDB, ensure that MariaDB is not required in the service environment and the uninstallation does not affect the operating environment and services.

   1. Run the following commands to uninstall MariaDB:

      rpm -qa | grep mariadb | xargs yum remove -y
      

   2. Run the following commands to clear the configuration directory:

      rm -rf /etc/my.cnf
      rm -rf /var/lib/mysql/