Upgrading the Gateway

Upgrading the Gateway to a new major version requires the following steps:

Install new virtual appliance.
Export current database.
Trust SSH key of new appliance.
Download database export.
Import database export.
Restart back-end.
Configure missing settings (MTA, TLS certificate etc.)

Install new virtual appliance

Install the new virtual appliance and make sure the old appliance is accessible over the network on port 22 (SSH) from the new appliance.

Export current database

On the old appliance, export the database in XML form to the directory /root/database.

sudo mkdir /root/database
cd /usr/share/djigzo
sudo database_type=mysql /usr/share/ciphermail-xml-config/scripts/xml-config-tool.sh --export /root/database/

The database export can be found in the directory /root/database.

Trust SSH key of new appliance

The exported database should be imported into the new appliance. This is done using rsync over SSH. To allow SSH connections for the root user from the new appliance, the SSH key of the new appliance should be trusted by the old appliance.

To trust the SSH key of the new appliance, use the following procedure:

Print the new SSH public key.
Import the SSH public key into the old appliance.

Print the new SSH public key

Log into the new appliance with an SSH client.

Tip

If an SSH client is not available, you can log into the cockpit application with your browser and open the terminal from the tools section (see Cockpit Management App )

Print and copy the SSH public key.

cat /etc/ssh/ssh_host_ecdsa_key.pub

The SSH key should look similar to:

ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlz....

Import the SSH public

Log into the old appliance with an SSH client (the default appliance user is sa).

Execute the following command to add the SSH key to the list of trusted SSH keys:

sudo mkdir -p /root/.ssh
echo "ecdsa-sha2-nistp256 AAAAE2V..." | sudo tee -a /root/.ssh/authorized_keys

Warning

Make sure that ecdsa-sha2-nistp256 AAAAE2V... is replaced by the SSH key from the new appliance (which was printed and copied in the previous step).

Alternatively you can use an editor (like for example vi) to manually add the SSH key to the file /root/.ssh/authorized_keys.

Download database export

Log into the new appliance with SSH (or via the cockpit terminal app).

Download the database export from the old appliance to the new appliance:

sudo rsync -ra [email protected]:/root/database /root

Replace 10.7.7.95 by the IP or hostname of the old appliance.

Note

If the SSH key of the new appliance was correctly imported, you should not be asked for the root password. However, because of the sudo command, you might be asked to provide the password for the current logged in user.

The database XML files should now be stored in /root/database.

Import database

On the new appliance, clear the existing database:

cd /usr/share/djigzo
sudo /usr/share/ciphermail-xml-config/scripts/xml-config-tool.sh --clear-database

Warning

Make sure you only clear the database of the newly imported virtual appliance and not the old appliance. Clearing the database cannot be undone unless you have a backup.

On the new appliance, import the existing database:

cd /usr/share/djigzo
sudo /usr/share/ciphermail-xml-config/scripts/xml-config-tool.sh --import /root/database/

Restart back-end

After importing the database, the back-end should be restarted:

sudo systemctl restart ciphermail-gateway-backend

Now log into the new appliance and check if all database settings are restored.

Configure missing settings

The above procedure only transfers settings which are stored in the database. This however does not include the MTA settings, the license, The TLS settings, the cluster configuration. These settings should be manually applied.