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
ordata
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.header
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.
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. 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[].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.
3.4. Database directives
- 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.5. 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.yamlThe following configuration is based on the Elasticsearch index template called halon-transactions:
$ cp /opt/halon/web/share/history/transactions.yaml /etc/halon/web-history.yamlSample 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.
3.6. 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.7. 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
.