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/

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-----
      ...
listeners[].proxy.trust

Can either be a boolean or a list of IP addresses and subnets to trust as being reverse proxies. If it’s a boolean and it’s set to true it will trust all IP-addresses and subnets as being reverse proxies.

listeners[].proxy.userheader

This setting allows for automatic login when behind a reverse proxy. If configured, this header should be set by the reverse proxy and contain the username for the session.

listeners[].proxy.groupheader

When logging in via reverse proxy. This header is set to assign group permissions for the user.

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[].name

The display name. The default is the address. Cannot be combined with the expand option.

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.

hosts[].timeout

The timeout against the node (in seconds). The default is 5.

reresolve

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

3.3. Group directives

groups[]

You can set up groups to easily manage permissions instead of setting them on each user. Groups can also be used when logging in via reverse proxy.

groups[].name

The name of the group Required

groups[].features.preview.enabled

If the user should be able to preview messages. The default is true.

groups[].features.configuration.enabled

If the user should be able to view the configuration. The default is false.

groups[].features.readonly

If the user should only have readonly access. The default is false.

groups[].features.writable

If group[].features.readonly is set to true you can set an array of commands that the group should be able to execute.

groups[].features.memory.enabled

If the user should be able to view the memory page. The default is true.

groups[].features.rates.enabled

If the user should be able to view the rates page. The default is true.

groups[].features.datamasking

Configure the group datamasking settings

Note

Enabling any of these datamasking settings also disables group[].features.preview.enabled

Warning

These datamasking settings do not apply for the history feature. If you need to mask data in the history logging you should use the redact option in the history-elastic plugin.

groups[].features.datamasking.localpart

If the localpart of a mail should be masked for the user. The default is false

groups[].features.datamasking.subject

If the subject of a mail should be masked for the user. The default is false

groups[].features.datamasking.retryreason

If the retryreason of a mail should be masked for the user. The default is false

groups[].features.datamasking.saslusername

If the salusername of a mail should be masked for the user. The default is false

3.4. 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.

Note

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

$ /opt/halon/web/bin/generatepass
users[].group

The group the user should be assigned to.

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 configuration. The default is false.

users[].features.readonly

If the user should only have readonly access. The default is false.

users[].features.writable

If users[].features.readonly is set to true you can set an array of commands that the user should be able to execute.

users[].features.memory.enabled

If the user should be able to view the memory page. The default is true.

users[].features.rates.enabled

If the user should be able to view the rates page. The default is true.

users[].features.datamasking

Configure the users datamasking settings

Note

Enabling any of these datamasking settings also disables users[].features.preview.enabled

Warning

These datamasking settings do not apply for the history feature. If you need to mask data in the history logging you should use the redact option in the history-elastic plugin.

users[].features.datamasking.localpart

If the localpart of a mail should be masked for the user. The default is false

users[].features.datamasking.subject

If the subject of a mail should be masked for the user. The default is false

users[].features.datamasking.retryreason

If the retryreason of a mail should be masked for the user. The default is false

users[].features.datamasking.saslusername

If the salusername of a mail should be masked for the user. The default is false

3.5. Database directives

database

The database settings (knex) for storing per-user settings.

Note

A SQLite3 example would look like this. In this example make sure the /var/db/halon folder is writeable by the environment.privdrop.user or environment.privdrop.group.

database:
  client: sqlite3
  connection:
    filename: /var/db/halon/web.sqlite
database.client

The included client drivers are sqlite3, pg and mysql.

database.connection

The client driver connection string. See knex manual for specifics of each database driver.

3.6. Elasticsearch directives

This enables the history feature in the web administration.

Note

The history feature requires an additional configuration file. This configuration file is used to define fields in Elasticsearch and how they should be rendered.

halon-web loads the non-reloadable configuration from /etc/halon/web-history.yaml. It is described by, and can be validated with, the web-history.schema.json JSON schema. The default startup configuration file in /opt/halon/web/share can normally be used as a base (only choose one of them):

The following configuration is based on the Elasticsearch index template called halon-delivery-attempts:

$ cp /opt/halon/web/share/history/delivery-attempts.yaml /etc/halon/web-history.yaml

The following configuration is based on the Elasticsearch index template called halon-transactions:

$ cp /opt/halon/web/share/history/transactions.yaml /etc/halon/web-history.yaml

Sample web.yaml config:

elasticsearch:
  index: 'halon-delivery-attempts'
  nodes:
    - url: http://127.0.0.1:9200
  auth:
    username: elastic
    password: elastic
  tls:
    rejectUnauthorized: false
elasticsearch

The settings for Elasticsearch.

elasticsearch.index

The index pattern for all Elasticsearch queries.

elasticsearch.nodes[]

A list of Elasticsearch nodes.

elasticsearch.nodes[].url

The Elasticsearch URL to connect to.

elasticsearch.auth

Specify any credentials for authentication.

elasticsearch.auth.username

The username for basic authentication.

elasticsearch.auth.password

The password for basic authentication.

elasticsearch.tls

TLS settings (Node.js).

3.7. Other directives

instance

The name that will be shown in the document title.

solution

The solution, can be either engage or protect.

accounting

If accounting logs should be generated. The default is false.

3.8. Environment directives

environment.privdrop.user

The user to run the process as.

environment.privdrop.group

The group to run the process as.

environment.session.path

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