3. Configuration

The configuration consists of files in YAML format on disk. The package comes with multiple example configurations in /opt/halon/share/examples.

The YAML configuration files can be edited directly, and validated against the JSON schemas using the halonconfig script. The schemas can be browsed using a tool like Bovet’s docson. They are also included in our Visual Studio Code integration, which provides validation, autocomplete and hover support when editing them.

The YAML configuration allows for byte format and time format syntax in a lot of places. For example time such as servers[].timeout.idle may be specified in the format of ?d?h?m?s. Size fields such as servers[].phases.data.maxsize may be specified in the format of ?(TiB|GiB|MiB|KiB|B).

The YAML configurations support ${ENVIRONMENT:DEFAULT} replacements. In order to interpet a ${STRING} as a replacement use the custom !Env tag in the YAML file as well as start the smtpd process with the --config-env-substitution flag. This can be used to template in strings and numbers (such a default values and API keys etc).

version: !Env "${VERSION:6.10}"
...
monitor:
  apikeys:
    - !Env "${MYAPIKEY}"

Tip

For services started by systemd, command-line flags such as --config-env-substitution, and environment variables are set by editing the service configuration.

Edit the service configuration with sudo systemctl edit halon
Make your edits above the ### Edits below this comment will be discarded line
The empty ExecStart= line is important. This tells systemd to “forget” the command from the original service file and use your new one instead.

[Service]
Environment="HALON_TYPE=staging"
ExecStart=
ExecStart=/opt/halon/sbin/smtpd -c /etc/halon/smtpd.yaml --config-env-substitution

Restart the service. You can check which flags are set using ps aux | grep halon
You can check the environment variables of the service using sudo tr '\0' '\n' < /proc/$(pgrep smtpd)/environ

Startup and running configuration

The running configuration contains the bulk of the configuration data, including all the Halon script. It can be softly reloaded and deployed in a blue-green fashion using per-connection conditions, using the control sockets, API, command line interface or web administration. The default startup configuration loads the running configuration from /etc/halon/smtpd-app.yaml as per the environment.appconf directive.