Upgrading the gateway

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

  1. Install new virtual appliance.

  2. Export current database.

  3. Trust SSH key of new appliance.

  4. Download database export.

  5. Import database export.

  6. Restart back-end.

  7. 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:

  1. Print the new SSH public key.

  2. Import the SSH public key into the old appliance.

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


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 root@ /root

Replace by the IP or hostname of the old appliance.


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


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.