Version upgrade

Considerations

Upgrading to Zentyal 8.0 must be performed from a Zentyal 7.1 fully updated. Versions prior to 7.1 must be upgraded progressively. The complete upgrade sequence from Zentyal 3.2 version is as follows:

3.2 -> 4.x -> 5.x -> 5.x -> 6.0 -> 6.1 -> 6.2 -> 7.0 -> 7.1 -> 8.0

Warning

These instructions are valid for upgrading from version 7.1 Development Edition to 8.0. For a Commercial Edition, you must contact the Support Team. If you do not have access to the Support Portal [1] you must contact the Zentyal Team [2] to request access.

[1]Support Portal: https://zentyal.atlassian.net/servicedesk/customer/portal/4/
[2]Contact: https://zentyal.com/contact-us/

Before starting with the upgrade, we strongly recommend to perform a series of preliminary checks to try to minimize prior checks to try to minimize possible issues. These checks are detailed in the following section.

It is of vital importance to have a backup of the server before proceeding with the upgrade. The upgrade is a complex process and can fail leaving the system damaged or even unrecoverable.

Warning

Please remember that a configuration backup is not a full backup as detailed here [3].

[3]Configuration backup: https://doc.zentyal.org/en/backup-conf.html

Pre-update

The following are the actions to be checked prior to the upgrade.

Zentyal-core package version

In order to update the Zentyal server to version 8.0 we will need to have the version installed 7.1.1 or higher of the zentyal-core package:

dpkg -l zentyal-core

Log errors

One of the most important tasks is to confirm that the most critical system log files are free of errors. The minimum files to check are:

  • /var/log/zentyal/zentyal.log
  • /var/log/syslog

Disk space

As this is a major update, the minimum required disk size is 3 GB for the / partition and 250 MB for the /boot partition:

df -h

Internet access

In order to download the packages needed to perform the upgrade, the server must have Internet access:

ping -c5 google.com

Access to the repositories

Another critical task to check is the access to Ubuntu and Zentyal repositories. To do so, just run the following command to confirm that there are no errors:

sudo apt update

Available packages

To check if the operating system is up to date, we will have to execute the following commands:

sudo apt update
sudo apt list --upgradable

Broken packages

It is imperative that we check for any broken packages, otherwise, the update will fail.

dpkg -l | egrep -v '^(ii|rc)'

In case of broken packages, the Troubleshooting section [4] explains how to try to fix them.

[4]Troubleshooting: https://doc.zentyal.org/en/upgrade.html#id15

Database errors

Another important task is to check if there are any errors in the MySQL hosted databases used by Zentyal for its modules:

mysqlcheck -u root -p$(sudo cat /var/lib/zentyal/conf/zentyal-mysql.passwd) --all-databases 2> /dev/null

In case of using the [5] domain controller module, it is also highly recommended to confirm its status:

sudo samba-tool dbcheck --cross-ncs

In case of detecting an error in this last database, we will have to follow [6] this link.

[5]Domain Controller: https://doc.zentyal.org/en/directory.html
[6]Documentation on the Samba database: https://wiki.samba.org/index.php/Dbcheck

Virtual interfaces

The virtual interfaces feature is deprecated in Zentyal 8.0, so before proceeding with the update it is important to check that there is no network interface configured with this functionality.

System report

We can obtain the results of the checks mentioned in this section and much more information by generating a system report [7] and analyzing it before scheduling the server upgrade.

[7]System report: https://doc.zentyal.org/en/smart-admin.html#system-status-reports

Update

Once we have reviewed your system and confirmed that it is stable, we can proceed with the upgrade. We have two options to carry out the upgrade:

1. Upgrade the system by clicking on the Upgrade button available on the Webadmin.

Upgrade button

Upgrade button

Warning

If the server does not have an Internet connection, the button will not be displayed.

Once we start the upgrade, we will see the process in a modal window and in the log file /var/log/zentyal/upgrade.log.

Upgrade in progress

Upgrade in progress

When the upgrade finishes, we should see a success or failure message.

Upgrade finished successfully

Upgrade finished successfully

Warning

If we do not get any of those messages, the web browser session might have expired, so we will need to check in the log file /var/log/zentyal/zentyal.log. If the upgrade has finished, just refresh the page.

2. From the command line (recommended):

sudo bash /usr/share/zentyal/release-upgrade

# With debug:
sudo bash -x /usr/share/zentyal/release-upgrade

Warning

The terminal from which the command is being executed cannot be closed until the process has finished.

Tip

A good practice is to store the output generated by the script in a text file in case it is necessary to analyze it in detail.

Post-update

Once the upgrade has finished, we will need to check the following before restarting the server.

1. The Ubuntu version is 22.04:

lsb_release -a

2. The Zentyal packages have been upgraded to 8.0:

dpkg -l | egrep 'zen(tyal|buntu)-'

3. There are no broken packages:

dpkg -l | egrep -v '^(ii|rc)'

4. The service networking is disabled:

systemctl is-enabled networking

# In case it is still enabled
sudo systemctl disable --now networking

5. The old network configuration file /etc/network/interfaces is not present:

sudo rm -f /etc/network/interfaces

6. The following services are disabled and stopped:

sudo systemctl status resolvconf named-resolvconf

# In case they are is still enabled or running
sudo systemctl disable --now resolvconf named-resolvconf

7. If all of the above is correct, we can proceed to reboot the server.

8. Once it has started, we will analyze the following log files to confirm that no errors have occurred:

  • /var/log/zentyal/zentyal.log
  • /var/log/syslog.

9 Finally, we will check the operation of each module to make sure that it is stable after the upgrade.

Troubleshooting

In the event that the upgrade has failed, we must identify the point at which the server is where the server is before considering restoring a backup.

Current server status

To confirm the status of the server after the failure during the upgrade, first, we must analyze the log file /var/log/zentyal/upgrade.log. After that, the questions we should ask to determinate if a rollback is needed are:

1. Is Ubuntu version still 20.04 and Zentyal packages 7.1?
If the answer is affirmative and there are no broken packages, there will be no need to restore the backup.
2. Has the Ubuntu version been updated to something other than 22.04?
If the answer is affirmative, a backup will have to be restored, since Zentyal 8.0 is based on Ubuntu 22.04.
3. Have any Zentyal packages been updated?
If no package was updated but Ubuntu was updated to 22.04, we can analyze the log file /var/log/zentyal/upgrade.log and try run the update script again.
4. Have Zentyal packages been updated to a version other than 8.0?
If so, you will have to restore the backup.
5. Are there broken packages?
If Ubuntu and Zentyal were updated but there are broken packages, we can try to fix them without the need to restore a backup.

Broken packages

If you have broken packages, you can try to fix them with the following commands.

To fix all the packages at once:

sudo dpkg --configure --force-confdef -a

Warning

It may be necessary to run the command multiple times

In case this does not work, you will have to do it package by package:

sudo dpkg --configure --force-confdef name_of_the_package

Database MySQL

If we get errors in the log file /var/log/zentyal/zentyal.log related to the service mysql like the following:

2024/04/26 11:04:02 ERROR> MyDBEngine.pm:200 EBox::MyDBEngine::_connect - Connection DB Error: Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
at Connection DB Error: Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
at /usr/share/perl5/EBox/MyDBEngine.pm line 200

And the service is stopped:

sudo systemctl status mysql

We must check if the directory /var/log/mysql/ exists, in case it doesn’t:

sudo mkdir -v -m 0750 /var/log/mysql
sudo chown -R mysql:adm /var/log/mysql

In case it exists, we must run the following commands:

sudo chown -R mysql:adm /var/log/mysql
sudo chmod -R 0750 /var/log/mysql

Finally, we must restart the service. In case the error persists, we must analyze the log files /var/log/syslog and /var/log/mysql/error.log

sudo systemctl restart mysql
sudo systemctl status mysql

Antivirus module

After updating to Zentyal 8.0, if the Antivirus module appears as STOPPED and in the log /var/log/clamav/clamav.log we see the following message:

ERROR: LOCAL: Socket file /var/run/clamav/clamd.ctl could not be bound: Permission denied

What we have to do is modify the owner of the directory /var/run/clamav/ and then reconfigure the package, to do this, we will execute the following commands:

sudo -i
chown clamav:clamav /var/run/clamav/
echo "clamav-daemon     clamav-daemon/debconf boolean false" | debconf-set-selections
DEBIAN_FRONTEND=noninteractive dpkg-reconfigure clamav-daemon

Once we have the package reconfigured, we will only have to restart the module:

sudo zs antivirus restart