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

# 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](http://lbovet.github.io/docson/index.html#https://docs.halon.io/json-schemas/web/1.32-stable/web.schema.json)
[JSON schema](https://docs.halon.io/json-schemas/web/1.32-stable/) (included in our [Visual Studio Code integration](https://docs.halon.io/manual/vscode.html)).
The default startup configuration file in `/opt/halon/web/share` can normally be used as a base:

```console
# cp /opt/halon/web/share/web.yaml /etc/halon/
```

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

## Listener directives

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

### listeners[]

The web administration must have one or more listen directives,
which specify which TCP port and address to listen on. **Required.**

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

### listeners[].port

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

<a id="confval-listeners-.baseurl"></a>

### listeners[].baseurl

An optional public base URL (scheme, host and optional port, e.g. [https://web.example.com](https://web.example.com)).

<a id="confval-listeners-.basepath"></a>

### listeners[].basepath

An optional URL path prefix under which the web administration is served, for example /web.

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

### listeners[].address

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

<a id="confval-listeners-.tls"></a>

### listeners[].tls

TLS settings for the listener.

<a id="confval-listeners-.tls.pki"></a>

### listeners[].tls.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-listeners-.tls.ciphers"></a>

### listeners[].tls.ciphers

Cipher suite specification

<a id="confval-listeners-.tls.protocols.min"></a>

### listeners[].tls.protocols.min

Minimum TLS version to allow

<a id="confval-listeners-.tls.protocols.max"></a>

### listeners[].tls.protocols.max

Maximum TLS version to allow

<a id="confval-listeners-.proxy.trust"></a>

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

> ```yaml
> listeners:
>   - proxy:
>       trust:
>         - 1.2.3.4
>     ...
> ```

<a id="confval-listeners-.proxy.userheader"></a>

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

> ```yaml
> listeners:
>   - proxy:
>       userheader: X-Proxy-User
>     ...
> ```

<a id="confval-listeners-.proxy.groupheader"></a>

### listeners[].proxy.groupheader

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

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

## Host directives

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

### hosts[]

The web administration must have one or more host directives,
which specify which [HTTP/JSON endpoints](https://docs.halon.io/http-api) to connect to. **Required.**

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

### hosts[].port

Which TCP port to connect to. **Required.**

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

### hosts[].address

Hostname, IPv4 address or IPv6 address to connect to. **Required.**

<a id="confval-hosts-.name"></a>

### hosts[].name

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

<a id="confval-hosts-.expand"></a>

### hosts[].expand

Add all IP addresses for the hostname as unique hosts. The default is *false*.  Mutually exclusive with [`hosts[].kubernetes`](#confval-hosts-.kubernetes).

<a id="confval-hosts-.kubernetes"></a>

### hosts[].kubernetes

The Kubernetes settings. Mutually exclusive with [`hosts[].expand`](#confval-hosts-.expand).

<a id="confval-hosts-.kubernetes.namespace"></a>

### hosts[].kubernetes.namespace

The namespace for the smtpd *StatefulSet\`*.

<a id="confval-hosts-.kubernetes.name"></a>

### hosts[].kubernetes.name

The name for the smtpd *StatefulSet*.

<a id="confval-hosts-.kubernetes.address"></a>

### hosts[].kubernetes.address

How to address each pod: *ip* (default, e.g. *10.42.0.12*), *hostname* (e.g. *halon-smtpd-0.halon-smtpd.default*), or *ip-hostname* (e.g. *10-42-0-12.halon-smtpd.default*).
DNS names use the pod’s subdomain and namespace. Resolution requires a matching service endpoint record. CoreDNS uses an endpoint’s hostname when set; the dashed IP is a fallback for unnamed endpoints, so the two DNS forms are not interchangeable.

<a id="confval-hosts-.kubernetes.clusterdomain"></a>

### hosts[].kubernetes.clusterdomain

The cluster DNS domain, e.g. *cluster.local*, used by the DNS address modes. A non-empty value appends  *.svc.\<clusterdomain>*; otherwise the resolver must supply that suffix through its DNS search list.

<a id="confval-hosts-.tls.enabled"></a>

### hosts[].tls.enabled

If TLS should be used for the requests. The default is *false*.

<a id="confval-hosts-.tls.verify"></a>

### hosts[].tls.verify

If the server certificate should be verified. The default is *true*.

<a id="confval-hosts-.tls.verifyname"></a>

### hosts[].tls.verifyname

Hostname to verify against the server certificate’s CN and SAN.

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

### hosts[].secret

The secret that will be sent in the requests using the *X-API-Key* header.

<a id="confval-hosts-.processes"></a>

### hosts[].processes[]

The processes that are running on the host. The default is *smtpd* and *rated*.

<a id="confval-hosts-.timeout"></a>

### hosts[].timeout

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

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

### reresolve

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

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

## Group directives

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

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

<a id="confval-groups-.name"></a>

### groups[].name

The name of the group **Required**

<a id="confval-groups-.features.preview.enabled"></a>

### groups[].features.preview.enabled

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

<a id="confval-groups-.features.readonly"></a>

### groups[].features.readonly

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

<a id="confval-groups-.features.writable"></a>

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

<a id="confval-groups-.features.memory.enabled"></a>

### groups[].features.memory.enabled

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

<a id="confval-groups-.features.rates.enabled"></a>

### groups[].features.rates.enabled

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

<a id="confval-groups-.features.datamasking"></a>

### groups[].features.datamasking

Configure the group datamasking settings

> **Note**
> 
> Enabling `localpart`, `subject`, `retryreason`, or `saslusername` masking also disables [`groups[].features.preview.enabled`](#confval-groups-.features.preview.enabled)

> **Warning**
> 
> The `localpart`, `subject`, `retryreason`, and `saslusername` settings do not apply for the [history feature](history.html.md).
> Use the `history` datamasking setting to hide history source paths in the web administration.
> To redact data in the stored history logs, use the `redact` option in the [history-elastic](https://github.com/halon-extras/history-elastic) plugin.

<a id="confval-groups-.features.datamasking.localpart"></a>

### groups[].features.datamasking.localpart

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

<a id="confval-groups-.features.datamasking.subject"></a>

### groups[].features.datamasking.subject

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

<a id="confval-groups-.features.datamasking.retryreason"></a>

### groups[].features.datamasking.retryreason

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

<a id="confval-groups-.features.datamasking.saslusername"></a>

### groups[].features.datamasking.saslusername

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

<a id="confval-groups-.features.datamasking.history"></a>

### groups[].features.datamasking.history

History source paths to hide and disallow in queries. True masks the path and its descendants.
The timestamp and transaction identifier are reserved. Charts that read or filter on masked paths are hidden.

The following example uses the [delivery-attempts](history.html.md#history-delivery-attempts) index template:

```yaml
datamasking:
  history:
    sender: true
    senderlocalpart: true
    recipient: true
    recipientlocalpart: true
    smtpreasonnormalized: true
    smtpreason: true
```

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

## User directives

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

### users[]

The web administration must have one or more user directives,
which specify which users can log in to the web administration. **Required.**

<a id="confval-users-.username"></a>

### users[].username

The username. **Required.**

<a id="confval-users-.password"></a>

### users[].password

The password.

> **Note**
> 
> The password needs to be encrypted using bcrypt. You can run the following command to generate a password:
> 
> ```console
> $ /opt/halon/web/bin/generatepass
> ```

<a id="confval-users-.group"></a>

### users[].group

The group the user should be assigned to.

<a id="confval-users-.features.preview.enabled"></a>

### users[].features.preview.enabled

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

<a id="confval-users-.features.readonly"></a>

### users[].features.readonly

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

<a id="confval-users-.features.writable"></a>

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

<a id="confval-users-.features.memory.enabled"></a>

### users[].features.memory.enabled

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

<a id="confval-users-.features.rates.enabled"></a>

### users[].features.rates.enabled

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

<a id="confval-users-.features.datamasking"></a>

### users[].features.datamasking

Configure the users datamasking settings

> **Note**
> 
> Enabling `localpart`, `subject`, `retryreason`, or `saslusername` masking also disables [`users[].features.preview.enabled`](#confval-users-.features.preview.enabled)

> **Warning**
> 
> The `localpart`, `subject`, `retryreason`, and `saslusername` settings do not apply for the [history feature](history.html.md).
> Use the `history` datamasking setting to hide history source paths in the web administration.
> To redact data in the stored history logs, use the `redact` option in the [history-elastic](https://github.com/halon-extras/history-elastic) plugin.

<a id="confval-users-.features.datamasking.localpart"></a>

### users[].features.datamasking.localpart

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

<a id="confval-users-.features.datamasking.subject"></a>

### users[].features.datamasking.subject

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

<a id="confval-users-.features.datamasking.retryreason"></a>

### users[].features.datamasking.retryreason

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

<a id="confval-users-.features.datamasking.saslusername"></a>

### users[].features.datamasking.saslusername

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

<a id="confval-users-.features.datamasking.history"></a>

### users[].features.datamasking.history

History source paths to hide and disallow in queries. True masks the path and its descendants.
The timestamp and transaction identifier are reserved. Charts that read or filter on masked paths are hidden.

The following example uses the [delivery-attempts](history.html.md#history-delivery-attempts) index template:

```yaml
datamasking:
  history:
    senderlocalpart: true
    recipientlocalpart: true
    smtpreason: true
    smtpreasonnormalized: true
```

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

## OIDC directives

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

### oidc

OpenID Connect (OIDC) settings. This is an object with two required fields: `enabled` and `provider`.

<a id="confval-oidc.enabled"></a>

### oidc.enabled

If OIDC should be enabled. **Required.**

<a id="confval-oidc.provider"></a>

### oidc.provider

The OIDC provider configuration object. **Required.**
The provider must contain the unique provider ID, discovery URL, client ID and client secret.

<a id="confval-oidc.provider.providerid"></a>

### oidc.provider.providerid

The unique provider ID. **Required.**

<a id="confval-oidc.provider.discoveryurl"></a>

### oidc.provider.discoveryurl

The OIDC discovery URL. **Required.**

<a id="confval-oidc.provider.clientid"></a>

### oidc.provider.clientid

The OIDC client ID. **Required.**

<a id="confval-oidc.provider.clientsecret"></a>

### oidc.provider.clientsecret

The OIDC client secret. **Required.**

<a id="confval-oidc.provider.pkce"></a>

### oidc.provider.pkce

If PKCE should be used. The default is `true`.

<a id="confval-oidc.provider.groupclaim"></a>

### oidc.provider.groupclaim

The claim containing the user’s group(s). Values from this claim are matched against configured groups in the YAML config.
If this option is set, [`oidc.provider.allowedgroups[]`](#confval-oidc.provider.allowedgroups) becomes required.

<a id="confval-oidc.provider.allowedgroups"></a>

### oidc.provider.allowedgroups[]

List of allowed config group names that OIDC users may belong to. Each entry is a non-empty string.
This option is required when [`oidc.provider.groupclaim`](#confval-oidc.provider.groupclaim) is set and must not be present otherwise.

<a id="confval-oidc.provider.displayname"></a>

### oidc.provider.displayname

The display name for the provider.

<a id="confval-oidc.provider.displayicon"></a>

### oidc.provider.displayicon

An icon for the provider. Two alternatives supported:

- Inline data + extension:
  ```yaml
  displayicon:
    data: |-
      iVBORw0KGgoAAAANSUhEUg...
    extension: .png
  ```
- Path to file + extension (optional):
  ```yaml
  displayicon:
    path: /opt/halon/web/share/icons/myprovider.svg
  ```

Supported extensions are `.png` and `.svg`.

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

## MCP directives

A MCP server that provides tools to interact with Halon hosts and their processes.

> **Important**
> 
> When [`mcp.enabled`](#confval-mcp.enabled) is *true*, every listener must have a [`listeners[].baseurl`](#confval-listeners-.baseurl).
> 
> When both MCP and OAuth are enabled, the following requirements also apply:
> 
> * [`database`](#confval-database) must be configured.
> * [`environment.session.secret`](#confval-environment.session.secret) must be configured.
> * A custom [`listeners[].basepath`](#confval-listeners-.basepath) is not supported.
> * Every listener’s [`listeners[].baseurl`](#confval-listeners-.baseurl) must use HTTPS, except for loopback hosts: `localhost` or `[::1]`.
> 
> Use [`users[].features.datamasking`](#confval-users-.features.datamasking) or [`groups[].features.datamasking`](#confval-groups-.features.datamasking) to hide sensitive data from the LLM when using MCP.

<a id="confval-mcp.enabled"></a>

### mcp.enabled

If the MCP endpoint should be enabled. The default is *false*.
The MCP endpoint will be available at `https://<your-web-instance>/mcp`.

<a id="confval-mcp.oauth.enabled"></a>

### mcp.oauth.enabled

If OAuth should be enabled for the MCP endpoint. The default is *true*.
The MCP client inherits the permissions of the user who signed in.

> **Warning**
> 
> Disabling OAuth means no authentication is required to access the MCP endpoint.
> Only disable it in a trusted environment or when behind an MCP gateway.

<a id="confval-mcp.oauth.accesstoken.expiresin"></a>

### mcp.oauth.accesstoken.expiresin

How long an MCP access token is valid (in seconds). Clients refresh it when it expires.
The default is *3600*.

<a id="confval-mcp.oauth.refreshtoken.expiresin"></a>

### mcp.oauth.refreshtoken.expiresin

How long an MCP client stays signed in without being used (in seconds). Each token refresh starts the period again.
The default is *2592000*.

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

<a id="id2"></a>

## Database directives

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

### database

The database settings ([knex](https://knexjs.org/guide/#configuration-options)) for storing per-user settings.

> **Note**
> 
> A SQLite3 example would look like this. In this example make sure the `/var/lib/halon/web` folder is writeable by the
> [`environment.privdrop.user`](#confval-environment.privdrop.user) or [`environment.privdrop.group`](#confval-environment.privdrop.group).
> 
> > ```yaml
> > database:
> >   client: sqlite3
> >   connection:
> >     filename: /var/lib/halon/web/web.sqlite
> > ```

<a id="confval-database.client"></a>

### database.client

The included client drivers are *sqlite3*, *pg* and *mysql*.

<a id="confval-database.connection"></a>

### database.connection

The client driver connection string or object. See [knex manual](https://knexjs.org/guide/#configuration-options) for specifics of each database driver.

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

## Elasticsearch directives

This enables the [history feature](history.html.md) in the web administration.

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

### elasticsearch

The settings for Elasticsearch.

<a id="confval-elasticsearch.index.history"></a>

### elasticsearch.index.history

The index pattern for the history logs.

<a id="confval-elasticsearch.index.policyd"></a>

### elasticsearch.index.policyd

The index pattern for the policyd logs.

<a id="confval-elasticsearch.nodes"></a>

### elasticsearch.nodes[]

A list of Elasticsearch nodes.

<a id="confval-elasticsearch.nodes-.url"></a>

### elasticsearch.nodes[].url

The Elasticsearch URL to connect to.

<a id="confval-elasticsearch.auth"></a>

### elasticsearch.auth

Specify any credentials for authentication.

<a id="confval-elasticsearch.auth.username"></a>

### elasticsearch.auth.username

The username for basic authentication.

<a id="confval-elasticsearch.auth.password"></a>

### elasticsearch.auth.password

The password for basic authentication.

<a id="confval-elasticsearch.tls"></a>

### elasticsearch.tls

TLS settings ([Node.js](https://nodejs.org/api/tls.html)).

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

## Other directives

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

### instance

The name that will be shown in the document title.

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

### solution

The solution, can be either *engage* or *protect*.

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

### accounting

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

<a id="confval-maxmind.geoip.path"></a>

### maxmind.geoip.path

The directory to MaxMind’s GeoIP database. The default is  */var/lib/GeoIP/GeoLite2-Country.mmdb*.

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

### policyd.port

The port for the `policyd` service.

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

### policyd.address

The address for the `policyd` service.

<a id="confval-policyd.tls.enabled"></a>

### policyd.tls.enabled

If TLS should be used for the requests. The default is *false*.

<a id="confval-policyd.tls.verify"></a>

### policyd.tls.verify

If the server certificate should be verified. The default is *true*.

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

### policyd.secret

The secret that will be sent in the requests using the *X-API-Key* header.

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

### trustedorigins[]

A list of trusted origins. This list should only contain domains or wildcard domains (eg. `*.example.com`).

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

## Environment directives

<a id="confval-environment.privdrop.user"></a>

### environment.privdrop.user

The user to run the process as.

<a id="confval-environment.privdrop.group"></a>

### environment.privdrop.group

The group to run the process as.

> **Tip**
> 
> The `privdrop.user` and `privdrop.group` settings to use will depend on your Linux distribution:
> 
> * For Ubuntu, suitable values are `nobody` and `nogroup`
> * For RHEL and related distibutions, the values are `nobody` and `nobody`.

<a id="confval-environment.session.secret"></a>

### environment.session.secret

> The secret used for encryption, signing, and hashing.
> The default is to generate a unique UUID during startup.

> **Note**
> 
> The minimum length is 32 characters.

<a id="confval-environment.session.secure"></a>

### environment.session.secure

> If secure cookies should be used. The default is `true` if [`listeners[].tls.pki`](#confval-listeners-.tls.pki) is configured, otherwise *false*.

> **Note**
> 
> It’s recommended to set this to *true* when doing SSL termination at a reverse proxy.
