Deploying a mail server with Ansible

Pangs of conscience

I refused to provide automatic installation scripts since I started the first ISPmail guide for Debian. Why? Because my intention is to help you understand the complexity of setting up your own mail server. The protocols. The software components. The caveats. The features. There are countless copy’n’paste tutorials on the internet that you can follow if you don’t care learning all that. Unfortunately even if those tutorials help you set up a mail server (which quite often does not work) you will not understand how it works nor be able to troubleshoot a faulty installation. I purposely make you do all the tiny steps manually and explain what they mean. Not to torture you but to help and educate you.

But I have to be honest with you. As I’m dealing with mail servers nearly every day I have automated everything that I describe in this guide. So let me share it with you. Just promise me that you won’t take the easy route. Don’t just use the playbook without reading the entire tutorial. I will help you a bit with Ansible and Vagrant but bear with me if I refuse to expain topics that are actually part of the ISPmail guide.

Ansible

The repository is currently in the process of migration for the Buster guide. Sorry about that.

There are various tools to help you install and configure a server – they are called configuration management systems. In their special syntax you describe how you want your system to look like and then the tools checks what has to be done and does it. You can use them to automatically install a whole system or just deploy your own application. Famous pieces of software like that are Puppet and Chef. However both are painful on different levels. More modern alternatives are Ansible and Salt. I have been using Ansible very successfully in the last two years so obviously I chose it for setting up ISPmail servers.

You haven’t tried Ansible? You should. Head over to their introduction page and walk through the first chapter. From now on I expect you to know the basics of playbooks, roles and variables.

Make sure you have Ansible (at least version 1.9) installed. That version is contained in Debian testing or Ubuntu 15.10. Otherwise you can install it as a Debian package from an Ubuntu PPA or – if you don’t mind spoiling your workstation – running “pip install ansible”. Now you can clone my Git repository that contains everything you need. Use Git to clone it to somewhere on the disk of your workstation. It does not belong onto the mail server.

git clone https://git.workaround.org/chaas/ansible-ispmail-jessie.git

Vagrant

This is another very valuable tool. It is mainly used by developers but is also useful for system administrators. Have you ever thought… “Heck, I would just need a quick Debian Jessie installation to try something.”? Vagrant is the answer. It has a repository of prepared installation images that you can download and run as a virtual machine in VirtualBox.

The reason I am mentioning it is that it allows you to run all the tasks necessary to create an ISPmail server in a virtual machine. All the work that is explained in this tutorial is contained in the Ansible playbook and roles in machine-readable form. So with Ansible and Vagrant you can easily simulate a mail server installation in a virtual machine without the need of an actual server. You could use it to play around with it and don’t have to fear breaking it. Should it break you just throw it away and rebuild it.

Install Vagrant and VirtualBox:

apt-get install vagrant virtualbox

My Git repository contains a Vagrantfile that defines what Vagrant is supposed to do. It is very simple indeed:

Vagrant.configure(2) do |config|
  config.vm.box = "debian/jessie64"

  config.vm.provision "ansible" do |ansible|
    ansible.playbook = "ispmail.yml"
    ansible.sudo = true
  end

config.vm.provider "virtualbox" do |vb|
  config.vm.network "private_network", ip: "10.0.0.100"
  end
end

When you start Vagrant it downloads the image “debian/jessie64” from the image repository and boots it. You could already log into a working Jessie installation and administer it with sudo. Then it takes the ispmail.yml file and runs it as an Ansible playbook. That installs the mail server. And it sets up a virtual network on your workstation and makes the virtual server available as 10.0.0.100.

Make sure you are in the directory that contains the Vagrantfile and go create a mail server:

vagrant up

Be patient while the server is provisioned. Downloading the Jessie image takes a bit depending on your internet connection. And the first task “ispmail-packages” downloads and installs quite a lot of software – so give a few minutes. At the end you should just see green and yellow result message. Let me know if any red messages appear because that probably means a bug in the playbook.

After that you can log into the server using

vagrant ssh

And become root…

sudo -i

Of course everything else is set up already. Point your browser to https://10.0.0.100/ and you will get the RoundCube webmail interface. Go to https://10.0.0.100/phpmyadmin to manage the database via PHPmyAdmin. IMAP, POP3 and SMTP work as expected. And the example data described in this guide is already there, too.

To destroy the virtual server again run…

vagrant destroy

Customizing the installation

I am using various variable to allow you to customize the installation. See group_vars/all. Their meaning:

• ispmail_populate_test_data: true
  Populates the database with sample data (e.g. john@example.org)
• ispmail_mysql_mailuser_password: ChangeMe
  MySQL password for the ‘mailuser’ user
• ispmail_mysql_root_password: ChangeMeRoot
  MySQL password for the ‘root’ user
• ispmail_mysql_roundcube_password: ChangeMeRound
  MySQL password for the ’roundcube’ user
• ispmail_dovecot_auth_mechanisms: plain login
  Authentication mechanisms for Dovecot. ‘plain’ is the common mechanism. ‘login’ is needed for old Microsoft clients.
• ispmail_postmaster_address: postmaster@example.org
  Email address of the person who is responsible for the server
• ispmail_webmail_hostname: 10.0.0.100
  Host name to be used for the web server. Should be set to the FQN.
• ispmail_certificate_country: DE
  Entries starting with ‘ispmail_certificate…’ are strings passed to OpenSSL when generating the self-signed certificate.
• ispmail_certificate_state: Hamburg
• ispmail_certificate_location: Hamburg
• ispmail_certificate_organisation: workaround.org
• ispmail_certificate_orgunit: IT-Crowd
• ispmail_certificate_domains:
  – example.org
  You can use multiple hostnames/domains here if your mail server should be used for them. Additional entries get added as “alternate names” in the certificate. The names must exactly match the name that users enter to access the mail server.
• ispmail_certificate_email: postmaster@example.org
• ispmail_certificate_days_valid: 3650
  Number of days that the certificate will be valid

Using Ansible to deploy a real-life server

Have you played with your virtual Vagrant mail server enough? Would you like to deploy a real server with Ansible? That’s easy. After a basic installation of Debian Jessie make sure that you can access the server without authentication – use SSH public key authentication.

Edit the group_vars/all. Choose proper secure passwords (‘pwgen’ is your friend) and set the email addresses, domains and certificate information to values that fit your bill.

Tell Ansible where your mail server is by editing the ‘hosts’ file and changing the ‘default’ host to the FQDN of your server. Then run

ansible-playbook ispmail.yml

You are invited to add a comment if this page helped you. Even though it’s a pretty advanced topic.