2. Installation

2.1. Linux

The 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

Note

Some of the software provided from Halon Security AB are subject to export control restrictions listed in category 5D002 of the Annex I of the European Union dual use regulations, Regulation (EU) 2021/821. The software downloaded may not be re-exported or re-transferred without the expressed approval from concerned authority or legislation.

2.1.1. Ubuntu

To install the .deb package use the following commands, replacing the username and password with the provided credentials.

$ HALON_REPO_USER=<username>
$ HALON_REPO_PASS=<password>
$ wget -O- https://raw.githubusercontent.com/halon/pgp-keys/master/pgp-keys/7F0A73B5.gpg | sudo tee /usr/share/keyrings/halon-archive-keyring.gpg > /dev/null
$ . /etc/lsb-release && echo "deb [arch=`dpkg --print-architecture` signed-by=/usr/share/keyrings/halon-archive-keyring.gpg] https://repo.halon.io/ $DISTRIB_CODENAME stable" | sudo tee /etc/apt/sources.list.d/halon.list
$ echo "machine repo.halon.io login $HALON_REPO_USER password $HALON_REPO_PASS" | sudo tee /etc/apt/auth.conf > /dev/null
$ sudo apt-get update
$ sudo apt-get install halon
$ sudo halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS
$ echo "$(($RANDOM % 60)) $(($RANDOM % 24)) * * * root /opt/halon/bin/halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS --syslog" | sudo tee /etc/cron.d/halon-license

To install the optional packages mentioned in the programs section use the following commands

$ sudo apt-get install halon-rated halon-extras-rate
$ sudo apt-get install halon-dlpd halon-extras-dlp

2.1.1.1. Version pinning

To pin the .deb package to a specific minor version, use the following commands

$ cat <<'EOF' | sudo tee /etc/apt/preferences.d/halon
Package: halon
Pin: version 1:5.6.*
Pin-Priority: 1000
EOF
$ sudo apt-get update

Now any future apt-get upgrade will not upgrade the package beyond the 5.6 minor version.

2.1.2. RHEL

To install the .rpm package use the following commands, replacing the username and password with the provided credentials.

Note

The RHEL repository can also be used when installing Halon on CentOS, Rocky Linux or AlmaLinux.

$ HALON_REPO_USER=<username>
$ HALON_REPO_PASS=<password>
$ sudo yum install epel-release
$ REPO="/etc/yum.repos.d/Halon.repo"
$ DIST="rhel$(cat /etc/redhat-release | sed 's/.*release \([0-9]\+\).*/\1/')"
$ echo "[halon]" | sudo tee $REPO
$ echo "name=Halon repository" | sudo tee -a $REPO
$ echo "baseurl=https://$HALON_REPO_USER:$HALON_REPO_PASS@repo.halon.io/dists/$DIST/amd64/stable" | sudo tee -a $REPO
$ echo "gpgcheck=1" | sudo tee -a $REPO
$ echo "gpgkey=https://raw.githubusercontent.com/halon/pgp-keys/master/pgp-keys/7F0A73B5.asc" | sudo tee -a $REPO
$ echo "enabled=1" | sudo tee -a $REPO
$ sudo yum install halon
$ sudo halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS
$ echo "$(($RANDOM % 60)) $(($RANDOM % 24)) * * * root /opt/halon/bin/halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS --syslog" | sudo tee /etc/cron.d/halon-license

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

$ sudo groupadd staff

To install the optional packages mentioned in the programs section use the following commands

$ sudo yum install halon-rated halon-extras-rate
$ sudo yum install halon-dlpd halon-extras-dlp

2.1.2.1. Version locking

To lock the .rpm package to a specific version, use the following commands

Note

Install the yum-plugin-versionlock package instead if you’re using RHEL 7.

$ sudo yum install python3-dnf-plugin-versionlock
$ sudo yum versionlock add halon

Now any future yum update or yum upgrade will not upgrade the package.

2.2. Docker & K8s

For instructions on how to build container images of the programs as well as deploying them on K8s (Kubernetes), see our halon-docker GitHub repository.

2.3. 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.1. Versioning scheme

All packages provided both the base software packages and halon-extras plugins follow the standard format of semantic versioning often referred to as “SemVer”. This allows you to do version pinning on both major.* and major.minor.* releases to safely move between feature and patch releases.

2.3.2. Lifecycle compatibility

The lifecycle of our software releases will follow the lifecycle of the currently supported Linux distributions. For this reason we choose support the LTS (Long Term Support) versions of a specific Linux distribution if possible. For an additional yearly fee the support term may be extended during the Linux distribution extended paid support term.

Distribution

End-of-Life

Final supported version

RHEL 9.x

— 2032

RHEL 8.x

— 2029

RHEL 7.x

Jun 2024

Ubuntu 22.04

Apr 2027

Ubuntu 20.04

Apr 2025

Ubuntu 18.04

Oct 2023

6.0.2

2.4. License

In order for Halon to operate it needs to have a valid non-expired license environment.licensekey. This license can be obtained once with the following command.

$ halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS

Importantly, the license needs to be updated before the end of the license period as the system will not operate without a valid non-expired license. It can easily be done using eg. a cron job. This fetches your license once per day at a random minute and hour.

$ echo "$(($RANDOM % 60)) $(($RANDOM % 24)) * * * root /opt/halon/bin/halonctl license fetch --username $HALON_REPO_USER --password $HALON_REPO_PASS --syslog" | sudo tee /etc/cron.d/halon-license

If running in a container or if you have other ways of deploying Halon where you don’t have cron available, another method needs to be used.

The current license status and expiration can be shown either using the halonctl license show or halonctl process-stats command or using the Web UI.

2.5. 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

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 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 program can be enabled on system boot and started with:

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

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

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

2.6. Programs

This section describes the programs. These are:

  • smtpd which is main MTA server process, and what runs the connect, HELO, AUTH, MAIL, RCPT, EOD, disconnect, pre- and post delivery, and proxy script hooks.

  • hsh that can be used to run standard library functions.

  • halonctl is used to control the MTA.

  • halontop is used to view statistics from the MTA.

  • halonconfig is used to verify and compile the configuration.

These packages can be optionally installed as separate packages:

  • rated that manages operations from the rate() function and synchronise this information in the cluster. A ratectl tool is provided to control the rated daemon.

    It is important to note that since the rated daemon is using UDP for syncing the rates it’s not possible to 100% guarantee that packets are never lost, either during the initial sync at startup or during regular operation. Because of this we recommend using the rate function for things where it’s not critical that the rates are always 100% identical in the cluster and that rate data is never lost. The aim of the rated process is to be a very simple and fast rate database which is why it has been designed this way. Other solutions might be a better fit if data consistency is very important.

  • dlpd that manages operations from the dlp() function. A dlpctl tool is provided to control the dlpd daemon.

2.6.1. Default paths

Each of the programs have default paths for configurations, Unix domain sockets, temporary directories, and the queue. Those are specified in the JSON schemas, but repeated below for your convenience.

smtpd loads its startup configuration from /etc/halon/smtpd.yaml, which have the following defaults:

Setting

Default

Description

environment.appconf

/etc/halon/smtpd-app.yaml

Running configuration

environment.policyconf

/etc/halon/smtpd-policy.yaml

Active queue policies

environment.suspendconf

/etc/halon/smtpd-suspend.yaml

Active queue suspends

environment.deliveryconf

/etc/halon/smtpd-delivery.yaml

Active queue delivery settings

environment.spool.path

/var/spool/halon/queue

Queued messages

environment.publicsuffix

Used by DMARC functions

environment.controlsocket.path

/var/run/halon/smtpd.ctl

Control socket

rated loads its startup configuration from /etc/halon/rated.yaml, which have the following defaults:

Setting

Default

Description

environment.appconf

/etc/halon/rated-app.yaml

Running configuration

environment.controlsocket.path

/var/run/halon/rated.ctl

Control socket

environment.socket.path

/var/run/halon/rated.sock

IPC socket

dlpd loads its startup configuration from /etc/halon/dlpd.yaml, which have the following defaults:

Setting

Default

Description

environment.appconf

/etc/halon/dlpd-app.yaml

Running configuration

environment.tmpdir

/var/spool/halon/tmp

Extracted messages

environment.controlsocket.path

/var/run/halon/dlpd.ctl

Control socket

environment.socket.path

/var/run/halon/dlpd.sock

IPC socket

2.6.2. File permissions

Each of the programs are compiled with default paths for Unix domain sockets, temporary directories, and the queue.

The permissions and user/group settings need to be configured however, but the default configuration files comes with recommended settings as you can see in the /opt/halon/share/examples directory. This default configuration gives users of group staff the privilege of administration via the control sockets.

Below is a description of why those permissions were chosen:

  • smtpd runs as user “halon” with umask 0027. This leaves messages on disk with read/write for user “halon”, and read for group “halon”. The control socket is owned by group “staff” with chmod 0660 which makes it read/writeable by both “staff”.

  • rated runs as “nobody”, and its IPC socket is owned by user/group “halon” with chmod 0660 so that smtpd can communicate with it. Like above, its control socket is owned by group “staff” with chmod 0660.

  • dlpd runs as “halon” with umask 0027 so that it can read the message files and write extracted message parts. Its IPC socket is owned by user/group “halon” with chmod 0600 so that smtpd can communicate with it. Like the others, its control socket is owned by group “staff” with chmod 0660.

2.6.3. Troubleshooting

If the program doesn’t start, this is usually due to an erroneous configuration change. To avoid this, checking the script and configuration with halonconfig (and doing a test deploy with live stage) before configuration deployment is recommended. Certain types of errors can however not be detected by the syntax checker. By default, errors are logged to syslog (which with systemd is managed by journald):

# journalctl -xe -u halon-smtpd
...
Dec 12 03:12:47 mta1 smtpd[57556]: - listen on 192.0.2.5:25
Dec 12 03:12:47 mta1 smtpd[57556]: Could not load configuration: bind: Cannot assign requested address
...

If you want to see startup errors directly on the console you can start smtpd with log sent to foreground (stderr) using the -f flag:

# LD_LIBRARY_PATH=/opt/halon/lib /opt/halon/sbin/smtpd -f
smtpd: Starting Halon (5.3.0)
smtpd: serverid: inbound
smtpd: - listen on 192.0.2.5:25
smtpd: Could not load configuration: bind: Cannot assign requested address