7.3. Configuration

halon-web loads the non-reloadable configuration from /etc/halon/web.yaml. It is described by, and can be validated with, the web.schema.json JSON schema (included in our Visual Studio Code integration). The default startup configuration file in /opt/halon/web/share can normally be used as a base:

$ cp /opt/halon/web/share/web.yaml /etc/halon/

7.3.1. Listener directives

listeners[]: The web administration must have one or more listen directives, which specify which TCP port and address to listen on. Required.

listeners[].port: Which TCP port to listen on. Required.

listeners[].address: IPv4 or IPv6 address to listen on. The default is to listen to all IPv4 and IPv6 addresses.

listeners[].pki

The X.509 certificate and private key. The private key and certificate should have either a path or data property.

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

7.3.2. Host directives

hosts[]: The web administration must have one or more host directives, which specify which HTTP/JSON endpoints to connect to. Required.

hosts[].port: Which TCP port to connect to. Required.

hosts[].address: Hostname, IPv4 address or IPv6 address to connect to. Required.

hosts[].expand: Add all IP addresses for the hostname as unique hosts. The default is false.

hosts[].tls.enabled: If TLS should be used for the requests. The default is false.

hosts[].tls.verify: If the server certificate should be verified. The default is true.

hosts[].secret: The secret that will be sent in the requests using the X-API-Key header.

hosts[].processes[]: The processes that are running on the host. The default is smtpd and rated.

reresolve: Automatically re-resolve the hostnames of the hosts every x seconds.

7.3.3. User directives

users[]: The web administration must have one or more user directives, which specify which users can log in to the web administration. Required.

users[].username: The username. Required.

users[].password

The password. Required.

Note

The password needs to be encrypted using bcrypt. You can run the following command to generate a password:

$ /opt/halon/web/node/bin/node /opt/halon/web/backend/src/bin/password.js

users[].features.preview.enabled: If the user should be able to preview messages. The default is true.

users[].features.configuration.enabled: If the user should be able to view the Halon MTA configuration. The default is false.

7.3.4. Environment directives

environment.privdrop.user

environment.privdrop.group

environment.session.path: The directory where the session files will be stored. The default is /tmp/halon/web.