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`

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

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

sudo systemctl reload dovecot

After reload, validate the HTTP endpoint:

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:

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.