A lightweight, bash-based Prometheus exporter for Dovecot mail server statistics. This exporter uses only bash and socat to provide comprehensive Dovecot metrics for monitoring with Prometheus and Grafana.

• Pure Bash Implementation: No external dependencies except socat
• Comprehensive Metrics: Exports Dovecot statistics including:
  • Login statistics by protocol (IMAP, POP3, LMTP, ManageSieve)
  • Authentication success and failures
  • Connection and disconnection tracking
  • Message operations (read, delete, expunge, save, copy)
  • Mailbox operations (create, delete, rename)
  • Bandwidth statistics (bytes read/written)
  • Process status and uptime
  • Dovecot version information
• Stateful Counter Tracking: Maintains persistent counters for accurate Prometheus rate calculations
• HTTP Server: Built-in HTTP server using socat for serving metrics
• Systemd Integration: Ready-to-use systemd service file
• Grafana Dashboard: Pre-built comprehensive dashboard
• Multi-Instance Support: Monitor multiple Dovecot servers

• Dovecot mail server
• socat package installed
• Prometheus server for scraping metrics
• Read access to Dovecot logs

1. Clone the repository:

git clone https://github.com/itefixnet/prometheus-dovecot-exporter.git
cd prometheus-dovecot-exporter

2. Make scripts executable:

chmod +x *.sh

3. Test the exporter:

sudo ./dovecot-exporter.sh test

4. Start the HTTP server:

sudo ./http-server.sh start

5. Access metrics at http://localhost:9166/metrics

For production deployment, install as a system service:

# Create user and directories
sudo useradd -r -s /bin/false dovecot-exporter
sudo mkdir -p /opt/dovecot-exporter
sudo mkdir -p /var/lib/dovecot-exporter

# Copy files
sudo cp *.sh /opt/dovecot-exporter/
sudo cp config.sh /opt/dovecot-exporter/
sudo cp dovecot-exporter.conf /opt/dovecot-exporter/
sudo cp dovecot-exporter.service /etc/systemd/system/

# Set permissions
sudo chown -R dovecot-exporter:dovecot-exporter /opt/dovecot-exporter
sudo chown -R dovecot-exporter:dovecot-exporter /var/lib/dovecot-exporter
sudo chmod +x /opt/dovecot-exporter/*.sh

# Add user to adm group for log access
sudo usermod -a -G adm dovecot-exporter

# Enable and start service
sudo systemctl daemon-reload
sudo systemctl enable dovecot-exporter
sudo systemctl start dovecot-exporter

# Check status
sudo systemctl status dovecot-exporter

The exporter can be configured using environment variables or configuration files:

How it works: The exporter maintains persistent counters in a state file, tracking the log file position (inode and byte offset). On each scrape, it:

1. Reads only new log entries since the last position
2. Parses all metrics (logins, authentications, messages, mailbox operations) in a single pass
3. Increments the appropriate counters in memory
4. Saves the updated state (counters and position) to disk

This architecture ensures counters monotonically increase as required by Prometheus, enabling accurate rate() and increase() calculations. Log rotation and truncation are automatically detected and handled.

1. config.sh: Shell configuration file (sourced by scripts)
2. dovecot-exporter.conf: Systemd environment file

The exporter provides comprehensive Dovecot mail server metrics:

• dovecot_master_process_running - Dovecot master process status (1=running, 0=not running)
• dovecot_master_process_uptime_seconds - Dovecot master process uptime in seconds (counter)
• dovecot_version_info{version="..."} - Dovecot version information with label

• dovecot_logins_total{protocol="imap"} - Total IMAP logins (counter)
• dovecot_logins_total{protocol="pop3"} - Total POP3 logins (counter)
• dovecot_logins_total{protocol="lmtp"} - Total LMTP deliveries (counter)
• dovecot_logins_total{protocol="managesieve"} - Total ManageSieve logins (counter)

• dovecot_auth_success_total - Total successful authentications (equals total logins) (counter)
• dovecot_auth_failures_total - Total authentication failures (counter)
• dovecot_login_failures_total - Total login failures (counter)

• dovecot_disconnects_total - Total number of disconnections (counter)

• dovecot_messages_read_total - Total messages read (counter)
• dovecot_messages_deleted_total - Total messages deleted (counter)
• dovecot_messages_expunged_total - Total messages expunged (counter)
• dovecot_messages_saved_total - Total messages saved/delivered (counter)
• dovecot_messages_copied_total - Total messages copied (counter)

• dovecot_mailbox_create_total - Total mailboxes created (counter)
• dovecot_mailbox_delete_total - Total mailboxes deleted (counter)
• dovecot_mailbox_rename_total - Total mailboxes renamed (counter)

• dovecot_bytes_read_total - Total bytes read (counter)
• dovecot_bytes_written_total - Total bytes written (counter)

# Test connection to Dovecot
sudo ./dovecot-exporter.sh test

# Collect metrics once
sudo ./dovecot-exporter.sh collect

# Start HTTP server manually
sudo ./http-server.sh start

# Test HTTP endpoints
curl http://localhost:9166/metrics
curl http://localhost:9166/health
curl http://localhost:9166/

Add jobs to your prometheus.yml for single or multiple Dovecot instances:

scrape_configs:
  # Single instance
  - job_name: 'dovecot-exporter'
    static_configs:
      - targets: ['localhost:9166']
    scrape_interval: 30s
    metrics_path: /metrics
    
  # Multiple instances with labels
  - job_name: 'dovecot-servers'
    static_configs:
      - targets: ['mail1.example.com:9166', 'mail2.example.com:9166']
        labels:
          environment: 'production'
          datacenter: 'dc1'
      - targets: ['staging.example.com:9166']
        labels:
          environment: 'staging' 
          datacenter: 'dc2'
    scrape_interval: 30s
    metrics_path: /metrics

Import the provided grafana-dashboard.json file into your Grafana instance:

1. Go to Dashboards → Import
2. Upload grafana-dashboard.json or copy/paste the JSON content
3. Configure Data Source: Select your Prometheus datasource from the dropdown
4. Click "Import"

Troubleshooting Dashboard Import:

• If you get "data source was not found" error, ensure your Prometheus datasource is properly configured in Grafana
• Make sure your Prometheus is scraping the Dovecot exporter endpoints
• Verify metrics are available by checking: http://your-grafana/explore → Select Prometheus → Query dovecot_master_process_running

Dashboard Features:

The comprehensive Grafana dashboard includes:

• Overview Row:

  • Login and Authentication Rate (time series showing IMAP, POP3, LMTP logins/min and auth failures)
  • Dovecot Status gauge (Up/Down with color indicators)
  • Uptime gauge (displays process uptime in seconds)

• Logins by Protocol Row:

  • Logins by Protocol (stacked area chart with rate per minute, aggregated by protocol)
  • Login Distribution (pie chart showing protocol distribution over 1h)

• Authentication & Connections Row:

  • Authentication Rate (time series showing success/failures per minute)
  • Connection Statistics (disconnects per minute)

• Message Operations Row (collapsed by default):

  • Message Operations per minute (time series: read, saved, deleted, expunged, copied)
  • Message Operations Distribution (pie chart showing 24h operation breakdown)

• Mailbox Operations & Bandwidth Row (collapsed by default):

  • Mailbox Operations per minute (time series: created, deleted, renamed)
  • Bandwidth Usage (time series showing bytes read/written with proper rate calculation)

All panels support:

• Rate-based calculations using Prometheus rate() and increase() functions
• Protocol aggregation with sum by (protocol) for cleaner visualizations
• Multi-instance filtering with template variables ($job, $instance)
• Auto-refresh (30 second default)
• Time range selection (default: last 6 hours)
• Responsive layout with collapsible rows for detailed metrics

Multi-Instance Support: The dashboard includes template variables for monitoring multiple Dovecot instances:

• Instance: Filter by specific instance (e.g., mail1.example.com:9166, localhost:9166)
• Job: Filter by Prometheus job name

To monitor multiple instances, configure your prometheus.yml as shown above.

The dashboard supports:

• Multi-Instance Monitoring: Automatically discovers all Dovecot exporters
• Flexible Filtering: Filter by instance (host:port) and job name
• Multi-Select Variables: Monitor multiple instances simultaneously
• Instance Labeling: All metrics show which instance they come from

1. Permission Denied:

   • Ensure scripts are executable: chmod +x *.sh
   • Add exporter user to adm group for log access: sudo usermod -a -G adm dovecot-exporter
   • Check log file permissions

2. Cannot Read Log File:

   • Verify log file path: ls -la /var/log/mail.log
   • Check user permissions: sudo -u dovecot-exporter cat /var/log/mail.log
   • Ensure log file exists and is readable

3. Port Already in Use:

   • Change LISTEN_PORT in configuration
   • Check for other services: netstat -tlnp | grep 9166

4. Missing Dependencies:

   # Install socat (Ubuntu/Debian)
   sudo apt-get install socat
   
   # Install socat (CentOS/RHEL)
   sudo yum install socat

5. Dovecot Not Detected:

   • Verify Dovecot is running: systemctl status dovecot
   • Ensure dovecot command is available: which dovecot

• Service logs: journalctl -u dovecot-exporter -f
• Manual logs: Scripts output to stderr

For high-traffic mail servers:

• Adjust LOG_LINES to analyze fewer lines (faster but less accurate)
• Consider running exporter on a separate monitoring server
• Monitor system resources
• Tune scrape interval in Prometheus

# Run basic tests
sudo ./dovecot-exporter.sh test
sudo ./http-server.sh test

# Test with different configurations
DOVECOT_LOG=/var/log/maillog sudo ./dovecot-exporter.sh test

1. Fork the repository
2. Create a feature branch
3. Test thoroughly
4. Submit a pull request

This project is licensed under the BSD 2-Clause License - see the LICENSE file for details.

• GitHub Issues: https://github.com/itefixnet/prometheus-dovecot-exporter/issues
• Documentation: This README and inline script comments

This exporter focuses on simplicity and minimal dependencies. For more advanced features, consider:

• dovecot_exporter (Go-based)