How to perform dist-upgrade procedure on Linux server with Plesk?

• Install the previous version of OS on a test server or inside a virtual machine. Upgrade it using the instructions provided in the documentation by the OS vendor:

  Debian 9 to Debian 10

  Ubuntu 16 to Ubuntu 18

  Ubuntu 18 to Ubuntu 20

• Solve all potential problems and make sure Plesk is working after the upgrade before proceeding with the upgrade on the production server.

If you want or need Plesk to assist on this task or to do it on your behalf, place a request to Plesk Professional Services team here: Plesk Professional Services: Administrative Services

Warning: The dist-upgrade process from Ubuntu 22.04 to Ubuntu 24.04 is supported on x64 CPUs from Plesk Obsidian 18.0.61 version and later.

Warning: Plesk Premium Email extension depends on Kolab which does not yet support Ubuntu 24. Remove the extension before proceeding with the dist-upgrade.

Preparing server for upgrade

1. Create a full server backup. Before the upgrade, make a full server backup (which includes a full backup of all the databases). Also, notify the customers about upcoming downtime of one to three hours

2. Connect to the server via SSH

3. Change to root user by using the following command:

   # sudo su -

4. Remove packages which were installed by dependencies but are not required:

   # apt-get autoremove

5. Execute the command below to be sure that system is up-to-date:

   # plesk sbin pum --update

6. Run the command to make Plesk up-to-date:

   # plesk installer update

7. Install aptitude:

   # apt-get install aptitude

8. Remove repository lists that are related to Plesk:

   # rm -f /etc/apt/sources.list.d/plesk*.list

   Performing the dist-upgrade

9. Replace 'jammy' sources lists with 'noble' sources lists in /etc/apt/sources.list and /etc/apt/sources.list.d/*.list:

   # sed -i "s/jammy/noble/g" /etc/apt/sources.list

   Note: below is the example for /etc/apt/sources.list file:

   deb http://archive.ubuntu.com/ubuntu noble main restricted universe
   deb http://archive.ubuntu.com/ubuntu noble-updates main restricted universe
   deb http://security.ubuntu.com/ubuntu noble-security main restricted universe multiverse

10. Make installer to create Plesk sources list for Ubuntu 24.04:

    # plesk installer --override-os-version 24.04 --check-updates --skip-cleanup

11. Change bind-address in the /etc/mysql/my.cnf to accept IPv4 connections (From 10.6.0 :: refers to IPv6 stictly):

    bind-address = ::ffff:127.0.0.1

    to

    bind-address = 127.0.0.1

12. Add the string below into the /etc/mysql/my.cnf file under [mysqld] section:

    innodb_fast_shutdown=0

13. Restart MariaDB/MySQL service to apply the changes:

    # systemctl restart mariadb || systemctl restart mysql

14. Install modern kernel, libc6, python3, mariadb packages with the command:

    • For MariaDB:

      # aptitude install base-files linux-generic libc6 python3 mariadb-server

    • For MySQL:

      # aptitude install base-files linux-generic libc6 python3 mysql-server-8.0

    Note: Make sure that after execution of the command above, Plesk-related packages are not marked for removal. Normally if mariadb server is installed the list should be as below:

    Remove the following packages:
    1. chrony [4.2-2ubuntu2 (now.]
    2. libssl3 [3.0.2-0ubuntu1.15 (now.]
    3. mariadb-client-10.6 [1:10.6.16-0ubuntu0.22.04.1 (now.]
    4. mariadb-client-core-10.6 [1:10.6.16-0ubuntu0.22.04.1 (now.]
    5. mariadb-server-core-10.6 [1:10.6.16-0ubuntu0.22.04.1 (now.] 

    Note: When a request to overwrite SSHd configuration appears, select to leave the configuration as it is.

    Note: Select to allow automatic restart for services

15. Remove line below from the /etc/mysql/my.cnf file:

    innodb_fast_shutdown=0

16. Reboot the server:

    # reboot

17. Wait some time for the server to reboot, then connect to the server via SSH

18. Switch to root user:

    # sudo su -

19. Execute the command below to get Plesk build for Ubuntu 24.04:

    # plesk installer update --skip-cleanup

20. Update the Plesk extensions:

    # plesk bin extension -l | egrep '(panel-migrator|site-import|docker|grafana)'| awk {'print $1'} | xargs -i plesk bin extension -i {}

21. Complete distupgrade process:

    # apt-get dist-upgrade

    Note: leave the configurations for Postfix, PAM, rsyslog, SpamAssassin, cloud-init and other services as is.

22. Optional step: Remove unused packages:

    # apt-get autoremove

23. Optional step: Purge the configuration files of the removed packages:

    # apt-get purge `dpkg -l | grep "^rc" | awk '{print $2}'`

24. Restore the Plesk packages configuration:

    # plesk installer update

25. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

26. Reboot the server:

    # reboot

27. Wait some time for the server to reboot and check that Plesk and all its services are working.

Preparing server for upgrade: To avoid downtime and data loss, make sure you have read and understood the following information before using the utility:

• Create a full server backup: Before the upgrade, make a full server backup (which includes a full backup of all the databases). It's strongly recommend to create a snapshot as a recovery point in case the conversion process fails.

• Remote management module must be installed on the server, because in some tests the sshd service could not be started during the process.

• Server runs the latest version of Plesk

• Notify the customers about upcoming downtime. Expected downtime is 20-30 minutes where server reboots one or more times (Plesk services, hosted websites, and emails will be unavailable).

• Requirements: grub boot is installed, server has at least 5 GB of free disk space and at least 2 GB of installed RAM.

• Read the list of Known issues or limiters for the tool here.

Using the tool to upgrade from Ubuntu 20 to Ubuntu 22:

1. Connect to the server via SSH as root or other sudoer user and run sudo su -.

2. Download and extract the latest tool version into the server:

   # wget https://github.com/plesk/ubuntu20to22/releases/download/v1.0.0/ubuntu20to22-1.0.0.zip
   # unzip ubuntu20to22-1.0.0.zip
   # chmod 755 ubuntu20to22

3. In order to monitor the conversion process, we recommend using the 'screen' utility to run the tool in the background with the following command:

   # screen -S ubuntu20to22

   3.1 Run the tool convert stage by running the tool with the next command. Note that this process may reboot the server a several times:

   # ./ubuntu20to22

   Note: In case the SSH connection to the server is lost, reconnect to the screen session by running screen -r ubuntu20to22

4. Reconnect to the server after the convert stage completes (around 20-30 minutes) and monitor the finish stage with:

   # ./ubuntu20to22 --status

   or

   # ./ubuntu20to22 --monitor

   • Alternatively the status can be tracked by checking the log file at /var/log/plesk/ubuntu20to22.log. Once the process completes the following message will be observed:

     Message from the Plesk ubuntu20to22 tool:
     The server has been upgraded to Ubuntu 22.
     You can remove this message from the /etc/motd file.

Note: If the process was interrupted before the first reboot, restart it with ./ubuntu20to22 --resume option. If the interruption was after the first reboot, restart the process running systemctl restart plesk-dist-upgrader.

Note: If the operation fails before the distupgrade performs during the conversion stage, run ./ubuntu20to22 --revert to restore Plesk to normal operation. The tool will attempt to undo some of the changes it made and restart Plesk services. Once the root cause of the failure be solved try the conversion again.

Warning: Revert cannot be used to undo the changes after the distupgrade take place because packages provided by Ubuntu 22 already installed. Check the status of the conversion process and monitor its progress

Warning: The dist-upgrade process from Ubuntu 20.04 to Ubuntu 22.04 on x64 CPUs is supported by Plesk Obsidian 18.0.44 version. The dist-upgrade process from Ubuntu 20.04 to Ubuntu 22.04 on ARM CPUs is supported by Plesk Obsidian 18.0.46 version.

Preparing server for upgrade

1. Create a full server backup. Before the upgrade, make a full server backup (which includes a full backup of all the databases). Also, notify the customers about upcoming downtime of one to three hours

2. Connect to the server via SSH

3. Change to root user by using the following command:

   # sudo su -

4. Enable enhanced security mode:

   # plesk bin passwords --encrypt

5. Uninstall the unsupported components Mailman and PHP handlers below version 7.3:

   # plesk installer remove --components php7.1 php7.2 php7.3 mailman

6. Remove packages which were installed by dependencies but are not required:

   # apt-get autoremove

7. Execute the command below to be sure that system is up-to-date:

   # plesk sbin pum --update

8. Run the command to make Plesk up-to-date:

   # plesk installer update

9. Install aptitude:

   # apt-get install aptitude

10. Remove repository lists that are related to Plesk:

    # rm -f /etc/apt/sources.list.d/plesk*.list

    Performing the dist-upgrade

11. Replace focal sources lists with jammy sources lists in /etc/apt/sources.list and /etc/apt/sources.list.d/*.list:

    # sed -i "s/focal/jammy/g" /etc/apt/sources.list

    Note: below is the example for /etc/apt/sources.list file:

    deb http://archive.ubuntu.com/ubuntu jammy main restricted universe
    deb http://archive.ubuntu.com/ubuntu jammy-updates main restricted universe
    deb http://security.ubuntu.com/ubuntu jammy-security main restricted universe multiverse

12. Make installer to create Plesk sources list for Ubuntu 22.04:

    # plesk installer --override-os-version 22.04 --check-updates --skip-cleanup

13. Change bind-address in the /etc/mysql/my.cnf to accept IPv4 connections (From 10.6.0 :: refers to IPv6 stictly):

    bind-address = ::ffff:127.0.0.1

    to

    bind-address = 127.0.0.1

14. Add the string below into the /etc/mysql/my.cnf file under [mysqld] section:

    innodb_fast_shutdown=0

15. Restart MariaDB/MySQL service to apply the changes:

    # systemctl restart mariadb || systemctl restart mysql

16. Install modern kernel, libc6, python3, mariadb packages with the command:

    Note: mysql-community-server has not been published for Ubuntu 22.04 Jammy yet.

    • For MariaDB:

      # aptitude install base-files linux-generic libc6 python3 mariadb-server-10.6

    • For MySQL:

      # aptitude install base-files linux-generic libc6 python3 mysql-server-8.0

    Note: Make sure that after execution of the command above, Plesk-related packages are not marked for removal. Normally if mariadb server is installed the list should be as below:

    Remove the following packages:
    1. galera-3 [25.3.29-1 (now)]
    2. mariadb-client-10.3 [1:10.3.34-0ubuntu0.20.04.1 (now)]
    3. mariadb-client-core-10.3 [1:10.3.34-0ubuntu0.20.04.1 (now)]
    4. mariadb-server-10.3 [1:10.3.34-0ubuntu0.20.04.1 (now)]
    5. mariadb-server-core-10.3 [1:10.3.34-0ubuntu0.20.04.1 (now)]
    6. python3-systemd [234-3build2 (now)]
    7. python3-twisted-bin [18.9.0-11ubuntu0.20.04.2 (now)

    Note: When a request to overwrite SSHd configuration appears, select to leave the configuration as it is.

    Note: Select to allow automatic restart for services

17. Remove line below from the /etc/mysql/my.cnf file:

    innodb_fast_shutdown=0

18. Reboot the server:

    # reboot

19. Wait some time for the server to reboot, then connect to the server via SSH

20. Switch to root user:

    # sudo su -

21. Execute the command below to get Plesk build for Ubuntu 22.04:

    # plesk installer update --skip-cleanup

22. Update the Plesk extensions:

    # plesk bin extension -l | egrep '(panel-migrator|site-import|docker|grafana)'| awk {'print $1'} | xargs -i plesk bin extension -i {}

23. Complete distupgrade process:

    # apt-get dist-upgrade

    Note: leave the configurations for Postfix, PAM, rsyslog, SpamAssassin, cloud-init and other services as is.

24. Optional step: Remove unused packages:

    # apt-get autoremove

25. Optional step: Purge the configuration files of the removed packages:

    # apt-get purge `dpkg -l | grep "^rc" | awk '{print $2}'`

26. Restore the Plesk packages configuration:

    # plesk installer update

27. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

28. Reboot the server:

    # reboot

29. Wait some time for the server to reboot and check that Plesk and all its services are working.

Preparing server for upgrade: To avoid extra downtime and/or data loss, make sure to read and understand the following information before using the distupgrade tool:

• Create a full server backup: Before the upgrade, make a full server backup (which includes a full backup of all the databases). It's strongly recommend to create a snapshot as a recovery point in case the conversion process fails.

• Remote management module must be installed on the server, because in some tests the sshd service could not be started during the process.

• Server runs the latest version of Plesk

• Notify the customers about upcoming downtime. Expected downtime is 20-30 minutes where server reboots one or more times (Plesk services, hosted websites, and emails will be unavailable).

• Requirements: grub boot is installed, server has at least 5 GB of free disk space and at least 2 GB of installed RAM.

• Read the list of Known issues or limiters for the tool here.

• Once downloaded check the general stages of the tool with ./ubuntu18to20 --help and the detailed plan with ./ubuntu18to20 --show-plan output. More information can be found here.

Using the tool to upgrade from Ubuntu 18 to Ubuntu 20:

1. Connect to the server via SSH as root or other sudoer user and run sudo su -.

2. Download and extract the latest tool version into the server:

   # wget https://github.com/plesk/ubuntu18to20/releases/download/v2.0.0/ubuntu18to20-2.0.0.zip
   # unzip ubuntu18to20-2.0.0.zip
   # chmod 755 ubuntu18to20

3. In order to monitor the conversion process, we recommend using the 'screen' utility to run the tool in the background with the following command:

   # screen -S ubuntu18to20

   3.1 Run the tool convert stage by running the tool with the next command. Note that this process may reboot the server a several times:

   # ./ubuntu18to20

   Note: In case the SSH connection to the server is lost, reconnect to the screen session by running screen -r ubuntu18to20

4. Reconnect to the server after the convert stage completes (around 20-30 minutes) and monitor the finish stage with:

   # ./ubuntu18to20 --status

   or

   # ./ubuntu18to20 --monitor

   • Alternatively the status can be tracked by checking the log file at /etc/motd. Once the process completes the following message will be observed:

     CONFIG_TEXT: Message from the Plesk ubuntu18to20 tool:
     The server has been upgraded to Ubuntu 20.
     You can remove this message from the /etc/motd file.

Note: If the process was interrupted before the first reboot, restart it with ./ubuntu18to20 --resume option. If the interruption was after the first reboot, restart the process running systemctl restart plesk-dist-upgrader.

Note: If the operation fails before the distupgrade performs during the conversion stage, run ./ubuntu18to20 --revert to restore Plesk to normal operation. The tool will attempt to undo some of the changes it made and restart Plesk services. Once the root cause of the failure be solved try the conversion again.

Warning: Revert cannot be used to undo the changes after the distupgrade take place because packages provided by Ubuntu 20 already installed. Check the status of the conversion process and monitor its progress

Warning: The dist-upgrade process from Ubuntu 18.04 to Ubuntu 20.04 is supported by Plesk Obsidian 18.0.33 version.

Warning: The dist-upgrade process from Ubuntu 18.04 to Ubuntu 20.04 is supported with MariaDB scenario only.

Preparing server for upgrade

1. Create a full server backup. Before the upgrade, make a full server backup (which includes a full backup of all the databases). Also, notify the customers about upcoming downtime of one to three hours.

2. Remote management module must be installed on the server (This is because, in some tests, sshd service could not be started during the process)

3. Connect and perform the process connected as root or by using the # su - or # sudo su -command.

4. Uninstall unsupported components like PHP below 7.0, Watchdog (Ubuntu users only)... It can be done through Plesk installer.

   Note: More information can be found here: Software Requirements for Plesk Obsidian

5. Temporary install msmtp component instead of Postfix. It can be done through Plesk installer or by using the command:

   # plesk installer add --components msmtp

   Note: this action will remove Postfix, Dovecot, SpamAssassin and Mailman components

6. In case the extension “TuxCare Extended Lifecycle Support” is installed, this needs to be removed with:

   # plesk bin extension -u tuxcare-els

7. Add to the mariadb config file /etc/mysql/mariadb.conf.d/50-server.cnf the string innodb_fast_shutdown=0 in the [mysqld] section. In case MySQL is installed, add the string into /etc/mysql/my.cnf in the [mysqld] section.

8. Restart the DB server to apply changes:

   # systemctl restart mariadb || systemctl restart mysql || systemctl restart mysqld

9. Make sure that update-manager-core package is installed:

   # apt-get install update-manager-core

10. Update the current system to the latest available version:

    # apt-get update && apt-get upgrade

11. Remove all plesk-related repos from /etc/apt/sources.list.d/. For example, you can archive them by removing originals using the next command:

    # tar -cvf ~apt-sources.tar /etc/apt/sources.list.d/plesk* --remove-files

12. Stop grafana service:

    # systemctl stop grafana-server.service

    Performing the dist-upgrade

13. Update the file sources.list and configure the repository for the OS release that is going to upgrade to:

    # cat /etc/apt/sources.list
    deb http://archive.ubuntu.com/ubuntu/ focal main restricted universe
    deb http://archive.ubuntu.com/ubuntu/ focal-updates main restricted universe
    deb http://archive.ubuntu.com/ubuntu/ focal-security main restricted universe
    deb http://autoinstall.plesk.com/PSA_18.0.37/ focal all
    deb http://autoinstall.plesk.com/pool/PHP_7.1.33_96 focal all
    deb http://autoinstall.plesk.com/pool/PHP_7.2.34_150 focal all
    deb http://autoinstall.plesk.com/PHP73_17/ focal all
    deb http://autoinstall.plesk.com/PHP74_17/ focal all
    deb http://autoinstall.plesk.com/PHP80_17/ focal all
    deb http://autoinstall.plesk.com/grafana/deb stable main
    deb [arch=amd64] http://autoinstall.plesk.com/PMM_0.1.11 focal all
    deb [arch=amd64] http://autoinstall.plesk.com/NODE_0.0.2 all all
    deb [arch=amd64] http://autoinstall.plesk.com/RUBY_0.0.2 focal all

    Note: The example above is for an installed version of Plesk Obsidian 18.0.37. The correct link for each installed version must be modified accordingly. "sources.list" should be replaced with the contents presented above in the article. Only the highlighted line is to be updated/edited.

    For example: http://autoinstall.plesk.com/PSA_x.y.z/
    
    Whereas the version x.y.z is the current Plesk installed version, which can be found in the output of the command:
    
    # plesk -v

14. Update the repositories:

    # apt-get update

15. Upgrade the kernel:

    # apt-get install linux-generic

16. Update MariaDB to the next major version provided by the vendor:

    # apt-get install mariadb-server-10.3

    In case MySQL installed, update it to the next major version provided by the vendor

    # apt-get install mysql-server-5.7

    Warning: MariaDB/MySQL will not start until the next reboot is performed.

17. In the mariadb config file /etc/mysql/mariadb.conf.d/50-server.cnf remove the string innodb_fast_shutdown=0 in the [mysqld] section, added at the beginning of this process. In case MySQL is installed, remove the string from /etc/mysql/my.cnf in the [mysqld] section.

18. Install udev package:

    # apt-get install udev

    Warning: The udev package installation may fail on Ubuntu systems which may be needed to be solved manually. If that is the case, the following should be checked and applied:

    18.1. At line 26 in the /lib/systemd/system/systemd-udevd.service file, the following string should be changed:

    From:

    ExecReload=udevadm control --reload --timeout 0

    To:

    ExecReload=/bin/udevadm control --reload --timeout 0

    18.2. Then execute the following command:

    # apt-get -f install

19. Install Systemd package:

    # apt-get install systemd

20. Reboot the server to the new kernel:

    # shutdown -r now

    Note: This will help to avoid problems with services that already loaded old libc6/libstdc libraries

21. Remove packages that were installed by dependencies and not needed anymore and LXD:

    # apt-get autoremove
    # apt purge lxd lxd-client

22. Upgrade packages:

    # apt-get upgrade

    Note: When prompted, you should keep the previous version of Spamassassin configuration file.

23. Remove packages that were installed by dependencies and not needed anymore:

    # apt-get autoremove

24. Execute the dist-upgrade command:

    # apt-get dist-upgrade

    Note: At this point, plesk-mail-pc-driver, postfix, drweb, kav packages will be removed because there is already a vendor's Postfix that will be used in Ubuntu 20 (which version is lower that the psa-postfix installed in Ubuntu 18)

25. Remove packages that were installed by dependencies and not needed anymore:

    # apt-get autoremove

26. Update Plesk to the next available version finishing the dist-upgrade process:

    # plesk installer update

27. Fix the Bind DNS server defaults file:

    # cp /etc/default/bind9 /etc/default/named

28. Check that all Plesk components(Dovecot, SpamAssassin, Mailman) are installed as needed. e.g. In case there were components uninstalled at the dist upgrade step, select and re-install them again through the plesk installer along with Postfix which was replaced by msmtp at the beginning:

    # plesk installer

29. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

30. Reboot the server:

    # shutdown -r now

31. Check that Plesk and all its services are working.

Note: Ubuntu 16 by default has MySQL 5.7 installed, as a result of dist-upgrade it will remain intact and won't be replaced with MariaDB.

Preparing server for upgrade

1. Create a full server backup. Before the upgrade, make a full server backup (which includes a full backup of all the databases). Also, notify the customers about upcoming downtime of one to three hours.

2. Remote management module must be installed on the server so that it can still be managed if sshd service cannot be started. Like KVM over IP or IPMI. (This is because, in some tests, sshd service could not be started during the process)

3. Update the current system to the latest available versions:

   # apt-get update && apt-get upgrade

4. Add to the mariadb config file /etc/mysql/mariadb.conf.d/50-server.cnf the string innodb_fast_shutdown=0 in the [mysqld] section. In case MySQL is installed, add the string into /etc/mysql/my.cnf in the [mysqld] section.

5. Restart the DB server to apply changes:

   # systemctl restart mariadb || systemctl restart mysql || systemctl restart mysqld

   Warning: If removal of packages in the following two steps stops with message E: Unable to locate package package-name, remove the package-name from the command and run it again.

6. Remove packages that are no longer supported:

   # apt-get remove samba-common samba-libs samba-vfs-modules

7. Remove Plesk components that are no longer supported or can break the upgrade:

   Note: Only the bold marked components and packages may be installed back later on this guide

   # apt-get remove psa-watchdog plesk-php52* plesk-php53* plesk-php54* plesk-php55* plesk-php56* plesk-php70* psa-spamassassin docker*

   Performing the dist-upgrade

8. Update source.list file and configure the repository for the OS release that is going to upgrade to, in this case to bionic

   # cat /etc/apt/sources.list
   deb http://archive.ubuntu.com/ubuntu bionic main restricted universe
   deb http://archive.ubuntu.com/ubuntu bionic-updates main restricted universe
   deb http://security.ubuntu.com/ubuntu bionic-security main restricted universe multiverse
   deb http://autoinstall-archives.plesk.com/PSA_18.0.37/ bionic all
   deb http://autoinstall-archives.plesk.com/PHP70_17/ bionic all
   deb http://autoinstall-archives.plesk.com/PHP71_17/ bionic all
   deb http://autoinstall-archives.plesk.com/PHP72_17/ bionic all
   deb http://autoinstall-archives.plesk.com/PHP73_17/ bionic all
   deb http://autoinstall-archives.plesk.com/PHP74_17/ bionic all
   deb http://autoinstall-archives.plesk.com/SITEBUILDER_17.8.12/ all all
   deb [arch=amd64] http://autoinstall.plesk.com/PMM_0.1.11/ all all
   deb [arch=amd64] http://autoinstall.plesk.com/NODE_0.0.2/ all all
   deb http://autoinstall.plesk.com/grafana/deb stable main
   deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable

   Note: The example above is for an installed version of Plesk Obsidian 18.0.37. The correct link for each installed version must be modified accordingly. "sources.list" should be replaced with the contents presented above in the article. Only the highlighted line is to be updated/edited.

   For example: http://autoinstall.plesk.com/PSA_x.y.z/
   
   Whereas the version x.y.z is the current Plesk installed version, which can be found in the output of the command:
   # plesk -v

9. Update the repositories:

   # apt-get update

10. Upgrade the kernel:

    # apt-get install linux-generic

11. Remove the string innodb_fast_shutdown=0 in the [mysqld] section, added in step 4. of section "Preparing server for upgrade" above.

12. Reboot the server

    # reboot

13. Install packages dpkg and apt

    # apt-get install dpkg apt

14. Upgrade all possible packages:

    # apt-get upgrade

15. When prompted, choose to keep local version config installed for:

    • /opt/psa/etc/apparmor.d/usr.lib.dovecot.dovecot-lda

    • /etc/awstats/awstats.conf

16. Execute the dist-upgrade process:

    # apt-get dist-upgrade

17. When prompted, keep the previous version of /etc/apache2/apache2.conf

    Warning: after this operation, apache2 may not start due to problems with http_proxy module.

    1. Disable it by removing file /etc/apache2/mods-enabled/proxy_http.load

       # rm /etc/apache2/mods-enabled/proxy_http.load

    2. Start apache:

       # systemctl start apache2.service

18. When prompted, keep the local version currently installed for the config files below:

    • /usr/share/rsyslog/50-default.conf

    • /etc/cron.daily/spamassassin

    • /etc/apache2/apache2.conf

    • /etc/pam.d/common-*

    • /etc/rsyslog.d/50-default.conf

    • /usr/share/psa-roundcube/config/config.inc.php

    • /etc/pam.d/common-*

19. It is safe to install the maintainer's version for the configuration files below when prompted:

    • /etc/apparmor.d/*

    • /etc/ssh/sshd_config

20. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

21. Reboot the server.

    # reboot

22. Check that Plesk and all its services are working.

Preparing server for upgrade: To avoid extra downtime and/or data loss, make sure to read and understand the following information before using the distupgrade tool:

• Create a full server backup: Before the upgrade, make a full server backup (which includes a full backup of all the databases). It's strongly recommend to create a snapshot as a recovery point in case the conversion process fails.

• Remote management module must be installed on the server, because in some tests the sshd service could not be started during the process.

• Server runs the latest version of Plesk

• Notify the customers about upcoming downtime. Expected downtime is 20-30 minutes where server reboot one or more times (Plesk services, hosted websites, and emails will be unavailable).

• Requirements: grub boot is installed, server has at least 5 GB of free disk space and at least 2 GB of installed RAM.

• Read the list of Known issues or limiters for the tool here.

• Once downloaded check the general stages of the tool with ./debian11to12 --help and the detailed plan with ./debian11to12 --show-plan output. More information can be found here.

Using the tool to upgrade from Debian 11 to Debian 12:

1. Connect to the server via SSH as root or other sudoer user and run sudo su -.

2. Download and extract the latest tool version into the server:

   # wget https://github.com/plesk/debian11to12/releases/download/v1.0.0/debian11to12-1.0.0.zip
   # unzip debian11to12-1.0.0.zip
   # chmod 755 debian11to12

3. In order to monitor the conversion process, we recommend using the 'screen' utility to run the tool in the background with the following command:

   # screen -S debian11to12

   3.1 Run the dist upgrade convert stage by running the tool with the next command. Note that this process may reboot the server a several times:

   # ./debian11to12

   Note: In case the SSH connection to the server is lost, reconnect to the screen session by running screen -r debian11to12

4. Reconnect to the server after the above stage completes (around 20-30 minutes) and monitor the status with:

   # ./debian11to12 --status

   or

   # ./debian11to12 --monitor

   • Alternatively the status can be tracked by checking the log file at /var/log/plesk/debian11to12.log. Once the process completes the following message will be observed:

     CONFIG_TEXT: Message from the Plesk debian11to12 tool:
     The server has been upgraded to Debian 12.
     You can remove this message from the /etc/motd file.

Note: If the process was interrupted before the first reboot, restart it with ./debian11to12 --resume option. If the interruption was after the first reboot, restart the process running systemctl restart plesk-dist-upgrader.

Note: If the operation fails before the distupgrade performs during the conversion stage, run ./debian11to12 --revert to restore Plesk to normal operation. The tool will attempt to undo some of the changes it made and restart Plesk services. Once the root cause of the failure be solved try the conversion again.

Warning: Revert cannot be used to undo the changes after the distupgrade take place because packages provided by Debian 12 already installed. Check the status of the conversion process and monitor its progress

Warning: The dist-upgrade from Debian 11 to Debian 12 is supported by Plesk Obsidian 18.0.57 version.

Warning: The dist-upgrade process from Debian 11 to Debian 12 is supported with MariaDB scenario only.

1. Create a full server backup. Before the upgrade, make a full server backup. Also, notify the customers about upcoming downtime of one to three hours.

2. Connect to the server and perform the process connected as root or by using the # su - or # sudo su -command.

3. Uninstall unsupported components like PHP handlers below version 7.3:

   Note: before applying the command below, switch the existing websites to PHP version 7.4 or higher.

   # plesk installer remove --components php7.1 php7.2 php7.3

4. Remove packages which were installed by dependencies but aren't required:

   # apt-get autoremove

5. Execute the command below to be sure that system is up-to-date:

   # plesk sbin pum --update

   OR

   # apt-get update && apt-get upgrade

6. Run the command to make Plesk up-to-date:

   # plesk installer update

7. Install aptitude:

   # apt-get install aptitude

8. Remove repository lists that are related to Plesk:

   # rm -f /etc/apt/sources.list.d/plesk*.list

9. Replace bullseye sources lists with bookworm ones in /etc/apt/sources.list and /etc/apt/sources.list.d/*.list:

   Note: below is the example for /etc/apt/sources.list file:

   deb http://deb.debian.org/debian bookworm main contrib non-free
   deb-src http://deb.debian.org/debian bookworm main contrib non-free
   
   deb http://deb.debian.org/debian-security/ bookworm-security main contrib non-free
   deb-src http://deb.debian.org/debian-security/ bookworm-security main contrib non-free
   
   deb http://deb.debian.org/debian bookworm-updates main contrib non-free
   deb-src http://deb.debian.org/debian bookworm-updates main contrib non-free

10. Make installer to create Plesk sources list for Debian 12:

    # plesk installer --override-os-version 12 --check-updates --skip-cleanup

11. Change bind-address in the /etc/mysql/my.cnf to accept IPv4 connections (From 10.6.0 :: refers to IPv6 strictly):

    bind-address = ::ffff:127.0.0.1

    To:

    bind-address = 127.0.0.1

12. Add string below into the /etc/mysql/my.cnf file under [mysqld] section:

    innodb_fast_shutdown=0

13. Restart MariaDB service to apply the changes:

    # systemctl restart mariadb

14. Install modern kernel, libc6, python3, mariadb packages with the command:

    # aptitude install base-files linux-image-amd64 libc6 python3 mariadb-server-10.5

    Note:Make sure that after execution of the command above, Plesk-related packages are not marked, for removal, normally list should be as below:

    Remove the following packages:
    1 python3-debianbts [3.1.0 (now)]
    2 python3-pycurl [7.43.0.6-5 (now)]
    3 python3-pysimplesoap [1.16.2-3 (now)]
    4 python3-reportbug [7.10.3+deb11u1 (now)]
    5 reportbug [7.10.3+deb11u1 (now)]

    Note: when you will be asking to overwrite sshd configuration, left it as is. Also allow automatic restart for services

15. Remove line below from the /etc/mysql/my.cnf file:

    innodb_fast_shutdown=0

16. Reboot the server

17. Execute the command below to get Plesk build for Debian 12 OS:

    # plesk installer update --skip-cleanup

18. Update the Plesk extensions:

    # plesk bin extension -l | egrep '(panel-migrator|site-import|docker|grafana|ruby)' | awk {'print $1'} | xargs -i plesk bin extension -i {}

19. Complete distupgrade process:

    # apt-get dist-upgrade

    Note: leave configuration for Postfix, PAM, rsyslog, SpamAssassin, cloud-init and other services as is.

20. Optional step: Remove unused packages:

    # apt-get autoremove

21. Optional step: Purge the configuration files of the removed packages:

    # apt-get purge `dpkg -l | grep "^rc" | awk '{print $2}'`

22. Restore the Plesk packages configuration:

    # plesk installer update

23. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

24. Reboot the server

Warning: The dist-upgrade from Debian 10 to Debian 11 is supported by Plesk Obsidian 18.0.42 version.

Warning: The dist-upgrade process from Debian 10 to Debian 11 is supported with MariaDB scenario only.

1. Create a full server backup. Before the upgrade, make a full server backup. Also, notify the customers about upcoming downtime of one to three hours.

2. Connect to the server and perform the process connected as root or by using the # su - or # sudo su -command.

3. Uninstall unsupported components like mailman, webalizer, watchdog and PHP handlers below version 7.3:

   Note: before applying the command below, switch the existing websites to PHP version 7.4 or higher.

   # plesk installer remove --components php7.1 php7.2 php7.3 mailman webalizer watchdog

4. Remove packages which were installed by dependencies but aren't required:

   # apt-get autoremove

5. Execute the command below to be sure that system is up-to-date:

   # plesk sbin pum --update

   OR

   # apt-get update && apt-get upgrade

6. Run the command to make Plesk up-to-date:

   # plesk installer update

7. Install aptitude:

   # apt-get install aptitude

8. Remove repository lists that are related to Plesk:

   # rm -f /etc/apt/sources.list.d/plesk*.list

9. Replace buster sources lists with bullseye ones in /etc/apt/sources.list and /etc/apt/sources.list.d/*.list:

   Note: below is the example for /etc/apt/sources.list file:

   CONFIG_TEXT: deb http://deb.debian.org/debian bullseye main contrib non-free
   deb-src http://deb.debian.org/debian bullseye main contrib non-free
   
   deb http://deb.debian.org/debian-security/ bullseye-security main contrib non-free
   deb-src http://deb.debian.org/debian-security/ bullseye-security main contrib non-free
   
   deb http://deb.debian.org/debian bullseye-updates main contrib non-free
   deb-src http://deb.debian.org/debian bullseye-updates main contrib non-free

10. Make installer to create Plesk sources list for Debian 11:

    # plesk installer --override-os-version 11 --check-updates --skip-cleanup

11. Add string below into the /etc/mysql/my.cnf file under [mysqld] section:

    CONFIG_TEXT: innodb_fast_shutdown=0

12. Restart MariaDB service to apply the changes:

    # systemctl restart mariadb

13. Install modern kernel, libc6, python3, mariadb packages with the command:

    # aptitude install base-files linux-image-amd64 libc6 python3 mariadb-server-10.5

    Note:Make sure that after execution of the command above, Plesk-related packages are not marked, for removal, normally list should be as below:

    CONFIG_TEXT: Remove the following packages:

    1. g++-8 [8.3.0-6 (now)] \
    2. galera-3 [25.3.25-2 (now)] \
    3. gcc-8 [8.3.0-6 (now)] \
    4. libgcc-8-dev [8.3.0-6 (now)] \
    5. libpython-stdlib [2.7.16-1 (now)] \
    6. libstdc++-8-dev [8.3.0-6 (now)] \
    7. mariadb-client-10.3 [1:10.3.22-0+deb10u1 (now)] \
    8. mariadb-client-core-10.3 [1:10.3.22-0+deb10u1 (now)] \
    9. mariadb-server-10.3 [1:10.3.22-0+deb10u1 (now)] \
    10. mariadb-server-core-10.3 [1:10.3.22-0+deb10u1 (now)] \
    11. openssh-sftp-server [1:7.9p1-10+deb10u1 (now)] \
    12. python [2.7.16-1 (now)] \
    13. python-minimal [2.7.16-1 (now)]

    Note: when you will be asking to overwrite sshd configuration, left it as is. Also allow automatic restart for services

14. Remove line below from the /etc/mysql/my.cnf file:

    CONFIG_TEXT: innodb_fast_shutdown=0

15. Reboot the server

16. Rename configuration from bind9 to named:

    # mv /etc/default/bind9 /etc/default/named

17. Execute the command below to get Plesk build for Debian 11 OS:

    # plesk installer update --skip-cleanup

18. Update the Plesk extensions:

    # plesk bin extension -l | egrep '(panel-migrator|site-import|docker|grafana|ruby)' | awk {'print $1'} | xargs -i plesk bin extension -i {}

19. Complete distupgrade process:

    # apt-get dist-upgrade

    Note: leave configuration for Postfix, PAM, rsyslog, SpamAssassin, cloud-init and other services as is.

20. Optional step: Remove unused packages:

    # apt-get autoremove

21. Optional step: Purge the configuration files of the removed packages:

    # apt-get purge `dpkg -l | grep "^rc" | awk '{print $2}'`

22. Restore the Plesk packages configuration:

    # plesk installer update

23. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

24. Reboot the server

Warning: dist-upgrade from Debian 9 to Debian 10 is supported by Plesk Obsidian 18.0.30 version.

Warning: The dist-upgrade process from Debian 9 to Debian 10 is supported with MariaDB scenario only.

Warning: Due to mail server being temporarily uninstalled for the time of upgrade, some settings, i.e. maximum message size, can be reset.

1. Create a full server backup. Before the upgrade, make a full server backup. Also, notify the customers about upcoming downtime of one to three hours.

2. Connect and perform the process connected as root or by using the # su - or # sudo su -command.

3. Uninstall unsupported components such as Docker and PHP below version 7.0 with Plesk installer.

   Note: More information can be found here: Software Requirements for Plesk Obsidian

4. Temporary install msmtp component instead of Postfix. It can be done through Plesk installer or by using the command:

   # plesk installer add --components msmtp --source http://autoinstall-archives.plesk.com

5. Add to the mariadb/mysql config file (Usually /etc/mysql/my.cnf) the string innodb_fast_shutdown=0 in the [mysqld] section.

6. Restart the DB server to apply changes:

   # systemctl stop mariadb.service ; systemctl start mariadb.service

7. Update the current system to the latest available versions:

   # apt-get update && apt-get upgrade

8. Remove all plesk-related repos from /etc/apt/sources.list.d/. For example, you can archive them by using the next command:

   # tar -cvf ~apt-sources.tar /etc/apt/sources.list.d/plesk* --remove-files

9. Stop grafana service:

   # systemctl stop grafana-server.service

10. Replace stretch sources lists with buster ones in /etc/apt/sources.list and /etc/apt/sources.list.d/*.list:

    Note: below is the example for the resulting /etc/apt/sources.list file:

    # cat /etc/apt/sources.list
    deb http://security.debian.org/debian-security buster/updates main contrib non-free
    deb http://deb.debian.org/debian/ buster-updates main contrib non-free
    deb http://deb.debian.org/debian/ buster main contrib non-free

11. Make installer to create Plesk sources list for Debian 10:

    # plesk installer --override-os-version 10.0 --check-updates --skip-cleanup --source http://autoinstall-archives.plesk.com

12. Temporarily add the following Plesk repositories (e.g. vi /etc/apt/sources.list.d/plesk_temp.list):

    CONFIG_TEXT: deb https://autoinstall-archives.plesk.com/pool/PSA_18.0.44_9078/ buster all
    deb https://autoinstall-archives.plesk.com/SITEBUILDER_18.0.29 all all
    deb https://autoinstall-archives.plesk.com/PHP80_17 buster all
    deb https://autoinstall-archives.plesk.com/PHP81_17 buster all
    deb https://autoinstall-archives.plesk.com/PHP74_17 buster all
    deb https://autoinstall-archives.plesk.com/PHP73_17 buster all
    deb https://autoinstall-archives.plesk.com/PHP72_17 buster all
    deb https://autoinstall-archives.plesk.com/PHP71_17 buster all

13. Run apt update to refresh the repositories:

    # apt update

14. Run the dist-upgrade to upgrade the packages from Debian 9 to Debian

    # apt dist-upgrade

    Note: When prompted, you should keep the previous version of Rsyslog configuration file.

    Note: When prompted, you should keep the previous version of Spamassassin configuration file.

15. Remove the temporary sources file created in step 12 (e.g. rm /etc/apt/sources.list.d/plesk_temp.list).

16. Run plesk installer to update the current packages:

    # plesk installer update --source http://autoinstall-archives.plesk.com

17. In case that systemctl status apache2 results in apache service being stopped/failed:

    Resolve it by installing a the package and starting apache2:

    # apt-get install libapache2-mod-fcgid-psa

    # service apache2 start

18. Run apt update again:

    # apt update

19. Update MariaDB to the next major version provided by the vendor:

    # apt-get install mariadb-server-10.3

    Warning: MariaDB/MySQL may not start till the reboot is performed.

20. Remove from the mariadb/mysql config file (Usually /etc/mysql/my.cnf) the string innodb_fast_shutdown=0 in the [mysqld] section, added at the beginning of this process.

21. When AppArmor was installed, bind service fails to start with permission denied shown at systemctl status bind9 output:

    Resolve it by either disabling AppArmor with following commands or reconfigure AppArmor:

    # systemctl stop apparmor
    # systemctl restart bind9

22. Reboot the server to the new kernel:

    # shutdown -r now

23. Clean packages installed by dependencies and not needed anymore:

    # apt-get autoremove

24. In case AppApmor is enabled adjust it by following this article to let Bind9 load properly

Note: At this point, there is a possibility that components are removed, like for example: php7.0-curl plesk-mail-pc-driver postfix psa-drweb-configurator psa-spamassassin which is because on Debian 10 vendor's postfix is used and its version is lower than postfix shipped by Plesk for Debian 9

23. Check that all the Plesk components are installed and if not (Like for example in case there were components uninstalled like the ones in the dist upgrade step), select and re-install them again through the plesk installer along with Postfix which was replaced by msmtp at the beginning:

    # plesk installer

24. Run the repair command below to run all needed upgrade scripts:

    # plesk repair installation

25. Check that Plesk and all its services are working.

26. Use the following commands to regenerate web server as well as DNS configuration files if needed:

    # plesk repair web

    # plesk repair dns

Warning: dist-upgrade from Ubuntu 14 to Ubuntu 16 is supported for Plesk Onyx version 17.8.

Warning: During an upgrade from Ubuntu 14 to Ubuntu 16, system PHP 5.x shipped by OS vendor will be upgraded to PHP 7.x. So to avoid any PHP compatibility issues, before an upgrade, it is highly recommended to switch all sites having PHP handler 5.x by OS vendor to corresponding custom PHP handlers. Please refer to these KB articles for details: How to configure PHP handlers in Plesk for Linux? and How to apply new PHP handler to multiple domains via CLI?

Warning: if PHP by OS vendor was updated from third-party sources prior to dist-upgrade, it may break webmail functionality.

1. Create a full server backup. Before the upgrade, make a full server backup. Also, notify the customers about upcoming downtime of one to three hours.

2. Run below script and follow the wizard:

   # /opt/psa/bin/distupgrade.helper.ubt14-ubt16.x64.sh

   The script logs all its actions in /var/log/plesk/install/plesk-distupgrade.log .

3. During the script execution, you will be asked to reboot the server. Reboot the server.

4. After the server reboot, run the script once again.

Warning: dist-upgrade from Debian 8 to Debian 9 is supported by Plesk Onyx 17.8 version.

Warning: if PHP by OS vendor was updated from third-party sources prior to dist-upgrade, it may break webmail functionality.

Preparing server for upgrade

1. Create a full server backup. Before the upgrade, make a full server backup. Also notify the customers about upcoming downtime of one to three hours.

2. Consider to remove sources list backup files which might be left from the previous dist-upgrade:

   • /etc/apt/sources.list.saved_by_plesk_distupgrade
   • /etc/apt/sources.list.d/50sw_autoinstaller.list.saved_by_plesk_distupgrade`

3. Download the distupgrade scripts

   # wget https://raw.githubusercontent.com/plesk/kb-scripts/master/distupgrade-helper-deb8-deb9/distupgrade.helper.deb8-deb9_pre.x64.sh

   # wget https://raw.githubusercontent.com/plesk/kb-scripts/master/distupgrade-helper-deb8-deb9/distupgrade.helper.deb8-deb9.x64.sh

4. Move the scripts to /opt/psa/bin/

   # mv distupgrade.helper.deb8-deb9*.x64.sh /opt/psa/bin/

5. Make the scripts executable by running following command:

   # chmod +x /opt/psa/bin/distupgrade.helper.deb8-deb9*.x64.sh

6. Run pre-upgrade helper script and prepare Plesk and the system for the upgrade:

   # /opt/psa/bin/distupgrade.helper.deb8-deb9_pre.x64.sh

   The script logs all its actions in /var/log/plesk/install/plesk-distupgrade.log.

Performing the dist-upgrade

1. Update source.list file and configure the repository for the OS release that is going to upgrade to:

   # cat /etc/apt/sources.list
   deb http://deb.debian.org/debian stretch main contrib non-free
   deb http://security.debian.org/debian-security/ stretch/updates main contrib non-free
   deb http://deb.debian.org/debian stretch-updates main contrib non-free

2. Update information about system packages:

   # apt-get update

3. Upgrade the system:

   # /opt/psa/bin/distupgrade.helper.deb8-deb9.x64.sh

   This command will perform a complete upgrade of the system, install the newest available versions of all packages and resolve all possible dependency changes between packages in different releases.

   During the upgrade the system might produce prompts like:

   CONFIG_TEXT: Configuration file /etc/mysql/my.cnf
   ==> Modified (by you or by a script) since installation.
   ==> Package distributor has shipped an updated version.
   What would you like to do about it ?
   Your options are:
   Y or I : install the package maintainer's version
   N or O : keep your currently-installed version
   D : show the differences between the versions
   Z : start a shell to examine the situation
   The default action is to keep your current version.
   *** my.cnf (Y/I/N/O/D/Z) [default=N] ?
   
   Choose to replace configuration files with a new one (answer Y).

Finalizing the upgrade

1. Run post-upgrade helper script:

   # /opt/psa/bin/distupgrade.helper.deb8-deb9_post.x64.sh

   Note: This script is already called during the execution of /opt/psa/bin/distupgrade.helper.deb8-deb9.x64.sh, run it to verify that everything was successfully done. Its actions are logged in /var/log/plesk/install/plesk-distupgrade.log too.

2. Run the repair command below to run all needed upgrade scripts:

   # plesk repair installation

3. Reboot the server.

4. Check that Plesk and all its services are working.