<a id="configuration"></a>

# Configuration

*halon* loads the non-reloadable configuration from the `plugins` section in `/etc/halon/smtpd.yaml`.
It is described by, and can be validated with, the
[submission.schema.json](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/submission/2.2-stable/submission.schema.json)
[JSON schema](https://docs.halon.io/json-schemas/submission/2.2-stable/).

<a id="authentication-directives"></a>

## Authentication directives

<a id="confval-apikeys"></a>

### apikeys[]

List of allowed API keys for the HTTP server (sent in the *X-API-Key* header).

<a id="listener-directives"></a>

## Listener directives

<a id="confval-serverid"></a>

### serverid

Which `serverid` to use. The server should be of type `plugin`. **Required.**

<a id="confval-transportid"></a>

### transportid

Which `transportid` to use. The default is the one configured for the server in `smtpd-app.yaml`.

<a id="confval-port"></a>

### port

Which TCP port to listen on. **Required.**

<a id="confval-address"></a>

### address

IPv4 or IPv6 address to listen on.
The default is to listen to all IPv4 and IPv6 addresses.

<a id="confval-pki"></a>

### pki

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

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

<a id="confval-proxy"></a>

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

<a id="tracking-directives"></a>

## Tracking directives

<a id="confval-tracking.click"></a>

### 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`.

<a id="confval-tracking.open"></a>

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

<a id="confval-tracking.unsubscribe"></a>

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

<a id="confval-tracking.url"></a>

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

<a id="confval-tracking.secret.id"></a>

### 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.**

<a id="confval-tracking.secret.key"></a>

### tracking.secret.key

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

<a id="other-directives"></a>

## Other directives

<a id="confval-threads"></a>

### threads

The amount of worker threads that should be started to handle incoming requests. The default is as many as there are CPU cores.

<a id="confval-maxsize"></a>

### maxsize

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

<a id="confval-source"></a>

### source

Pass source information in the metadata. The default is *false*.
