Monitoring Kopano Groupware with Vigilmon

Kopano is the open source successor to Zarafa Groupware, providing an Exchange-compatible email, calendar, contacts, and collaboration platform for European enterprises and public sector organisations. Users access Kopano through Outlook (via the Kopano Outlook Extension), a browser (Kopano WebApp), and mobile devices (Z-Push ActiveSync / CalDAV). All of these access paths depend on kopano-server — the core MAPI store — and MySQL holding every mailbox item.

Vigilmon gives you end-to-end visibility across all Kopano components: the MAPI store, the database, IMAP/POP3 gateway, inbound and outbound mail delivery, CalDAV, Z-Push, and the web application. This tutorial walks through setting up monitoring for each layer so your team knows about failures before users start filing tickets.

What You'll Set Up

• kopano-server process and MAPI port health check
• MySQL database health monitor
• kopano-gateway IMAP/POP3 port monitor
• kopano-dagent and kopano-spooler delivery health
• kopano-ical CalDAV endpoint health check
• Z-Push ActiveSync endpoint health check
• Kopano WebApp HTTP health check
• Alert routing to Slack or email

Prerequisites

• Kopano 8.7+ installed on Debian/Ubuntu or RHEL/CentOS
• kopano-server, kopano-gateway, kopano-dagent, kopano-spooler, kopano-ical, Z-Push, and Kopano WebApp configured
• A free Vigilmon account

Step 1: Monitor kopano-server

kopano-server is the MAPI store that underpins all Kopano access — Outlook, WebApp, and mobile clients all communicate through it. A kopano-server crash means immediate, total loss of groupware functionality.

kopano-server listens on TCP port 236 (default) or a Unix socket. Monitor the TCP port:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to TCP Port.
3. Enter your Kopano server hostname.
4. Set Port to 236.
5. Set Check interval to 1 minute.
6. Click Save.

If kopano-server is configured for Unix socket only, add a lightweight HTTP health endpoint using a custom script:

#!/bin/bash
# /usr/local/bin/kopano-health-check
# Returns 0 if kopano-server is responsive, 1 otherwise
kopanoctl status kopano-server 2>/dev/null | grep -q "Active: active" && exit 0 || exit 1

Then expose this via a simple HTTP wrapper (e.g., systemd socket or a small FastCGI script) and monitor the HTTP endpoint.

Step 2: Monitor MySQL Health

kopano-server stores all groupware items (emails, calendar events, contacts, tasks, notes) as MAPI objects in MySQL. A database failure causes complete loss of access to all mailboxes.

Add a TCP port monitor for MySQL:

1. Click Add Monitor → TCP Port.
2. Enter your MySQL server hostname.
3. Set Port to 3306.
4. Set Check interval to 1 minute.
5. Click Save.

For a query-level health check, create a PHP or Python endpoint:

#!/usr/bin/env python3
# /var/www/html/kopano-db-health.py (via CGI or uWSGI)
import pymysql, os, json, sys

try:
    conn = pymysql.connect(
        host='localhost', user='kopano',
        password=os.environ.get('KOPANO_DB_PASS', ''),
        database='kopano'
    )
    conn.cursor().execute('SELECT 1')
    conn.close()
    print('Status: 200 OK\r\nContent-Type: application/json\r\n')
    print(json.dumps({'db': 'ok'}))
except Exception as e:
    print('Status: 503 Service Unavailable\r\nContent-Type: application/json\r\n')
    print(json.dumps({'db': 'error', 'msg': str(e)}))

Monitor this endpoint every 1 minute with an expected status of 200.

Step 3: Monitor kopano-gateway (IMAP/POP3)

kopano-gateway provides IMAP and POP3 access to the MAPI store, enabling standard email clients (Thunderbird, Apple Mail) to access Kopano mailboxes. Monitor both IMAP and POP3 ports:

Add a TCP port monitor for IMAPS:

1. Click Add Monitor → TCP Port.
2. Enter your Kopano server hostname.
3. Set Port to 993 (IMAPS).
4. Set Check interval to 1 minute.
5. Click Save.

Repeat for IMAP with STARTTLS (port 143) and POP3S (port 995) if enabled:

993  → IMAPS
143  → IMAP + STARTTLS
995  → POP3S
110  → POP3 + STARTTLS

A failed TCP connection on any of these ports means affected email clients lose access immediately.

Step 4: Monitor kopano-dagent Delivery Health

kopano-dagent receives inbound email via LMTP from Postfix and delivers it into the MAPI store. If dagent fails, inbound email queues up in Postfix but never reaches Kopano mailboxes — users see no new email even though the IMAP gateway is responding.

Monitor the LMTP port that dagent listens on:

1. Click Add Monitor → TCP Port.
2. Enter your Kopano server hostname.
3. Set Port to 2003 (kopano-dagent default LMTP port).
4. Set Check interval to 1 minute.
5. Click Save.

For end-to-end delivery verification, combine the TCP check with a heartbeat monitor: send a test email at a regular interval (e.g., from a cron job) and use Vigilmon's cron heartbeat URL to confirm delivery:

#!/bin/bash
# /etc/cron.d/kopano-delivery-test — runs every 5 minutes
*/5 * * * * root echo "Delivery test $(date)" | mail -s "Kopano Health Check" monitor@yourdomain.com && curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID

Step 5: Monitor kopano-spooler (Outbound Email)

kopano-spooler takes emails from the MAPI outbox and hands them to Postfix for delivery. If the spooler fails, users appear to send email but nothing leaves the server.

kopano-spooler does not expose a direct network port, but you can monitor it via a health endpoint that checks the process and queue depth:

#!/bin/bash
# /usr/local/bin/kopano-spooler-health (served via simple HTTP)
if systemctl is-active --quiet kopano-spooler; then
    echo '{"spooler":"ok"}'
    exit 0
else
    echo '{"spooler":"stopped"}'
    exit 1
fi

Wrap this in a small HTTP server or CGI handler and monitor the endpoint. Alternatively, monitor Postfix's deferred queue as a proxy for spooler health — a growing deferred queue combined with kopano-spooler being down is a reliable failure signal.

Step 6: Monitor kopano-ical CalDAV Endpoint

kopano-ical provides CalDAV/iCalendar access to the MAPI calendar store, enabling mobile devices and third-party calendar apps to sync with Kopano calendars.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter https://groupware.yourdomain.com/ical/.
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 401 (CalDAV returns 401 without authentication — confirms the service is alive).
5. Click Save.

kopano-ical typically runs as a separate service on its own port (default: 8080 for HTTP, 8443 for HTTPS) or is proxied via Apache/Nginx. Adjust the URL accordingly.

Step 7: Monitor Z-Push (ActiveSync)

Z-Push is the ActiveSync implementation that enables Outlook (via its native Exchange connector) and mobile devices to sync email, calendar, and contacts with Kopano. A Z-Push failure blocks all mobile sync and Outlook connectivity.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter https://groupware.yourdomain.com/Microsoft-Server-ActiveSync.
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 401 (ActiveSync requires authentication; a 401 confirms Z-Push is responding).
5. Click Save.

If Z-Push is behind a path prefix or subdomain, update the URL. The critical check is that the endpoint responds at all — a 502 or connection refused indicates Apache/PHP or Z-Push itself has failed.

Step 8: Monitor Kopano WebApp

Kopano WebApp is the browser-based groupware interface backed by PHP and the kopano-server MAPI store. A WebApp failure blocks all browser users.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter https://groupware.yourdomain.com/webapp/.
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 200.
5. Enable Monitor SSL certificate and alert when less than 21 days remain.
6. Click Save.

For PHP-FPM health, add a status endpoint via Nginx:

# In your Nginx config
location = /fpm-status {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php7.4-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    allow 127.0.0.1;
    deny all;
}

Monitor http://localhost/fpm-status from a local cron heartbeat, or expose it on an internal-only address and monitor it from Vigilmon.

Step 9: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. For kopano-server and MySQL monitors, set Consecutive failures before alert to 1 — these are critical infrastructure; single-probe failures warrant immediate notification.
3. For CalDAV and ActiveSync monitors, set to 2 — transient proxy timeouts can cause single-probe failures without a real outage.
4. Enable On-call escalation if you have an on-call rotation: Vigilmon can notify a primary contact and escalate to a secondary after a configurable delay.

Summary

| Monitor | Target | What It Catches | |---|---|---| | kopano-server | TCP port 236 | MAPI store crash — total groupware outage | | MySQL | TCP port 3306 | Database crash — all mailbox access fails | | kopano-gateway | TCP ports 993, 143 | IMAP/POP3 access failure for email clients | | kopano-dagent | TCP port 2003 (LMTP) | Inbound email delivery failure | | kopano-spooler | Process health endpoint | Outbound email stuck in MAPI outbox | | kopano-ical | /ical/ HTTP endpoint | Mobile calendar sync failure | | Z-Push | /Microsoft-Server-ActiveSync | Outlook and mobile sync failure | | Kopano WebApp | /webapp/ HTTP endpoint | Browser interface failure |

Kopano's Exchange-compatible architecture means it has multiple independently-failable components. With Vigilmon watching each one, you catch failures at any layer — from the MAPI store and database up through delivery agents and the web interface — long before users notice their email, calendar, or contacts have stopped working.