Alerts: Difference between revisions

From VoIPmonitor.org
(Add comprehensive troubleshooting section for email alerts including CLI testing, MTA status, mail logs, and queue inspection)
(Restructure: add PlantUML diagram, fix syntax highlighting, add tables, reference Anti-fraud page, streamline AI summary)
Line 1: Line 1:
{{DISPLAYTITLE:Alerts & Reports}}
Category:GUI manual
== Alerts & Reports ==
== Alerts & Reports ==


Alerts & Reports generate email notifications based on QoS parameters or SIP error conditions. It includes daily reports, ad hoc reports, and stores all generated items in history.
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.


Emails use PHP's "mail" function, relying on the server's MTA (e.g., Exim, Postfix, Sendmail). Configure MTA per your Linux distribution documentation.
<kroki lang="plantuml">
@startuml
skinparam shadowing false
skinparam defaultFontName Arial


Process alerts via a PHP script in crontab:
rectangle "VoIPmonitor\nSensor" as sensor
database "MySQL\nDatabase" as db
rectangle "Cron Job\n(every minute)" as cron
rectangle "Alert\nProcessor" as processor
rectangle "MTA\n(Postfix/Exim)" as mta
actor "Admin" as admin


For CentOS & Debian:
sensor --> db : CDRs with\nQoS metrics
cron --> processor : Trigger
processor --> db : Query alerts\n& CDRs
processor --> mta : Send email
mta --> admin : Alert notification
@enduml
</kroki>


echo "* * * * * root php /var/www/html/php/run.php cron" >> /etc/crontab
=== Email Configuration Prerequisites ===


(Adjust path to run.php based on VoIPmonitor GUI installation.)
Emails are sent using PHP's <code>mail()</code> 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.


Reload crontab: killall -HUP cron (or crond).
==== Setting Up the Cron Job ====
 
Alert processing requires a cron job that runs every minute:
 
<syntaxhighlight lang="bash">
# 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
</syntaxhighlight>


=== Configure Alerts ===
=== Configure Alerts ===


Email alerts trigger on SIP protocol or RTP QoS metrics. Types: RTP alerts and SIP signaling.
Email alerts can trigger on SIP protocol events or RTP QoS metrics. Access alerts configuration via '''GUI > Alerts'''.


Common filters: Call duration, IP addresses, numbers, and email recipients.
[[File:alertgrid.png|frame|center|Alert configuration grid]]


[[File:alertgrid.png]]
==== Alert Types ====


* '''RTP Alerts''': Trigger on MOS, packet loss, jitter, delay, one-way calls (answered but one RTP stream missing), or missing RTP (answered but both streams missing). Alert if thresholds exceeded and incidents > set value or CDR percent > threshold.
===== RTP Alerts =====


[[File:alertrtpform.png]]
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


* '''SIP Response Alerts''': Trigger on SIP response codes. Empty response: All call attempts per filters. Response 0: Unreplied INVITEs.
Configure alerts to trigger when:
* Number of incidents exceeds a set value, OR
* Percentage of CDRs exceeds a threshold


[[File:alertsipform.png]]
[[File:alertrtpform.png|frame|center|RTP alert configuration form]]


* '''Sensors Alerts''': Built-in alert type for monitoring the status and 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 is open even if the process is frozen or unresponsive), sensors alerts verify that the sensor instance is actively communicating with the VoIPmonitor GUI server. Configure sensors in Settings > Sensors, then create a sensors alert to be notified when a probe goes offline or becomes unresponsive.
===== SIP Response Alerts =====


* '''Filters''':
SIP response alerts trigger based on SIP response codes:
  - IP/Number Group: Apply to defined groups (from Groups menu).
* '''Empty response field''': Matches all call attempts per configured filters
  - IP Addresses/Numbers: Individual IPs, numbers, or ranges (delimited by Enter).
* '''Response code 0''': Matches unreplied INVITE requests (no response received)
  - Email Group: Send to group-defined emails.
* '''Specific codes''': Match exact codes like 404, 503, etc.
  - Emails: Individual emails (delimited by Enter).


[[File:alertgroup.png]]
[[File:alertsipform.png|frame|center|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:
:# Configure sensors in '''Settings > Sensors'''
:# Create a sensors alert to be notified when a probe goes offline or becomes unresponsive
 
==== Common Filters ====
 
All alert types support the following filters:
 
{| class="wikitable"
|-
! 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)
|}
 
[[File:alertgroup.png|frame|center|Alert filter configuration]]


=== Sent Alerts ===
=== Sent Alerts ===


Sent alerts are saved in history, matching email content.
All triggered alerts are saved in history and can be viewed via '''GUI > Alerts > Sent Alerts'''. The content matches what was sent via email.
 
[[File:alert-sentalerts.png|frame|center|Sent alerts history]]
 
==== Parameters Table ====
 
The parameters table shows QoS metrics with problematic values highlighted for quick identification.
 
[[File:alert-perameters.png|frame|center|Alert parameters with highlighted bad values]]
 
==== CDR Records Table ====


[[File:alert-sentalerts.png]]
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


Parameters table shows QoS metrics with bad values highlighted.
=== Anti-Fraud Alerts ===


[[File:alert-perameters.png]]
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


CDR records table lists cases, with alert flags: (M)OS, (J)itter, (P)acket loss, (D)elay.
For detailed configuration of anti-fraud rules and custom action scripts, see [[Anti-fraud|Anti-Fraud Rules]].


=== Troubleshooting Email Alerts ===
=== Troubleshooting Email Alerts ===


If email alerts are not being sent, the issue is typically with the Mail Transfer Agent (MTA) rather than VoIPmonitor. Follow these steps to diagnose and fix the problem.
If email alerts are not being sent, the issue is typically with the Mail Transfer Agent (MTA) rather than VoIPmonitor.


==== Test Email Delivery from Command Line ====
==== Step 1: Test Email Delivery from Command Line ====


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


{{{
<syntaxhighlight lang="bash">
# Test sending an email using the 'mail' command
# Test using the 'mail' command
echo "Test email body" | mail -s "Test Subject" your.email@example.com
echo "Test email body" | mail -s "Test Subject" your.email@example.com
}}}
</syntaxhighlight>


If this fails, the issue is with your MTA (Postfix, Exim, or Sendmail) and not with VoIPmonitor.
If this fails, the issue is with your MTA configuration, not VoIPmonitor.


==== Check Mail Transfer Agent (MTA) Status ====
==== Step 2: Check MTA Service Status ====


Ensure the MTA service is running:
Ensure the MTA service is running:


{{{
<syntaxhighlight lang="bash">
# For Postfix (most common)
# For Postfix (most common)
sudo systemctl status postfix
sudo systemctl status postfix


# For Exim
# For Exim (Debian default)
sudo systemctl status exim4
sudo systemctl status exim4


# For Sendmail
# For Sendmail
sudo systemctl status sendmail
sudo systemctl status sendmail
}}}
</syntaxhighlight>


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


==== Check Mail Logs ====
==== Step 3: Check Mail Logs ====


Examine the MTA logs for specific error messages that indicate why emails are failing:
Examine the MTA logs for specific error messages:


{{{
<syntaxhighlight lang="bash">
# Debian/Ubuntu (default mail log location)
# Debian/Ubuntu
tail -f /var/log/mail.log
tail -f /var/log/mail.log


# RHEL/CentOS/Alma/Rocky
# RHEL/CentOS/AlmaLinux/Rocky
tail -f /var/log/maillog
tail -f /var/log/maillog
</syntaxhighlight>


# Look for errors such as:
Common errors and their meanings:
# - "Connection refused" - MTA not running or firewall blocking
{| class="wikitable"
# - "Relay access denied" - SMTP relay misconfiguration
|-
# - "Authentication failed" - Incorrect credentials for external relay
! Error Message !! Cause !! Solution
# - "Host or domain name lookup failed" - DNS issues
|-
# - "Greylisted" - Temporary rejection, may retry later
| Connection refused || MTA not running or firewall blocking || Start MTA service, check firewall rules
}}}
|-
 
| Relay access denied || SMTP relay misconfiguration || Configure proper relay settings
Common issues found in logs:
|-
*'''Authentication Issues''': If relaying through an external SMTP server, verify your credentials in `/etc/postfix/sasl_passwd` or the Exim equivalent.
| Authentication failed || Incorrect credentials || Verify credentials in sasl_passwd
*'''Network Problems''': Check firewall rules (`iptables` or `firewalld`) to ensure outbound SMTP (port 25) is allowed.
|-
*'''DNS Resolution''': If the MTA cannot resolve recipient domains, check `/etc/resolv.conf` and network connectivity.
| Host or domain name lookup failed || DNS issues || Check /etc/resolv.conf
|-
| Greylisted || Temporary rejection || Wait and retry, or whitelist sender
|}


==== Check Mail Queue ====
==== Step 4: Check Mail Queue ====


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


{{{
<syntaxhighlight lang="bash">
# View the mail queue
# View the mail queue
mailq
mailq
Line 119: Line 213:
# Force immediate delivery attempt
# Force immediate delivery attempt
postqueue -f
postqueue -f
}}}
</syntaxhighlight>


If the queue shows many deferred or failed messages, those messages contain error details explaining why delivery failed.
Deferred or failed messages in the queue contain error details explaining why delivery failed.


==== Verify Cronjob ====
==== Step 5: Verify Cronjob ====


Ensure the alert processing script runs every minute:
Ensure the alert processing script runs every minute:


{{{
<syntaxhighlight lang="bash">
# Check current crontab
crontab -l
crontab -l
}}}
</syntaxhighlight>


You should see a line similar to:
You should see:
{{{
<syntaxhighlight lang="bash">
* * * * * root php /var/www/html/php/run.php cron
* * * * * root php /var/www/html/php/run.php cron
}}}
</syntaxhighlight>


If missing, add it:
If missing, add it:
{{{
<syntaxhighlight lang="bash">
crontab -e
crontab -e
# Add this line:
# Add the line above, then reload cron
* * * * * root php /var/www/html/php/run.php cron
killall -HUP cron
}}}
</syntaxhighlight>


Reload the cron daemon:
==== Step 6: Verify Alert Configuration in GUI ====
{{{
killall -HUP cron
}}}


==== Verify Alert Configuration ====
After confirming the MTA works:
# Navigate to '''GUI > Alerts'''
# Verify alert conditions are enabled
# Check that recipient email addresses are valid
# Go to '''GUI > Alerts > Sent Alerts''' to see if alerts were triggered


After confirming the MTA works, check that alerts are configured correctly in the GUI:
'''Diagnosis:'''
* Entries in "Sent Alerts" but no emails received → MTA issue
* No entries in "Sent Alerts" → Check alert conditions or cronjob


1. Navigate to '''GUI > Alerts'''
==== Step 7: Test PHP mail() Function ====
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 and handed off to the MTA


If entries appear in "Sent Alerts" but recipients never receive emails, the MTA is the issue. If no entries appear, check the alert conditions or cronjob.
Isolate the issue by testing PHP directly:


==== Testing with PHP ====
<syntaxhighlight lang="bash">
php -r "mail('your.email@example.com', 'Test from PHP', 'This is a test email');"
</syntaxhighlight>


You can test PHP's mail() function directly to isolate the issue:
* If this works but VoIPmonitor alerts don't → Check GUI cronjob and alert configuration
* If this fails → MTA or PHP configuration issue


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


If this works but VoIPmonitor alerts don't, check the GUI cronjob and alert configuration. If it fails, the issue is purely MTA-related.
* [[Anti-fraud|Anti-Fraud Rules]] - Detailed fraud detection configuration
* [[Reports|Reports]] - Daily reports and report generator
* [[Sniffer_troubleshooting|Sniffer Troubleshooting]] - General troubleshooting


=== AI Summary for RAG ===
== AI Summary for RAG ==


'''Summary:''' This article covers VoIPmonitor's Alerts & Reports for email notifications on QoS/SIP issues, daily/ad hoc reports, crontab setup, alert configuration (RTP/SIP/Sensors types, filters), viewing sent alerts with metrics and CDR details, and troubleshooting email delivery issues including MTA status, mail logs, queue inspection, and CLI/PHP email testing.
'''Summary:''' VoIPmonitor Alerts & Reports system for email notifications on QoS and SIP issues. Covers RTP alerts (MOS, jitter, packet loss), SIP response alerts, and sensors health monitoring. Includes email troubleshooting for MTA configuration.


'''Keywords:''' alerts, reports, email notifications, QoS metrics, SIP responses, crontab, RTP alerts, SIP alerts, sensors alerts, filters, history, MTA configuration, troubleshooting, email not working, mail command, postfix, exim, sendmail, mail queue, mail logs
'''Keywords:''' alerts, email notifications, QoS, MOS, jitter, packet loss, SIP response, sensors monitoring, crontab, MTA, Postfix, Exim, troubleshooting


'''Key Questions:'''
'''Key Questions:'''
* How do I set up email alerts in VoIPmonitor?
* How do I set up email alerts in VoIPmonitor?
* What are the types of alerts (RTP vs. SIP vs. Sensors)?
* What types of alerts are available (RTP, SIP, Sensors)?
* How do I configure crontab for alert processing?
* How do I configure crontab for alert processing?
* What filters can I use for alerts?
* How do I monitor remote sensor health?
* How are sent alerts stored and viewed?
* What do alert flags in CDR mean?
* How do I monitor the status of remote VoIPmonitor sensors and probes?
* Why are email alerts not being sent?
* Why are email alerts not being sent?
* How do I test email delivery from command line?
* How do I troubleshoot MTA email issues?
* How do I troubleshoot MTA (Postfix/Exim/Sendmail) email issues?
* How do I check mail logs and mail queue?

Revision as of 18:03, 4 January 2026

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.

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

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, and sensors health monitoring. Includes email troubleshooting for MTA configuration.

Keywords: alerts, email notifications, QoS, MOS, jitter, packet loss, SIP response, sensors monitoring, crontab, MTA, Postfix, Exim, troubleshooting

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?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Alerts&oldid=6532"