Web UI Guide

← Back to Main Documentation

This guide provides comprehensive documentation for using the OmniSS7 Web UI (Phoenix LiveView interface).

Table of Contents

1. Overview
2. Accessing the Web UI
3. Routing Management Page
4. Active Subscribers Page
5. Common Operations
6. Auto-Refresh Behavior

---

Overview

The OmniSS7 Web UI is a Phoenix LiveView application that provides real-time monitoring and management capabilities. The available pages depend on which operational mode is active (STP, HLR, or SMSc).

Web UI Architecture

Server Configuration

Parameter	Value
Protocol	HTTPS (force_ssl enabled)
Port	8087 (configured under config :control_panel, ControlPanelWeb.Endpoint → https: [port: 8087])
Default IP	0.0.0.0 (listens on all interfaces)
Certificate	priv/cert/omnitouch.crt
Private key	priv/cert/omnitouch.pem
Adapter	Bandit (Phoenix)

Access URL: https://[server-ip]:8087

---

Accessing the Web UI

Prerequisites

1. SSL Certificates: Ensure valid SSL certificates are present in priv/cert/:

   • omnitouch.crt - Certificate file
   • omnitouch.pem - Private key file

2. Application Running: Start the application with iex -S mix

3. Firewall: Ensure port 8087 is open for HTTPS traffic

Available Pages by Mode

The page label shown here is exactly the label registered in config/config.exs (use_builtin_pages / use_additional_pages). Mode columns indicate the operational mode (STP/HLR/SMSc) in which a page is typically relevant; runtime configuration filters the page list per deployment.

Page (route)	Label	STP Mode	HLR Mode	SMSc Mode	Description
/application	Resources	✅	✅	✅	System resources and monitoring
/configuration	Configuration	✅	✅	✅	Configuration viewer
/license	License	✅	✅	✅	License status
/events	SS7 Events	✅	✅	✅	Event logging and SCCP message capture
/logs	System Logs	✅	✅	✅	Live application log viewer
/client	SS7 Client	✅	✅	✅	Manual MAP operation testing
/m3ua	Peers	✅	✅	✅	M3UA peer / ASP connection status
/sctp	SCTP Connections	✅	✅	✅	Live SCTP association status
/routing	Routing	✅	❌	✅	M3UA routing table management
/routing_test	Routing Test	✅	❌	✅	Route testing and validation
/hlr_links	HLR Links	❌	✅	❌	HLR API status and subscriber management
/subscribers	Active Subscribers	❌	✅	❌	Real-time subscriber location tracking (HLR)
/smsc_links	SMSc Links	❌	❌	✅	SMSc API status and queue management
/smsc_subscribers	SMSc Subscribers	❌	❌	✅	Real-time subscriber tracking (SMSc)
/camel_sessions	CAMEL Sessions	✅	✅	✅	Live CAMEL/CAP dialogue monitoring
/camel_request	CAMEL Request Builder	✅	✅	✅	Interactive CAP request builder
/msisdn_imsi_test	MSISDN/IMSI Test	✅	✅	✅	MSISDN ↔ IMSI lookup / conversion testing

The M3UA page is labelled "Peers" in the navigation (route /m3ua).

---

Routing Management

Page: /routing Modes: STP, SMSc Auto-Refresh: Every 5 seconds

The Routing Management page provides a tabbed interface for managing M3UA routing tables.

Page Layout

Peers Tab

Manage M3UA peer connections (other STPs, HLRs, MSCs, SMSCs).

Peer Table Columns

Column	Description	Example
ID	Unique peer identifier	1
Name	Human-readable peer name	"STP_West"
Role	Connection role	client, server, stp
Point Code	Peer's SS7 point code	100
Remote	Remote IP:Port	10.0.0.10:2905
Status	Connection status	active, aspup, down
Actions	Edit/Delete buttons	-

Adding a Peer

1. Click the Peers tab
2. Fill in the form fields:
   • Peer ID: Auto-generated if left empty
   • Peer Name: Descriptive name (required)
   • Role: Select client, server, or stp
   • Point Code: SS7 point code (required)
   • Local IP: Your system's IP address
   • Local Port: 0 for dynamic port assignment
   • Remote IP: Peer's IP address
   • Remote Port: Peer's port (typically 2905)
   • Routing Context: M3UA routing context ID
   • Network Indicator: international or national
3. Click "Add Peer"

Persistence: Peer is immediately saved to Mnesia and survives restart.

Editing a Peer

1. Click the "Edit" button on the peer row
2. Modify the form fields as needed
3. Click "Update Peer"

Note: If you change the Peer ID, the old peer is deleted and a new one is created.

Deleting a Peer

1. Click the "Delete" button on the peer row
2. Confirm the deletion (all routes using this peer will also be removed)

Peer Status Indicators

Status	Color	Description
active	🟢 Green	Peer is connected and routing messages
aspup	🟡 Yellow	ASP is up but not yet active
down	🔴 Red	Peer is disconnected

---

Point Code Routes Tab

Configure routing rules based on destination Point Codes.

Route Table Columns

Column	Description	Example
Destination PC	Target point code (zone.area.id format)	1.2.3 (100)
Mask	Subnet mask for PC matching	/14 (exact), /8 (range)
Peer ID	Target peer for this route	1
Peer Name	Name of target peer	"STP_West"
Priority	Route priority (1 = highest)	1
Network	Network indicator	international
Actions	Edit/Delete buttons	-

Adding a Point Code Route

1. Click the "Point Code Routes" tab
2. Fill in the form fields:
   • Destination Point Code: Enter as zone.area.id (e.g., 1.2.3) or integer (0-16383)
   • Mask: Select mask /14 for exact match, lower values for ranges
   • Peer ID: Select target peer from dropdown
   • Priority: Enter priority (1 = highest, default)
   • Network Indicator: Select international or national
3. Click "Add Route"

Point Code Format: You can enter point codes in two formats:

• 3-8-3 Format: zone.area.id (e.g., 1.2.3)
• Integer Format: 0-16383 (e.g., 1100)

The system automatically converts between formats.

Understanding Masks

Point codes are 14-bit values (0-16383). The mask specifies how many most significant bits must match:

Mask	PCs Matched	Use Case
/14	1 (exact match)	Route to specific destination
/13	2 PCs	Small range
/8	64 PCs	Medium range
/0	All 16,384 PCs	Default/fallback route

Examples:

• PC 1000 /14 → Matches only PC 1000
• PC 1000 /8 → Matches PC 1000-1063 (64 consecutive PCs)
• PC 0 /0 → Matches all point codes (default route)

Point Code Mask Reference Card

The web page includes an interactive reference showing all mask values and their ranges.

---

Global Title Routes Tab

Configure routing rules based on SCCP Global Title addresses.

Requirement: Global Title routing must be enabled in configuration:

config :omniss7,
  enable_gt_routing: true

Route Table Columns

Column	Description	Example
GT Prefix	Called party GT prefix (empty = fallback)	"1234", ""
Source SSN	Match on called party SSN (optional)	6 (HLR), any
Peer ID	Target peer	1
Peer	Peer name	"HLR_West (1)"
Dest SSN	Rewrite SSN when forwarding (optional)	6, preserve
Priority	Route priority	1
Description	Route description	"US numbers"
Actions	Edit/Delete buttons	-

Adding a Global Title Route

1. Click the "Global Title Routes" tab
2. Fill in the form fields:
   • GT Prefix: Leave empty for fallback route, or enter digits (e.g., "1234")
   • Source SSN: Optional - filter by called party SSN
   • Peer ID: Select target peer
   • Dest SSN: Optional - rewrite SSN when forwarding
   • Priority: Route priority (1 = highest)
   • Description: Human-readable description
3. Click "Add Route"

Fallback Routes: If GT Prefix is empty, the route acts as a catch-all for GTs that don't match any other route.

Common SSN Values

The page includes a reference card with common SSN values:

SSN	Network Element
6	HLR (Home Location Register)
7	VLR (Visitor Location Register)
8	MSC (Mobile Switching Center)
9	EIR (Equipment Identity Register)
10	AUC (Authentication Center)
142	RANAP
145	gsmSCF (Service Control Function)
146	SGSN

SSN Rewriting

• Source SSN: Match on the Called Party SSN in incoming messages
• Dest SSN: If set, rewrites the Called Party SSN when forwarding
  • Empty = preserve original SSN
  • Value = replace with this SSN

Use Case: Route messages with SSN=6 (HLR) to a peer, and rewrite to SSN=7 (VLR) on the outgoing side.

---

Routing Table Persistence

All routes are stored in Mnesia and survive application restarts.

How Routes Persist

1. Web UI Changes: All add/edit/delete operations are immediately saved to Mnesia
2. Application Restart: Routes are loaded from Mnesia on startup
3. Runtime.exs Merge: Static routes from config/runtime.exs are merged with Mnesia routes (no duplicates)

Route Priority

When multiple routes match a destination:

1. More Specific First: Higher mask values (more specific) take precedence
2. Priority Field: Lower priority numbers route first (1 = highest priority)
3. Peer Status: Only routes to active peers are used

---

Active Subscribers

Page: /subscribers Mode: HLR only Auto-Refresh: Every 2 seconds

Displays real-time tracking of subscribers who have sent UpdateLocation requests.

Page Features

Subscriber Table Columns

Column	Description	Example
IMSI	Subscriber IMSI	"50557123456789"
VLR Number	Current VLR GT address	"555123155"
MSC Number	Current MSC GT address	"555123155"
Updated At	Last UpdateLocation timestamp	"2025-10-25 14:23:45 UTC"
Duration	Time since registration	"2h 15m 34s"

Statistics Summary

When subscribers are present, a summary card displays:

• Total Active: Total number of registered subscribers
• Unique VLRs: Number of distinct VLR addresses
• Unique MSCs: Number of distinct MSC addresses

Clearing Subscribers

Clear All Button: Removes all active subscribers from the tracker.

Confirmation: Requires confirmation before clearing (cannot be undone).

Use Case: Clear stale subscriber records after network maintenance or testing.

Auto-Refresh

The page automatically refreshes every 2 seconds to show real-time subscriber updates.

---

SMSc Subscribers

Page: /smsc_subscribers Mode: SMSc only Auto-Refresh: Every 2 seconds

Displays real-time tracking of subscribers based on alertServiceCenter messages received from HLRs, message delivery status, and failure tracking.

Page Features

Subscriber Table Columns

Column	Description	Example
MSISDN	Subscriber's phone number	"15551234567"
IMSI	Subscriber IMSI	"001010123456789"
HLR GT	HLR GT that sent alertServiceCenter	"15551111111"
Msgs Sent	Count of MT-FSM messages sent	5
Msgs Rcvd	Count of MO-FSM messages received	2
Status	Active or Failed (color-coded)	● Active
Last Updated	Last update timestamp	"2025-10-30 14:23:45 UTC"
Duration	Time since last update	"15m 34s"

Status Indicators

• ● Active (Green): Subscriber is reachable, last alertServiceCenter received successfully
• ○ Failed (Red): Last delivery attempt failed (SRI-for-SM or absent subscriber error)

Statistics Summary

When subscribers are present, a summary card displays:

• Total Tracked: Total number of tracked subscribers
• Active: Number of subscribers with active status
• Failed: Number of subscribers with failed status
• Unique HLRs: Number of distinct HLRs sending alerts

Managing Subscribers

Remove Button: Removes individual subscriber from tracking.

Clear All Button: Removes all tracked subscribers.

Confirmation: Clear All requires confirmation before clearing (cannot be undone).

Use Case:

• Remove stale entries after network issues
• Clear test data after development
• Monitor which HLRs are sending alerts

Message Counters

The tracker automatically increments counters:

• Messages Sent: Incremented when SRI-for-SM succeeds and MT-FSM is sent
• Messages Received: Incremented when MO-FSM is received from subscriber

Auto-Refresh

The page automatically refreshes every 2 seconds to show real-time subscriber and status updates.

---

Common Operations

Searching and Filtering

Currently, the Web UI does not include built-in search/filter functionality. To find specific routes:

1. Use your browser's find function (Ctrl+F / Cmd+F)
2. Search for peer names, point codes, or GT prefixes

Bulk Operations

To perform bulk route changes:

1. Option 1: Use the REST API for programmatic access
2. Option 2: Edit config/runtime.exs and restart the application
3. Option 3: Use the Web UI for individual route changes

Export/Import

Note: The Web UI does not currently support exporting or importing routing tables. Routes are:

• Stored in Mnesia database files
• Configured in config/runtime.exs

To backup routes:

1. Mnesia: Backup the Mnesia.{node_name}/ directory
2. Config: Version control config/runtime.exs

---

Auto-Refresh Behavior

Different pages have different refresh intervals:

Page	Refresh Interval	Reason
Routing Management	5 seconds	Route changes are infrequent
Active Subscribers	2 seconds	Subscriber state changes frequently
M3UA Status	Varies by page	Connection state monitoring

WebSocket Connection: All pages use Phoenix LiveView WebSocket connections for real-time updates.

Network Interruption: If the WebSocket connection is lost, the page will attempt to reconnect automatically.

---

Troubleshooting

Page Not Loading

1. Check HTTPS Certificate: Ensure priv/cert/omnitouch.crt and priv/cert/omnitouch.pem are present
2. Verify Port 8087: Check firewall rules allow HTTPS traffic on port 8087
3. Application Running: Confirm application is running with iex -S mix
4. Browser Console: Check for SSL certificate errors (self-signed cert warnings)

Routes Not Persisting

1. Check Mnesia Storage: Verify mnesia_storage_type: :disc_copies in config
2. Mnesia Directory: Ensure Mnesia directory is writable
3. Check Logs: Look for Mnesia errors in application logs

Auto-Refresh Not Working

1. WebSocket Connection: Check browser console for WebSocket errors
2. Network: Verify stable network connection
3. Page Reload: Try refreshing the page (F5)

---

Related Documentation

• STP Guide - Detailed routing configuration
• HLR Guide - Subscriber management
• API Guide - REST API for programmatic access
• Configuration Reference - All configuration parameters

---

Summary

The OmniSS7 Web UI provides intuitive, real-time management of routing tables and subscriber tracking:

✅ Real-time Updates - Auto-refresh keeps data current ✅ Persistent Storage - Mnesia ensures routes survive restarts ✅ Role-Based UI - Pages adapt to operational mode (STP/HLR/SMSc) ✅ Interactive Management - Add, edit, delete routes without restart ✅ Status Monitoring - Live connection and peer status

For advanced operations or automation, see the API Guide.