Skip to main content

Halon configuration deployment and clustering with Ansible

Halon provides built-in configuration clustering using pre-made Ansible roles and although there are alternative approaches to managing this aspect, our usual recommendation is Ansible, particularly for users without established processes for configuration deployment and clustering. The built-in clustering provides both configuration deployment and, if needed, advanced replacement of settings using so-called "overlays" on a per-host basis.

Getting started​

Below are some instructions on how to get started with a basic Ansible setup, this can be further expanded upon by incorporating additional instructions and creating your own custom roles as needed.

  • Connect over SSH to a host where halon-smtpd is installed

  • Install Ansible from the OS distribution package repository: apt-get install ansible-core

  • Create a playbook.yaml file in the root folder of your Halon configuration:

- hosts:
    - mx
  roles:
    - halon/smtpd
  • Create a hosts file in the same directory which will contain the hostnames of the nodes that the configuration should be deployed to:
[mx]
mx1.example.com
mx2.example.com
  • You can then run the playbook with the specified hosts file to deploy any changes, using the --check flag performs a "dry run" and report back any changes that would have been made without actually executing them.
halonconfig && ansible-playbook -i hosts playbook.yaml --check

The smtpd Ansible role will copy over files and reload/restart the services as necessary, supported files are:

dist/smtpd.yaml
dist/smtpd-app.yaml
dist/smtpd-suspend.yaml
dist/smtpd-policy.yaml
dist/smtpd-delivery.yaml

If for example a change is made to the startup configuration, the service will be restarted but if a change is made to the running configuration it will just be reloaded instead.

Additional roles that come with the halon-rated and halon-dlpd packages can be found at /usr/share/ansible/roles/halon.

Overlays​

Overlays allows you to extend or override content, typically by adding or modifying content within roles or plugins. This is useful when you want to customize settings without altering its original source code.

If you want to have configuration overlays for the different hosts you can create a file in a folder called src/overlay named by the name of the host, a double underscore and the name of the file the overlay should be applied to. An overlay for mx1.example.com would for example use src/overlay/mx1.example.com__smtpd-app.yaml.

The content of this file should follow the syntax of ytt. A sample replacement could look like this.

#@ load("@ytt:overlay", "overlay")

#@overlay/match by=overlay.all
---
servers:
#@overlay/match by="id"
#@overlay/remove
- id: "http"

This example will remove the server ID called "http" when deploying to mx1.example.com.