Asterisk 'Peer Is Not Registered' — SIP Registration Failure Debug

Master the diagnosis and resolution of SIP registration failures in Asterisk/ViciDial production environments by understanding peer registration mechanics, common misconfiguration patterns, and step-by-step troubleshooting methodology.

Prerequisites

Before you begin this guide, ensure you have:

• Asterisk 1.6+, 11.x, 13.x, or 16.x (ViciDial typically runs 11.x or 13.x)
• Root or sudo access to the Asterisk server
• Knowledge of basic SIP concepts (registrar, registrant, peer, friend)
• Access to /etc/asterisk/ configuration directory
• Ability to tail logs in real-time: tail -f /var/log/asterisk/messages
• Familiarity with asterisk -rx CLI commands
• Understanding of your network topology (NAT, firewall, carrier routing)

Understanding SIP Registration in Asterisk

How Asterisk Registration Works

When Asterisk is configured as a SIP registrant (client), it sends a SIP REGISTER request to a remote SIP server (registrar). The registrar acknowledges and stores the binding. Asterisk then periodically re-registers to maintain the binding.

When an external peer attempts to register to Asterisk (Asterisk acting as registrar), Asterisk receives the REGISTER request, validates credentials, and stores the peer location in memory.

The error "Peer is not registered" occurs when:

1. Asterisk expects a peer to have registered but hasn't
2. The peer's registration has expired
3. The peer never completed registration
4. The peer is configured incorrectly
5. Network/firewall blocks SIP traffic
6. DNS resolution fails

Registration State Lifecycle

Peer Configured (type=friend or type=peer)
    ↓
SIP REGISTER Request Sent (or expected)
    ↓
401 Unauthorized / 200 OK Response
    ↓
Credentials Validated / Failed
    ↓
Binding Stored in Memory / Rejected
    ↓
Re-registration Timer Starts (default: 3600s)
    ↓
Expiration / Renewal Cycle

Configuration Fundamentals

SIP Peer vs. Friend vs. User Types

ViciDial typically uses SIP configuration in /etc/asterisk/sip-vicidial.conf. Understanding peer types is critical:

[general]
context=from-internal
recordhistory=yes
bindport=5060
bindaddr=0.0.0.0
srvlookup=yes
transport=udp,tcp
allowguest=no
qualify=yes
qualifyfreq=60

# TYPE 1: PEER (one-way trust, inbound calls only)
[carrier_sip]
type=peer
host=203.0.113.45
port=5060
context=from-pstn
directmedia=no
disallow=all
allow=ulaw,alaw
fromuser=vicidial_account
fromdomain=203.0.113.45

# TYPE 2: USER (deprecated in modern Asterisk, avoid)
[user_extension]
type=user
host=dynamic
context=from-internal

# TYPE 3: FRIEND (peer + user, two-way trust)
[agent_extension]
type=friend
host=dynamic
context=from-internal
defaultuser=1001
secret=MySecurePassword123
directmedia=no
disallow=all
allow=ulaw,alaw
mailbox=1001@default
qualify=yes
qualifyfreq=120

Step 1: Verify Configuration Syntax

Check SIP Configuration for Errors

Invalid syntax prevents Asterisk from loading the peer entirely.

asterisk -rx "sip show peers" 2>&1 | head -20

Expected output:

Name/username             Host                                    Dyn Forcerport ACL Port     Status      
agent_1001               192.168.1.100                            D   No         A  5060     OK (19 ms)
carrier_sip              203.0.113.45                             N   Yes        A  5060     UNREACHABLE

If a peer is missing from this list entirely, it failed to parse.

Reload and Check for Parse Errors

asterisk -rx "sip reload" 2>&1 | grep -i "error\|warning\|parse"
tail -f /var/log/asterisk/messages | grep -i "sip\|error"

Look for lines like:

[2024-01-15 14:32:18] WARNING[12345]: chan_sip.c:30123 in parse_register_line(): Line 145: Bad syntax
[2024-01-15 14:32:18] ERROR[12345]: config.c:4567 in config_text_file_load(): Can't load config file "sip-vicidial.conf"

Common Configuration Syntax Errors

# WRONG: Missing equals sign
[agent_1001]
type friend
secret=password

# WRONG: Invalid values
[agent_1001]
type=invalid_type
qualify=maybe

# WRONG: Commented out required field
[agent_1001]
type=friend
;secret=password

# CORRECT:
[agent_1001]
type=friend
secret=password
qualify=yes

Step 2: Confirm Peer is Loaded and Present

List All Registered and Unregistered Peers

asterisk -rx "sip show peers"

Parse the output methodically:

• Dyn = Y/D: Peer expects dynamic (changing) host IP
• Host = actual IP or hostname: Current known location
• Port: SIP port (default 5060)
• Status:
  • OK (X ms) = responsive
  • UNREACHABLE = can't reach this peer
  • UNKNOWN = hasn't registered yet
  • Unmonitored = qualify=no

Check Specific Peer Registration Status

asterisk -rx "sip show peer agent_1001"

Output example (peer IS registered):

  Name       : agent_1001
  Secret     : <Set>
  MD5Secret  : <Not set>
  Context    : from-internal
  Language   : en
  AMA flags  : Unknown
  Transfer mode : open
  Dtmfmode   : rfc2833
  Tohost     : 192.168.1.100
  Addr->IP   : 192.168.1.100
  Defname    : agent_1001
  Useragent  : Zoiper 2.52 (VoIP Client)
  Reg. Contact: sip:[email protected]:5060

Output example (peer NOT registered):

  Name       : agent_1002
  Secret     : <Set>
  Context    : from-internal
  Host       : dynamic
  Addr->IP   : (null)
  Defname    : agent_1002
  Useragent  : 
  Reg. Contact: <Not set>
  Status     : UNKNOWN

Key indicator: If Addr->IP : (null) and Reg. Contact: <Not set>, the peer has never registered.

Step 3: Check Network Connectivity and Firewall

Verify UDP/TCP Port 5060 is Open

# Check if Asterisk is listening
netstat -tulpn | grep asterisk | grep 5060

Expected output:

udp        0      0 0.0.0.0:5060            0.0.0.0:*                           12345/asterisk
tcp        0      0 0.0.0.0:5060            0.0.0.0:*                           12345/asterisk

Test Firewall from Client

From the SIP client machine:

nc -u -zv <asterisk-server-ip> 5060
nc -zv <asterisk-server-ip> 5060

If both fail, firewall is blocking. Check iptables (or firewalld):

# Check iptables rules
sudo iptables -L -n | grep 5060

# If nothing, add rule (CentOS/RHEL with firewalld):
sudo firewall-cmd --permanent --add-port=5060/udp
sudo firewall-cmd --permanent --add-port=5060/tcp
sudo firewall-cmd --reload

# Or with iptables directly:
sudo iptables -I INPUT -p udp --dport 5060 -j ACCEPT
sudo iptables -I INPUT -p tcp --dport 5060 -j ACCEPT
sudo service iptables save

Test DNS Resolution

nslookup asterisk.example.com
dig asterisk.example.com

If the client uses a hostname to register and DNS fails, registration fails silently.

Step 4: Enable SIP Debugging and Capture Registration Attempts

Enable Verbose SIP Debugging

asterisk -rx "sip set debug on"
tail -f /var/log/asterisk/messages | grep -i "register\|sip"

Or capture to a separate file:

asterisk -rx "sip set debug on peer agent_1001"

Real-World Debug Output: Successful Registration

<--- SIP read from UDP:192.168.1.100:52341 --->
REGISTER sip:asterisk.local SIP/2.0
Via: SIP/2.0/UDP 192.168.1.100:5060;branch=z9hG4bK776asdhds
From: <sip:[email protected]>;tag=1928301774
To: <sip:[email protected]>
Call-ID: [email protected]
CSeq: 314159 REGISTER
Contact: <sip:[email protected]:5060>
Expires: 3600

Asterisk responds:

----- Transmitting SIP response to UDP:192.168.1.100:52341 -----
SIP/2.0 200 OK
Via: SIP/2.0/UDP 192.168.1.100:5060;branch=z9hG4bK776asdhds
From: <sip:[email protected]>;tag=1928301774
To: <sip:[email protected]>;tag=as52a3c4a9
Call-ID: [email protected]
CSeq: 314159 REGISTER
Contact: <sip:[email protected]:5060>;expires=3600

Real-World Debug Output: Failed Registration (No Credentials)

<--- SIP read from UDP:192.168.1.100:52341 --->
REGISTER sip:asterisk.local SIP/2.0
...
Contact: <sip:[email protected]:5060>
...

[Asterisk checks credentials against sip-vicidial.conf]

----- Transmitting SIP response to UDP:192.168.1.100:52341 -----
SIP/2.0 401 Unauthorized
...
WWW-Authenticate: Digest realm="asterisk.local", nonce="..."

Client should re-send REGISTER with Authorization header.

Disable Debug When Done

asterisk -rx "sip set debug off"

Step 5: Check ViciDial Database Configuration

ViciDial stores extensions and phone registrations in MySQL. Verify the extension is enabled.

Query ViciDial Extensions

mysql -u vicidial -p asterisk -e "
SELECT extension, voicemail_id, full_name, status
FROM vicidial_extensions
WHERE extension='1001';"

Output:

+-----------+---------------+-----------+--------+
| extension | voicemail_id  | full_name | status |
+-----------+---------------+-----------+--------+
| 1001      | 1001          | John Doe  | ACTIVE |
+-----------+---------------+-----------+--------+

Critical: If status is not ACTIVE, the extension is disabled. Check vicidial_users too:

mysql -u vicidial -p asterisk -e "
SELECT user, full_name, status, phone_login_pin
FROM vicidial_users
WHERE user='1001';"

Verify SIP Registration in Database

Check if the peer appears in the registration tracking table:

mysql -u vicidial -p asterisk -e "
SELECT * FROM vicidial_sip_registration
WHERE extension='1001'\G"

If empty, check the log table for failed attempts:

mysql -u vicidial -p asterisk -e "
SELECT event_date, extension, description
FROM vicidial_log
WHERE extension='1001' AND description LIKE '%register%'
ORDER BY event_date DESC LIMIT 10;"

Step 6: Verify Credentials Match

Common Credential Mismatches

The most frequent cause of registration failure is mismatched credentials.

In sip-vicidial.conf:

[agent_1001]
type=friend
defaultuser=agent_1001
secret=MySecurePassword123

Expected client configuration:

• Username: agent_1001
• Password: MySecurePassword123
• Registrar: asterisk.local or IP
• Port: 5060

If client uses:

• Username: 1001 (without prefix)
• Password: MySecurePassword1234 (typo)
• Port: 5061 (wrong port)

→ Registration fails silently or returns 401.

Force Credential Check

Temporarily enable authentication debugging:

asterisk -rx "core set debug 5"
tail -f /var/log/asterisk/messages | grep -i "auth\|credential"
asterisk -rx "core set debug 0"  # Disable when done

Step 7: Check Expiration and Re-Registration Timers

Verify Peer Expiration Settings

asterisk -rx "sip show peer agent_1001" | grep -i "expire\|refresh"

Output:

  Expire        : 3600 (sec)
  Refresh Timer : 1800 (sec)
  Reg. Contact  : sip:[email protected]:5060

If a peer registered hours ago but hasn't re-registered, the binding expires and "Peer is Not Registered" errors occur.

Set Shorter Re-registration Intervals in sip-vicidial.conf

[agent_1001]
type=friend
secret=password
defaultuser=agent_1001
context=from-internal
qualify=yes
qualifyfreq=60          ; Keep-alive check every 60 seconds
defaultexpire=3600      ; Registration validity: 1 hour
minexpire=120           ; Minimum allowed expiration
maxexpire=7200          ; Maximum allowed expiration

Reload:

asterisk -rx "sip reload"

Monitor Live Registration Status

watch -n 1 "asterisk -rx 'sip show peer agent_1001' | grep -E 'Status|Reg. Contact'"

You should see the status update periodically. If it goes stale, re-registration is failing.

Step 8: Diagnose NAT and External IP Issues

Problem: Peer Behind NAT with Wrong Contact IP

When a peer is behind NAT, the SIP REGISTER Contact header contains the private IP (e.g., 192.168.1.100). Asterisk stores this. When Asterisk tries to send SIP traffic back, it fails because 192.168.1.100 is unreachable from outside the NAT.

Enable Symmetric RTP and IP Checking

[general]
directmedia=no
nat=force_rport
symmetric_rtp=yes

[agent_1001]
type=friend
secret=password
nat=force_rport
directmedia=no

Use STUN for NAT Traversal

Configure STUN server in sip-vicidial.conf:

[general]
externip=203.0.113.50
localnet=192.168.1.0/255.255.255.0

Or use STUN:

[general]
stunaddr=stun.l.google.com:19302
stunrefreshinterval=3600

Check External IP Detection

asterisk -rx "sip show settings" | grep -i "external\|nat\|stun"

Step 9: Examine SIP Request/Response Logs in Asterisk

Check Full Call Trace with Verbose Logging

asterisk -rx "core set verbose 5"
asterisk -rx "sip set debug on"
tail -f /var/log/asterisk/messages | tail -100
asterisk -rx "core set verbose 0" # Disable when done

Parse Key Messages

Look for these indicators in /var/log/asterisk/messages:

# GOOD: Registration accepted
chan_sip.c: Registration accepted for 'agent_1001' <sip:agent_1001@...>

# BAD: Invalid credentials
chan_sip.c: Failed to authenticate user 'agent_1001'

# BAD: Peer not configured
chan_sip.c: No matching SIP user or peer found for 'agent_1001'

# BAD: Expiration
chan_sip.c: Registration of 'agent_1001' expired

Export Full Debug to File

asterisk -rx "sip set debug on" > /tmp/sip_debug.log 2>&1 &
# Wait for activity, then:
asterisk -rx "sip set debug off"
cat /tmp/sip_debug.log | head -200

Step 10: Test with SIP CLI Commands

Send Manual REGISTER Request

Use sipsak (if installed) to simulate a registration:

sipsak -r sip:[email protected] -u agent_1001:MySecurePassword123

Or install it:

yum install sipsak  # CentOS/RHEL
apt-get install sipsak  # Debian/Ubuntu

Query Asterisk SIP Registry State

asterisk -rx "sip show registry"

This shows outbound registrations (when Asterisk registers to another server):

Host                           Username       Refresh State                Reg.Time
203.0.113.45:5060             vicidial_acc   105 Registered           Wed Jan 15 14:32:18 2024

If a carrier registration shows Request Sent or Auth. Sent, it's stuck in the handshake.

Troubleshooting Checklist

Production Best Practices

Recommended sip-vicidial.conf Configuration for Agents

[general]
context=from-internal
recordhistory=yes
bindport=5060
bindaddr=0.0.0.0
srvlookup=yes
transport=udp,tcp
allowguest=no
qualify=yes
qualifyfreq=60
defaultexpire=3600
minexpire=120
maxexpire=7200
externip=203.0.113.50
localnet=192.168.1.0/255.255.255.0
directmedia=no
nat=force_rport
symmetric_rtp=yes
rtptimeout=300
icesupport=yes

[agent_template](!)
type=friend
context=from-internal
disallow=all
allow=ulaw,alaw,gsm
directmedia=no
nat=force_rport
qualify=yes
qualifyfreq=120
defaultexpire=3600
mailbox=${EXTEN}@default

Then per-extension:

[1001](agent_template)
defaultuser=1001
secret=SecurePassword2024
fullname=John Doe

[1002](agent_template)
defaultuser=1002
secret=SecurePassword2024
fullname=Jane Smith

Monitoring Script

Create /usr/local/bin/monitor_sip_registrations.sh:

#!/bin/bash
ASTERISK_CLI="/usr/bin/asterisk -rx"

echo "=== SIP Registration Status ==="
$ASTERISK_CLI "sip show peers" | grep -E "^[a-z0-9_]+" | while read LINE; do
    PEER=$(echo "$LINE" | awk '{print $1}')
    STATUS=$(echo "$LINE" | awk '{print $NF}')
    
    if [[ "$STATUS" != "OK" ]] && [[ "$STATUS" != "UNKNOWN" ]]; then
        echo "WARNING: $PEER - $STATUS"
    fi
done

echo ""
echo "=== Expired Registrations (older than 1 hour) ==="
mysql -u vicidial -p asterisk -e "
SELECT extension, registration_date, NOW() FROM vicidial_sip_registration
WHERE TIMESTAMPDIFF(HOUR, registration_date, NOW()) > 1;" 2>/dev/null

echo ""
echo "=== Failed Registration Attempts (Last 10) ==="
tail -100 /var/log/asterisk/messages | grep -i "failed.*register\|unauthorized" | tail -10

Run as a cron job:

0 * * * * /usr/local/bin/monitor_sip_registrations.sh >> /var/log/sip_monitor.log 2>&1

Advanced Troubleshooting: Outbound Registration Issues

If Asterisk is trying to register TO an external carrier and shows "Peer is Not Registered":

Check Outbound Registration Config

register => vicidial_account:[email protected]:5060/from-pstn

Verify Outbound Registration Status

asterisk -rx "sip show registry"

If stuck in Request Sent:

1. Check carrier endpoint is reachable:

   nc -zv 203.0.113.45 5060
   

2. Check firewall allows outbound SIP:

   sudo iptables -L -n | grep 5060
   

3. Verify carrier accepts registrations from your IP:

   Contact your carrier to whitelist your public IP
   

4. Check authentication with carrier:

   asterisk -rx "sip set debug on"
   asterisk -rx "sip reload"
   tail -f /var/log/asterisk/messages | grep -E "register|auth|carrier_sip"
   

5. Test with SIPp if available:

   sipp -sf /tmp/register.xml -s [email protected] 203.0.113.45
   

Summary

Resolving "Peer Is Not Registered" errors in production Asterisk/ViciDial systems requires systematic diagnosis:

1. Verify configuration syntax — invalid peers won't load at all
2. Confirm peer exists — check sip show peers output
3. Test network connectivity — firewall must allow UDP/TCP 5060
4. Enable debugging — capture SIP REGISTER requests and responses
5. Check database state — ViciDial extensions must be ACTIVE
6. Match credentials — secret, defaultuser, and realm must align
7. Monitor expiration — registrations expire after the configured interval
8. Handle NAT — enable nat=force_rport, set externip=, disable directmedia
9. Review logs — parse /var/log/asterisk/messages for authentication/registration failures
10. Test systematically — isolate variables (network, config, credentials, firewall)

When a peer shows "Peer is Not Registered" in your ViciDial call logs or Asterisk CLI, follow the 10-step process above. Most issues resolve at steps 2–3 (configuration/firewall) or step 6 (credentials). For edge cases, enable SIP debugging and parse the actual REGISTER request/response sequence.

Keep this guide bookmarked. SIP registration is the foundation of ViciDial's agent connectivity. When it breaks, nothing works.