3. Configuration

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

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

3.1. Authentication directives

authentication.apikeys[]: List of allowed API keys for the HTTP server (sent in the X-API-Key header).

3.2. Listener directives

listeners[]: One or more listen directives needs to be configured 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[]: 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.

3.3. Host directives

hosts[]: One or more host directives needs to be configured which specify which HTTP submission endpoint to connect to on your Halon instance. Required.

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

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

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[].apikey: The API key that will be used for the requests (sent in the X-API-Key header).

hosts[].xforwardedfor: Set the X-Forwarded-For header.

3.4. Queue directives

queues.timeout.connect: The connect timeout (in seconds) against the backend hosts. The default is 30.

queues.timeout.socket: The socket timeout (in seconds) against the backend hosts. The default is 900.

queues.concurrency.total: The total amount of concurrent connections that should be allowed against all the backend hosts.

Note

This value is unique to each worker (child process).

queues.concurrency.ip: The max amount of concurrent connections that should be allowed against each individual backend host.

Note

This value is unique to each worker (child process).

3.5. Tracking directives

tracking.click: If click tracking should be enabled or not. The default is false.

Note

This setting can be overriden in the HTTP request by setting the tracking.click property. It can also be turned off for individual links by including the tracking=off attribute inside the anchor of a link before the href.

tracking.open: If open tracking should be enabled or not. The default is false.

Note

This setting can be overriden in the HTTP request by setting the tracking.open property.

tracking.unsubscribe: If one-click list unsubscribe should be enabled or not. The default is false.

Note

This setting can be overriden in the HTTP request by setting the tracking.unsubscribe property.

tracking.url: The base url that should be used for the rewritten links and tracking pixels. Required.

Note

This setting can be overriden in the HTTP request by setting the tracking.url property.

tracking.secret.id: The ID of the secret that should be used to generate the hash of the tracking payload. This must be an integer between 1 and 254. Required.

tracking.secret.key: The key for the secret that should be used to generate the hash of the tracking payload. Required.

3.6. Other directives

workers: The amount of child processes that should be started to handle incoming requests. The default is as many as there are CPU cores.

maxsize: The maximum request body size to accept. The default is 10 485 760 bytes.

source: Pass source information to the configured hosts in the metadata. The default is false.

3.7. Environment directives

environment.privdrop.user

environment.privdrop.group