Register: Difference between revisions

From VoIPmonitor.org
(Enhance AI Summary with specific keywords for 'registered client list showing fewer trunks' query)
(Rewrite: konsolidace a vylepšení struktury)
 
(6 intermediate revisions by the same user not shown)
Line 1: Line 1:
The SIP Register section shows three tables -  Active registered SIP users, Failed registrations and State changes in SIP registrations. Those tables are filled once you enable sip-register = yes in /etc/voipmonitor.conf.
{{DISPLAYTITLE:SIP Registration Monitoring}}
[[Category:GUI manual]]
[[Category:Configuration]]


By default PCAP files are not saved for SIP register messages (it can easily overload file system). If you need to record SIP messages you can control this in capture rules main section and here in all three sections there are gray/red small circles which indicates if SIP messages are being recorded to pcap file so it can be retrieved by clicking on PCAP link. Clicking on the circle enables / disables recording. In the dialog window you can adjust values and set auto remove for the rule at specific date.
= SIP Registration Monitoring =
Note: If you need to record all register packets by the sniffer instance without need to create capture rules in a GUI use sip-register-save-all=yes in its config (/etc/voipmonitor.conf)


[[File:register-recording.png]]
The Register section in VoIPmonitor GUI tracks SIP REGISTER transactions across three views: '''Active''' (current registrations), '''Failed''' (unsuccessful attempts), and '''State''' (historical changes). This feature is '''disabled by default'''.


== Active table ==
== Quick Start ==


The active table shows current registered users with this columns:
{| class="wikitable"
|-
! Parameter !! Value !! Description
|-
| <code>sip-register</code> || <code>yes</code> || Enable registration tracking and DB storage
|-
| <code>sip-register-save-all</code> || <code>yes</code> || Save PCAP files for all registrations
|-
| <code>sip-register-state-timeout</code> || <code>600</code> || State snapshot interval (seconds)
|}


[[File:register-active.png]]
<syntaxhighlight lang="ini">
 
# /etc/voipmonitor.conf - Basic setup
*ID/sensor id shows internal unique ID and if enabled sensor id
sip-register = yes
*datetime is time creation
</syntaxhighlight>
*User name / realm shows username and realm from REGISTER message
*Source IP / Destination IP
*From / To / Contact are values from SIP headers
*Expires at shows date when the registration expires
*User agent
*Commands - download PCAP


On the picture below you can see a detail area where a sub-grid with state changes and failed registrations from the user name is located. This holds quick filters for a particular active user where you can quickly see his history. Once the SIP registration is expired  the history is no longer in the Active table . Each expired registration is stored in the State table.
{{Note|1=When <code>sip-register=no</code> (default), the Active tab still works using real-time data from the sniffer process. The error "Table 'voipmonitor.register' doesn't exist" is expected in this mode.}}


[[File:register-activesubstate.png]]
== Distributed Architecture ==


On the picture below you can see a detail area where a sub-grid with related CDR from the user name is located.
Configuration depends on your <code>packetbuffer_sender</code> setting:
 
[[File:register-activesubcdr.png]]
 
== Failed table ==
 
The failed table shows failed SIP registrations. If some device fails to register continuously the counter column increases instead of creating a new row. If there is a one-hour gap between two failed registrations from the same user a new row will be created.
 
[[File:register-failed.png]]
 
== State table ==
 
The state table retains registration history where REGISTER, UNREGISTER and EXPIRE are saved. In each state row you can click on detail [+] to show all related SIP register messages to the selected user. If device registers in regular intervals it will not save state change in the state table (not true now, see bellow) but keeps the last registration status until the re-registration stops - then UNREGISTER will be the last register state change. If the device do not resend registration in time (register expires + 5 second) the last state will be EXPIRE (with red flag).
 
The same state is periodically saved due to e.g. graphing, etc. The default is 600 seconds. It can be changed by sip-register-state-timeout option in the sensor config.
 
[[File:register-state.png]]
 
== Configuration Location in Distributed Architecture ==
 
In distributed/client-server deployments, the location where you must enable <code>sip-register = yes</code> depends on your <code>packetbuffer_sender</code> configuration:


{| class="wikitable"
{| class="wikitable"
|-
|-
! Mode !! Configuration Location !! Processing Location
! Mode !! Where to Configure
|-
|-
| '''<code>packetbuffer_sender = yes</code>''' (Packet Mirroring) | Central server | Central server processes raw packets from remote sensors
| <code>packetbuffer_sender = yes</code> || '''Central server''' only
|-
|-
| '''<code>packetbuffer_sender = no</code>''' (Local Processing) | Remote sensor | Each sensor processes packets locally before sending CDRs to central server
| <code>packetbuffer_sender = no</code> || Each '''remote sensor'''
|}
|}


To determine where to configure <code>sip-register</code>:
== GUI Views ==
 
=== Active Table ===


;1. Check the <code>packetbuffer_sender</code> setting on your remote sensors:
Displays currently registered SIP users:
<syntaxhighlight lang="bash">
grep packetbuffer_sender /etc/voipmonitor.conf
</syntaxhighlight>


;2. If <code>packetbuffer_sender = yes</code>:
* Registration timestamp, username, realm
* Configure <code>sip-register = yes</code> on the **central server's** <code>/etc/voipmonitor.conf</code>
* Source/destination IP addresses
* Restart the voipmonitor service on the central server
* SIP headers (From, To, Contact)
* Expiration time and User-Agent
* Sub-grids: state changes, failed attempts, related CDRs
* PCAP download (if enabled)


;3. If <code>packetbuffer_sender = no</code> (or not set):
=== Failed Table ===
* Configure <code>sip-register = yes</code> on the **remote sensor's** <code>/etc/voipmonitor.conf</code>
* Restart the voipmonitor service on the remote sensor(s)


For detailed information on distributed architectures and configuration locations, see [[Sniffer_distributed_architecture]].
Shows unsuccessful registration attempts:


== How the Active tab retrieves data ==
* Consecutive failures from the same device increment a counter (no duplicate rows)
* New entry created after >1 hour gap between attempts
* Red flag indicates failure status


The Active table in the GUI displays registration data in two different ways, depending on whether the sip-register feature is enabled:
=== State Table ===


*When sip-register is disabled (default):* The GUI retrieves active registration data directly from the running sniffer processes in real-time. The sniffer maintains an in-memory list of currently registered SIP devices and provides this information to the GUI. In this configuration, the database tables (register, register_state, register_failed) are '''not''' created or used. The Active tab will still function correctly and show live registration data.
Historical registration events (REGISTER, UNREGISTER, EXPIRE):


*When sip-register = yes:* Registration data is stored in database tables (register, register_state, register_failed) for persistent storage and historical reporting. The GUI can then query these tables to display both current and historical registration information.
* Periodic snapshots at <code>sip-register-state-timeout</code> interval (default 600s)
* EXPIRE status: device missed renewal deadline by >5 seconds
* Used for graphing registration trends


== Displaying Multiple Registrations for the Same Account Independently ==
== Advanced Configuration ==


By default, multiple registrations for the same SIP account (same username) from different IP addresses or ports may be displayed as a single aggregated record in the GUI Active table. To view all registrations for the same account separately (differentiated by their source and destination IP addresses and ports), enable comparison options in the sniffer configuration file.
=== Multiple Registration Tracking ===


Add these lines to <code>/etc/voipmonitor.conf</code> (the configuration that processes <code>sip-register=yes</code>):
Display separate entries when the same SIP account registers from different locations:


<pre>
<syntaxhighlight lang="ini">
# Enable independent display of multiple registrations for the same account
# Show each IP/port combination independently
sip-register-compare-sipcallerip = yes
sip-register-compare-sipcallerip = yes
sip-register-compare-sipcallerport = yes
sip-register-compare-sipcallerport = yes
sip-register-compare-sipcalledip = yes
sip-register-compare-sipcalledip = yes
sip-register-compare-sipcalledport = yes
sip-register-compare-sipcalledport = yes
# Optional: Track registration state changes separately by From domain
# Useful when the same SIP account registers from different domains
sip-register-state-compare-from_domain = yes
sip-register-state-compare-from_domain = yes
</pre>
</syntaxhighlight>


These settings instruct the system to create separate registration entries when the source IP (sipcallerip), source port (sipcallerport), destination IP (sipcalledip), destination port (sipcalledport), or From domain differ. This allows you to see each registration instance independently rather than having them merged into a single record. The <code>sip-register-state-compare-from_domain</code> option is particularly useful for accurate alerting when multiple registrations from the same account should be tracked separately based on their originating domain.
=== User-Agent Change Detection ===


After modifying the configuration, reload or restart the voipmonitor service for changes to take effect.
Track when a device's User-Agent changes (potential fraud indicator):


In distributed architectures, apply these settings to the same location where <code>sip-register = yes</code> is configured (central server for <code>packetbuffer_sender=yes</code>, or remote sensor for <code>packetbuffer_sender=no</code>).
<syntaxhighlight lang="ini">
sip-register-state-compare-digest_ua = yes
</syntaxhighlight>


== Error: Table 'voipmonitor.register' doesn't exist ==
{{Warning|1=This setting detects UA changes but does '''NOT''' trigger GUI alerts. For alerting, use '''GUI > Alerts > Anti Fraud''' with "Change REGISTER Country Alert" or custom SQL queries.}}


If you see the error message "Table 'voipmonitor.register' doesn't exist" when viewing the Active tab, this is '''expected and correct behavior''' when the sip-register feature is disabled.
== API Access ==


The error message typically appears if the GUI attempts to query the database table for historical information while the feature is disabled. However, the Active tab will still display live registration data retrieved directly from the sniffer processes.
Query active registrations programmatically via the Manager API.


'''No action is required to fix this error.'''' The system is functioning as intended. The error simply indicates that persistent database storage is not enabled for registration data.
=== Configuration ===


If you want to enable persistent storage of registration history, add sip-register = yes to /etc/voipmonitor.conf and restart the sniffer. This will create the database tables and eliminate the error message, but it is optional for basic registration monitoring.
<syntaxhighlight lang="ini">
 
# /etc/voipmonitor.conf
== Troubleshooting: Registration Data Missing Despite Traffic Being Present ==
manager_ip = 127.0.0.1
 
manager_port = 5029
If SIP registration information is missing from the GUI even though traffic is confirmed present on your network mirror port, the issue is likely with packet capture rather than the sip-register configuration. Follow these troubleshooting steps:
# Alternative: Unix socket
# manager_socket = /tmp/vm_manager_socket
</syntaxhighlight>


;1. Verify packets are reaching the sensor host:
=== Query Examples ===
Run a packet capture directly on the sensor to verify REGISTER packets are arriving at the interface. Use <code>tcpdump</code> or <code>tshark</code> on the correct interface:


'''TCP with filter:'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check for REGISTER packets on the sensor interface
echo 'listregisters {"zip":"no","limit":30,"states":"OK","filter":{"digestusername":"user"},"sort_field":"calldate","sort_dir":"desc"}' | nc 127.0.0.1 5029
tcpdump -i napa0 -s 0 -c 10 "port 5060 and udp"
 
# Or use tshark for more detailed analysis
tshark -i napa0 -Y "sip.Method == REGISTER" -c 10
</syntaxhighlight>
</syntaxhighlight>


If no packets appear, the problem is with your network mirroring configuration (SPAN/TAP). See [[Sniffer_troubleshooting]] for detailed packet capture troubleshooting.
'''Unix socket:'''
 
;2. Check for packet drops in the GUI:
Navigate to '''Settings → Sensors''' in the VoIPmonitor GUI. Expand the sensor details and check the '''# packet drops''' counter.
 
{| class="wikitable"
|-
! Packet Drops Value !! Meaning !! Action
|-
| 0 || Normal || No drop issues
|-
| Non-zero value || Sensor is dropping packets || See [[Sniffer_troubleshooting#Check_Sensor_Statistics_in_GUI|Sniffer Troubleshooting: Sensor Statistics]]
|}
 
;3. If using Napatech hardware:
Standard capture tools may show no packets if Napatech interfaces are in a DOWN state. This is a common issue with Napatech cards.
 
Check interface status:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
ip link show napa0
echo 'listregisters' | nc -U /tmp/vm_manager_socket
</syntaxhighlight>
</syntaxhighlight>


If the interface shows DOWN instead of UP, the solution is to use a custom <code>libpcap</code> library provided by Napatech. See [[Napatech#Troubleshooting:_Napatech_Interfaces_in_DOWN_State|Napatech Troubleshooting]] for detailed steps to:
'''GUI API (auto-detects connection method):'''
* Check if Napatech drivers are loaded
* Verify voipmonitor is linked against Napatech libpcap
* Rebuild the sniffer with the correct library
 
The key command to verify:
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
# Check which libpcap voipmonitor is using
php /var/www/html/php/run.php send_manager_cmd -s NULL -c 'listregisters'
ldd /usr/local/sbin/voipmonitor | grep pcap
 
# Should show: /opt/napatech3/lib/libpcap.so.1
# NOT: /lib/x86_64-linux-gnu/libpcap.so.1
</syntaxhighlight>
</syntaxhighlight>


;4. Additional troubleshooting resources:
'''Key parameters:''' <code>filter</code> (digestusername, sipcallerip), <code>limit</code>, <code>sort_field</code>, <code>sort_dir</code>
* [[Sniffer_troubleshooting]] - Comprehensive guide for diagnosing packet capture issues
* [[Sniffer_troubleshooting#Is_Network_Traffic_Reaching_the_Server|Network traffic verification with tshark]]
* [[Sniffer_troubleshooting#Check_the_VoIPmonitor_Configuration]] - Verify interface, sipport, and filter settings


== Slow Queries on register_state Table ==
== Database Optimization ==


If queries on the <code>register_state</code> table are extremely slow or time out when filtering by text fields (Username, Domain, Number), especially for older data, this indicates missing indexes on frequently queried columns.
=== Create Indexes ===


=== Problem Description ===
For slow queries on large datasets:


The <code>register_state</code> table stores SIP registration history (REGISTER, UNREGISTER, EXPIRE events). Because SIP devices re-register frequently (typically every 30-60 seconds), this table accumulates rows very quickly. Queries filtering by text fields without proper indexes require full table scans, which are extremely slow on large tables.
<syntaxhighlight lang="sql">
 
CREATE INDEX digestusername ON register_state (digestusername);
=== Common Symptoms ===
CREATE INDEX digest_from_number ON register_state (digest_from_number);
 
CREATE INDEX digest_to_number ON register_state (digest_to_number);
* Queries with filters on Username, Domain, or Number time out
CREATE INDEX digest_to_domain ON register_state (digest_to_domain);
* Searches for specific registration events take 30+ seconds or indefinite
CREATE INDEX digest_realm ON register_state (digest_realm);
* GUI Register State tab is unresponsive when applying filters
</syntaxhighlight>
* MySQL shows high CPU usage from register_state queries
 
=== Solution: Create Missing Indexes ===


The root cause is almost always missing indexes on columns used in WHERE clauses. Create indexes manually on the most frequently queried columns.
=== Data Retention ===


First, verify which indexes already exist:
Control storage with <code>cleandatabaseregister</code> parameter:


<syntaxhighlight lang="sql">
<syntaxhighlight lang="ini">
-- Show current indexes on register_state
# /etc/voipmonitor.conf
SHOW INDEX FROM register_state;
cleandatabaseregister = 7  # Days to retain
</syntaxhighlight>
</syntaxhighlight>


Look for indexes on:
=== Buffer Pool Sizing ===
* <code>digestusername</code>
* <code>digest_from_number</code>
* <code>digest_to_number</code>
* <code>digest_to_domain</code>
* <code>digest_realm</code>


If these indexes are missing, create them:
For high-volume environments (30M+ records/day):


<syntaxhighlight lang="sql">
<code>innodb_buffer_pool_size</code> = daily partition size x retention days
-- Create index on username (most common query)
CREATE INDEX digestusername ON register_state (digestusername);


-- Create indexes on other frequently queried columns
''Example: 15GB daily x 7 days = 105GB minimum''
CREATE INDEX digest_from_number ON register_state (digest_from_number);
CREATE INDEX digest_to_number ON register_state (digest_to_number);
CREATE INDEX digest_to_domain ON register_state (digest_to_domain);
CREATE INDEX digest_realm ON register_state (digest_realm);
</syntaxhighlight>


{{Warning|
== Troubleshooting ==
<code>CREATE INDEX</code> operations on large tables can be very slow and may block write operations to the table. Schedule index creation during a maintenance window or low-traffic periods.
}}


=== Additional Performance Optimization ===
{| class="wikitable"
|-
! Symptom !! Solution
|-
| No registrations appear || Verify packets: <code>tcpdump -i eth0 port 5060</code>
|-
| "Table doesn't exist" error || Normal when <code>sip-register=no</code>; Active tab still works
|-
| Missing data with Napatech || Check <code>ip link show napa0</code> and libpcap path
|-
| Packet drops || Check '''Settings > Sensors''' for drop counters
|}


If performance is still insufficient after adding indexes:
{{Tip|Avoid large historical queries during peak traffic hours and partition maintenance windows (1:00-5:00 AM).}}


1. Increase <code>innodb_buffer_pool_size</code> in MySQL configuration (see [[Scaling#Memory_Configuration|Scaling Guide]])
== See Also ==
2. Configure <code>cleandatabaseregister = 7</code> (or 30) in <code>/etc/voipmonitor.conf</code> to limit data retention (see [[Data_Cleaning]])


{{Note|
* [[Anti-fraud]] - Registration country change alerts
For MySQL 5.6+ or MariaDB 10.1+, use online index creation to avoid blocking writes:
* [[Capture_rules]] - Per-registration PCAP rules
<code>CREATE INDEX digestusername ON register_state (digestusername) ALGORITHM=INPLACE, LOCK=NONE;</code>
* [[Data_Cleaning]] - Database retention settings
}}
* [[Sniffer_distributed_architecture]] - Central vs. distributed processing


== AI Summary for RAG ==
== AI Summary for RAG ==
'''Summary:''' The SIP Register section displays Active, Failed, and State tables. Enable with <code>sip-register = yes</code> for persistent storage; Active tab works in real-time even when disabled (retrieves from sniffer process). In distributed architectures, configure <code>sip-register</code> on the central server if <code>packetbuffer_sender=yes</code> (Packet Mirroring), or on remote sensors if <code>packetbuffer_sender=no</code> (Local Processing). '''CRITICAL FOR "REGISTERED CLIENT LIST SHOWS FEWER TRUNKS":''' If the GUI Registered client list shows fewer SIP trunks than are actually registered, or if registrations appear aggregated rather than separate, this is caused by default settings that merge multiple registrations from the same account. To see all registered SIP trunks independently and enable proper alerting, you MUST enable stateful registration comparison options in <code>/etc/voipmonitor.conf</code>: <code>sip-register-compare-sipcallerip = yes</code>, <code>sip-register-compare-sipcallerport = yes</code>, <code>sip-register-compare-sipcalledip = yes</code>, <code>sip-register-compare-sipcalledport = yes</code>, and optionally <code>sip-register-state-compare-from_domain = yes</code> for domain-based differentiation. Restart the sniffer service after changes. These options are essential for accurate registration tracking when multiple registrations exist for the same SIP account. '''CRITICAL TROUBLESHOOTING PRIORITY:''' If SIP registration data is missing from GUI despite confirmed network traffic on mirror port, FIRST verify packets reach the sensor interface using <code>tcpdump</code> or <code>tshark</code> BEFORE checking configuration. Step 2: Check GUI Settings → Sensors for packet drops. Step 3: For Napatech hardware, verify interface status (must be UP) and ensure voipmonitor uses Napatech's custom libpcap (<code>ldd /usr/local/sbin/voipmonitor | grep pcap</code> should show <code>/opt/napatech3/lib/libpcap.so.1</code>). Only after verifying packet capture works should you check <code>sip-register</code> configuration or database tables. '''Slow register_state queries:''' If queries filtering by Username/Domain/Number timeout, create indexes: <code>CREATE INDEX digestusername ON register_state (digestusername)</code>, <code>CREATE INDEX digest_from_number ON register_state (digest_from_number)</code>, <code>CREATE INDEX digest_to_number ON register_state (digest_to_number)</code>, <code>CREATE INDEX digest_to_domain ON register_state (digest_to_domain)</code>, <code>CREATE INDEX digest_realm ON register_state (digest_realm)</code>. Index creation on large tables blocks writes - schedule during maintenance window. Use <code>ALGORITHM=INPLACE, LOCK=NONE</code> for online index creation on MySQL 5.6+/MariaDB 10.1+. Additional optimization: increase <code>innodb_buffer_pool_size</code> and configure <code>cleandatabaseregister</code> retention.


'''Keywords:''' SIP Register, Active, Failed, State, sip-register, registered client list shows fewer trunks, fewer trunks than registered, missing registered SIP trunks, missing registrations, aggregated registrations, registration discrepancies, alerting discrepancies, registration tracking, stateful registration tracking, show all registered trunks, display all registrations, sip-register-compare-sipcallerip, sip-register-compare-sipcallerport, sip-register-compare-sipcalledip, sip-register-compare-sipcalledport, sip-register-state-compare-from_domain, multiple registrations same account, differentiate registrations, independent display, separate entries, source IP, destination IP, source port, destination port, From domain, domain comparison, sniffer service restart, sip-register-compare options, enable registration comparison, fix aggregated registrations, fix missing trunks in GUI, registration monitoring accuracy, alerting based on registration state, missing registration, traffic present, mirror port, tcpdump, tshark, FIRST troubleshooting step, packet drops, Napatech, interface DOWN, custom libpcap, ldd, verify packets reach sensor, packet capture verification, real-time, database, distributed architecture, packetbuffer_sender, central server, remote sensor, configuration location, registration troubleshooting, register_state slow query, timeout, index, digestusername, digest_from_number, digest_to_number, digest_to_domain, digest_realm, create index, innodb_buffer_pool_size, cleandatabaseregister, maintenance window
'''Summary:''' VoIPmonitor SIP Register monitoring tracks registration events in three GUI tables: Active (current registrations with real-time data even when DB storage disabled), Failed (unsuccessful attempts with counter deduplication), and State (historical REGISTER/UNREGISTER/EXPIRE events). Enable with <code>sip-register=yes</code> in voipmonitor.conf. In distributed architecture, configure on central server if <code>packetbuffer_sender=yes</code>, otherwise on each remote sensor. PCAP files require <code>sip-register-save-all=yes</code>. Advanced options include multi-registration tracking (<code>sip-register-compare-*</code> parameters) and User-Agent change detection (<code>sip-register-state-compare-digest_ua=yes</code>) for fraud detection. API access via Manager port 5029 with <code>listregisters</code> command. Database optimization requires indexes on register_state table and proper <code>innodb_buffer_pool_size</code> sizing.
 
'''Keywords:''' SIP register, registration monitoring, Active table, Failed table, State table, sip-register, sip-register-save-all, sip-register-state-timeout, sip-register-compare-sipcallerip, sip-register-compare-sipcallerport, sip-register-state-compare-digest_ua, User-Agent change, fraud detection, listregisters, Manager API, port 5029, cleandatabaseregister, register_state, distributed architecture, packetbuffer_sender


'''Key Questions:'''
'''Key Questions:'''
* Registered client list shows fewer SIP trunks than actually registered?
* How do I enable SIP registration monitoring in VoIPmonitor?
* GUI shows fewer registered SIP trunks than expected?
* Where should I configure sip-register in a distributed architecture?
* Registered client list missing trunks causing alerting discrepancies?
* How do I track the same SIP account registering from multiple locations?
* How to show all registered SIP trunks independently?
* How do I detect User-Agent changes for fraud detection?
* Fewer registrations displayed in GUI than actual?
* How do I query active registrations via API?
* Registrations aggregated instead of separate entries?
* What indexes should I create for register_state performance?
* Enable stateful registration tracking for accurate alerting?
* Why do I see "Table doesn't exist" error for register table?
* What are sip-register-compare-sipcallerip sip-register-compare-sipcallerport sip-register-compare-sipcalledip sip-register-compare-sipcalledport sip-register-state-compare-from_domain?
* How do I configure data retention for registration data?
* How to fix aggregated registrations in Active tab?
* Multiple registrations for same account displayed as single record?
* How to view multiple registrations for the same account independently?
* GUI SIP Register section shows aggregated registrations how to fix?
* Differentiate registrations by IP address and port
* SIP registration missing from GUI but traffic on network?
* What is the sip-register option and how do I enable it?
* Active SIP Register tab shows no data how to fix?
* Napatech interfaces in DOWN state, how to fix?
* Tcpdump shows no packets on Napatech interface?
* How to verify packets reaching sensor?
* Check for packet drops in Sensors GUI
* Where do I configure sip-register in distributed architecture?
* Should I configure sip-register on central server or remote sensor?
* What is packetbuffer_sender and how does it affect configuration location?
* Queries filtering by Username/Domain/Number timing out on register_state table?
* How to create indexes on register_state columns?

Latest revision as of 16:48, 8 January 2026


SIP Registration Monitoring

The Register section in VoIPmonitor GUI tracks SIP REGISTER transactions across three views: Active (current registrations), Failed (unsuccessful attempts), and State (historical changes). This feature is disabled by default.

Quick Start

Parameter Value Description
sip-register yes Enable registration tracking and DB storage
sip-register-save-all yes Save PCAP files for all registrations
sip-register-state-timeout 600 State snapshot interval (seconds) 
# /etc/voipmonitor.conf - Basic setup
sip-register = yes

ℹ️ Note: When sip-register=no (default), the Active tab still works using real-time data from the sniffer process. The error "Table 'voipmonitor.register' doesn't exist" is expected in this mode.

Distributed Architecture

Configuration depends on your packetbuffer_sender setting:

Mode Where to Configure
packetbuffer_sender = yes Central server only
packetbuffer_sender = no Each remote sensor

GUI Views

Active Table

Displays currently registered SIP users:

  • Registration timestamp, username, realm
  • Source/destination IP addresses
  • SIP headers (From, To, Contact)
  • Expiration time and User-Agent
  • Sub-grids: state changes, failed attempts, related CDRs
  • PCAP download (if enabled)

Failed Table

Shows unsuccessful registration attempts:

  • Consecutive failures from the same device increment a counter (no duplicate rows)
  • New entry created after >1 hour gap between attempts
  • Red flag indicates failure status

State Table

Historical registration events (REGISTER, UNREGISTER, EXPIRE):

  • Periodic snapshots at sip-register-state-timeout interval (default 600s)
  • EXPIRE status: device missed renewal deadline by >5 seconds
  • Used for graphing registration trends

Advanced Configuration

Multiple Registration Tracking

Display separate entries when the same SIP account registers from different locations: 

# Show each IP/port combination independently
sip-register-compare-sipcallerip = yes
sip-register-compare-sipcallerport = yes
sip-register-compare-sipcalledip = yes
sip-register-compare-sipcalledport = yes
sip-register-state-compare-from_domain = yes

User-Agent Change Detection

Track when a device's User-Agent changes (potential fraud indicator): 

sip-register-state-compare-digest_ua = yes

⚠️ Warning: This setting detects UA changes but does NOT trigger GUI alerts. For alerting, use GUI > Alerts > Anti Fraud with "Change REGISTER Country Alert" or custom SQL queries.

API Access

Query active registrations programmatically via the Manager API.

Configuration

# /etc/voipmonitor.conf
manager_ip = 127.0.0.1
manager_port = 5029
# Alternative: Unix socket
# manager_socket = /tmp/vm_manager_socket

Query Examples

TCP with filter: 

echo 'listregisters {"zip":"no","limit":30,"states":"OK","filter":{"digestusername":"user"},"sort_field":"calldate","sort_dir":"desc"}' | nc 127.0.0.1 5029

Unix socket: 

echo 'listregisters' | nc -U /tmp/vm_manager_socket

GUI API (auto-detects connection method): 

php /var/www/html/php/run.php send_manager_cmd -s NULL -c 'listregisters'

Key parameters: filter (digestusername, sipcallerip), limit, sort_field, sort_dir

Database Optimization

Create Indexes

For slow queries on large datasets: 

CREATE INDEX digestusername ON register_state (digestusername);
CREATE INDEX digest_from_number ON register_state (digest_from_number);
CREATE INDEX digest_to_number ON register_state (digest_to_number);
CREATE INDEX digest_to_domain ON register_state (digest_to_domain);
CREATE INDEX digest_realm ON register_state (digest_realm);

Data Retention

Control storage with cleandatabaseregister parameter: 

# /etc/voipmonitor.conf
cleandatabaseregister = 7  # Days to retain

Buffer Pool Sizing

For high-volume environments (30M+ records/day):

innodb_buffer_pool_size = daily partition size x retention days

Example: 15GB daily x 7 days = 105GB minimum

Troubleshooting

Symptom Solution
No registrations appear Verify packets: tcpdump -i eth0 port 5060
"Table doesn't exist" error Normal when sip-register=no; Active tab still works
Missing data with Napatech Check ip link show napa0 and libpcap path
Packet drops Check Settings > Sensors for drop counters

💡 Tip: Avoid large historical queries during peak traffic hours and partition maintenance windows (1:00-5:00 AM).

See Also

AI Summary for RAG

Summary: VoIPmonitor SIP Register monitoring tracks registration events in three GUI tables: Active (current registrations with real-time data even when DB storage disabled), Failed (unsuccessful attempts with counter deduplication), and State (historical REGISTER/UNREGISTER/EXPIRE events). Enable with sip-register=yes in voipmonitor.conf. In distributed architecture, configure on central server if packetbuffer_sender=yes, otherwise on each remote sensor. PCAP files require sip-register-save-all=yes. Advanced options include multi-registration tracking (sip-register-compare-* parameters) and User-Agent change detection (sip-register-state-compare-digest_ua=yes) for fraud detection. API access via Manager port 5029 with listregisters command. Database optimization requires indexes on register_state table and proper innodb_buffer_pool_size sizing.

Keywords: SIP register, registration monitoring, Active table, Failed table, State table, sip-register, sip-register-save-all, sip-register-state-timeout, sip-register-compare-sipcallerip, sip-register-compare-sipcallerport, sip-register-state-compare-digest_ua, User-Agent change, fraud detection, listregisters, Manager API, port 5029, cleandatabaseregister, register_state, distributed architecture, packetbuffer_sender

Key Questions:

  • How do I enable SIP registration monitoring in VoIPmonitor?
  • Where should I configure sip-register in a distributed architecture?
  • How do I track the same SIP account registering from multiple locations?
  • How do I detect User-Agent changes for fraud detection?
  • How do I query active registrations via API?
  • What indexes should I create for register_state performance?
  • Why do I see "Table doesn't exist" error for register table?
  • How do I configure data retention for registration data?
Retrieved from "https://www.voipmonitor.org/doc/index.php?title=Register&oldid=10126"