Skip to main content

HLR Lookup and Call Simulator - User Guide

Overview​

Diagnostic tools to help operations staff troubleshoot call routing. The HLR Lookup and Call Simulator are read-only and do not affect live traffic. The Echo Test Call is different — it places a real MT call (see its own section).

HLR Lookup Tool​

Purpose​

The HLR Lookup tool queries the Home Location Register (HLR) via SS7 MAP protocol to retrieve real-time subscriber routing information.

Access​

Navigate to /hlr or click "HLR" in the navigation menu.

What It Shows​

For any phone number, the HLR Lookup displays:

  1. MSRN (Mobile Station Roaming Number)

    • Temporary routing number assigned when subscriber roams to 2G/3G network
    • Only present if subscriber is currently roaming
    • Used by the dialplan to route calls to roaming subscriber's current location

  2. Call Forwarding Settings

    • Real-time call forwarding configuration from HLR
    • Types: Unconditional, Busy, No-Reply, Not-Reachable
    • Shows forwarding destination number
    • Shows if notification is enabled

  3. Dialplan Variables

    • Exactly which channel variables will be set
    • Variables match those used in actual call processing
    • Shows how HLR data overrides Sh data

Use Cases​

Diagnosing Roaming Issues​

Scenario: Incoming call to roaming subscriber fails or routes incorrectly

Steps:

  1. Open HLR Lookup page
  2. Enter the subscriber's phone number
  3. Click "Lookup HLR Data"
  4. Check for MSRN in results
  5. If MSRN present: Subscriber is roaming, verify MSRN is valid
  6. If no MSRN: Subscriber may be in LTE/VoLTE (no MSRN needed)

Verifying Call Forwarding​

Scenario: Call forwarding not working as expected

Steps:

  1. Open HLR Lookup page
  2. Enter the subscriber's phone number
  3. Click "Lookup HLR Data"
  4. Look for "Call Forwarding" in results
  5. Verify forwarding type (Unconditional, Busy, etc.)
  6. Verify forwarding destination number
  7. Note: HLR data overrides any Sh/HSS data

Testing HLR Connectivity​

Scenario: Verify SS7 MAP gateway is working

Steps:

  1. Open HLR Lookup page
  2. Enter any known subscriber number
  3. Click "Lookup HLR Data"
  4. Check for "Error" in results
  5. If error: Check SS7 MAP gateway connectivity
  6. Common errors:
    • "SS7 MAP is disabled" - Check configuration
    • "Timeout" - Network issue to HLR
    • "No VLR Number" - Subscriber offline or doesn't exist

Information Box​

The HLR Lookup page includes educational information explaining:

  • What MSRN is and when it's used
  • How call forwarding works in HLR
  • How this integrates with call processing
  • SS7 MAP protocol basics

Call Simulator Tool​

Purpose​

The Call Simulator allows you to simulate complete call routing without actually placing a call or affecting live traffic.

Access​

Navigate to /simulator or click "Simulator" in the navigation menu.

Features​

Input Parameters​

  1. Source Number (Caller)

    • Phone number of calling party
    • For MT calls: Can be any number
    • For MO calls: Must be provisioned subscriber

  2. Destination Number (Called Party)

    • Phone number of called party
    • For MT calls: Must be provisioned subscriber
    • For MO calls: Can be any number
    • For Emergency: Use "urn:service:sos" or similar

  3. Source IP Address

    • IP address of SIP signaling source
    • Must be in allowed_sbc_source_ips (for MT) or allowed_cscf_ips (for MO)
    • Determines call disposition (MT vs MO)

  4. Force Disposition

    • Auto: Determine from IP address (normal behavior)
    • MT: Force Mobile Terminating (incoming)
    • MO: Force Mobile Originating (outgoing)
    • Emergency: Force emergency call processing

  5. Options

    • Skip OCS Authorization: Bypass online charging (faster simulation)
    • Skip HLR Lookup: Bypass SS7 MAP query (faster simulation)

Output​

The simulator shows comprehensive results:

  1. Call Type Banner

    • MT, MO, or Emergency
    • Color-coded for quick identification
    • Shows source and destination numbers

  2. Processing Steps (Left Column)

    • Subscriber Data: Results from Sh interface (HSS)
    • HLR Data: Results from SS7 MAP lookup (MT only)
    • OCS Authorization: Results from online charging (MO only)
    • On-Net Status: Whether destination is on your network (MO only)

  3. Dialplan Variables (Right Column)

    • Every variable that would be set on the channel
    • Sorted alphabetically for easy reading
    • Color-coded values (green for normal, red for errors)

  4. Processing Notes

    • Step-by-step explanation of what happened
    • Describes data flow and decision points
    • Helps understand why certain variables were set

Use Cases​

Pre-Flight Testing​

Scenario: Testing configuration change before deploying to production

Steps:

  1. Make configuration change in dev/test environment
  2. Open Call Simulator
  3. Test multiple scenarios:
    • MT call from your SBC
    • MO call from your CSCF
    • Emergency call
    • On-net destination
    • Off-net destination
  4. Verify all variables are correct
  5. Check processing notes for any issues
  6. Deploy to production with confidence

Debugging MT Call Issues​

Scenario: Incoming calls to subscriber failing

Steps:

  1. Open Call Simulator
  2. Enter destination as the problem subscriber
  3. Enter source as test number
  4. Set source IP to your SBC IP
  5. Leave Force Disposition as "Auto"
  6. Click "Simulate Call"
  7. Check Subscriber Data section for Sh lookup success
  8. Check HLR Data section for MSRN or forwarding
  9. Check Final Variables for hangup_case
  10. If hangup_case is "UNALLOCATED_NUMBER": Subscriber not provisioned
  11. If variables look correct: Issue may be in dialplan template

Debugging MO Call Issues​

Scenario: Outgoing calls from subscriber failing

Steps:

  1. Open Call Simulator
  2. Enter source as the problem subscriber
  3. Enter destination as test number
  4. Set source IP to your CSCF IP
  5. Uncheck "Skip OCS Authorization" if testing charging
  6. Click "Simulate Call"
  7. Check Caller Data section for Sh lookup success
  8. Check OCS Authorization section for success/failure
  9. Check On-Net Status to verify correct routing
  10. Check Final Variables for allocated_time or hangup_case
  11. If hangup_case is "OUTGOING_CALL_BARRED": OCS denied the call

Testing Emergency Call Handling​

Scenario: Verify emergency calls work correctly

Steps:

  1. Open Call Simulator
  2. Enter source as test subscriber
  3. Enter destination as "urn:service:sos"
  4. Set any source IP (emergency calls bypass IP auth)
  5. Click "Simulate Call"
  6. Verify Call Type shows "Emergency (SOS)"
  7. Verify hangup_case is "none" (emergency calls always proceed)
  8. Check that OCS and HLR were bypassed
  9. Verify caller data was retrieved for location info

Training Staff​

Scenario: Teaching operations staff how call routing works

Steps:

  1. Open Call Simulator
  2. Run various scenarios and explain each section:
    • Show MT call and explain Sh + HLR lookups
    • Show MO call and explain OCS authorization
    • Show Emergency call and explain bypass behavior
    • Show unauthorized IP and explain rejection
  3. Have staff try different combinations
  4. Use Processing Notes to explain each decision
  5. Compare variables between different scenarios

Comparing Sh vs HLR Data​

Scenario: Understanding how HLR overrides Sh data

Steps:

  1. Open Call Simulator for MT call
  2. Uncheck "Skip HLR Lookup"
  3. Click "Simulate Call"
  4. Compare Subscriber Data variables vs HLR Data variables
  5. Check Final Variables to see which values won
  6. Note: HLR data always takes precedence for:
    • MSRN
    • call_forward_all_destination
    • call_forward_not_reachable_destination

Tips​

  • Use "Skip OCS Authorization" and "Skip HLR Lookup" for faster simulations when testing other aspects
  • Copy/paste phone numbers from logs into simulator for quick testing
  • Use "Force Disposition" to test specific call types regardless of IP
  • Check Processing Notes if you're unsure why certain variables were set
  • Run simulation multiple times to verify consistency
  • Compare simulation results to actual call logs

Limitations​

The simulator:

  • Does NOT actually place calls
  • Does NOT affect the call routing system
  • Does NOT consume OCS quota (even if OCS is queried)
  • Does NOT generate CDRs
  • Is safe to use on production systems

The simulator DOES:

  • Query actual Sh interface (HSS) if not skipped
  • Query actual HLR via SS7 MAP if not skipped
  • Query actual OCS if not skipped
  • Show exactly what would happen in real call
  • Use real configuration values

Echo Test Call (real MT call)​

Unlike the Call Simulator above, this places a real call. It rings the destination subscriber and runs them through the full terminating path (Sh lookup, OCS, CDR, media).

Purpose​

Start a real Mobile Terminating call to a subscriber that connects them to a FreeSWITCH echo application, so they hear their own audio back. Useful for end-to-end verification of the MT path and the media/codec leg without a real upstream caller.

API​

POST /simulator/echo_call

FieldRequiredDescription
destinationYesMSISDN to ring — the terminating subscriber (must be provisioned/registered). Digits, optional leading +.
sourceNoMSISDN shown as the caller ID. Digits, optional leading +.
curl -k -X POST https://<tas>:8444/simulator/echo_call \
  -H 'content-type: application/json' \
  -d '{"destination":"99988037866","source":"61400000001"}'

Response (issued via bgapi, returns immediately):

{
  "ok": true,
  "command": "bgapi originate {tas_call_reason=echo_test,ignore_early_media=true,origination_caller_id_number=61400000001,origination_caller_id_name=61400000001}sofia/internal/99988037866@10.8.82.60 &echo",
  "result": "+OK Job-UUID: <uuid>"
}

How it works​

It issues a FreeSWITCH originate that loops the call back into the local internal profile (sofia/internal/<destination>@<tas_ip>). Because the INVITE then arrives from the TAS's own IP — which is in allowed_sbc_source_ips — it is classified as MT (as if delivered by the upstream SBC) and runs the real MT dialplan, routing out to the subscriber via the IMS core. The originate's &echo answers, so the rung subscriber hears their own audio.

The loopback target is taken server-side from the Diameter listen IP (the local box); it is not a request parameter.

What it does / doesn't do​

Unlike the dry-run simulator, the echo call DOES:

  • Place a real call and ring the destination subscriber
  • Run Sh lookup, OCS authorization, and generate a CDR / Ro CCRs
  • Exercise the real MT dialplan and media path

It is safe against MO / toll fraud:

  • Always MT, never MO — the loopback arrives from the local IP, which can never be a CSCF source IP (the only thing that yields MO).
  • It cannot dial an arbitrary outbound number — the MT bridge target comes from the Sh subscriber lookup (NokiaCSCF/+<msisdn>), not the raw destination; an unknown destination has no MSISDN and the bridge fails. It can only ring provisioned on-net subscribers.
  • The loopback IP is server-side only, so the call can never be aimed at an external gateway. source/destination are validated as phone numbers before reaching the ESL command (no command injection).

Caller ID (source) is shown to the rung subscriber as provided — keep the endpoint behind your normal API access control, as it does place real calls.

Integration with Monitoring​

Both tools integrate with Prometheus metrics:

  • HLR lookups via the tool are counted in hlr_lookups_total
  • Call simulations are counted in call_simulations_total{call_type, source}
  • Processing times are tracked in respective duration metrics

This helps:

  • Track diagnostic tool usage
  • Monitor performance of diagnostic queries
  • Identify heavy users of diagnostic tools

For complete metrics documentation: See metrics.md for all available metrics, query examples, and monitoring setup.

Best Practices​

  1. Use Call Simulator First

    • Before making configuration changes
    • When troubleshooting subscriber-specific issues
    • To understand call flow for training

  2. Use HLR Lookup For

    • Quick check of roaming status
    • Verifying call forwarding from HLR
    • Testing SS7 MAP connectivity

  3. Document Findings

    • Take screenshots of simulator results
    • Note any unexpected behavior
    • Share results with team for analysis

  4. Compare to Logs

    • Run simulation with same parameters as failed call
    • Compare simulator variables to actual call logs
    • Identify discrepancies

  5. Regular Testing

    • Weekly spot checks with simulator
    • Test each call type (MT/MO/Emergency)
    • Verify OCS and HLR integration

Troubleshooting the Tools​

HLR Lookup Issues​

Tool shows "SS7 MAP is disabled"

  • Check config/runtime.exs for ss7_map.enabled
  • Restart application after config change

Tool shows timeout errors

  • Check SS7 MAP gateway is reachable
  • Check network connectivity to HLR
  • Check ss7_map.timeout_ms in configuration

Tool shows "No VLR Number"

  • Subscriber is offline or doesn't exist in HLR
  • Normal for subscribers who are powered off
  • Normal for non-existent numbers

Call Simulator Issues​

Simulator shows "No Sh data"

  • Subscriber not provisioned in HSS
  • HSS is unreachable
  • Check diameter.sh_application configuration

Simulator shows "Source IP is not authorized"

  • IP not in allowed_sbc_source_ips or allowed_cscf_ips
  • Use "Force Disposition" to override IP-based auth

Simulator shows "Missing required parameters"

  • All fields are required except options
  • Enter valid phone numbers
  • Enter valid IP address

Simulator takes too long

  • Uncheck "Skip OCS Authorization" if not testing OCS
  • Uncheck "Skip HLR Lookup" if not testing HLR
  • Check actual system performance (Sh/HLR/OCS response times)

Support​

For issues with these tools:

  1. Check application logs for errors
  2. Verify configuration (Sh, HLR, OCS)
  3. Test connectivity to external systems
  4. Contact support team with screenshots and error messages
Last updated on