Community Edition updates

Warning

This update procedure is only applicable to the community edition. If you are using the professional edition Pro/Ent only, the gateway will provide an online update mechanism (see Minor updates).

Warning

The update procedures described here, and indeed the Community Edition of CipherMail Gateway, are not covered by CipherMail commercial support. If you need commercial support, please consider a support contract with us. We can assist you with migrating to the latest version of the professional edition.

Before performing the, 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, et cetera.

The actual update procedure depends on how CipherMail Gateway has been installed.

Tip

After an update, restart your browser or clear the browser cache to make sure that updated CSS files are loaded correctly.

Updating the virtual appliance

The steps that follow describe this procedure for updating virtual appliance installations of CipherMail Gateway Community Edition:

  1. Export a backup of the old virtual machine.

  2. Install the new virtual machine image.

  3. Import the backup into the new virtual machine.

Create a backup on the old VM

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

Note

A backup can be encrypted with a password. Sometimes it may be necessary to export the backup without encryption because there might be some incompatible changes in how the backup is encrypted between releases. In that case, make absolutely sure to keep the unencrypted backup safe.

Note

The backup does not contain the TLS certificates and private key. The TLS certificates and private key should be manually restored.

Install the new VM

Import the VM into VMware, HyperV, KVM/QEMU or whatever your hypervisor of choice is and configure the network.

Import the backup

Start the new VM and import the backup (Admin ‣ Backup). You will need to restore your TLS certificates and private keys separately.

Well done, you have updated your CipherMail Community Gateway appliance!

Updating the packages

Note

Virtual appliance users don’t need to update the CipherMail packages as long as they follow the appliance update procedure above.

If the Community Gateway has been installed with one of the provided (Debian or RPM) packages, the Community Gateway can be updated using your distribution’s package manager. This procedure is more involved compared to updating the virtual appliance.

It is wise to perform a backup before updating. You will also need the new distribution packages which you can download here: https://www.ciphermail.com/downloads-gateway-distributions.html

Major changes in version 5.0

The following changes in CipherMail Community Gateway 5.0 are relevant for the update process:

  • The PostgreSQL packages have been removed. PostgreSQL should be configured manually.

  • The SUSE-specific RPM package has been removed. The RPM packages are now usable for both RHEL/CentOS and SUSE Linux.

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

  • Systemd is now required.

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

Note

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

Core OS package

Any Debian or RPM package can contain a list of required packages. When the package gets installed, the package manager (APT or dpkg for Debian/Ubuntu, DNF, Zypper or RPM for RHEL/CentOS/SUSE) makes sure that all dependencies get installed as well.

In previous versions of CipherMail Gateway, the packages did not provide any dependency information. Before installing the packages, the administrator had to make sure that all required software was preinstalled. Since CipherMail Gateway 5.0, 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 three virtual OS dependency packages that all provide 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 RHEL 8 and CentOS 8 Stream.

ciphermail-core-os-no-deps is a special package. It provides the required dependency ciphermail-core-os without having any requirements itself. If ciphermail-core-os-no-deps is installed, the CipherMail package dependecies behave exactly as things were in versions before 5.0. When upgrading an existing setup, it is therefore recommended to install ciphermail-core-os-no-deps.

PAM authentication

Administrators can now log in with their Unix credentials if their account is a member of the wheel or sudo groups. For example, users of the virtual appliance can now log in on the web interface with the user account sa and the corresponding password. Users logged in with PAM authentication have full admin rights in the web interface.

PAM authentication can be disabled from the web interface after logging in (see the 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

systemd

CipherMail Gateway now requires systemd. The backend log is now processed using journald and gets written via rsyslog to the log file /var/log/ciphermail-gateway-backend.log. The backend log file was world-readable in previous releases. It is now only readable by the root user.

Instead of directly accessing the log file, the backend log can also be viewed with journalctl:

sudo journalctl -u ciphermail-gateway-backend

The backend service should now be started and stopped using systemctl:

sudo systemctl start ciphermail-gateway-backend
sudo systemctl stop ciphermail-gateway-backend

Journal rate limiting

journald will start dropping log messages if the number of log messages from a process exceeds the 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 ...

Change the RateLimitInterval and RateLimitBurst journald settings to modify this limit.

Rsyslog rate limiting

Rsyslog has built-in rate limiting as well. Modify imjournalRatelimitInterval and imjournalRatelimitBurst to change the default rate limit settings.

Step 1: stop services

On Debian and Ubuntu:

sudo service postfix stop
sudo service djigzo stop
sudo service tomcat[5-9] stop

On RHEL, CentOS and SUSE:

sudo service postfix stop
sudo service djigzo stop
sudo service tomcat stop

Step 2: install OS dependency package

On Debian and Ubuntu:

sudo dpkg -i ciphermail-core-os-no-deps_[0-9]*[0-9]_all.deb

On RHEL, CentOS and SUSE:

sudo rpm -i ciphermail-core-os-no-deps-[0-9]*[0-9].noarch.rpm

Step 3: update CipherMail Gateway backend and frontend

On Debian and Ubuntu:

sudo dpkg -i djigzo_[0-9]*[0-9]_all.deb djigzo-web_[0-9]*[0-9]_all.deb

On RHEL, CentOS and SUSE:

sudo rpm -U djigzo-[0-9]*[0-9].noarch.rpm djigzo-web-[0-9]*[0-9].noarch.rpm

Step 4: clear Tomcat cache

Note

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

On Debian and Ubuntu:

sudo rm -r /var/cache/tomcat[5-9]/Catalina/localhost/ciphermail
sudo rm -r /var/cache/tomcat[5-9]/Catalina/localhost/web

On RHEL and CentOS:

sudo rm -rf /var/cache/tomcat/work/Catalina/localhost/ciphermail
sudo rm -rf /var/cache/tomcat/work/Catalina/localhost/web

On SUSE:

sudo rm -r /srv/tomcat/webapps/ciphermail
sudo rm -r /srv/tomcat/webapps/web

Step 5: restart services

On Debian and Ubuntu:

sudo systemctl restart rsyslog
sudo systemctl restart tomcat[5-9]
sudo systemctl restart ciphermail-gateway-backend
sudo systemctl restart postfix

On RHEL, CentOS and SUSE:

sudo systemctl restart rsyslog
sudo systemctl restart tomcat
sudo systemctl restart ciphermail-gateway-backend
sudo systemctl restart postfix

Well done, you have updated your CipherMail Community Gateway packages!