tutorial

Monitoring Znuny with Vigilmon

Znuny (formerly OTRS Community Edition) is the ITSM backbone for thousands of European enterprises. Here's how to monitor Znuny's web app, daemon, email pipeline, and ticket SLAs with Vigilmon.

Znuny (forked from OTRS 6 in 2021) is the open source ITSM and helpdesk ticketing system used widely across European enterprises and government organizations. It handles ticket management, SLA tracking, change management, and customer service workflows on a Perl-based stack backed by MySQL/MariaDB or PostgreSQL. For teams that rely on Znuny for incident management, an outage in Znuny is an incident — and you need to know about it from outside the system. Vigilmon monitors Znuny's web application, daemon, email pipeline, and database from the outside so you're alerted the moment your ITSM platform goes dark.

What You'll Set Up

  • Znuny web application HTTP health monitoring
  • Znuny Daemon process health via heartbeat
  • Email ingestion (IMAP/POP3) health monitoring
  • Database health checks
  • Ticket escalation rate alerting
  • Outbound email (SMTP) delivery monitoring
  • GenericInterface API health

Prerequisites

  • Znuny 6.x or later installed
  • SSH access to the Znuny server
  • A free Vigilmon account

Step 1: Monitor the Znuny Web Application

Znuny serves its ITSM interface via Apache/mod_perl or Nginx/FastCGI. Monitor the login page to confirm the web tier is healthy.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Znuny URL: https://your-znuny-server/otrs/index.pl.
  4. Set Check interval to 1 minute.
  5. Enable Keyword check and enter Znuny (or OTRS) to verify the page content.
  6. Click Save.

Also monitor the customer-facing portal if you have one:

https://your-znuny-server/otrs/customer.pl

A down response here means agents and customers can't log in, create tickets, or update their issues.

If you have SSL, enable Monitor SSL certificate with a 21-day alert threshold — Znuny installations often handle sensitive internal communications and a certificate expiry is a high-visibility incident.

Step 2: Monitor the Znuny Daemon via Heartbeat

The Znuny Daemon (znuny.Daemon.pl) handles scheduled tasks: GenericInterface calls, escalation checks, automatic email fetching, and GenericAgent jobs. If the daemon crashes, escalations stop firing and emails stop being fetched.

In Vigilmon:

  1. Click Add Monitor → Cron Heartbeat.
  2. Set timeout to 10 minutes.
  3. Copy the heartbeat URL.

Create the daemon health script:

# /usr/local/bin/znuny-daemon-heartbeat.sh
#!/bin/bash

HEARTBEAT_URL="https://vigilmon.online/heartbeat/abc123"
ZNUNY_HOME="/opt/otrs"  # Adjust to your Znuny installation path
ZNUNY_USER="otrs"

# Check daemon status
DAEMON_STATUS=$(su - "$ZNUNY_USER" -c "perl $ZNUNY_HOME/bin/znuny.Daemon.pl status 2>/dev/null" | grep -c "Running")

if [ "$DAEMON_STATUS" -gt 0 ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
else
    echo "CRITICAL: Znuny Daemon is not running" >&2
    exit 1
fi

Add to crontab (run as root):

*/5 * * * * /usr/local/bin/znuny-daemon-heartbeat.sh

The Znuny Daemon spawns multiple child processes. The status command confirms all critical scheduler and cron task processes are active.

Step 3: Monitor Email Ingestion Health

Znuny polls IMAP or POP3 mailboxes to create tickets from incoming email. Fetch failures mean inbound requests go untracked.

Create a heartbeat that checks the last successful email fetch:

# /usr/local/bin/check-znuny-email.sh
#!/bin/bash

HEARTBEAT_URL="https://vigilmon.online/heartbeat/def456"
DB_NAME="znuny"
DB_USER="znuny"
DB_PASS="znuny"

# Check the last time the mail account fetcher ran successfully
# Znuny logs mail account polling in the communication log
last_fetch=$(mysql -u "$DB_USER" -p"$DB_PASS" "$DB_NAME" -s --skip-column-names \
    -e "SELECT MAX(create_time) FROM communication_log WHERE account_type IN ('IMAP','POP3') AND status='Successful' AND create_time > DATE_SUB(NOW(), INTERVAL 30 MINUTE);" 2>/dev/null)

if [ -n "$last_fetch" ] && [ "$last_fetch" != "NULL" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
else
    echo "WARNING: no successful email fetch in the last 30 minutes" >&2
fi

Set the Vigilmon heartbeat timeout to 35 minutes. Add to crontab:

*/15 * * * * /usr/local/bin/check-znuny-email.sh

Step 4: Monitor Database Health

All Znuny ticket data, user accounts, SLAs, and configuration live in MySQL/MariaDB or PostgreSQL. Database failure stops everything.

MySQL/MariaDB

Add a TCP port monitor in Vigilmon:

  1. Click Add Monitor → TCP Port.
  2. Port: 3306.
  3. Check interval: 1 minute.
  4. Save.

Add a deeper query-level heartbeat:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/ghi789"

# Verify the DB is accepting queries and ticket tables are accessible
ticket_count=$(mysql -u znuny -pznuny znuny -s --skip-column-names \
    -e "SELECT COUNT(*) FROM ticket WHERE create_time > DATE_SUB(NOW(), INTERVAL 24 HOUR);" 2>/dev/null)

if [ $? -eq 0 ] && [ -n "$ticket_count" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
fi

PostgreSQL

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/ghi789"

ticket_count=$(PGPASSWORD=znuny psql -U znuny -d znuny -t -c \
    "SELECT COUNT(*) FROM ticket WHERE create_time > NOW() - INTERVAL '24 hours';" 2>/dev/null | xargs)

if [ $? -eq 0 ] && [ -n "$ticket_count" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
fi

Step 5: Monitor Ticket Escalation Rate

Znuny tracks SLA breaches as escalated tickets. A growing escalation count means your team is falling behind their SLA commitments — or the daemon that monitors escalations has stopped.

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/jkl012"
MAX_ESCALATIONS=20  # Adjust for your team's SLA budget

# Count currently escalated open tickets
escalated=$(mysql -u znuny -pznuny znuny -s --skip-column-names \
    -e "SELECT COUNT(*) FROM ticket WHERE ticket_state_id IN (
        SELECT id FROM ticket_state WHERE type_id IN (
            SELECT id FROM ticket_state_type WHERE name IN ('open','pending reminder')
        )
    ) AND escalation_time > 0 AND escalation_time < UNIX_TIMESTAMP();" 2>/dev/null)

if [ -n "$escalated" ] && [ "$escalated" -lt "$MAX_ESCALATIONS" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
else
    echo "WARNING: $escalated escalated tickets (threshold: $MAX_ESCALATIONS)" >&2
fi

Set heartbeat timeout to 30 minutes. Missing = escalation count too high or DB unreachable.

Step 6: Monitor Outbound Email Delivery

Znuny sends ticket notifications, auto-responses, and SLA alerts via SMTP. Delivery failures mean agents miss ticket updates and customers get no response acknowledgments.

Add a TCP monitor for your SMTP server:

  1. Click Add Monitor → TCP Port.
  2. Port: 25 (or 587 for submission).
  3. Check interval: 1 minute.
  4. Save.

For a deeper check that verifies Znuny's outbound mail queue isn't backing up:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/mno345"

# Check the Znuny communication log for recent successful outbound deliveries
recent_sent=$(mysql -u znuny -pznuny znuny -s --skip-column-names \
    -e "SELECT COUNT(*) FROM communication_log WHERE direction='Outgoing' AND status='Successful' AND create_time > DATE_SUB(NOW(), INTERVAL 30 MINUTE);" 2>/dev/null)

# If no emails have been sent in 30 minutes but tickets exist, that might be a problem
# Only alert if it's business hours (adjust logic for your timezone)
hour=$(date +%H)
if [ "$hour" -ge 8 ] && [ "$hour" -le 18 ]; then
    if [ -n "$recent_sent" ] && [ "$recent_sent" -gt 0 ]; then
        curl -fsS "$HEARTBEAT_URL" --max-time 10
    fi
else
    # Outside business hours, just check SMTP connectivity
    curl -fsS "$HEARTBEAT_URL" --max-time 10
fi

Step 7: Monitor the GenericInterface API

Znuny's GenericInterface provides REST/SOAP endpoints for integrating with ITSM tools, monitoring systems, and CRMs. API failures break external integrations.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://your-znuny-server/otrs/nph-genericinterface.pl/Webservice/YourWebservice.
  3. Set Expected HTTP status to 200 or 401 (401 means the endpoint is alive but requires authentication).
  4. Check interval: 2 minutes.
  5. Save.

For a scripted check that validates authentication works:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/pqr678"
ZNUNY_URL="https://your-znuny-server"
API_USER="api_user"
API_PASS="api_password"

response=$(curl -fsS -o /dev/null -w "%{http_code}" \
    -X POST "${ZNUNY_URL}/otrs/nph-genericinterface.pl/Webservice/GenericTicketConnectorREST/Session" \
    -H "Content-Type: application/json" \
    -d "{\"UserLogin\":\"${API_USER}\",\"Password\":\"${API_PASS}\"}" \
    --max-time 10 2>/dev/null)

if [ "$response" = "200" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
fi

Step 8: Monitor Queue Depth Per Service Team

Tickets queued for specific teams can pile up silently. Monitor the queue depth per service team to catch routing failures and staffing gaps.

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/stu901"
QUEUE_NAME="Service Desk"  # Monitor your most critical queue
MAX_TICKETS=50

pending=$(mysql -u znuny -pznuny znuny -s --skip-column-names \
    -e "SELECT COUNT(*) FROM ticket t
        JOIN queue q ON t.queue_id = q.id
        JOIN ticket_state ts ON t.ticket_state_id = ts.id
        JOIN ticket_state_type tst ON ts.type_id = tst.id
        WHERE q.name = '${QUEUE_NAME}'
        AND tst.name IN ('open','pending reminder');" 2>/dev/null)

if [ -n "$pending" ] && [ "$pending" -lt "$MAX_TICKETS" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
else
    echo "WARNING: $pending tickets in queue ${QUEUE_NAME} (threshold: $MAX_TICKETS)" >&2
fi

Create separate heartbeats for each critical queue and set thresholds appropriate to each team's capacity.

Step 9: Configure Alerting

  1. In Vigilmon, click Alerts → Add Alert Channel.
  2. Add your notification channels:
    • Email — service desk manager or on-call
    • Slack — #itsm-alerts channel
    • PagerDuty — for P1 outages affecting all ticket creation

Recommended Alert Policy

| Monitor | Condition | Severity | |---------|-----------|----------| | Znuny web app | Down for 2 minutes | Critical | | Znuny Daemon heartbeat | Missing for 15 minutes | Critical | | Email ingestion heartbeat | Missing for 40 minutes | Warning | | Database TCP port | Down for 1 minute | Critical | | SMTP port | Down for 2 minutes | Warning | | Escalation rate | Heartbeat missing | Warning | | GenericInterface API | Down for 5 minutes | Warning |

The Daemon and web app failures should be P1 — if Znuny is down, your ITSM process is broken.

Step 10: Monitor Session Storage Health

Znuny stores web sessions in the database or filesystem. Session storage failure causes all users to get logged out.

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/vwx234"

# For DB-based sessions: check session table is accessible
session_count=$(mysql -u znuny -pznuny znuny -s --skip-column-names \
    -e "SELECT COUNT(*) FROM sessions WHERE create_time > DATE_SUB(NOW(), INTERVAL 2 HOUR);" 2>/dev/null)

if [ $? -eq 0 ] && [ -n "$session_count" ]; then
    curl -fsS "$HEARTBEAT_URL" --max-time 10
fi

For filesystem-based sessions, check the session directory is writable:

#!/bin/bash
HEARTBEAT_URL="https://vigilmon.online/heartbeat/vwx234"
SESSION_DIR="/opt/otrs/var/sessions"

if [ -w "$SESSION_DIR" ] && [ -d "$SESSION_DIR" ]; then
    # Verify sessions directory is accessible and not full
    usage=$(df "$SESSION_DIR" | awk 'NR==2{print $5}' | tr -d '%')
    if [ "${usage:-0}" -lt 90 ]; then
        curl -fsS "$HEARTBEAT_URL" --max-time 10
    fi
fi

Conclusion

Znuny is the backbone of ITSM operations for your organization — when it fails, there's no system to track the incident. Vigilmon provides external, independent monitoring that alerts you before your users find out Znuny is down.

Key monitoring priorities for Znuny:

  • Web application must be accessible for all agents and customers at all times
  • Znuny Daemon is critical — escalations, email fetching, and automated jobs all depend on it
  • Email ingestion failures silently discard incoming support requests
  • Database health is foundational — all Znuny data flows through it
  • Queue depth monitoring catches staffing gaps and routing problems before SLAs are breached

Deploy these monitors now and keep your ITSM platform visible from the outside.

Start monitoring Znuny with Vigilmon →

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles