Alerts

Category:GUI manual

Alerts & Reports

Alerts & Reports generate email notifications based on QoS parameters or SIP error conditions. The system includes daily reports, ad hoc reports, and stores all generated items in history.

Overview

The alert system monitors call quality and SIP signaling in real-time, triggering notifications when configured thresholds are exceeded.

Email Configuration Prerequisites

Emails are sent using PHP's mail() function, which relies on the server's Mail Transfer Agent (MTA) such as Exim, Postfix, or Sendmail. Configure your MTA according to your Linux distribution documentation.

Setting Up the Cron Job

Alert processing requires a cron job that runs every minute:

# Add to /etc/crontab (adjust path based on your GUI installation)
echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab

# Reload crontab
killall -HUP cron   # Debian/Ubuntu
# or
killall -HUP crond  # CentOS/RHEL

Configure Alerts

Email alerts can trigger on SIP protocol events or RTP QoS metrics. Access alerts configuration via GUI > Alerts.

Alert configuration grid

Alert Types

RTP Alerts

RTP alerts trigger based on voice quality metrics:

• MOS (Mean Opinion Score) - below threshold
• Packet loss - percentage exceeded
• Jitter - variation exceeded
• Delay (PDV) - latency exceeded
• One-way calls - answered but one RTP stream missing
• Missing RTP - answered but both RTP streams missing

Configure alerts to trigger when:

• Number of incidents exceeds a set value, OR
• Percentage of CDRs exceeds a threshold

RTP alert configuration form

SIP Response Alerts

SIP response alerts trigger based on SIP response codes:

• Empty response field: Matches all call attempts per configured filters
• Response code 0: Matches unreplied INVITE requests (no response received)
• Specific codes: Match exact codes like 404, 503, etc.

SIP response alert configuration form

Sensors Alerts

Sensors alerts monitor the health of VoIPmonitor probes and sniffer instances. This is the most reliable method to check if remote sensors are online and actively monitoring traffic.

Unlike simple network port monitoring (which may show a port as open even if the process is frozen or unresponsive), sensors alerts verify that the sensor instance is actively communicating with the VoIPmonitor GUI server.

Setup

1. Configure sensors in Settings > Sensors
2. Create a sensors alert to be notified when a probe goes offline or becomes unresponsive

Common Filters

All alert types support the following filters:

Filter	Description
IP/Number Group	Apply alert to predefined groups (from Groups menu)
IP Addresses	Individual IPs or ranges (one per line)
Numbers	Individual phone numbers or prefixes (one per line)
Email Group	Send alerts to group-defined email addresses
Emails	Individual recipient emails (one per line)

Alert filter configuration

Sent Alerts

All triggered alerts are saved in history and can be viewed via GUI > Alerts > Sent Alerts. The content matches what was sent via email.

Sent alerts history

Parameters Table

The parameters table shows QoS metrics with problematic values highlighted for quick identification.

Alert parameters with highlighted bad values

CDR Records Table

The CDR records table lists all calls that triggered the alert. Each row includes alert flags indicating which thresholds were exceeded:

• (M) - MOS below threshold
• (J) - Jitter exceeded
• (P) - Packet loss exceeded
• (D) - Delay exceeded

Anti-Fraud Alerts

VoIPmonitor includes specialized anti-fraud alert rules for detecting attacks and fraudulent activity. These include:

• Realtime concurrent calls monitoring
• SIP REGISTER flood/attack detection
• SIP PACKETS flood detection
• Country/Continent destination alerts
• CDR/REGISTER country change detection

For detailed configuration of anti-fraud rules and custom action scripts, see Anti-Fraud Rules.

Alerts Based on Custom Reports

In addition to native alert types (RTP, SIP response, Sensors), VoIPmonitor supports generating alerts from custom reports. This workflow enables alerts based on criteria not available in native alert types, such as SIP header values captured via CDR custom headers.

Workflow Overview =

1. Capture custom SIP headers in the database 2. Create a custom report filtered by the custom header values 3. Generate an alert from that report 4. Configure alert email options (e.g., limit email size)

Example: Alert on SIP Max-Forwards Header Value =

This example shows how to receive an alert when the SIP Max-Forwards header value drops below 15.

Step 1: Configure Sniffer Capture

Add the header to your /etc/voipmonitor.conf configuration file:

# Capture Max-Forwards header
custom_headers = Max-Forwards

Restart the sniffer to apply changes:

service voipmonitor restart

Step 2: Configure Custom Header in GUI

1. Navigate to GUI > Settings > CDR Custom Headers 2. Select Max-Forwards from the available headers 3. Enable Show as Column to display it in CDR views 4. Save configuration

Step 3: Create Custom Report

1. Navigate to GUI > CDR Custom Headers or use the Report Generator 2. Create a filter for calls where Max-Forwards is less than 15 3. Since custom headers store string values, use a filter expression that matches the desired values:

15 14 13 12 11 10 0_ _

  Include additional space-separated values or use NULL to match other ranges as needed.

4. Run the report to verify it captures the expected calls

Step 4: Generate Alert from Report

You can create an alert based on this custom report using the Daily Reports feature:

1. Navigate to GUI > Reports > Configure Daily Reports 2. Click Add Daily Report 3. Configure the filter to target the custom header criteria (e.g., Max-Forwards < 15) 4. Set the schedule (e.g., run every hour) 5. Save the daily report configuration

Step 5: Limit Alert Email Size (Optional)

If the custom report generates many matching calls, the alert email can become large. To limit the email size:

1. Edit the daily report 2. Go to the Basic Data tab 3. Set the max-lines in body option to the desired limit (e.g., 100 lines)

Additional Use Cases =

This workflow can be used for various custom monitoring scenarios:

• SIP headers beyond standard SIP response codes - Monitor any custom SIP header
• Complex filtering logic - Create reports based on multiple custom header filters
• Threshold monitoring for string fields - When numeric comparison is not available, use string matching

For more information on configuring custom headers, see CDR Custom Headers.

Troubleshooting Email Alerts

If email alerts are not being sent, the issue is typically with the Mail Transfer Agent (MTA) rather than VoIPmonitor.

Step 1: Test Email Delivery from Command Line

Before investigating complex issues, verify your server can send emails:

# Test using the 'mail' command
echo "Test email body" | mail -s "Test Subject" your.email@example.com

If this fails, the issue is with your MTA configuration, not VoIPmonitor.

Step 2: Check MTA Service Status

Ensure the MTA service is running:

# For Postfix (most common)
sudo systemctl status postfix

# For Exim (Debian default)
sudo systemctl status exim4

# For Sendmail
sudo systemctl status sendmail

If the service is not running or not installed, install and configure it according to your Linux distribution's documentation.

Step 3: Check Mail Logs

Examine the MTA logs for specific error messages:

# Debian/Ubuntu
tail -f /var/log/mail.log

# RHEL/CentOS/AlmaLinux/Rocky
tail -f /var/log/maillog

Common errors and their meanings:

Error Message	Cause	Solution
Connection refused	MTA not running or firewall blocking	Start MTA service, check firewall rules
Relay access denied	SMTP relay misconfiguration	Configure proper relay settings
Authentication failed	Incorrect credentials	Verify credentials in sasl_passwd
Host or domain name lookup failed	DNS issues	Check /etc/resolv.conf
Greylisted	Temporary rejection	Wait and retry, or whitelist sender

Step 4: Check Mail Queue

Emails may be stuck in the queue if delivery is failing:

# View the mail queue
mailq

# Force immediate delivery attempt
postqueue -f

Deferred or failed messages in the queue contain error details explaining why delivery failed.

Step 5: Verify Cronjob

Ensure the alert processing script runs every minute:

# Check current crontab
crontab -l

You should see:

* * * * * root php /var/www/html/php/run.php cron

If missing, add it:

crontab -e
# Add the line above, then reload cron
killall -HUP cron

Step 6: Verify Alert Configuration in GUI

After confirming the MTA works:

1. Navigate to GUI > Alerts
2. Verify alert conditions are enabled
3. Check that recipient email addresses are valid
4. Go to GUI > Alerts > Sent Alerts to see if alerts were triggered

Diagnosis:

• Entries in "Sent Alerts" but no emails received → MTA issue
• No entries in "Sent Alerts" → Check alert conditions or cronjob

Step 7: Test PHP mail() Function

Isolate the issue by testing PHP directly:

php -r "mail('your.email@example.com', 'Test from PHP', 'This is a test email');"

• If this works but VoIPmonitor alerts don't → Check GUI cronjob and alert configuration
• If this fails → MTA or PHP configuration issue

See Also

• Anti-Fraud Rules - Detailed fraud detection configuration
• Reports - Daily reports and report generator
• Sniffer Troubleshooting - General troubleshooting

AI Summary for RAG

Summary: VoIPmonitor Alerts & Reports system for email notifications on QoS and SIP issues. Covers RTP alerts (MOS, jitter, packet loss), SIP response alerts, sensors health monitoring, and creating alerts from custom reports based on CDR custom headers. Includes email troubleshooting for MTA configuration.

Keywords: alerts, email notifications, QoS, MOS, jitter, packet loss, SIP response, sensors monitoring, crontab, MTA, Postfix, Exim, troubleshooting, custom headers, custom reports, Max-Forwards, daily reports

Key Questions:

• How do I set up email alerts in VoIPmonitor?
• What types of alerts are available (RTP, SIP, Sensors)?
• How do I configure crontab for alert processing?
• How do I monitor remote sensor health?
• Why are email alerts not being sent?
• How do I troubleshoot MTA email issues?
• How can I create alerts based on SIP headers like Max-Forwards?
• How do I use CDR custom headers for custom reports?
• How do I limit the size of alert emails from custom reports?