help centre
For more info visit

How can we help?

Search our knowledge base for answers to
common questions and latest updates.

My activities New request


introduction to ansible with atmail

Dominic -


What is ansible?
How is ansible used with atmail?


  • atmail mail server.


I would like to further understand ansible's role within atmail mail server.


The latest version of atmail mail server takes advantage of the configuration management software known as ansible. The following document will be divided into the following sections:

What is ansible?

Ansible's main intention is a focus on software orchestration, configuration, automation and deployment. Ansible provides a layer of abstraction above automated tasks that allows for an easy, efficient and flexible management of infrastructure. Primarily used in two ways, ansible can deploy a pre-configured environment or be used for ad-hoc tasks like querying the status of service across multiple nodes. The following are some of the core concepts behind ansible.

  • Playbooks are composed of 'plays'. Playbooks are written in YAML syntax.
  • Tasks make up a play. This is normally the desired action you wish to execute. For example service name=nginx state=started.
  • Roles are units of organisation within ansible that can be used to automatically load tasks and handlers.

How ansible is integrated into the atmail mail server environment?

Ansible is utilised by atmail to write configuration files and then deploy. When you click the publish button from your webadmin, you actually execute the following on the backend:

# sudo -u atmail ansible-playbook /var/lib/atmail/mailserver/mailserver.yml --vault-password-file /etc/atmail/mailserver/.vault

The above command can be broken down into the following segments.

  1. sudo -u atmail <- execute as the atmail user
  2. ansible-playbook <- execute an ansible playbook
  3. /var/lib/atmail/mailserver/mailserver.yml <- path to playbook
  4. --vault-password-file <- execute with auth for editing of sensitive information
  5. /etc/atmail/mailserver/.vault <- path to authentication key

The mailserver.yml file then uses a conditional statement which checks if pb_ss1ip.yml has been defined. If it has, it is executed.

The contents of the pb_ss1ip.yml shows units of organisation that were previously defined as roles. Each defined role will then be executed accordingly.

[root@a8 mailserver]# cat pb_ss1ip.yml
# file: atmail/mailserver/pb_ss1ip.yml

- hosts:
    - ss1ip

    - { role: dovecot }
    - { role: clamav }
    - { role: spamassassin }
    - { role: exim }

In further examining the exim role, it is comprised of various files and directories that support its execution. One directory to make note of is templates. The files located within this directory are the basis of what will become /etc/exim/exim.conf

[root@a8 mailserver]# tree roles/exim/
├── defaults
│   └── main.yml
├── files
│   └──
├── handlers
│   └── main.yml
├── tasks
│   ├── config_ss1ip.yml
│   ├── config.yml
│   ├── empty.yml
│   ├── install_Debian.yml
│   ├── install_RedHat.yml
│   └── main.yml
├── templates
│   ├── dkim_key.j2
│   ├── exim.conf.j2
│   └── ss1ip
│       ├── acl_check_connect.j2
│       ├── acl_check_data.j2
│       ├── acl_check_dkim.j2
│       ├── acl_check_helo.j2
│       ├── acl_check_mail.j2
│       ├── acl_check_mime.j2
│       ├── acl_check_rcpt.j2
│       ├── acl_on_exit.j2
│       ├── acl_on_quit.j2
│       ├── acls.j2
│       ├── authenticators.j2
│       ├── exim.conf.j2
│       ├── macros.j2
│       ├── mail-cfg.j2
│       ├── reject_helo.j2
│       ├── retry.j2
│       ├── rewrite.j2
│       ├── routers.j2
│       └── transports.j2
└── vars
    ├── Debian.yml
    └── RedHat.yml

7 directories, 32 files

In summary, ansible provides the atmail mail server a modular backend configuration that allows for flexibility of publishing and customising your environment. 

If you wish to further explore ansible and its inner workings, please consult the official documentation.

Have more questions? Submit a request


Contact our support team

+61 (7) 5357 6605