# Dovecot Integration

Dovecot is a popular open‑source IMAP, POP3, and LMTP server. Xitoring’s Dovecot integration taps into the built‑in _stats_ service and exposes key metrics inside the Xitoring app, so administrators can diagnose authentication spikes, cache efficiency drops, and I/O bottlenecks before users complain.

## Supported platforms

Verified on **Linux** distributions where Dovecot > 2.3.11 is compiled with the `stats` plugin (enabled by default on most vendor packages).

# 1. Prepare Dovecot for metrics collection

Before enabling the integration in **Xitogent**, configure Dovecot to publish the required metrics.

## 1.1 Create `/etc/dovecot/conf.d/10-metrics.conf`

```conf
# ────────────────────────── 1. Sessions ──────────────────────────
metric sessions_total {
  filter = event=client_connection_connected
}

# ────────────────────────── 2. Successful logins ─────────────────
metric logins_total {
  filter = event=user_login_finished AND success=yes
}

# ────────────────────────── 3. Auth attempts (OK + FAIL) ─────────
metric auth_attempts_total {
  filter = event=auth_request_finished
}

# ────────────────────────── 4. Completed commands ────────────────
metric imap_commands_total {
  filter = event=imap_command_finished
}

metric pop3_commands_total {
  filter = event=pop3_command_finished
}

metric lmtp_commands_total {
  filter = event=lmtp_command_finished
}

# ────────────────────────── 5. Mailbox switches ──────────────────
metric switches_total {
  filter = event=mailbox_switch
}

# ────────────────────────── 6. I/O events (per txn) ──────────────
metric io_total {
  filter = event=mail_transaction_finished
}

# ────────────────────────── 7‑8. Network byte counters ───────────
metric net_input_bytes_total {
  filter = event=tcp_connection_finished
  fields = bytes_in          # yields dovecot_net_input_bytes_total
}

metric net_output_bytes_total {
  filter = event=tcp_connection_finished
  fields = bytes_out         # yields dovecot_net_output_bytes_total
}

# ────────────────────────── 9. Syscalls ──────────────────────────
metric syscalls_total {
  filter = event=process_syscall
}

# ────────────────────────── 10. Dict / map look‑ups ──────────────
metric lookups_total {
  filter = event=dict_lookup_finished
}

# ────────────────────────── 11‑12. Index‑cache use  ──────────────
metric cache_hits_total {
  filter = event=index_cache_hit
}

metric cache_requests_hit {
  filter = event=index_cache_hit
}

metric cache_requests_miss {
  filter = event=index_cache_miss
}

# ────────────────────────── 13. Auth‑cache requests ──────────────
metric auth_cache_requests_total {
  filter = event=auth_cache_request
}
}

service stats {
  inet_listener http {
    port = 9900
  }
}
```

## 1.2 Append to `/etc/dovecot/conf.d/10-master.conf`

```conf
service stats {
    unix_listener stats-reader {
        user = dovecot
        group = dovecot
        mode = 0660
    }

unix_listener stats-writer {
        user = dovecot
        group = dovecot
        mode = 0660
    }
}
```

## 1.3 Reload Dovecot

```bash
sudo systemctl reload dovecot
```

After reload, validate the HTTP endpoint:

```bash
curl http://localhost:9900/metrics
```

You should see Prometheus‑style metrics beginning with `dovecot_…`.

# 2. Enable Dovecot integration in Xitogent

Once metrics are confirmed available, run:

```bash
xitogent integrate
```

Select **Dovecot**. Xitogent will create `/etc/xitogent/integrations/dovecot_integration.conf` and start scraping `http://localhost:9900/metrics` every 60 seconds.

> **Note**  If you expose the stats listener on another host or port, edit the generated configuration file and set it accordingly.

# 4. Setup Triggers for Dovecot integration

Example high‑value Triggers:

| Use‑case | Condition | Severity |
| --- | --- | --- |
| **Authentication flood** | `dovecot auth attempts` increases > 500 in 5 min | MAJOR |
| **Poor cache efficiency** | `dovecot cache hit percentage < 80` for 10 min | WARNING |
| **High network output** | `dovecot net output bytes` rate > 50 MB/min | WARNING |
| **Surge in IMAP commands** | `dovecot imap commands` rate > 1000/min | INFO |

# 5. Troubleshooting

| Symptom | Resolution |
| --- | --- |
| _No metrics in Xitogent_ | Ensure the HTTP stats listener is reachable (curl the endpoint) and that the Xitogent configuration points to the correct URL. |
| _Permissions denied_ | Confirm the `dovecot` user owns the stats sockets (`stats-reader`, `stats-writer`) and that the stats service is enabled in both metric and master configs. |
| _Cache hit percentage stuck at 0_ | Ensure `mail_cache_stats=yes` is set in `dovecot.conf` for the relevant protocols. |

# 6. Next steps

- Combine Dovecot metrics with SMTP/IMAP checks to build comprehensive mail‑stack dashboards.