OmniSS7 - User Guide

OmniSS7 by Omnitouch Network Services is a comprehensive, general-purpose SS7 signaling stack that provides flexible network element functionality.

Routing Overview

Documentation Overview

This documentation is organized by network element role. Choose the guide that matches your deployment:

📚 Configuration Guides

STP Guide - Signal Transfer Point Configuration
- Route SS7 traffic between network peers
- Point Code and Global Title routing
- Load balancing and topology hiding
- Use this if you're routing SS7 traffic between networks
MAP Client Guide - MAP Client Configuration
- Connect as M3UA client to send MAP requests
- HLR queries, authentication, routing info
- Generic MAP protocol support
- Use this if you're sending MAP requests to network elements
SMS Center Guide - SMS Center (SMSc) Configuration
- SMS message routing and delivery
- Database-backed message queuing
- Auto-flush and delivery reports
- Use this if you're operating an SMS Center
HLR Guide - Home Location Register Configuration
- Subscriber database management
- Authentication vector generation
- Location updates and routing information
- Use this if you're operating an HLR/HSS
CAMEL Gateway Guide - CAMEL Gateway Configuration
- Intelligent network services (CAP/CAMEL)
- Real-time call control and charging
- CGrateS integration for billing
- Interactive request builder and session monitoring
- Use this if you're providing IN services or real-time charging
USSD Gateway Guide - USSD Gateway Configuration
- Bridge SS7/MAP USSD to HTTP/JSON callbacks
- Multi-turn interactive USSD menus
- Short code routing to different callback URLs
- Network-originated USSD push via REST API
- Use this if you're building USSD applications (balance checks, top-ups, etc.)

🔧 Common Features

Common Features Guide - Shared Components
- Web UI overview and configuration
- API documentation
- Monitoring and metrics (Prometheus)
- Best practices and troubleshooting

📖 Reference Documentation

Appendix - Technical Reference
- SS7 protocol specifications
- MAP operation codes
- TCAP transaction flows
- Character encodings and formats

Quick Start

1. System Overview

OmniSS7 can operate in different modes depending on your network requirements:

3. Configuration

OmniSS7 selects its role from a set of mode flags in config/config.exs. The flags compose, so a single instance can act as several roles at once (for example, MAP Client plus SMSc).

Note: config/runtime.exs in this repository is a short test stub. Production servers have their own runtime.exs deployed separately. Edit config/config.exs (and the environment-specific file it imports) to change the default configuration.

To select a role:

Set the relevant mode flags in config/config.exs
Configure the M3UA connection (map_client_m3ua or cap_client_m3ua) and any backend API URLs
Restart the application

→ See the mode-specific guides below for complete configuration instructions

STP Mode — route SCCP/M3UA traffic between peers:

config :omniss7,
  sctp_handler: %{enabled: true, local_ip: {0, 0, 0, 0}, local_port: 2905, point_code: 100},
  enable_gt_routing: true,
  m3ua_peers: [...],
  m3ua_routes: [...],
  m3ua_gt_routes: [...]

HLR Mode:

config :omniss7,
  hlr_mode_enabled: true,
  map_client_enabled: true,
  hlr_api_base_url: "https://hlr-backend:8443",
  map_client_m3ua: %{...}

SMSc Mode:

config :omniss7,
  map_client_enabled: true,
  smsc_mode_enabled: true,
  smsc_api_base_url: "https://smsc-backend:8443",
  auto_flush_enabled: true,
  map_client_m3ua: %{...}

CAMEL Gateway Mode:

config :omniss7,
  cap_client_enabled: true,
  camelgw_mode_enabled: true,
  cgrates_enabled: true,
  cgrates_url: "http://localhost:2080/jsonrpc",
  cgrates_tenant: "cgrates.org",
  cap_client_m3ua: %{...}

See the Configuration Reference for every parameter, including the USSD Gateway (ussd_gateway_enabled).

4. Access Web UI

The Web UI is served over HTTPS on port 8087 — for example https://localhost:8087/ (or your configured host). The endpoint enforces TLS, so plain http:// is redirected.

System Architecture

Feature Matrix

Feature	STP Mode	MAP Client	SMSc Mode	HLR Mode	CAMEL GW
Point Code Routing	✅	❌	❌	❌	❌
Global Title Routing	✅	❌	❌	❌	❌
SSN Rewriting	✅	❌	❌	❌	❌
Multi-Peer Support	✅	✅	✅	✅	✅
MAP Requests (Send)	❌	✅	✅	✅	❌
MAP Responses (Receive)	❌	✅	✅	✅	❌
SMS Queue Management	❌	❌	✅	❌	❌
Auto-Flush SMS	❌	❌	✅	❌	❌
Subscriber Database	❌	❌	❌	✅	❌
Authentication Vectors	❌	❌	❌	✅	❌
Location Updates	❌	❌	❌	✅	❌
CAP/CAMEL Support	❌	❌	❌	❌	✅
Real-time Charging	❌	❌	❌	❌	✅
Call Control (IN Services)	❌	❌	❌	❌	✅
Web UI	✅	✅	✅	✅	✅
REST API	✅	✅	✅	✅	✅
Prometheus Metrics	✅	✅	✅	✅	✅

Common Operations

OmniSS7 listens on several ports, each serving a different surface:

Port	Protocol	Served by	Purpose
`8087`	HTTPS	ControlPanel (Phoenix)	Web UI dashboard (TLS enforced)
`8445`	HTTPS	api_ex	JSON status API (`/api/status`, `/api/m3ua-status`, `/api/routing`, …)
`8080`	HTTP	APIhandler (Plug.Cowboy)	MAP operation API (`/api/*`), Swagger UI (`/swagger`), OpenAPI spec (`/swagger.json`), Prometheus metrics (`/metrics`)
`2905`	SCTP	M3UA/M2PA	SS7 signaling transport

Web UI Access

Web UI: https://localhost:8087/ (or configured host)
Swagger UI: http://localhost:8080/swagger
OpenAPI spec: http://localhost:8080/swagger.json
Metrics: http://localhost:8080/metrics

Monitoring

# View Prometheus metrics
curl http://localhost:8080/metrics

# Check M3UA peer status (TLS, self-signed cert)
curl -k https://localhost:8445/api/m3ua-status

# Service status
curl -k https://localhost:8445/api/status

Logs

Logs are emitted as structured JSON (one object per line) for ingestion by Loki/Alloy, via OmniLogger.JsonFormatter. Set the log level in config/config.exs:

config :logger,
  level: :debug  # Options: :debug, :info, :warning, :error

Key Capabilities

Full MAP Protocol Support - MAP Phase 2/3 operations
CAP/CAMEL Protocol Support - CAP v1/v2/v3/v4 for intelligent network services
M3UA/SCTP Signaling - IP-based SS7 transport
Real-time Charging - CGrateS integration for prepaid/postpaid billing
SMS Delivery - HTTP/JSON backed message queue with auto-flush
Interactive Request Builder - Web UI for CAMEL/CAP testing
Session Monitoring - Real-time CAMEL call session tracking
Interactive API Docs - Swagger UI for testing
Prometheus Metrics - Complete observability
Multi-role Configuration - STP, MAP Client, SMSc, HLR, CAMEL Gateway, USSD Gateway

Protocol Stack Overview

Use Case Examples

Network Gateway (STP)

Route SS7 traffic between different mobile networks

Connect operator networks
International SS7 gateway
Load balancing across HLRs
Global Title Translation
SCCP NAT (Smart Global Title reuse)
→ STP Guide

SMS Center (SMSc)

Deliver SMS messages to mobile subscribers

MT-SMS delivery
MO-SMS origination
SMS Home Routing
IMSI Hiding
SMS Firewall
Message queue management
Delivery reports
Integrated into OmniMessage to handle all MAP SMS
→ SMS Center Guide

MAP Client

Interact with any network elements over MAP using a simple RESTful API

PRN / SRI / ATI / etc
Build your own SS7/MAP applications using RESTful APIs
USSD Gateways
Authentication vector requests
IMSI/MSISDN lookups
Routing information queries
→ MAP Client Guide

Subscriber Database (HLR)

Manage subscriber data and authentication

Location updates
Authentication generation
Routing information provisioning
Integrates fully into OmniHSS
→ HLR Guide

Intelligent Network Platform (CAMEL Gateway)

Real-time call control and charging for telecom operators

Prepaid/postpaid call charging
Call control (connect, release, routing)
Session management and CDR generation
Interactive request builder for testing
→ CAMEL Gateway Guide

Support and Resources

Documentation

Core Configuration Guides:

STP Configuration Guide - Signal Transfer Point routing
MAP Client Configuration Guide - MAP protocol client
SMS Center Configuration Guide - SMS routing and delivery
HLR Configuration Guide - Subscriber database
CAMEL Gateway Configuration Guide - Intelligent network & charging

Integration & Reference:

CAMEL Request Builder Guide - Interactive testing tool
Common Features Guide - Shared components & Web UI
Technical Reference - Protocol specifications

Documentation Overview​

📚 Configuration Guides​

🔧 Common Features​

📖 Reference Documentation​

Quick Start​

1. System Overview​

3. Configuration​

4. Access Web UI​

System Architecture​

Feature Matrix​

Common Operations​

Web UI Access​

Monitoring​

Logs​

Key Capabilities​

Protocol Stack Overview​

Use Case Examples​

Network Gateway (STP)​

SMS Center (SMSc)​

MAP Client​

Subscriber Database (HLR)​

Intelligent Network Platform (CAMEL Gateway)​

Support and Resources​

Documentation​