https://github.com/plesk/ubuntu20to22
Plesk dist-upgrader tool: Ubuntu 20 to 22
https://github.com/plesk/ubuntu20to22
Last synced: 4 months ago
JSON representation
Plesk dist-upgrader tool: Ubuntu 20 to 22
- Host: GitHub
- URL: https://github.com/plesk/ubuntu20to22
- Owner: plesk
- License: apache-2.0
- Created: 2024-01-24T12:23:21.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-02-09T07:47:38.000Z (5 months ago)
- Last Synced: 2026-02-09T13:27:29.236Z (5 months ago)
- Language: Python
- Size: 59.6 KB
- Stars: 0
- Watchers: 22
- Forks: 0
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The tool to dist-upgrade servers with Plesk from Ubuntu 20 to 22
## Introduction
This utility is the official tool to dist-upgrade servers with Plesk from Ubuntu 20 to 22.
The utility uses [Plesk dist-upgrader](https://github.com/plesk/dist-upgrader).
## Preparation
To avoid downtime and data loss, make sure you have read and understood the following information before using the utility:
1. **Upgrade Plesk to the last version.**
2. **Create a full server backup.** Before the upgrade, make a full server backup (which includes a full backup of all the databases).
3. Notify the customers about upcoming downtime. Expected downtime is 20-30 minutes.
4. **Remote management module must be installed on the server**.
5. We strongly recommend that you **create a snapshot you can use as a recovery point** in case the conversion process fails.
6. Read the [Known issues](#known-issues) section below for the list of known issues.
## Timing
The conversion process should run between 20 and 30 minutes. **Plesk services, hosted websites, and e-mails will be unavailable during the entirety of the conversion process**.
## Known issues
### Blockers
Do not use the utility if any of the following is true:
- **Your system is in a container (like Virtuozzo containers, Docker Containers, etc).**
## Requirements
- Last Plesk version.
- At least 5 GB of free disk space.
- At least 2 GB of RAM.
## Conversion phases
The conversion process consists of two phases:
1. The "convert" phase contains preparation and upgrading actions.
2. The "finish" phase is the last phase containing all finishing actions.
During each phase a conversion plan consisting of stages, which in turn consist of actions, is executed. You can see the general stages in the `--help` output and the detailed plan in the `--show-plan` output.
## Using the utility
To retrieve the latest available version of the tool, please navigate to the "Releases" section. Once there, locate the most recent version of the tool and download the attached archive.
To prepare the latest version of the tool for use, please run the following commands:
```shell
> wget https://github.com/plesk/ubuntu20to22/releases/download/v1.1.7/ubuntu20to22-1.1.7.zip
> unzip ubuntu20to22-1.1.7.zip
> chmod 755 ubuntu20to22
```
To monitor the conversion process, we recommend using the ['screen' utility](https://www.gnu.org/software/screen/) to run the utility in the background. To do so, run the following command:
```shell
> screen -S ubuntu20to22
> ./ubuntu20to22
```
If you lose your SSH connection to the server, you can reconnect to the screen session by running the following command:
```shell
> screen -r ubuntu20to22
```
You can also call ubuntu20to22 in the background:
```shell
> ./ubuntu20to22 &
```
And monitor its status with the '--status' or '--monitor' flags:
```shell
> ./ubuntu20to22 --status
> ./ubuntu20to22 --monitor
... live monitor session ...
```
The conversion process requires 2 reboots. It will be resumed automatically after reboot by the `plesk-dist-upgrader` systemd service. In addition to `--status` and `--monitor`, you can check the status of the conversion process by running the following command:
```shell
> systemctl status plesk-dist-upgrader
```
Running dist-upgrader without any arguments initiates the conversion process. The utility performs preliminary checks, and if any issues are detected, it provides descriptions of the problems along with guidance on how to resolve them.
Following the preliminary checks, the tool proceeds with the dist-upgrade process, which is divided into multiple stages. Some stages end with a reboot. You can check the list of stages and steps by `./ubuntu20to22 --show-plan`.
When dist-upgrade is finished, you will see the following login message:
```
===============================================================================
Message from the Plesk dist-upgrader tool:
The server has been upgraded to Ubuntu 22.
You can remove this message from the /etc/motd file.
===============================================================================
```
## Logs
If something goes wrong, read the logs to identify the problem.
The dist-upgrader writes its log to the `/var/log/plesk/ubuntu20to22.log` file, as well as to stdout.
After the first reboot, the process is resumed by the `plesk-dist-upgrader` service, so its output is available in system logs (see `systemctl status plesk-dist-upgrader` and `journalctl -u plesk-dist-upgrader`).
## Revert
If the utility fails during the the "convert" stage before actual dist-upgrade of packages, you can use the dist-upgrader utility with the `-r` or `--revert` options to restore Plesk to normal operation. The dist-upgrader will undo some of the changes it made and restart Plesk services. Once you have resolved the root cause of the failure, you can attempt the conversion again.
Note:
- You cannot use revert to undo the changes after the dist-upgrade of packages, because packages provided by the new OS version are already installed.
- `--revert` mode is not perfect, it can fail or be unable to restore the initial state of the system. So, the importance of creating full server backup or snapshot before starting dist-upgrade can't be stressed enough.
### Checking the status of the conversion process and monitoring its progress
To check the status of the conversion process, use the `--status` option. You can see the current stage of the conversion process, the elapsed time, and the estimated time until finish.
```shell
> ./ubuntu20to22 --status
```
To monitor the progress of the conversion process in real time, use the `--monitor` option.
```shell
> ./ubuntu20to22 --monitor
( stage 3 / action re-installing plesk components ) 02:26 / 06:18
```
## Issue handling
If for some reason the process has failed, inspect the log. By default, it's put to `/var/log/plesk/ubuntu20to22.log`. If the process was interrupted before the first reboot, you can restart it with the `--resume` option. If the problem has happened after the first reboot, you can restart the process by running `systemctl restart plesk-dist-upgrader`.
If something goes wrong, you will be informed on the next login with this message:
```
===============================================================================
Message from Plesk dist-upgrader tool:
Something went wrong during dist-upgrade by ubuntu20to22.
See the /var/log/plesk/ubuntu20to22.log file for more information.
You can remove this message from the /etc/motd file.
===============================================================================
```
### Send feedback
If you got any error, please [create an issue on GitHub](https://github.com/plesk/ubuntu20to22/issues). Describe your problem and attach the feedback archive or at least the log to the issue. The feedback archive can be created by calling the tool with the `--prepare-feedback` option:
```shell
> ./ubuntu20to22 --prepare-feedback
```