Articles in this section

How to make an in-place upgrade of a Plesk server from CloudLinux 8 to CloudLinux 9?

Vladimir Levchuk
Updated
kb: how-to Plesk Obsidian for Linux cloudlinux kb: ai-created kb: ai-edited

Applicable to:

  • Plesk for Linux

Question

How to make an in-place upgrade of a Plesk server from CloudLinux 8 to CloudLinux 9?

Answer

We prepared a CLI script that in-place converts a CloudLinux 8 server with Plesk to CloudLinux 9.

Note: The script is based on the CloudLinux ELevate tool, which uses the LEAPP modernization framework (see the CloudLinux announcement: CloudLinux ELevate: In-place upgrades from CloudLinux 8 to 9 are now supported). ELevate on its own does not support servers with Plesk, so use the Plesk script described in this article instead of running ELevate directly. The script includes additional repositories and configuration support provided by Plesk.

Note: If you'd like Plesk to assist with this task or handle it on your behalf, you can submit a request to the Plesk Professional Services team here: Plesk Professional Services - Administrative Services.

Requirements:

  • CloudLinux 8.10 or later.
  • Plesk version is not older than five releases back from the latest version.
  • grub2 is installed.
  • At least 5 GB of free disk space.
  • At least 1 GB of RAM.
  • Webalizer web statistics is not used. It is not supported in CloudLinux 9 and must be switched to another Plesk-supported statistics tool before the conversion.

Limitations:

Warning: Do not use the script if any of the following conditions is true.

  • The script was not tested on other Red Hat Enterprise Linux 8-based distributions. Run only if the server is using CloudLinux 8.10.
  • The script is only compatible with the most recent five versions of Plesk. It will prevent conversion if the Plesk version is outdated.
  • PHP 5.5 and earlier are not supported in CloudLinux 9 and will not receive any updates after the conversion. These PHP versions are deprecated and may have security vulnerabilities, so they are removed before the conversion.
  • PHP 7.1, 7.2, and 7.3 are not supported for now. The conversion is refused if one of them is installed.
  • Conversions inside containers (like Virtuozzo containers, Docker containers, etc.) are not supported.
  • More than one kernel-named interface (like ethX) is not supported. The stability of such names is not guaranteed, so LEAPP prevents the conversion in such cases.

Recommendations:

  • Back up all your databases and have the means to restore them. The script uses standard MariaDB and PostgreSQL tools to upgrade the databases, but this does not guarantee that the process will be free of issues.
  • Ensure that you have a way to restart the server without a direct SSH connection. The conversion process may get stuck once the server boots into the temporary OS distribution that does not start any network interfaces. A serial port connection to the server can be used to monitor the status of the conversion process in real time and to reboot the server if necessary. Reach out to the hosting provider if required.
  • Create a server-wide backup in Plesk and/or create a server snapshot in advance so it can be used as a recovery point in case the conversion process fails.

Warning: Read both tabs below, Conversion process and Special cases and troubleshooting, before performing any actions. Special cases may require additional flags or preparatory steps, and the conversion cannot be reverted after the first reboot.

Conversion process

Conversion process

Warning: Plesk services, hosted websites, and emails will be unavailable during the entire conversion process, which takes about 50 to 80 minutes: preparation (30 to 40 minutes), conversion (15 to 30 minutes, during which the server is not available remotely), and finalization (5 to 10 minutes). The server is rebooted several times, and the conversion automatically progresses after each reboot.

  1. Connect to the server via SSH.

  2. Verify there is at least 5 GB of free space on disk:

    # df -h

  3. Warning: Verify and disable custom repositories configured on the server. These repositories are known to cause issues due to the potential scale of replacement of base packages: LEAPP may fail on leapp preupgrade or leapp upgrade because of packages from custom repositories or because of conflicting packages between el8 and el9 repositories. The repositories are configured in the /etc/yum.repos.d directory. List the enabled repositories with:

    # dnf repolist enabled

    Examples of repositories that should be disabled or enabled:

    ❌ Repositories that should be disabled:

    • city-fan.org
    • Remi Repository
    • RPMFusion
    • ELRepo
    • Any EPEL repository that was not added by Plesk
    • Other third-party repositories

    ✅ CloudLinux official repositories:

    • cloudlinux-x86_64-server-8
    • almalinux-baseos
    • almalinux-appstream

    ✅ Repositories added by Plesk:

    • epel
    • PLESK_17_PHP
    • PLESK_18_0_XX-extras
    • imunify360
    • imunify360-rollout

    If a package from a custom repository cannot be handled by LEAPP, remove it before the conversion and reinstall it once the conversion is complete.

  4. Download and prepare the script following the latest instructions in the Using the script section of the repository README: GitHub - plesk/cloudlinux8to9: CloudLinux 8 to 9 conversion tool.

  5. Run the script inside a screen session so that the conversion continues if the SSH connection is lost:

    # screen -S cloudlinux8to9
    # ./cloudlinux8to9

    To reconnect to the session after losing the SSH connection, run:

    # screen -r cloudlinux8to9

    Alternatively, start the script in the background and check its progress with the --status or --monitor flag:

    # ./cloudlinux8to9 &
    # ./cloudlinux8to9 --status
    # ./cloudlinux8to9 --monitor

  6. Wait for the conversion to finish. The server reboots after the preparation stage, boots into a temporary OS distribution to convert the system to CloudLinux 9 (about 20 minutes), reboots again so that the script can restore Plesk-related services, configuration, and databases, and finally reboots one last time. After that, Plesk returns to normal operation, and the following message is shown on the next SSH login:

    CONFIG_TEXT: ===============================================================================
    Message from the Plesk cloudlinux8to9 tool:
    The server has been converted to CloudLinux 9.
    You can remove this message from the /etc/motd file.
    ===============================================================================

Special cases and troubleshooting

Special cases

  • Perl modules installed via CPAN. If the script detects Perl modules installed via CPAN whose RPM equivalents are unknown to it, it stops with a warning, because such modules will not be available after the conversion. Check for RPM analogues of these modules, remove the CPAN modules, and reinstall them after the conversion is complete. If you no longer need the modules, append the --remove-unknown-perl-modules flag to forcefully remove them during the conversion:

    # ./cloudlinux8to9 --remove-unknown-perl-modules

  • PostgreSQL earlier than version 10. If a PostgreSQL version earlier than 10 is installed, the script refuses to start to warn about potential data loss during the PostgreSQL upgrade performed as part of the conversion. It is recommended to upgrade PostgreSQL to version 10 manually before starting the conversion. Alternatively, create a complete backup of the databases and use the --upgrade-postgres flag to upgrade PostgreSQL during the conversion:

    # ./cloudlinux8to9 --upgrade-postgres

  • Note: The flags can be combined if both of the above apply:

    # ./cloudlinux8to9 --upgrade-postgres --remove-unknown-perl-modules

Troubleshooting

  • The script writes its log to /var/log/plesk/cloudlinux8to9.log. ELevate writes its log to /var/log/leapp/leapp-upgrade.log, and its reports to /var/log/leapp/leapp-report.txt and /var/log/leapp/leapp-report.json.

  • If the script fails before the first reboot, restore Plesk to normal operation with the --revert flag, resolve the root cause, and start the conversion again. Revert cannot be used after the first reboot, and it does not remove LEAPP or the packages installed by it:

    # ./cloudlinux8to9 --revert

  • If the final stage fails after the reboot to CloudLinux 9, a corresponding message is shown on the next SSH login. Check /var/log/plesk/cloudlinux8to9.log, resolve the root cause, and resume the conversion:

    # ./cloudlinux8to9 --resume

  • If the temporary OS distribution hangs during the conversion (for example, because of a custom Python installation or an encoding inconsistency), connect to the server via a serial port console to check the status and reboot the server. Note that an unfinished installation may result in missing packages and other issues.

  • If you encounter an error, prepare a feedback archive and attach it to a new issue at GitHub - plesk/cloudlinux8to9 issues:

    # ./cloudlinux8to9 --prepare-feedback

Was this article helpful?

Comments

0 comments

Please sign in to leave a comment.