Overall, the 3CX upgrade script upgrades Linux based customers from Debian 9 with v16 to Debian 10 with v18 with a success rate of 92%. In this blog post, we will cover common solutions for the remaining 8% of cases that failed to upgrade successfully.

Take a Backup

Before you attempt any software update, take a full backup of your 3CX System and download it off the host running 3CX. This will allow a speedy recovery for any unforeseeable situations. The upgrade script also will take a basic backup of your system, however, it does not contain voicemails, recordings or call-history data. In case your system is not accessible this backup will not be much of a help for you.

First, Find the Error

In case the upgrade fails/aborts, the first thing to do is to check the reason. The exact cause can be found in the status report sent by email from the 3CX System to the administrator. Alternatively, you can inspect the file /tmp/UPDATE.log. Note that the log file is removed from the system after a reboot so this needs to be inspected prior to any reboots.

Unsupported Environment

A big portion of unsuccessful upgrades is by customers who have installed additional packages, source lists or run in an environment/hosting provider which is not officially supported. In total, these are 70% of the most common reasons for an aborted upgrade.

Your v16 installation is not affected by the upgrade attempts and returns back to where you left it prior to the upgrade.

Inspection

The log will contain one of the following:
Preparation: Found an uncommon source list
Sources seems to be include oldstable

Solution / What to do

You must take a full backup of your 3CX System and re-deploy it using our 3CX iso or 3CX Deployment Service from the customer portal. Then perform a restore. This will not only help in upgrading directly to v18 but also ensures that the underlying OS is fully supported by 3CX.

Locked APT or DPKG

Both package managers of Debian can sometimes be busy at the moment you try to run the upgrade of your 3CX System. Combined, this totals to 10% of the cases for an unsuccessful upgrade. Commonly there is nothing to worry about, as the system remained unchanged in v16 from the moment the upgrade was attempted.

Your v16 installation is not affected by the upgrade attempts and returns back to where you left it prior to the upgrade.

Inspection

The log will contain a line response line:
There seems to be an apt file lock in place.
There seems to be a dpkg file lock in place.

Solution

It is recommended that you try to upgrade the process again in 30 minutes. If the situation remains unchanged you can debug why APT or DPKG is locked or take the route to reinstall the system via backup and restore functionality onto a new Debian 10 instance. This also clears out any uncertainty if you are not sure how you had installed 3CX previously.

Upgrade Stopped

In 15% of the cases the OS was not upgraded for various reasons such as wrongly configured OS language or wrong locales in the database.

Your v16 installation is not affected by the upgrade attempts and returns back to where you left it prior to the upgrade!

Inspection

The log will contain a line response line:
Locales seems to be invalid
Inspect the log entries above to determine the cause.

Solution

It is recommended that you try the upgrade process again in 30 minutes. If the situation remains unchanged reinstall the system via backup and restore functionality onto a new Debian 10 instance. This also clears out any uncertainty if you are not sure how you had installed 3CX previously.

Other Cases

The final 5% (of the 8% total non-upgradable systems) have an undefined state. For analytics reasons the system never responded to the upgrade process.

Inspection

The log will contain a line:
Upgrade/Update/Simulation/Download failed (package)

Solution

To address this state, take the full backup of your 3CX System you have taken prior to the upgrade and redeploy it using our 3CX iso or 3CX Deployment Service from the customer portal. This will not only help in upgrading directly to v18 but also ensures that the underlying OS is fully supported by 3CX.

See Also

For more information about upgrading from version 16 to version 18 (including an OS update for Linux), check out our blog post ‘Upgrade to v18 and Debian 10 (Buster)’.