Upgrade procedure

Before doing any upgrade create a backup of all the system settings with the Backup Manager (Admin → Backup). The backup contains all the relevant system settings like users, certificates, keys, MTA settings etc.

The actual upgrade procedure depends on how CipherMail is installed.

Tip

After an upgrade, restart your browser or clean the browser cache to make sure that updated CSS files are being reloaded.

Virtual Appliance

If you are using the CipherMail Professional or Enterprise edition Pro/Ent only, the gateway will automatically upgrade using our online repository or we will provide an executable which will upgrade the gateway in place.

Note

In certain cases, an in-place upgrade is not provided, for example because the underlying OS is updated to a major new version and an upgrade path is not available. When an in-place update is not available, install the new version and backup/restore the settings from the old system to the new system.

Backup/restore to a new virtual machine

To upgrade to a new major release, use the following procedure:

  1. Create a backup on the old VM

  2. Install the new VM

  3. Import the backup into the new VM

Create a backup on the old VM

Create a backup of all system settings (Admin ‣ Backup).

Note

A backup can be protected with a password. It is however advised to export the backup without a password because there might be some incompatible changes on how the backup is encrypted between releases.

Install the new VM

Import the VM into VMware, HyperV or some supported system and configure the network.

Import the backup

Import the backup into the new system (Admin ‣ Backup).

Note

The backup does not contain the SSL/TLS certificate. The SSL/TLS certificate should be manually restored.

Using the packages

If the gateway has been installed with one of the provided packages (.deb or .rpm) the gateway can be upgraded in-place by installing the new packages.

Upgrade from version ≤ 4

The following list of changes with release 5 are relevant for the upgrade process:

  • The Postgres packages are removed. Postgres should be configured manually.

  • The SUSE specific rpm is removed. The rpm’s are now usable for Red Hat/CentOS and SUSE.

  • The packages now require a ciphermail-core-os package.

  • Administrators can now log in with their Unix credentials via PAM authentication.

  • Systemd is now required.

Note

For a list of all release notes, see https://www.ciphermail.com/gateway-release-notes.html

Core OS package

A package (rpm or deb) can contain a list of required packages. When the package is installed, the package manager (apt, yum, zypper…) checks if all required packages are installed and if not suggests to install the required packages or refuses to install the package.

While providing a list if required packages is helpfull, it is however impossible to create a package which can be installed on different Linux versions/distributions and at the same time provide a list of all required packages. The main reason this is impossible, is that the list of required packages differs between different Linux distributions/versions.

In previous version of CipherMail, the packages did not provide any package requirements. Before installing the packages, the administrator had to make sure that all required packages were installed. From version 5 and up, the CipherMail core packages now depend on a virtual OS dependency package named ciphermail-core-os. The virtual OS dependency package provides the list of required packages.

Currently there are 3 virtual OS dependency packages all providing the required ciphermail-core-os package

  • ciphermail-core-os-debian

  • ciphermail-core-os-rhel8

  • ciphermail-core-os-no-deps

ciphermail-core-os-debian is for debian based systems (Debian and Ubuntu), ciphermail-core-os-rhel8 is for Red Hat 8 based systems (RHEL8/CentOS 8 stream).

ciphermail-core-os-no-deps is a special package. The ciphermail-core-os-no-deps package provides the required dependency ciphermail-core-os without providing any additional requirements. If ciphermail-core-os-no-deps is installed, the CipherMail package dependecies behave exactly as it was in versions ≤ 4, i.e., no additional dependencies.

When upgrading an existing setup, it’s therefore recommended to install ciphermail-core-os-no-deps.

PAM authentication

Administrators can now login with their Unix credentials if the Unix user is a member of the wheel or sudo group. For example user of the virtual appliance can now login with the user sa using the password of the sa user. Administrators logged in via PAM authentication have full admin rights.

PAM authentication can be disabled from the GUI after logging in (see Admin page).

Alternatively, PAM authentication can be disabled by overriding the default PAM setting with a property file:

echo "pam.enabled=false" | sudo tee /usr/share/djigzo/conf/djigzo.properties.d/disable-pam.properties

Logging

CipherMail now requires Systemd. The back-end log is now written to journald and via rsyslog written to the log file /var/log/ciphermail-gateway-backend.log. The back-end log file was world readable in previous releases. The back-end log file is now only readable by root.

Instead of directly accessing the log file, the back-end log can also be viewed with journalctl

sudo journalctl -u ciphermail-gateway-backend

The back-end service should now be started and stopped using systemctl.

Examples:

sudo systemctl sart ciphermail-gateway-backend
sudo systemctl stop ciphermail-gateway-backend
Systemd Journal Rate Limiting

Journald will start dropping log messages if the number of log messages from a process exceeds some limit.

A message similar to the following will be written to the logs if messages are dropped:

May  11 10:00:00 gateway journal: Suppressed 7124 messages from ...

To increase the limit at which message will be dropped, change the following journald settings: RateLimitInterval and RateLimitBurst

Rsyslog Rate Limiting

Rsyslog will start dropping log messages if the number of log messages from a process exceeds some limit.

To increase the limit at which message will be dropped, change the following Rsyslog settings: imjournalRatelimitInterval and imjournalRatelimitBurst

Upgrade Ubuntu/Debian

Stop services
sudo service postfix stop
sudo service djigzo stop
sudo service tomcat[5-9] stop
Install OS dependency package
sudo dpkg -i ciphermail-core-os-no-deps_[0-9]*[0-9]_all.deb
Update packages
sudo dpkg -i djigzo_[0-9]*[0-9]_all.deb djigzo-web_[0-9]*[0-9]_all.deb
Clear Tomcat cache

After an upgrade, the Tomcat cache file should be cleared.

Note

Tomcat caches certain files. The cache is not cleared even after a restart of Tomcat. To make sure that files from the previous version of CipherMail do not interfere with files from the newly installed version, you are strongly advised to clear the Tomcat cache.

sudo rm -r /var/cache/tomcat[5-9]/Catalina/localhost/ciphermail
sudo rm -r /var/cache/tomcat[5-9]/Catalina/localhost/web
Restart services
sudo systemctl restart rsyslog
sudo systemctl restart tomcat[5-9]
sudo systemctl restart ciphermail-gateway-backend
sudo systemctl restart postfix

Upgrade RedHat/CentOS

Stop services
service postfix stop
service djigzo stop
service tomcat stop
Install OS dependency package
rpm -i ciphermail-core-os-no-deps-[0-9]*[0-9].noarch.rpm
Update packages
rpm -U djigzo-[0-9]*[0-9].noarch.rpm djigzo-web-[0-9]*[0-9].noarch.rpm
Clear Tomcat cache

After an upgrade, the Tomcat cache file should be cleared.

Note

Tomcat caches certain files. The cache is not cleared even after a restart of Tomcat. To make sure that files from the previous version of CipherMail do not interfere with files from the newly installed version, you are strongly advised to clear the Tomcat cache.

rm -rf /var/cache/tomcat/work/Catalina/localhost/ciphermail
rm -rf /var/cache/tomcat/work/Catalina/localhost/web
Restart services
systemctl restart rsyslog
systemctl restart tomcat
systemctl restart ciphermail-gateway-backend
systemctl restart postfix

Upgrade SUSE

Stop services
service postfix stop
service djigzo stop
service tomcat stop
Install OS dependency package
rpm -i ciphermail-core-os-no-deps-[0-9]*[0-9]_all.deb
Update packages
rpm -U djigzo-[0-9]*[0-9].noarch.rpm, djigzo-web-[0-9]*[0-9].noarch.rpm
Clear Tomcat cache

After an upgrade, the Tomcat cache file should be cleared.

Note

Tomcat caches certain files. The cache is not cleared even after a restart of Tomcat. To make sure that files from the previous version of CipherMail do not interfere with files from the newly installed version, you are strongly advised to clear the Tomcat cache.

rm -r /srv/tomcat/webapps/ciphermail
rm -r /srv/tomcat/webapps/web
Restart services
systemctl restart rsyslog
systemctl restart tomcat
systemctl restart ciphermail-gateway-backend
systemctl restart postfix