How can we help?




Follow

MULTI-NODE SPLIT SERVICES: Installation Guide

Roger -

Introduction

The purpose of this document is to provide atmail customers with the information to install the atmail platform in a multi-node splitServices environment. The atmail mail server and atmail suite can be installed on multiple separate nodes and other components can be separated out onto their own servers as capacity and performance demands.

SSH Access

Ansible requires passwordless SSH to be configured on all nodes before running any playbooks. Instructions on how to create/configure a SSH key pair is described in the Installation section below.

Database

The atmail Mail Platform makes heavy use of MySQL Database and Redis memory caches. A highly available MariaDB database is recommended. This could either be master/slave, guid or galera replicated, failover should be transparent to the Atmail mail platform.

Three databases are used:

  • mailserver - Atmail Admin
  • apiserver - JMAP API Proxy
  • dav - Contacts/Calendar/Files

It is recommended to run a cluster for each database for performance, administrative and resilience reasons – issues with one service should not impact another.

Redis memory cache is used for:

  • Session Information for Atmail Mailserver
  • LRU cache for JAP/DAV services
  • LRU cache for RSPAMD

Load balancers

Multi-node presumes services sit behind load balancers that terminate SSL. For end-to-end encryption SSL can also be terminated at the node/service. For the purpose of this document we will terminate SSL at the service.

Overview

The atmail Mail Platform consists of and provides the following services

MX (Mail eXchange) Service

The MX service provides inbound mail for domains hosted on the mail platform. The IPs of this service are what are entered into the domains’ MX DNS entries.

CMR (Client Mail Relay) Service

The CMR service provides outbound SMTP services for clients hosted on the mail platform. It is where third party clients such as Thunderbird, Outlook, Mac Mail, as well as the atmail webmail connect to in order to send email. It is important to note that mailstores are also clients of this service for mail generated such as forwards and autoreplies.

CMA (Client Mail Access) Service

The CMA service provides POP/IMAP connectivity for clients in order to access the mailboxes hosted on the platform. This service proxies connection onto the relevant mailstore, but can also be used for migrations to proxy back to legacy systems. Internally it also provides a proxy for the managed sieve service that the JMAP API uses.

MRR (Mail Routing Relay) Service

The MRR service is an internal only service, accepting mail from the inbound Relays ONLY and making the decision on where to route be it internally to a hosted mailbox or externally to the OMR service.

OMR (Outbound Mail Relay) Service

The OMR service provides an outbound queue service that delivers mail to externally hosted domains via a DNS MX lookup. It is able to sign the outbound mail with a DKIM key if required.

MS (Mail Stores) Service

The MS service provides the store where mailboxes actually reside and hence the end point for imap/pop and smtp deliveries for mailboxes located on the store.

DAV Service

The DAV service provides a calDAV, cardDAV, WebDAV interface for contacts, calendars and files.

Admin Service (Webadmin)

The Admin Service is the heart of the core email system. It provides access to create/update/delete domains and users which is the information the MTAs require to accept and route mail properly. It also holds the UI interface into the ansible inventory and code required for configuring the platform.
The admin service is comprised of the following components
• atmail Mailserver – main api & UI to add/remove domains/users

JAP (JMAP Api Proxy/Webmail) Service

The JAP Service is at the heart of atmails’ webmail. It is this service that interacts with the JS front end UI to provide access to ALL services. The API creates the required connections out to IMAP, SMTP and DAV services to provide access to mail/contacts/calendars etc.

Other software Used

Whilst the JAP/DAV/Admin services are proprietary software written and distributed by atmail, the SMTP/IMAP/POP services as well as the web server are provided using the following 3rd party Open Source software

  • SMTP – Exim
  • IMAP/POP – Dovecot
  • WebServer – Nginx
  • Monitoring of atmail processes - monit
  • Nginx Interface - php-fpm
  • Antispam - rspamd
  • Antivirus - ClamAV

Architecture

For the purpose of this document we will be installing 4 Mailserver nodes and 2 Suite nodes. Mailserver nodes will be installed using the mailsvcs ansible role which includes the following services:

  • Admin
  • MX
  • CMA
  • CMR
  • MRR
  • OMR
  • MS
  • AA

All Suite nodes will be installed using the websvcs ansible role which includes the following services:

  • JAP
  • Webmail
  • DAV

 

 mceclip0.png

Architecture

This document will illustrate how to configure the atmail mail server and atmail suite software in an integrated environment. Our example will use the following hostnames for each service:

admin.yourdomainname.com lb1 10.10.10.1
webmail.yourdomainname.com lb2 10.10.10.2
ms1.yourdomainname.com mailserver 10.10.10.3
ms2.yourdomainname.com mailserver 10.10.10.4
ms3.yourdomainname.com mailserver 10.10.10.5
ms4.yourdomainname.com mailserver 10.10.10.6
suite1.yourdomainname.com suite 10.10.10.7
suite2.yourdomainname.com suite 10.10.10.8
ansible.yourdomainname.com ansible 10.10.10.9
db.yourdomainname.com mariadb 10.10.10.9
redis.yourdomainname.com redis 10.10.10.9

Note: An MX record should be configured in DNS for the email domain yourdomainname.com to relay emails to the admin.yourdomainname.com load balancer.

Mailboxes can be split over multiple mailserver volumes or use a shared volume. For the purpose of this document we will be using a shared volume. An NFS (or similarly shared filesystem) share is mounted to /var/atmail/users on all mailservers nodes. Additionally another NFS (or similarly shared filesystem) share is mounted to /var/lib/atmail/api/cache on all suite nodes.

Installation

Pre-requisites

MINIMUM SYSTEM HARDWARE REQUIREMENTS :


atmail suite - webmail
CPU: 2 cores
RAM: 4 GB
SSD: 20 GB


atmail suite - API server
CPU: 2 cores
RAM: 4 GB
SSD: 40 GB


atmail suite - DAV server
CPU: 2 cores
RAM: 4 GB
SSD: 40 GB


atmail mail server
CPU: 2 cores
RAM: 4 GB
SSD: 40 GB (excluding mail storage)


MINIMUM SYSTEM SOFTWARE REQUIREMENTS
Operating System - CentOS 7.x only

UPDATE
Before starting you need to bring the OS to the latest version of packages by issuing the following command.

yum update -y 

POSTFIX
If you are planning to use the atmail mail server, you will need to remove the Postifx MTA daemon, that is installed by default on CentOS 7.

As you will notice, Postfix is started and listens on localhost on port 25. Proceed with Postfix MTA service removal by issuing the following commands.  

systemctl stop postfix 
systemctl disable postfix  
yum remove postfix -y

RSYSLOG
Logging on suite servers happens on syslog via network on localhost. Syslog needs to be listening on port 514 to be able to receive log entries.

Locate the following lines in /etc/rsyslog.conf and remove the comment sign (#) at the start of the lines.

 #$ModLoad imudp  
 #$UDPServerRun 514  
 #$ModLoad imtcp
 
 #$InputTCPServerRun 514

Then restart rsyslog.

systemctl restart rsyslog  

MariaDB
MariaDB must be installed and configured on the ansible controller before installation of atmail
suite or atmail mail server software.

yum install mariadb mariadb-server -y -q

Once the installation is complete, enable MariaDB to start on boot and start the service:

systemctl enable mariadb
systemctl start mariadb

Ensure that the MariaDB service is active:

systemctl status mariadb
● mariadb.service - MariaDB database server
Loaded: loaded (/usr/lib/systemd/system/mariadb.service; enabled; vendor preset: disabled)
Active: active (running) since Mon 2019-12-09 16:05:34 AEST; 2s ago
Process: 18325 ExecStartPost=/usr/libexec/mariadb-wait-ready $MAINPID (code=exited,
status=0/SUCCESS)
Process: 18237 ExecStartPre=/usr/libexec/mariadb-prepare-db-dir %n (code=exited,
status=0/SUCCESS)
Main PID: 18324 (mysqld_safe)
CGroup: /system.slice/mariadb.service
├─18324 /bin/sh /usr/bin/mysqld_safe --basedir=/usr
└─18487 /usr/libexec/mysqld --basedir=/usr --datadir=/var/lib/mysql --plugindir=/
usr/lib64/mysql/plugin --log-error=/var/log/mariadb/mariadb.log --pid-file...

Finally, run the mysql_secure_installation script:

mysql_secure_installation
SERVERS IN PRODUCTION USE! PLEASE READ EACH STEP CAREFULLY!
In order to log into MariaDB to secure it, we'll need the current
password for the root user. If you've just installed MariaDB, and
you haven't set the root password yet, the password will be blank,
so you should just press enter here.
Enter current password for root (enter for none):
OK, successfully used password, moving on...
Setting the root password ensures that nobody can log into the MariaDB
root user without the proper authorisation.
Set root password? [Y/n]
y
New password:
*********
Re-enter new password:
*********
Password updated successfully!
Reloading privilege tables..
... Success!
By default, a MariaDB installation has an anonymous user, allowing anyone
to log into MariaDB without having to have a user account created for
them. This is intended only for testing, and to make the installation
go a bit smoother. You should remove them before moving into a
production environment.
Remove anonymous users? [Y/n]
y
... Success!
Normally, root should only be allowed to connect from 'localhost'. This
ensures that someone cannot guess at the root password from the network.
Disallow root login remotely? [Y/n]
n
... skipping.
By default, MariaDB comes with a database named 'test' that anyone can
access. This is also intended only for testing, and should be removed
before moving into a production environment.
Remove test database and access to it? [Y/n]
y
- Dropping test database...
... Success!
- Removing privileges on test database...
... Success!
Reloading the privilege tables will ensure that all changes made so far
will take effect immediately.
Reload privilege tables now? [Y/n]
y
... Success!
Cleaning up...
All done! If you've completed all of the above steps, your MariaDB
installation should now be secure.
Thanks for using MariaDB!
You will need to remember the root password as this will be required during the installation.

Test if you are able to run mariaDB:

mysql -u root -p 
Enter password: *********
Welcome to the MariaDB monitor. Commands end with ; or \g. Your MariaDB connection id is 20 Server version: 5.5.64-MariaDB MariaDB Server Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
MariaDB [(none)]> exit
Bye

Make sure MariaDB can respond to connections from the other servers including any DNS Reverse Lookup names / PTR records, you should be able to connect from the remote server with

mysql -u root -p -h db.yourdomainname.com

To check the configuration in MariaDB for remote connections look at the mysql.user table and add any entries as required making sure they have the same set of permissions as the local hosts.

mysql -u root -p 
use mysql
select Host,User,Password from user;
Host User Password
localhost root <matching password>
ansible.yourdomainname.com root <matching password>
127.0.0.1 root <matching password>
::1 root <matching password>
admin.yourdomainname.com root <matching password>
webmail.yourdomainname.com root <matching password>
ms1.yourdomainname.com root <matching password>
ms2.yourdomainname.com root <matching password>
ms3.yourdomainname.com root <matching password>
ms4.yourdomainname.com root <matching password>
suite1.yourdomainname.com root <matching password>
suite2.yourdomainname.com root <matching password>
db.yourdomainname.com root <matching password>
redis.yourdomainname.com root <matching password>
 exit

 In case permissions don’t match a useful command to set them up is

GRANT ALL PRIVILEGES ON *.* TO 'root'@'<ip address>' IDENTIFIED BY PASSWORD ‘<encoded password from above table>’ WITH GRANT OPTION; 

 

OpenSSL

OpenSSL must be installed and configured before installation of atmail suite or atmail mail server software.

yum install openssl openssl-libs -y -q

Firewalld

Ensure you have the appropriate firewalld configuration as this will ensure that the correct ports are opened. By default, all ports other than 22 will be closed.

Check if firewalld is enabled and started

systemctl is-enabled firewalld 
enabled

 

If this command does 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/basic.target.wants/firewalld.service to /usr/lib/systemd/system/firewalld.service.

Start firewalld

systemctl start firewalld 
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

List allowed services

firewall-cmd --list-service 
dhcpv6-client ssh 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=smtpsubmission --add-service=imap --add-service=imaps --add-service=pop3 --add-service=pop3s -- add-service=http --add-service=https --add-service=dhcp --add-service=redis --addservice= mysql --add-service=managesieve --permanent  
success
firewall-cmd --zone=public --add-port=4000/tcp --add-port=8000/tcp --add-port=8008/tcp --addport= 8443/tcp --add-port=9003/tcp --permanent  
success

Reload firewalld

firewall-cmd --reload  
success

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 http https imap imaps managesieve mysql pop3 pop3s redis smtp
smtp-submission smtps ssh
ports: 4000/tcp 8000/tcp 8008/tcp 8443/tcp 9003/tcp

If you are having any connection issues such as a log file reporting connections are failing, turn
off firewalld to see if this is the cause of failure. Another check to perform is that all the listeners
on server are open in firewalld,
netstat -nlpt4 will show the tcp v4 listeners. The commands
above give the same open ports for all servers but you can tune each role to just the listeners for
that role.

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

EXTRA PACKAGES FOR ENTERPRISE LINUX (EPEL)

Some packages are available from the EPEL repository which needs to be accessible.

yum install epel-release -y -q

Install atmail repository

In order for the ansible playbooks to download all required packages the atmail yum repository will need to be configured on all nodes. To install the atmail yum repository run the following command on all nodes:

bash <(curl -s https://repo.atmail.com/add_repo)

Redis

On your redis server, either standalone or as part of the ansible controller install and configure the redis package, this document has redis on the ansible controller.

yum install redis -y 
systemctl enable redis
systemctl start redis

Configure redis so that It listens on both localhost and the server ip address by adding the ip address of this server to the bind statement, only the ip address is needed and not the CIDR

ip a |grep "inet " 
vi /etc/redis.conf

Change the uncommented line bind 127.0.0.1 to

bind 127.0.0.1 <server ip address> 

Restart redis to start the new listener

systemctl restart redis

Configuration management node

The configuration management node (ansible controller) is the node hosting the ansible playbooks. In this example we will be using a standalone server running Ansible, MariaDB and Redis.

On the configuration management node install the following:

yum install atmail-common -y 
yum install atmail-mailserver-ansible -y

As the atmail user create a key pair for passwordless SSH.
The recommended command to generate a key pair with no passphrase is as follows:

su - atmail ssh-keygen -t ed25519 -f ~/.ssh/ansible.identity
Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /var/lib/atmail/mailserver/.ssh/ansible.identity.
Your public key has been saved in /var/lib/atmail/mailserver/.ssh/ansible.identity.pub.
The key fingerprint is:
SHA256:mdGO59BX6+Ne/NgJrZq95z6NQu43DawxLMt04lVElfM atmail@<ansible controller>
The key's randomart image is:

so we go back to root

exit

 Add the new public key to root’s authorized_keys file on all nodes.

On the ansible controller as root user

cd /root
mkdir .ssh
chmod 700 .ssh/
cd .ssh/touch authorized_keys
chmod 600 authorized_keys
cat /var/lib/atmail/mailserver/.ssh/ansible.identity.pub >>authorized_keys

On all the other servers as root user

cd /root
mkdir .ssh
chmod 700 .ssh/
cd .ssh/
touch authorized_keys
chmod 600 authorized_keys

Change the <ansible_controller> for hostname of your server

scp root@<ansible_controller>:/var/lib/atmail/mailserver/.ssh/ansible.identity.pub authorized_keys

Back on the Ansible Controller server we will run the first installation playbook is pb_setup.yml. This playbook provides a choice of three modules, each creating the database required.

• mailserver
• apiserver
• dav

mailserver module

As the atmail user run the following command:

su - atmail
ansible-playbook pb_setup.yml

Note: given nothing is in the ansible inventory at this time the following warnings will be seen and can be ignored.
[WARNING]: Unable to parse /var/lib/atmail/mailserver/inventory as an inventory source
[WARNING]: No inventory was parsed, only implicit localhost is available [WARNING]: provided hosts list is empty, only localhost is available. Note that the implicit localhost does not match 'all'

This will prompt you for the module to configure, choose the mailserver module. Also for the db host details of where the MariaDB database resides, this server must be configured to allow connections from this server, mysql.user should include the hostname of the

Ansible Controller or if the db server is the same as the Ansible Controller then the FQDN of this server can be used or the loopback ip address.

Enter atmail_module (mailserver|apiserver|dav) > : mailserver
Enter db host for above module > [127.0.0.1]: db.yourdomainname.com
Enter account for db that has user create and grant privileges > [root]:
Enter password for above account > : ********
The playbook will show you what is about to be configured and wait for you to press any key TASK [setup : debug]
************************************************************************************************************** ***
ok: [localhost] => { "msg": "Configuring atmail-mailserver on db.yourdomainname.com" }

TASK [setup : pause] ************************************************************************************************************** ***
[setup : pause] Press return key to continue !:

The next playbook is pb_setup_inventory.yml. This playbook configures the local inventory for ansible and configures access to a dynamic inventory script. The session is currently logged in as the atmail user so we need to exit and as the root user run the following commands:

exit 
cd /var/lib/atmail/mailserver
ansible-playbook pb_setup_inventory.yml

This will prompt you for the host details where the database resides.

Enter db host for mailserver > [127.0.0.1]: db.yourdomainname.com

When complete check to ensure that dynamic inventory is working by running:

su - atmail 
./inventory/atmailInventory.pl --list

This should return a JSON result listing the inventory.

The last playbook to run is pb_setup_roles.yml. This creates the accounts for the mailserver roles.

As the atmail user run the following command:

ansible-playbook pb_setup_roles.yml 

This will prompt you for the host details of where the database resides.

Enter db host for mailserver > [127.0.0.1]: db.yourdomainname.com
Enter account for db that has user create and grant privileges > [root]:
Enter password for above account > : ********
Enter chosen architecture (splitServices|fullScale) > : splitServices

 apiserver module

As the atmail user run the following command:

 ansible-playbook pb_setup.yml 

This will prompt you for the module to configure. Enter the apiserver module and the host details of where the apiserver database resides.

Enter atmail_module (mailserver|apiserver|dav) > : apiserver 
Enter db host for above module > [127.0.0.1]: db.yourdomainname.com
Enter account for db that has user create and grant privileges > [root]:
Enter password for above account > : ********

dav module

As the atmail user run the following command:

ansible-playbook pb_setup.yml

This will prompt you for the module to configure. Enter the dav module and the host details of where the dav database resides.

Enter atmail_module (mailserver|apiserver|dav) > : dav
Enter db host for above module >  [127.0.0.1]: db.yourdomainname.com
Enter account for db that has user create and grant privileges >  [root]:
Enter password for above account > : ********

Database Accounts

Random passwords are generated for all database accounts and can be found in group_vars/all/vault_*

Configuration

Configuration is made by adding variables into the inventory table or by updating ansible templates.

Return back to the root user

exit

Configure node roles

Add nodes to the inventory table in the amp_msvr database. Please replace yourdomainname.com with your domain. 

mysql -u root -p amp_msvr

 For mailstore servers

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('ms1.yourdomainname.com','_role','name','mailsvcs');

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('ms2.yourdomainname.com','_role','name','mailsvcs');

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('ms3.yourdomainname.com','_role','name',' mailsvcs');

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('ms4.yourdomainname.com','_role','name',' mailsvcs');

 For suite servers

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('suite1.yourdomainname.com','_role','name','websvcs');

insert into inventory(inventoryItem, configSection, configVariable, configValue) values('suite2.yourdomainname.com','_role','name','websvcs');

Show the entries

select * from inventory where configSection='_role' and configValue like '%svcs%';

inventoryId

inventoryItem

configSection

configVariable

configValue

355

ms1.yourdomainname.com

_role

name

mailsvcs

356

ms2.yourdomainname.com

_role

name             

mailsvcs      

357    

ms3.yourdomainname.com

_role              

name             

mailsvcs      

358    

ms4.yourdomainname.com

_role

name             

mailsvcs      

359

suite1.yourdomainname.com

_role

name             

websvcs  

360    

suite2.yourdomainname.com

_role

name             

websvcs      

Configure database locations   

update inventory set configValue='db.yourdomainname.com' where inventoryItem='_all' and configVariable='msvr_db_host';
update inventory set configValue='db.yourdomainname.com' where inventoryItem='_all' and configVariable='jap_db_host';
update inventory set configValue='db.yourdomainname.com' where inventoryItem='_all' and configVariable='dav_db_host';
select * from inventory where configValue = 'db.yourdomainname.com';

inventoryId

inventoryItem

configSection

configVariable

configValue

794    

_all

var                

msvr_db_host

db.yourdomainname.com

795    

_all

var                

jap_db_host

db.yourdomainname.com

796   

_all

var                         

dav_db_host 

db.yourdomainname.com

Configure redis locations

update inventory set configValue='redis.yourdomainname.com:6379' where inventoryItem='_default' and configVariable='redis_addr';
select * from inventory where ConfigVariable='redis_addr';

inventoryId

inventoryItem

configSection

configVariable

configValue

551   

_default

storeman      

redis_addr

redis.yourdomainname.com:6379

575   

_default

cosadm         

redis_addr

redis.yourdomainname.com:6379

641    

_default

apiserver               

redis_addr

redis.yourdomainname.com:6379

 Configure SSL termination

In this example for both Webmail and Webadmin we are terminating SSL at the nodes and not the load balancer. If you wish to terminate at the loadbalancer set lb_ssl_terminate to ‘on’ and ssl_enabled for inventoryItem _mailsvcs and _websvcs to ‘0’

insert into inventory (inventoryItem,configSection,configVariable,configValue) values ('_default','nginx','lb_ssl_terminate','off');
update inventory set configValue = '1' where configVariable= 'ssl_enabled' and inventoryItem = '_mailsvcs';
update inventory set configValue = '1' where configVariable= 'ssl_enabled' and inventoryItem = '_websvcs';
select * from  inventory where configVariable= 'ssl_enabled' or configVariable = 'lb_ssl_terminate';

inventoryId

inventoryItem

configSection

configVariable

configValue

769   

_default

nginx             

lb_ssl_terminate

off           

741   

_mailsvcs

nginx             

ssl_enabled

1

742  

_websvcs

nginx                         

ssl_enabled

1

Configure mailserver endpoint

update inventory set configValue='admin.yourdomainname.com' where configVariable='endpoint_admin' and inventoryItem='_all';
select * from inventory where configVariable = 'endpoint_admin';

inventoryId

inventoryItem

configSection

configVariable

configValue

812

_all

var

endpoint_admin

admin.yourdomainname.com

 Configure Atmail ID and License

update inventory set configValue = '<your atmail id>' where configVariable = 'atmail_id' and configSection = 'var' and inventoryItem = '_all';
update inventory set configValue = '<your suite license>' where configVariable = 'license' and configSection = 'apiserver' and inventoryItem = '_default';
select * from inventory where configVariable = 'atmail_id' and configSection = 'var' or configVariable ='license';

inventoryId

inventoryItem

configSection

configVariable

configValue

753    

_all

var                

atmail_id

<your atmail id>

684    

_default

apiserver      

license           

<your suite license>

Enter the following three update commands without any edits:

update inventory set configValue = '{{ atmail_id }}' where configVariable = 'atmail_id' and configSection = 'cosd' and inventoryItem = '_default';
update inventory set configValue = '{{ atmail_id }}' where configVariable = 'atmail_id' and configSection = 'cosadm' and inventoryItem = '_default';
update inventory set configValue = '{{ atmail_id }}' where configVariable = 'atmail_id' and configSection = 'apiserver' and inventoryItem = '_default';
select * from inventory where configVariable = 'atmail_id'  and configSection != 'aspamd' or configVariable ='license';

inventoryId

inventoryItem

configSection

configVariable

configValue

576    

_default

cosd             

atmail_id

{{ atmail_id }}

581    

_default

cosadm        

atmail_id

{{ atmail_id }}

697   

_default

apiserver                

atmail_id

{{ atmail_id }}

753    

_all

var                

atmail_id

<your atmail id>

684    

_default

apiserver      

license           

<your suite license>

Configure rspamd

update inventory set configValue = 'X-amp-spam-score' where configVariable = 'h_spam_score' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'X-amp-spam-bar' where configVariable = 'h_spam_bar' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'X-amp-spam-report' where configVariable = 'h_spam_report' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'X-amp-spam-override' where configVariable = 'h_spam_override' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'X-amp-whitelisted' where configVariable = 'h_whitelisted' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'X-amp-spam-action' where configVariable = 'h_spam_action' and configSection = 'exim' and inventoryItem = '_default';
update inventory set configValue = 'redis.yourdomainname.com' where configVariable = 'redis_write_servers' and configSection = 'rspamd' and inventoryItem = '_mailsvcs';
update inventory set configValue = 'redis.yourdomainname.com' where configVariable = 'redis_read_servers' and configSection = 'rspamd' and inventoryItem = '_mailsvcs';
select * from inventory where configValue like 'X-amp%' or configVariable like 'redis_%_servers' and inventoryItem='_mailsvcs'; 

inventoryId

inventoryItem

configSection

configVariable

configValue

361   

_default

exim               

h_spam_score

X-amp-spam-score

362   

_default

exim               

h_spam_bar

X-amp-spam-bar

363   

_default

exim               

h_spam_report

X-amp-spam-report

364   

_default

exim               

h_spam_override

X-amp-spam-override

365   

_default

exim               

h_whitelisted

X-amp-whitelisted

493   

_default

exim               

h_spam_action

X-amp-spam-action

725   

_mailsvcs

rspamd          

redis_write_servers

redis.yourdomainname.com

726   

_mailsvcs

rspamd          

redis_read_servers

redis.yourdomainname.com

Configure the apiserver         

update inventory set configValue = '/api' where configVariable = 'base_url' and configSection = 'apiserver' and inventoryItem = '_default';
update inventory set configValue = 'webmail.yourdomainname.com/api' where configVariable = 'endpoint_apiserver' and configSection = 'var' and inventoryItem = '_all';
update inventory set configValue = 'webmail.yourdomainname.com' where configVariable = 'endpoint_hostname' and configSection = 'apiserver' and inventoryItem = '_default';
update inventory set configValue = 'webmail.yourdomainname.com' where configVariable = 'endpoint_webmail' and configSection = 'var' and inventoryItem = '_all';
update inventory set configValue = 'admin.yourdomainname.com:993' where configVariable = 'imap_addr' and configSection = 'apiserver' and inventoryItem = '_default';
update inventory set configValue = 'admin.yourdomainname.com:465' where configVariable = 'smtp_addr' and configSection = 'apiserver' and inventoryItem = '_default';
update inventory set configValue = '1' where configVariable = 'webmail_route_api' and configSection = 'nginx' and inventoryItem = '_default';
select * from inventory where configVariable in ('base_url','endpoint_hostname','endpoint_webmail','endpoint_apiserver','smtp_addr','imap_addr','webmail_route_api');

inventoryId

inventoryItem

configSection

configVariable

configValue

655   

_default

apiserver

base_url

/api

658   

_all

var

endpoint_apiserver

webmail.yourdomainname.com/api

656   

_default

apiserver

endpoint_hostname

webmail.yourdomainname.com 

657 

_all

var

endpoint_webmail

webmail.yourdomainname.com

669   

_default

apiserver

imap_addr

admin.yourdomainname.com:993

662   

_default

apiserver

smtp_addr

admin.yourdomainname.com:465

660   

_default

nginx

webmail_route_api

1

Configure DAV

update inventory set configValue = 'DB' where configVariable = 'backend_auth_mode' and configSection = 'dav' and inventoryItem = '_default';
update inventory set configValue = 'redis.yourdomainname.com' where configVariable = 'cache_backend_host' and configSection = 'dav' and inventoryItem = '_default';
update inventory set configValue = 'changeme' where configVariable = 'smtp_password' and configSection = 'dav' and inventoryItem = '_default';
select * from inventory where configVariable in ('backend_auth_mode','cache_backend_host','smtp_password');

exit

inventoryId

inventoryItem

configSection

configVariable

configValue

1127   

_default

dav

backend_auth_mode

DB                               

1111   

_default

dav

cache_backend_host

redis.yourdomainname.com

1128

_default

dav

smtp_password

changeme

Install Service Roles

The final step is to install the service roles. This will install all software required for each node using the configuration we have made in the inventory table and in ansible templates. As the atmail user run the following:

su - atmail
ansible-playbook pb_config_role.yml --extra-vars "role_id=mailsvcs"


PLAY RECAP **************************************************************************************************************localhost                               : ok=2      changed=1    unreachable=0  failed=0  skipped=0    rescued=0    ignored=0  
ms1.yourdomainname.com  : ok=124  changed=71  unreachable=0  failed=0  skipped=27   rescued=0    ignored=1 
ms2.yourdomainname.com  : ok=124  changed=71  unreachable=0  failed=0  skipped=27   rescued=0    ignored=1
ms3.yourdomainname.com  : ok=124  changed=71  unreachable=0  failed=0  skipped=27   rescued=0    ignored=1
ms4.yourdomainname.com  : ok=124  changed=71  unreachable=0  failed=0  skipped=27   rescued=0    ignored=1

ansible-playbook pb_config_role.yml --extra-vars "role_id=websvcs"

PLAY RECAP **************************************************************************************************************localhost                                  : ok=2    changed=1    unreachable=0  failed=0  skipped=0    rescued=0    ignored=0  
suite1.yourdomainname.com  : ok=92  changed=33  unreachable=0  failed=0  skipped=7    rescued=0    ignored=0  
suite2.yourdomainname.com  : ok=92  changed=33  unreachable=0  failed=0  skipped=7    rescued=0    ignored=0

 Configure Webmail

 On one suite node run the following command to create an apiserver cryptography key:

cd /etc/atmail/api
apiadmin --key_file /etc/atmail/api/.keyring genkey
INFO[2020-01-14T06:08:11Z] Wrote keyFile /etc/atmail/api/.keyring      

 Copy /etc/atmail/api/.keyring to all other suite nodes and restart apiserver:

scp root@suite1.yourdomainname.com:/etc/atmail/api/.keyring /etc/atmail/api/.keyring
systemctl restart apiserver

Update the apiserver schema in one suite node

/usr/bin/apiserver -config /etc/atmail/api/api.conf --updatedb

On one suite node create an admin user by running the following command with your values for username and password, this will be needed later

apiadmin --config /etc/atmail/api/api.conf user add <username> <password> --role=admin

Restart the apiserver on all the suite nodes

systemctl restart apiserver

Configure Certificates for HTTPS

So there are secure connections between the servers the next step is to configure the domain certificates on all the mail and suite servers. We will assume that the new private key is called new-cert.key and certificate chain is called new-cert.pem and that you have copied them onto the servers to /tmp directory.

For Nginx copy the two files new-cert.key and new-cert.pem, renaming them to atmail.key and atmail.pem, and set the correct permissions.

\cp /tmp/new-cert.key /etc/pki/nginx/private/atmail.key
\cp /tmp/new-cert.pem /etc/pki/nginx/certs/atmail.pem

chown root:nginx /etc/pki/nginx/private/atmail.key
chmod 0640 /etc/pki/nginx/private/atmail.key

chown root:root /etc/pki/nginx/certs/atmail.pem
chmod 0444 /etc/pki/nginx/certs/atmail.pem

Restart the services depending on their roles,

on the mail servers run

systemctl restart nginx

and on the suite servers run

systemctl restart nginx apiserver

 You will now be able to use https with a secure trusted connection.

Configure Mailserver

In a browser register your license details by connecting to your installation.

Default access details

https://admin.yourdomainname.com/
Username: admin
Password: admin
Click on Login

mceclip0.png

Enter your atmail ID and the atmail mail server License key.

mceclip1.png

Click on Register license key and you will receive a pop-up window entitled Insecure Password.

mceclip2.png

Click on OK to be taken to the Change Password screen. 

mceclip3.png

Enter both the old and new passwords before pressing the Change button. This will logout this session and ask you to login with the new password.

Configure Webmail Integration

Go to webadmin > Services > Webmail API

Enter the URL of the webmail server/api, so in this example it would be https://webmail.yourdomainname.com/api

Also add the username and password of the API user that you created with apiadmin command above.

 mceclip4.png

Click on Save Settings

Configure Certificates For IMAP, POP3, and SMTP

For IMAP and POP3

\cp /tmp/new-cert.key /etc/pki/dovecot/private/atmail.key 
\cp /tmp/new-cert.pem /etc/pki/dovecot/certs/atmail.pem

chown root:root /etc/pki/dovecot/private/atmail.key

chmod 0640 /etc/pki/dovecot/private/atmail.key

chown root:root /etc/pki/dovecot/certs/atmail.pem
chmod 0444 /etc/pki/dovecot/certs/atmail.pem

Go to webadmin > Services > POP3/IMAP

  • Turn ON Enable SSL POP3/IMAP 
  • Turn ON Force SSL POP3/IMAP before authentication
  • update the entry for SSL certificate path 
  • update the entry for SSL key path

mceclip5.png

Click on Save settings

For SMTP

mkdir -p /etc/pki/exim/private /etc/pki/exim/certs

\cp /tmp/new-cert.key /etc/pki/exim/private/atmail.key
\cp /tmp/new-cert.pem /etc/pki/exim/certs/atmail.pem

chown root:exim /etc/pki/exim/private/atmail.key
chmod 0640 /etc/pki/exim/private/atmail.key

chown root:root /etc/pki/exim/certs/atmail.pem
chmod 0444 /etc/pki/exim/certs/atmail.pem

 

Go to webadmin > Services SMTP

  • Turn ON Force TLS/SSL before auth
  • update the entry for SSL certificate path
  • update the entry for SSL key path

mceclip6.png

Click on Save settings

Configure Class Of Service

Go to webadmin > Services -> CLASS OF SERVICE -> Settings

Enter the URL of the admin server:9003, so in this example it would be https://admin.yourdomainname.com:9003

Also add the username and password of the API user that you created with apiadmin command above.

 mceclip7.png

Click on Save Settings

Publish the changes

The final step is to Publish the configuration for both roles

su - atmail

ansible-playbook pb_config_role.yml --extra-vars "role_id=mailsvcs"

ansible-playbook pb_config_role.yml --extra-vars "role_id=websvcs"

 

Installation is now complete

Webadmin: https://admin.yourdomainname.com
Webmail: https://webmail.yourdomainname.com

Post-installation notes

KNOWN ISSUES

CRON

There are two known issues with the cron jobs for atmail on the mailstores which are held in /etc/cron.d/atmail-mailserver.cron, these can be corrected manually,

vi /etc/cron.d/atmail-mailserver.cron

The first is a missing command from the file, please add the following to run the task to remove deleted accounts from the server

0 10 * * * root php /usr/share/atmail/mailserver/webui/utilities/cron/delete_account.php

The second is the existing command has too many asterisks so does not run, please change

30 23 * * * * root php /usr/share/atmail/mailserver/webui/utilities/cron/atmail.php

to be

30 23 * * * root php /usr/share/atmail/mailserver/webui/utilities/cron/atmail.php

APISERVER

There are a few known issues with log entries in /var/log/atmail/api.log which are being addressed.

DAV INTEGRATION

If installing atmail-dav for contacts and calendars, the invites for an out the box install will not work as the dav sender needs to be set in the dav confilg file.  

On the suite servers open the config.php file

vi /etc/atmail/dav/config.php

Find the DAV_SENDER value define('DAV_SENDER', ''); and update this to your email domain

define('DAV_SENDER', 'noreply@yourdomainname.com');

 Save the update to the config.php file

Now you will be able to send calendar invites.

PHP SETTINGS

On all the mail and suite servers define your timezone for php by editing php.ini and updating the variable to your timezone as displayed below. A list of valid timezones can be found at http://php.net/date.timezone

vi /etc/php.ini

[Date]                                                                                              
 ; Defines the default timezone used by the date functions 
 ; http://php.net/date.timezone                              
date.timezone = Australia/Brisbane

After updating the php.ini file, restart services on mailstores and suite server:

systemctl restart php-fpm nginx

Customisations/overrides

Each of the above roles have ansible playbooks that are extensible by local install. Changes from the standard are held within the templates/amp directory of the role in question, with additional tasks being sourced from config_amp.yml if present in the roles/x/tasks directory. README files are provided that outline what can be added/overridden.

Comments


Contact our support team


+61 (7) 5357 6605       support@atmail.com