4.2. Programs

This section describes the Halon programs. These are:

  • smtpd which is main SMTP server process, and what runs the connect, HELO, AUTH, MAIL, RCPT, EOD, pre- and post delivery script hooks.
  • rated that manages operations from the rate() function and synchronise this information in the cluster.
  • httprd that processes background requests from the http() function.
  • dlpd that scans a message file for content patterns, file types, and such.
  • hsh that can be used to run standard library functions.

4.2.1. Control sockets

The Halon MTA programs accepts commands over control sockets, which in turn is used by management tools such as the command line interface, Visual Studio Code plugin, integrated package’s REST API and web administration. Those are normally installed on a central location, controlling an entire cluster. They can however also be installed on the MTA hosts as well.

If you wish to develop your own custom tools, take a look at the Protocol Buffer API documentation.

4.2.2. 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
environment.sockets.rated.path /var/run/halon/rated.sock rated socket
environment.sockets.httprd.path /var/run/halon/httprd.sock httprd socket
environment.sockets.dlpd.path /var/run/halon/dlpd.sock dlpd 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/queued.ctl Control socket
environment.socket.path /var/run/halon/rated.sock IPC socket

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

Setting Default Description
environment.socket.path /var/run/halon/httprd.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

4.2.3. 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/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 and queued can communicate with it. Like the other two above, its control socket is owned by group “staff” with chmod 0660.
  • httprd also runs as “nobody”, and its IPC socket is also owned by user/group “halon” with chmod 0660. It doesn’t have a control socket.
  • 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.

4.2.4. Troubleshooting

This section describes various ways of troubleshooting.

4.2.4.1. Startup errors

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 statup errors directly on the console you can start smtpd in the foreground:

# 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