6.1.3.3. Configuration

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

# cp /opt/halon/api/share/api.yaml /etc/halon/

6.1.3.3.1. Authentication directives

authentication.secret: The secret that needs to be sent in the request using the X-API-Key header.

6.1.3.3.2. Listener directives

listeners[]: The API 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[].maxsize: The maximum request body size to accept. The default is 52 428 800 bytes.

6.1.3.3.3. Other directives

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

6.1.3.3.4. Environment directives

environment.privdrop.user: The user to run the process as.

environment.privdrop.group

The group to run the process as.

environment.controlsockets.smtpd.path: See environment.controlsocket.path.

environment.controlsockets.smtpd.port: See environment.controlsocket.port.

environment.controlsockets.smtpd.address: See environment.controlsocket.address.

environment.controlsockets.smtpd.tls: The TLS settings to use when connecting to the smtpd control socket. The default is no TLS.

environment.controlsockets.smtpd.tls.certificate: The client certificate to use. This setting should have either a path or data property.

environment.controlsockets.smtpd.tls.privatekey: The private key for the client certificate. This setting should have either a path or data property.

environment.controlsockets.smtpd.tls.verify: If the server peer certificate should be verified. The default is true.

environment.controlsockets.smtpd.tls.verifyname: Hostname to verify against the server certificate’s CN and SAN.

environment.controlsockets.rated.path: See the rated manual.

environment.controlsockets.dlpd.path: See the dlpd manual.