How can we help?

Watch this space: Upcoming Help Centre Migration


atmail 8.7 UPGRADE GUIDE

Steve -

What is atmail suite

atmail suite is a browser-based email client and comprises of the email client and JMAP API.  This can be integrated with atmail DAV to provide contacts and calendar as well.

What is atmail mail server

The atmail mail server provides admin users with a GUI to perform many of the admin tasks related to running an email system. 

Some of the functionality provided by the mail server is:

  • the ability to create domains, accounts, sub-domains, and reset passwords.
  • Control settings related to IMAP, POP, and SMTP.
  • Integration of mail server and atmail suite.

Purpose of this guide

The instructions that follow will take you through the upgrade steps for atmail suite and then atmail mail server from 8.6.x to 8.7.x, If you only have a single server you apply all these steps to your server or if you have a Dual Server setup then apply the atmail suite or atmail mail server steps as required to each server.

Pre-upgrade notes


Before you upgrade the atmail suite, please make sure you meet the minimum system requirements.  

Minimum system software requirements

Operating System - CentOS 7.x and Redhat Enterprise 7.x only.

Publish config

Before starting the upgrade check that Publish config is in a working state already. Login to the Admin UI and go to  Services and press Publish config.



Make sure that Publish config completes successfully, that there are no failed steps reported in the PLAY RECAP. Should this command fail please stop any further upgrade steps and log a support ticket to obtain help on the issue.

PLAY RECAP *********************************************************************
localhost : ok=67 changed=11 unreachable=0 failed=0 skipped=6 rescued=0 ignored=1


This is required before you upgrade in case you need to roll-back any changes.

atmail suite

Ascertain the current version.

rpm -qa atmail-webmail atmail-api

Backup the apiserver database, you will need to enter the mysql root password.

mysqldump -u root -p -d apiserver > apiserver-`rpm -qa atmail-api | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.sql

Backup both apiserver and webmail files.

tar cfvz suite-`rpm -qa | grep atmail-webmail | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.tgz apiserver*.sql /etc/atmail/api /etc/atmail/webmail /etc/nginx/conf.d/atmail-api.locations /etc/nginx/conf.d/atmail-webmail.locations /var/lib/atmail/api /usr/share/atmail/webmail

 This will give you two files, the mysql apiserver database backup and the atmail suite tar file.

-rw-r--r--. 1 root root    15948 Apr 21 14:21 apiserver-8.6.0_20200421.sql
-rw-r--r--. 1 root root  3910268 Apr 21 14:22 suite-8.6.0_20200421.tgz

atmail mail server

Ascertain the current version.

rpm -qa atmail-mailserver

Backup the mailserver database.

mysqldump -u root -p -d mailserver > mailserver-`rpm -qa atmail-mailserver | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.sql

Backup the mailserver files.

tar cfvz mailserver-`rpm -qa atmail-mailserver | sed 's/-/ /g' | awk '{print $3}'`_`date +"%Y%m%d"`.tgz mailserver-*.sql /etc/atmail/mailserver /etc/nginx/conf.d/atmail-mailserver.locations /var/lib/atmail/mailserver /var/lib/atmail/dovecot /usr/share/atmail/mailserver/

 This will give you two files, the mysql mailserver database backup and the atmail mail server tar file.

-rw-r--r--. 1 root root    36937 Apr 21 13:39 mailserver-8.6.0_20200421.sql
-rw-r--r--. 1 root root 11099072 Apr 21 13:41 mailserver-8.6.0_20200421.tgz


If you have not done so already it is recommended to remove the Postifx MTA daemon that is installed by default on CentOS 7 so that it cannot start during a server reboot.

Check if Postfix is installed.

rpm -qa postfix

Should you find postfix is still installed please remove it.

systemctl stop postfix
systemctl disable postfix

yum remove postfix -y


Make sure you have the mariadb root password to hand.


Ensure you have the appropriate firewalld configuration as this will ensure that the correct ports are opened.  

List allowed services and ports. 

firewall-cmd --list-all | grep 'services\|ports' | head -n 2
services: dhcp dhcpv6-client https imap imaps pop3 pop3s smtp smtps ssh
ports: 8443/tcp 587/tcp

Please note, by default Exim does not have a service running on 587/tcp so this addition is optional.

Should the output match above you can continue with the EXTRA PACKAGES FOR ENTERPRISE LINUX (EPEL) section, if you want to check the firewalld configuration continue here.

Check firewalld is enabled.

systemctl is-enabled firewalld

If this command do not return enabled you should perform the next command
systemctl enable firewalld
Created symlink from /etc/systemd/system/dbus-org.fedoraproject.FirewallD1.service to /usr/lib/systemd/system/firewalld.service.
Created symlink from /etc/systemd/system/ to /usr/lib/systemd/system/firewalld.service.

Check firewalld is running.

systemctl status firewalld
● firewalld.service - firewalld - dynamic firewall daemon
   Loaded: loaded (/usr/lib/systemd/system/firewalld.service; enabled; vendor preset: enabled)
   Active: active (running) since Tue 2017-06-27 16:53:32 AEST; 5s ago

Start firewalld if the above command shows Active: inactive (dead)

systemctl start firewalld

Add required services: HTTPS, SMTP, IMAP, POP3, DAV, DHCP (May be required in a testing environment).

firewall-cmd --zone=public --add-service=smtp --add-service=smtps --add-service=imap --add-service=imaps --add-service=pop3 --add-service=pop3s --add-service=https --add-service=dhcp --permanent
firewall-cmd --zone=public --add-port=587/tcp --add-port=8443/tcp --permanent

Reload firewalld.

firewall-cmd --reload

List allowed services and ports. Check for previously added additions. Please note, by default Exim does not have a service running on 587/tcp so this addition is optional.

firewall-cmd --list-all | grep 'services\|ports' | head -n 2
services: dhcp dhcpv6-client https imap imaps pop3 pop3s smtp smtps ssh
ports: 8443/tcp 587/tcp

 Further information on the use of firewalld can be seen at on our Help Centre page firewalld 


Some packages are available from the EPEL repository

yum install -y

CentOS package upgrades

Check the server has all the required CentOS packages.

yum list installed clamav exim mariadb mariadb-server nginx openssl openssl-libs php php-fpm redis
Installed Packages
clamav.x86_64 0.99.2-1.el7 @epel
exim.x86_64              4.92.3-1.el7         @epel   
mariadb.x86_64           1:5.5.64-1.el7       @base   
mariadb-server.x86_64    1:5.5.64-1.el7       @base   
nginx.x86_64             1:1.16.1-1.el7       @epel   
openssl.x86_64           1:1.0.2k-19.el7      @anaconda
openssl-libs.x86_64      1:1.0.2k-19.el7      @anaconda
php.x86_64               5.4.16-46.1.el7_7    @updates
php-fpm.x86_64           5.4.16-46.1.el7_7    @updates
redis.x86_64             3.2.12-2.el7         @epel   

Use yum install to install any packages that are missing.

atmail 8.7 uses clamav-0.100.0-1 or later, however clamav does not update easily with yum.

First take backups of the existing files

cp /etc/clamd.d/scan.conf /etc/clamd.d/scan.conf.backup
cp /etc/sysconfig/freshclam /etc/sysconfig/freshclam.backup
cp /etc/freshclam.conf /etc/freshclam.conf.backup
cp /var/lib/clamav/main.cvd /var/lib/clamav/main.cvd.backup
cp /var/lib/clamav/daily.cvd /var/lib/clamav/daily.cvd.backup
cp /var/lib/clamav/bytecode.cvd /var/lib/clamav/bytecode.cvd.backup

before removing the old version

yum remove clamav-filesystem
Running transaction
  Erasing    : clamav-0.99.2-1.el7.x86_64                       1/9
  Erasing    : clamav-scanner-0.99.2-1.el7.noarch          2/9
  Erasing    : clamav-scanner-systemd-0.99.2-1.el7.noarch   3/9
  Erasing    : clamav-update-0.99.2-1.el7.x86_64           4/9
  Erasing    : clamav-server-systemd-0.99.2-1.el7.noarch     5/9
  Erasing    : clamav-server-0.99.2-1.el7.x86_64            6/9
  Erasing    : clamav-lib-0.99.2-1.el7.x86_64                   7/9
  Erasing    : clamav-data-0.99.2-1.el7.noarch                  8/9
  Erasing    : clamav-filesystem-0.99.2-1.el7.noarch        9/9
  Verifying  : clamav-server-systemd-0.99.2-1.el7.noarch     1/9
  Verifying  : clamav-data-0.99.2-1.el7.noarch                  2/9
  Verifying  : clamav-0.99.2-1.el7.x86_64                       3/9
  Verifying  : clamav-scanner-systemd-0.99.2-1.el7.noarch    4/9
  Verifying  : clamav-filesystem-0.99.2-1.el7.noarch        5/9
  Verifying  : clamav-server-0.99.2-1.el7.x86_64           6/9
  Verifying  : clamav-scanner-0.99.2-1.el7.noarch          7/9
  Verifying  : clamav-lib-0.99.2-1.el7.x86_64                   8/9
  Verifying  : clamav-update-0.99.2-1.el7.x86_64             9/9
  clamav-filesystem.noarch 0:0.99.2-1.el7                                                                                                                                                                   
Dependency Removed:
  clamav.x86_64 0:0.99.2-1.el7         clamav-data.noarch 0:0.99.2-1.el7            clamav-lib.x86_64 0:0.99.2-1.el7     clamav-scanner.noarch 0:0.99.2-1.el7  clamav-scanner-systemd.noarch 0:0.99.2-1.el7
  clamav-server.x86_64 0:0.99.2-1.el7  clamav-server-systemd.noarch 0:0.99.2-1.el7  clamav-update.x86_64 0:0.99.2-1.el7

 and then installing the new version.

yum install clamav clamav-filesystem clamav-lib clamav-update -y
Running transaction
  Installing : clamav-filesystem-0.102.2-4.el7.noarch        1/4
  Installing : clamav-update-0.102.2-4.el7.x86_64           2/4
  Installing : clamav-lib-0.102.2-4.el7.x86_64                  3/4
  Installing : clamav-0.102.2-4.el7.x86_64                      4/4
  Verifying  : clamav-lib-0.102.2-4.el7.x86_64                  1/4
  Verifying  : clamav-0.102.2-4.el7.x86_64                      2/4
  Verifying  : clamav-filesystem-0.102.2-4.el7.noarch        3/4
  Verifying  : clamav-update-0.102.2-4.el7.x86_64          4/4

  clamav.x86_64 0:0.102.2-4.el7                clamav-filesystem.noarch 0:0.102.2-4.el7                clamav-lib.x86_64 0:0.102.2-4.el7                clamav-update.x86_64 0:0.102.2-4.el7

Upgrade any packages that have newer releases.

yum update -y exim mariadb mariadb-server nginx openssl openssl-libs php php-fpm redis

atmail Public Software Repository

It is now possible to connect to the atmail Public Software Repository and allow yum to install the latest software releases directly.

To configure your server to use the repository run

bash <(curl -s


atmail suite Upgrade Notes

  • Use yum to update the atmail-common package.
yum update atmail-common -y
    No packages marked for update
  • Use yum to update the atmail-api package.
yum update atmail-api -y
Retrieving key from
Importing GPG key 0x66A5217A:
 Userid     : "atmail Pty Ltd (atmail RPM repo GPG key) <>"
 Fingerprint: ba0f d11a 30e2 f932 c0a8 dbe7 e12b 62e9 66a5 217a
 From       :
Is this ok [y/N]: y
Running transaction check
Running transaction test
Transaction test succeeded
Running transaction
  Updating   : atmail-api-8.7.6-1.el7.centos.x86_64                                   1/2
  Cleanup    : atmail-api-8.6.0-26.el7.centos.x86_64                                 2/2
  Verifying  : atmail-api-8.7.6-1.el7.centos.x86_64                                    1/2
  Verifying  : atmail-api-8.6.0-26.el7.centos.x86_64                                  2/2
  atmail-api.x86_64 0:8.7.6-1.el7.centos                                                                                                               
  •  Update the database schema
systemctl stop apiserver
apiserver -config /etc/atmail/api/api.conf --updatedb
INFO[0000] Migrations file pairs found: 42
INFO[0000] Applying migration: /var/lib/atmail/api/resources/migrations/42_V800_up.sql
INFO[0000] Rows affected: 1

wait for the migrations to complete, the script stops outputting lines to the screen, and hit Ctrl-C (^C) to exit

  • Restart API service
systemctl restart apiserver
  • Check the status of apiserver and ensure it is active and running.
systemctl status apiserver
● apiserver.service - atmail-api - jmap api for atmail webmail
Loaded: loaded (/usr/lib/systemd/system/apiserver.service; enabled; vendor preset: disabled)

  Drop-In: /etc/systemd/system/apiserver.service.d
   Active: active (running) since Tue 2020-04-21 14:36:37 BST; 13s ago
  Process: 7563 ExecStop=/bin/kill -s QUIT $MAINPID (code=exited, status=0/SUCCESS)
 Main PID: 7622 (apiserver)
   CGroup: /system.slice/apiserver.service
           └─7622 /usr/bin/apiserver -config /etc/atmail/api/api.conf
  • Use yum to update the atmail-webmail package.
yum update atmail-webmail -y
Running transaction
  Updating   : atmail-webmail-8.7.7-1.el7.centos.x86_64                                 1/2
Setting JMAP_API_URI to ..... [ OK ]
Setting Base HREF to / ..... [ OK ]
 Recover Password URL not found - will need to be configured before using if not set globally
  Cleanup    : atmail-webmail-8.6.0-21.el7.centos.x86_64                                2/2
  Verifying  : atmail-webmail-8.7.7-1.el7.centos.x86_64                                 1/2
  Verifying  : atmail-webmail-8.6.0-21.el7.centos.x86_64                                2/2
  atmail-webmail.x86_64 0:8.7.7-1.el7.centos                    

Use yum to update the atmail-dav package.

yum update atmail-dav -y 
Running transaction
  Updating   : atmail-dav-8.7.11-1.el7.centos.x86_64                                1/2
To complete upgrade cd /usr/share/atmail/dav and run php /usr/bin/atmail-dav-update.php
  Cleanup    : atmail-dav-8.6.0-15.el7.centos.x86_64                                2/2
  Verifying  : atmail-dav-8.7.11-1.el7.centos.x86_64                                 1/2
  Verifying  : atmail-dav-8.6.0-15.el7.centos.x86_64                                 2/2
  atmail-dav.x86_64 0:8.7.11-1.el7.centos 

Configure the atmail DAV service

php /usr/bin/atmail-dav-update.php
MEMORY_LIMIT already set.
ENABLE_STORAGE already set.
STORAGE_DIR already set.
STORAGE_TEMP_DIR already set.
ENABLE_CACHE already set.
CACHE_BACKEND already set.
Found 0 updates.
**Please check update notes for configuration changes.
  • Restart services.
systemctl restart php-fpm nginx apiserver

Your atmail suite upgrade is now complete!

Test your upgrade by connecting to webmail via your URL

This completes the atmail suite upgrade and the server is now ready for the atmail mail server upgrade.

atmail mail server Upgrade Notes

  • Use yum to upgrade the dovecot packages, dovecot dovecot-devel dovecot-mysql dovecot-pgsql dovecot-pigeonhole
yum update dovecot* -y
Running transaction
  Updating   : 1:dovecot-2.2.36-3.el7_7.1.x86_64                                            1/6
  Updating   : 1:dovecot-mysql-2.2.36-3.el7_7.1.x86_64                                  2/6
  Updating   : 1:dovecot-pigeonhole-2.2.36-3.el7_7.1.x86_64                        3/6
  Cleanup    : 1:dovecot-pigeonhole-2.2.19-1.atmail.el7.centos.x86_64          4/6
  Cleanup    : 1:dovecot-mysql-2.2.19-1.atmail.el7.centos.x86_64                  5/6
  Cleanup    : 1:dovecot-2.2.19-1.atmail.el7.centos.x86_64                              6/6
  Verifying  : 1:dovecot-2.2.36-3.el7_7.1.x86_64                                            1/6
  Verifying  : 1:dovecot-mysql-2.2.36-3.el7_7.1.x86_64                                   2/6
  Verifying  : 1:dovecot-pigeonhole-2.2.36-3.el7_7.1.x86_64                           3/6
  Verifying  : 1:dovecot-pigeonhole-2.2.19-1.atmail.el7.centos.x86_64           4/6
  Verifying  : 1:dovecot-mysql-2.2.19-1.atmail.el7.centos.x86_64                   5/6
  Verifying  : 1:dovecot-2.2.19-1.atmail.el7.centos.x86_64                              6/6
  dovecot.x86_64 1:2.2.36-3.el7_7.1                             dovecot-mysql.x86_64 1:2.2.36-3.el7_7.1                             dovecot-pigeonhole.x86_64 1:2.2.36-3.el7_7.1                            
  • Use yum to update the atmail-mailserver-ansible rpm.
yum update atmail-mailserver-ansible -y
Running transaction
  Updating   : atmail-mailserver-ansible-8.7.15-3.el7.centos.x86_64               1/2
  Cleanup    : atmail-mailserver-ansible-8.6.0-19.el7.centos.x86_64               2/2
  Verifying  : atmail-mailserver-ansible-8.7.15-3.el7.centos.x86_64               1/2
  Verifying  : atmail-mailserver-ansible-8.6.0-19.el7.centos.x86_64               2/2
  atmail-mailserver-ansible.x86_64 0:8.7.15-3.el7.centos
  • Use yum to update the atmail-cosadm rpm
yum update atmail-cosadm -y
Running transaction
  Updating   : atmail-cosadm-2.2.4-1.el7.centos.x86_64                            1/2
  Cleanup    : atmail-cosadm-1.3.7-1.x86_64                                       2/2
  Verifying  : atmail-cosadm-2.2.4-1.el7.centos.x86_64                            1/2
  Verifying  : atmail-cosadm-1.3.7-1.x86_64                                       2/2
  atmail-cosadm.x86_64 0:2.2.4-1.el7.centos
  • Use yum to update the atmail-mailserver rpm.
yum update atmail-mailserver -y
Running transaction
  Updating   : atmail-mailserver-8.7.15-1.el7.centos.x86_64                       1/2
Updating DB ....[DB-UPDATE] Current DB Version: 8.6.0
[DB-UPDATE] Updating for 8.7.13...
[DB-UPDATE] Completed(8.7.13)
[DB-UPDATE] DB Updated
.. [ OK ]
  Cleanup    : atmail-mailserver-8.6.0-19.el7.centos.x86_64                       2/2
  Verifying  : atmail-mailserver-8.7.15-1.el7.centos.x86_64                       1/2
  Verifying  : atmail-mailserver-8.6.0-19.el7.centos.x86_64                       2/2
  atmail-mailserver.x86_64 0:8.7.15-1.el7.centos
  • Run the atmail-mailserver-install script to configure any new variables. 
  • Use yum to update the atmail-mailserver-plugin-WebmailIntegration rpm.
yum update atmail-mailserver-plugin-WebmailIntegration -y
Running transaction
  Updating   : atmail-mailserver-plugin-WebmailIntegration-8.7.1-1.el7.centos.x86_64 1/2
Adding in any extra config settings to DB ..... [ OK ]
  Cleanup    : atmail-mailserver-plugin-WebmailIntegration-8.6.0-15.el7.centos.x86_64      2/2
  Verifying  : atmail-mailserver-plugin-WebmailIntegration-8.7.1-1.el7.centos.x86_64       1/2
  Verifying  : atmail-mailserver-plugin-WebmailIntegration-8.6.0-15.el7.centos.x86_64      2/2
  atmail-mailserver-plugin-WebmailIntegration.x86_64 0:8.7.1-1.el7.centos
  • Go to webadmin > Services > CLASS OF SERVICE Settings and set CoS Server to localhost:9003


Click on Save Settings

  • Go to webadmin > Services and press Publish config.Publish_config.png
  • Restart services.
systemctl restart php-fpm nginx

Using a browser navigate to the following address:
Open the file using a text editor and ensure it is the version number 8.7.21

This completes the atmail upgrade


Contact our support team

+61 (7) 5357 6605