1.1. Startup configuration

This is the non-reloadable part of the configuration. By default, smtpd loads it from /etc/halon/smtpd.yaml. It is described by, and can be validated with, the smtpd.schema.json.

It most importantly contains the server listen sockets (bind addresses and ports), PROXY protocol and thread settings.

Note

The example configuration in /opt/halon/example/ that is usually copied to /etc/halon/ during installation contains reasonable defaults. Normally you only need to modify it when adding additional virtual servers, or changing performance related settings such as the number of threads or open files resource limit.

1.1.1. Server directives

The virtual servers[] are configured in the running configuration, but which port(s) and address(es) to listen to needs to be specified in this file. Below is an example for adding a virtual server called “relay”, listening to any IP on port 587:

servers:
  - id: relay
    listeners:
    - port: 587
servers[].listeners[]

Each virtual server must have one or more listen direcives, which specify which TCP port and address to listen on.

servers[].listeners[].port

Which TCP port to listen on. Required.

servers[].listeners[].address

IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses.

servers[].listeners[].backlog

The kernel connection backlog. The default is the system default.

servers[].listeners[].id

An optional ID that can be used for referencing a listen directive from the running configuration so that for example implicit TLS can be enabled on a per-listener basis using servers[].tls.implicit.

servers[].protoprotocol[]

A list of IPv4 or IPv6 addresses to allow the PROXY protocol (v1) from.

servers[].threads.event

The number of servers[] event loop threads, allowing the event loop to take advantage of multiple CPUs. The default is 4.

servers[].threads.script

The number of servers[] script threads running the hooks such as servers[].phases.eod.hook. The default is 32.

1.1.2. Queue directives

queues.threads.event

The number of queue event loop threads, allowing the event loop to take advantage of multiple CPUs. The default is 4.

queues.threads.script

The number of queue script threads running the scripting.hooks.predelivery and scripting.hooks.postdelivery hooks. The default is 32.

spool.path

The email queue spool path. The default is /var/spool/halon/queue.

spool.threads.loader

Number of worker threads that read the spool files into memory during startup. Those are killed off once the spool is loaded. The default is 32.

spool.threads.update

The maximum number of worker threads for API or CLI queue update of the spool files. The default is 32.

1.1.3. Other directives

resolver.threads.event

Number of DNS resolver event pool threads. The default is 1.

pki.private[]

Array of private keys, possibly with X.509 certificates, for use with servers[] and script functions such as PKCS7, RSA, DKIM, client certificates, etc.

The id and privatekey properties are required, and certificate is optional. The private key and certificate should have either a path or data property.

pki:
  private:
    - id: selfsigned
      certificate:
        data: |-
          -----BEGIN CERTIFICATE-----
          ...
      privatekey:
        data: |-
          -----BEGIN PRIVATE KEY-----
          ...

Note

It is also possible to add those to the running configuration, but for privilege separation reasons it’s normally recommended to define private keys here instead, as this startup configuration is read before the privilege drop. It is however possible to load the private key from a path in this startup configuration, and load the certificate from a path in running configuration, which allows you to softly reload the certificate when it changes, as long as the private key stays the same.

scripting.ffi

Enable the use of FFI functions from the script language. The default is false.

scripting.rootpath

Enable accessing files from disk via the File class and the scripting.files[] path, relative from the specified root path. The default is to not allow accessing files on disk.

1.1.4. Environment directives

The default startup configuration that came with the installation package contains reasonable defaults for your platform. Some settings should however be revised.

1.1.4.1. Performance and log

Those settings are typicallt configured depending on your system and use case.

environment.rlimit.nofile

Set the max number of open file descriptors. This should be synchronised with servers[].concurrency.total and queues.concurrency.total. The default is the system default.

environment.syslog.mask

If you are using systemd-journald for syslog(), we strongly recommend masking away LOG_INFO (non-error email transaction) for performance reasons by setting this option to 191. For transaction logging you can use a module from our script library such as Elastic, libjlog or syslog directly to rsyslog. The default is no mask.

environment.syslog.ident

The syslog identity. The default is the program name.

environment.syslog.pid

Log the process ID. The default is false.

1.1.4.2. Configuration paths

Those paths can normally be left unchanged.

environment.appconf

From where to load the running configuration. The default is /etc/halon/smtpd-app.yaml.

environment.policyconf

From where to load the active queue policies. The default is /etc/halon/smtpd-policy.yaml.

environment.suspendconf

From where to load the active queue suspends. The default is /etc/halon/smtpd-suspend.yaml.

environment.deliveryconf

From where to load the active queue delivery settings. The default is /etc/halon/smtpd-delivery.yaml.

1.1.4.3. Other environment

Those settings should normallt be left unchanged. The default startup configuration in /opt/halon/examples that came with the installation package should contain correct parameters for your operating system or distribution. Those settings are described in the programs section.

environment.controlsocket.path
environment.controlsocket.owner
environment.controlsocket.group
environment.controlsocket.chmod
environment.sockets.rated.path
environment.sockets.httprd.path
environment.sockets.dlpd.path
environment.privdrop.user
environment.privdrop.group
environment.publicsuffix
environment.umask