Register: Difference between revisions

From VoIPmonitor.org
(Rewrite: konsolidace a vylepšení struktury)
 
(16 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
sip-register = yes
</syntaxhighlight>


*ID/sensor id shows internal unique ID and if enabled sensor id
{{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.}}
*datetime is time creation
*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.
== Distributed Architecture ==


[[File:register-activesubstate.png]]
Configuration depends on your <code>packetbuffer_sender</code> setting:


On the picture below you can see a detail area where a sub-grid with related CDR from the user name is located.
{| class="wikitable"
|-
! Mode !! Where to Configure
|-
| <code>packetbuffer_sender = yes</code> || '''Central server''' only
|-
| <code>packetbuffer_sender = no</code> || Each '''remote sensor'''
|}


[[File:register-activesubcdr.png]]
== GUI Views ==


= Failed table =
=== Active 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.
Displays currently registered SIP users:


[[File:register-failed.png]]
* 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)


= State table =
=== Failed 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).
Shows unsuccessful registration attempts:


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.
* 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


[[File:register-state.png]]
=== State Table ===
 
Historical registration events (REGISTER, UNREGISTER, EXPIRE):
 
* 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
 
== Advanced Configuration ==
 
=== Multiple Registration Tracking ===
 
Display separate entries when the same SIP account registers from different locations:
 
<syntaxhighlight lang="ini">
# 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
</syntaxhighlight>
 
=== User-Agent Change Detection ===
 
Track when a device's User-Agent changes (potential fraud indicator):
 
<syntaxhighlight lang="ini">
sip-register-state-compare-digest_ua = yes
</syntaxhighlight>
 
{{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.}}
 
== API Access ==
 
Query active registrations programmatically via the Manager API.
 
=== Configuration ===
 
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
manager_ip = 127.0.0.1
manager_port = 5029
# Alternative: Unix socket
# manager_socket = /tmp/vm_manager_socket
</syntaxhighlight>
 
=== Query Examples ===
 
'''TCP with filter:'''
<syntaxhighlight lang="bash">
echo 'listregisters {"zip":"no","limit":30,"states":"OK","filter":{"digestusername":"user"},"sort_field":"calldate","sort_dir":"desc"}' | nc 127.0.0.1 5029
</syntaxhighlight>
 
'''Unix socket:'''
<syntaxhighlight lang="bash">
echo 'listregisters' | nc -U /tmp/vm_manager_socket
</syntaxhighlight>
 
'''GUI API (auto-detects connection method):'''
<syntaxhighlight lang="bash">
php /var/www/html/php/run.php send_manager_cmd -s NULL -c 'listregisters'
</syntaxhighlight>
 
'''Key parameters:''' <code>filter</code> (digestusername, sipcallerip), <code>limit</code>, <code>sort_field</code>, <code>sort_dir</code>
 
== Database Optimization ==
 
=== Create Indexes ===
 
For slow queries on large datasets:
 
<syntaxhighlight lang="sql">
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);
</syntaxhighlight>
 
=== Data Retention ===
 
Control storage with <code>cleandatabaseregister</code> parameter:
 
<syntaxhighlight lang="ini">
# /etc/voipmonitor.conf
cleandatabaseregister = 7  # Days to retain
</syntaxhighlight>
 
=== Buffer Pool Sizing ===
 
For high-volume environments (30M+ records/day):
 
<code>innodb_buffer_pool_size</code> = daily partition size x retention days
 
''Example: 15GB daily x 7 days = 105GB minimum''
 
== Troubleshooting ==
 
{| 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
|}
 
{{Tip|Avoid large historical queries during peak traffic hours and partition maintenance windows (1:00-5:00 AM).}}
 
== See Also ==
 
* [[Anti-fraud]] - Registration country change alerts
* [[Capture_rules]] - Per-registration PCAP rules
* [[Data_Cleaning]] - Database retention settings
* [[Sniffer_distributed_architecture]] - Central vs. distributed processing
 
== 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 <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:'''
* 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?

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"