2.1. Installation

The Halon programs are installed using a Linux distribution package manager according to the corresponding instructions, or by manually copying the files to the /opt/halon directory.

In preparation; if you have another MTA running on the same host (eg. Exim, Sendmail or Postfix), you should in most installations stop it. To stop Postfix for example:

$ systemctl disable postfix
$ systemctl stop postfix

2.1.1. Ubuntu

To install the .deb package use the following commands.

$ apt-get update
$ apt-get install /path/to/halon.deb

Older version of Ubuntu uses (dpkg -i instead of apt-get install).

2.1.2. CentOS

To install the .rpm package use the following commands.

$ yum install -y epel-release
$ yum install -y /path/to/halon.rpm

The default configuration allows users in the staff group to manage the MTA

$ sudo groupadd staff

2.2. Upgrade

In order to upgrade the package, install the new package over the previous installed one (see the installation chapter). After the upgrade the service will be stopped and requires to be manually started. Important upgrades notes will be published in the release notes documents. Those may include

  • Configuration version compatibility

  • Protobuf API compatibility

  • C plugin API compatibility

2.3. Configuration

Each program has a small startup configuration, which contains settings such as control socket paths and user privilege drop. Most importantly, they point at the running configuration load path via environment.appconf. There are multiple sample configuration files in /opt/halon/share/examples directory. The running configuration contains the bulk of the configuration data, including all the Halon script.

The following sample configuration are available.

  • /opt/halon/share/examples/minimal

    • listen on localhost, port 25

    • deliver messages by lookup mx

    • contains only necessary configuration

  • /opt/halon/share/examples/standard

    • listen on all addresses, port 25 and 587

    • port 25: forward messages to a local server

    • port 587: deliver messages by lookup mx

    • contains a lot of example configuration

To quickly get started, follow the steps below.

$ mkdir -p test/dist
$ cd test
$ cp -r /opt/halon/share/examples/minimal src
$ halonconfig
$ sudo cp dist/* /etc/halon/

  • A sample configuration in /opt/halon/share/examples/{minimal,standard} is copied to a working directory

  • The halonconfig script prepares the configuration files

    • It validates the configuration files in src/config against the JSON schemas

    • It “packs” the script in src/hooks and src/files into the smtpd-app.yaml running configuration

    • It writes the result to the dist directory

  • The prepared configuration is copied from dist/ to /etc/halon/

When the initial configuration is in place, the programs can be enabled on system boot and started with:

$ sudo systemctl enable halon.service
$ sudo systemctl start halon

The default minimal configuration allows you to relay email on port 25 from localhost (port 587 when using the default standard configuration), so you can send a test email using for example swaks:

$ swaks --server 127.0.0.1 --port 25 --to [email protected]