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.
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¶
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
Each virtual server must have one or more listen direcives, which specify which TCP port and address to listen on.
Which TCP port to listen on. Required.
IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses.
The kernel connection backlog. The default is the system default.
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
A list of IPv4 or IPv6 addresses to allow the PROXY protocol (v1) from.
The number of
serversevent loop threads, allowing the event loop to take advantage of multiple CPUs. The default is 4.
1.1.2. Queue directives¶
The number of queue event loop threads, allowing the event loop to take advantage of multiple CPUs. The default is 4.
The email queue spool path. The default is /var/spool/halon/queue.
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.
1.1.3. Other directives¶
Number of DNS resolver event pool threads. The default is 1.
privatekeyproperties are required, and
certificateis optional. The private key and certificate should have either a
pki: private: - id: selfsigned certificate: data: |- -----BEGIN CERTIFICATE----- ... privatekey: data: |- -----BEGIN PRIVATE KEY----- ...
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.
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.
18.104.22.168. Performance and log¶
Those settings are typicallt configured depending on your system and use case.
If you are using
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.
The syslog identity. The default is the program name.
Log the process ID. The default is false.
22.214.171.124. Configuration paths¶
Those paths can normally be left unchanged.
From where to load the running configuration. The default is /etc/halon/smtpd-app.yaml.
From where to load the active queue policies. The default is /etc/halon/smtpd-policy.yaml.
From where to load the active queue suspends. The default is /etc/halon/smtpd-suspend.yaml.
126.96.36.199. 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.