# Configuration Reference

This section provides detailed reference documentation for all Mermin configuration options, from network interface discovery to export settings.

## How Configuration Works

Mermin uses a layered configuration approach:

1. **Configuration File (HCL/YAML)**: The primary method for detailed configuration.
2. **Environment Variables**: Override global options at runtime.
3. **Command-Line Flags**: Override global options at runtime.

Global options (documented below) are the only settings configurable via all three methods. All other configuration blocks require a configuration file.

***

## Configure Global Agent Options

Global options are top-level configuration settings that control Mermin's overall behavior. These are the only options that can be configured via CLI flags or environment variables in addition to the configuration file.

### Configuration Methods

#### Configuration File (HCL)

```hcl
# config.hcl
log_level = "info"
auto_reload = true
shutdown_timeout = "10s"
```

#### Command-Line Flags

```bash
mermin \
  --config=/etc/mermin/config.hcl \
  --log-level=debug \
  --auto-reload
```

#### Environment Variables

```bash
export MERMIN_CONFIG_PATH=/etc/mermin/config.hcl
export MERMIN_LOG_LEVEL=debug
export MERMIN_CONFIG_AUTO_RELOAD=true
mermin
```

### Configuration Options

#### `config` / `MERMIN_CONFIG_PATH`

**Type:** String (file path) **Default:** None (optional) **CLI Flag:** `--config` **Environment:** `MERMIN_CONFIG_PATH`

Path to the HCL or YAML configuration file. Omit to use built-in defaults.

**Example:**

```bash
mermin --config=/etc/mermin/config.hcl
# or
export MERMIN_CONFIG_PATH=/etc/mermin/config.hcl
```

#### `auto_reload` / `MERMIN_CONFIG_AUTO_RELOAD`

{% hint style="warning" %}
Currently, this features is not supported.
{% endhint %}

**Type:** Boolean **Default:** `false` **CLI Flag:** `--auto-reload` **Environment:** `MERMIN_CONFIG_AUTO_RELOAD`

Automatically reload configuration when the file changes. When enabled, Mermin watches the config file and reloads it without requiring a restart.

**HCL:**

```hcl
auto_reload = true
```

**CLI:**

```bash
mermin --auto-reload --config=config.hcl
```

**Environment:**

```bash
export MERMIN_CONFIG_AUTO_RELOAD=true
```

**Behavior:**

* File is monitored for changes using filesystem watches
* Configuration is reloaded atomically
* Brief pause in flow capture during reload (\~100ms)
* Invalid configuration prevents reload (old config remains active)
* Logs indicate successful/failed reload attempts

**Use Cases:**

* Development and testing: Iterate quickly without restarts
* Production: Update configuration without downtime
* Debugging: Temporarily change log levels or filters

{% hint style="warning" %}
Some configuration changes may require a full restart, such as changing monitored network interfaces or modifying RBAC permissions.
{% endhint %}

#### `log_level` / `MERMIN_LOG_LEVEL`

**Type:** String (enum) **Default:** `info` **CLI Flag:** `--log-level` **Environment:** `MERMIN_LOG_LEVEL`

Sets the logging verbosity level.

**Valid Values:**

* `trace`: Most verbose, includes all debug information
* `debug`: Detailed debugging information
* `info`: General informational messages (default)
* `warn`: Warning messages only
* `error`: Error messages only

**HCL:**

```hcl
log_level = "debug"
```

**CLI:**

```bash
mermin --log-level=trace --config=config.hcl
```

**Environment:**

```bash
export MERMIN_LOG_LEVEL=warn
```

**Recommendations:**

* **Production:** `info` or `warn` to reduce log volume
* **Debugging:** `debug` for detailed troubleshooting
* **Development:** `trace` for comprehensive visibility

#### `shutdown_timeout`

**Type:** Duration **Default:** `28s` **CLI Flag:** Not available **Environment:** Not available

Maximum time to wait for graceful shutdown before forcing termination.

**HCL:**

```hcl
shutdown_timeout = "10s"
```

**Behavior:** During shutdown, Mermin:

1. Stops accepting new packets
2. Waits for in-flight flows to export (up to `shutdown_timeout`)
3. Closes OTLP connections gracefully
4. Forces shutdown if timeout is exceeded

**Recommendations:**

* **Production:** `10s` to ensure flows are exported
* **Development:** `5s` (default) is usually sufficient
* **High-throughput:** Increase to `30s` or more

**Related Settings:**

* `export.otlp.max_export_timeout`: Should be less than `shutdown_timeout`

### Monitoring Shutdown Behavior

Mermin provides metrics to monitor shutdown behavior:

#### Shutdown Metrics

* `shutdown_duration_seconds`: Histogram of actual shutdown durations
* `shutdown_timeouts_total`: Count of shutdowns that exceeded timeout
* `shutdown_flows_total{status="preserved"}`: Flows successfully exported during shutdown
* `shutdown_flows_total{status="lost"}`: Flows lost due to shutdown timeout

## Next Steps

{% tabs %}
{% tab title="Essential Configuration" %}

1. [**Configure Network Interfaces**](/configuration/reference/network-interface-discovery.md): Select which interfaces to monitor
2. [**Set Up OTLP Export**](/configuration/reference/opentelemetry-otlp-exporter.md): Send flows to your backend
3. [**Tune Flow Generation**](/configuration/reference/flow-span-producer.md): Configure timeouts and thresholds
   {% endtab %}

{% tab title="Monitoring" %}

1. [**Configure Health Checks**](/configuration/reference/internal-server.md): Readiness and liveness probes
2. [**Expose Prometheus Metrics**](/configuration/reference/internal-prometheus-metrics.md): Enable scraping
   {% endtab %}

{% tab title="Examples" %}

1. [**Review Complete Configurations**](/configuration/examples.md): Production-ready examples
   {% endtab %}
   {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mermin.dev/configuration/reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.