Configuration Reference

This document provides a comprehensive reference for all OmniSS7 configuration parameters.

Overview
Where Configuration Lives
Operational Mode Flags
HLR Mode Parameters
SMSc Mode Parameters
STP Mode Parameters
CAMEL Gateway Mode Parameters
Global Title NAT Parameters
M3UA Connection Parameters
SCCP Subsystem Status
Gateway Screening
USSD Gateway Parameters
Runtime / Supervision Flags
Infrastructure Parameters
Database Parameters
Hardcoded Values

Overview

OmniSS7 supports four operational modes, selected entirely through configuration:

STP Mode - Signal Transfer Point for routing
HLR Mode - Home Location Register for subscriber management
SMSc Mode - SMS Center for message delivery
CAMEL GW Mode - CAMEL Gateway for intelligent call control

A single node may combine roles (for example HLR + SMSc) by enabling the relevant Operational Mode Flags.

Where Configuration Lives

OmniSS7 reads its configuration from two layers. Understanding which file owns a value determines where you change it on a deployed system.

File	Role	Edit on deployment?
`config/config.exs`	Default / compile-time configuration shipped with the release. Defines the control-panel pages, the `:api_ex` REST controllers, the logging formatter, and all baseline defaults.	No — part of the build.
`config/runtime.exs` (in the repo)	A 4-line test stub only. In the source tree it sets up nothing beyond the test environment.	No.
`config/runtime.exs` (deployed)	The per-deployment runtime configuration, deployed separately onto each server (typically rendered from an Ansible/Jinja template). This is where mode flags, GTs, point codes, M3UA peers, and API backends are set for a given site.	Yes — this is the operator-facing file.

In short: examples in this document use config :omniss7, .... On a live node these go into the deployed config/runtime.exs. The config/runtime.exs committed to the repository is intentionally a stub used only by the automated test suite — do not mistake it for the production configuration.

All keys below are read via Application.get_env(:omniss7, ...) (or the relevant application) at runtime, so the defaults shown are the values used when a key is omitted.

Operational Mode Flags

Control which features are enabled.

Parameter	Type	Default	Description	Modes
`map_client_enabled`	Boolean	`false`	Enable MAP client and M3UA connectivity	All
`hlr_mode_enabled`	Boolean	`false`	Enable HLR-specific features	HLR
`smsc_mode_enabled`	Boolean	`false`	Enable SMSc-specific features	SMSc
`cap_client_enabled`	Boolean	`false`	Enable CAP client for CAMEL operations	CAMEL GW
`camelgw_mode_enabled`	Boolean	`false`	Enable CAMEL Gateway features	CAMEL GW
`ussd_gateway_enabled`	Boolean	`false`	Enable USSD Gateway (HTTP/JSON bridge)	USSD GW

Example:

config :omniss7,
  map_client_enabled: true,
  hlr_mode_enabled: true,
  smsc_mode_enabled: false

HLR Mode Parameters

Configuration for HLR (Home Location Register) mode.

HLR API Configuration

Parameter	Type	Default	Required	Description
`hlr_api_base_url`	String	-	Yes	Backend HLR API endpoint URL
`hlr_api_status_path`	String	`"/api/status"`	No	Path appended to `hlr_api_base_url` for the HLR-links health/status probe (used by the HLR Links page and the `/hlr-links` REST controller)
`hlr_service_center_gt_address`	String	-	Yes	HLR Global Title address returned in UpdateLocation responses
`smsc_service_center_gt_address`	String	-	Yes	SMSC GT address returned in SRI-for-SM responses

SSL verification: There is no hlr_api_verify_ssl key — it is not read anywhere in the code. TLS certificate verification for backend API calls is governed by the generic :api map's verify_ssl field (see API Backend SSL Verification).

Example:

config :omniss7,
  hlr_api_base_url: "https://10.180.2.140:8443",
  hlr_api_status_path: "/api/status",
  hlr_service_center_gt_address: "55512341111",
  smsc_service_center_gt_address: "55512341112"

AlertServiceCenter Configuration

When a subscriber performs UpdateLocation, the HLR sends alertServiceCenter messages to configured SMSc GTs to indicate the subscriber is now reachable.

Parameter	Type	Default	Required	Description
`hlr_smsc_alert_gts`	List of Strings	`[]`	No	List of SMSc Global Titles to send alertServiceCenter notifications
`hlr_alert_location_expiry_seconds`	Integer	`172800`	No	Location validity duration in seconds (default: 48 hours). Set to 0 to disable expiry.

Example:

config :omniss7,
  hlr_smsc_alert_gts: [
    "15559876543",
    "15559876544"
  ],
  hlr_alert_location_expiry_seconds: 172800  # 48 hours

MSISDN ↔ IMSI Mapping

Configuration for synthetic IMSI generation from MSISDNs. For detailed technical explanation of the mapping algorithm, see MSISDN ↔ IMSI Mapping in HLR Guide.

Parameter	Type	Default	Required	Description
`hlr_imsi_plmn_prefix`	String	`"50557"`	No	PLMN prefix (MCC+MNC) for synthetic IMSI generation
`hlr_msisdn_country_code`	String	`"61"`	No	Country code prefix for IMSI→MSISDN reverse mapping
`hlr_msisdn_nsn_offset`	Integer	`0`	No	Offset into MSISDN where NSN starts (typically length of country code)
`hlr_msisdn_nsn_length`	Integer	`9`	No	Length of National Subscriber Number to extract from MSISDN

Example (2-digit country code):

config :omniss7,
  hlr_imsi_plmn_prefix: "50557",      # MCC 505 + MNC 57
  hlr_msisdn_country_code: "99",      # Example 2-digit country code
  hlr_msisdn_nsn_offset: 2,           # Skip 2-digit country code
  hlr_msisdn_nsn_length: 9            # Extract 9-digit NSN

Example (3-digit country code):

config :omniss7,
  hlr_imsi_plmn_prefix: "50557",      # MCC 505 + MNC 57
  hlr_msisdn_country_code: "999",     # Example 3-digit country code
  hlr_msisdn_nsn_offset: 3,           # Skip 3-digit country code
  hlr_msisdn_nsn_length: 8            # Extract 8-digit NSN

Important: Set nsn_offset to the length of your country code to properly extract the NSN. For example:

Country code "9" (1 digit) → nsn_offset: 1
Country code "99" (2 digits) → nsn_offset: 2
Country code "999" (3 digits) → nsn_offset: 3

InsertSubscriberData (ISD) Configuration

Configuration for subscriber provisioning data sent to VLRs during UpdateLocation. For detailed explanation of the ISD sequence and message flow, see InsertSubscriberData Configuration in HLR Guide.

Parameter	Type	Default	Required	Description
`isd_network_access_mode`	Atom	`:packetAndCircuit`	No	Network access type: `:packetAndCircuit`, `:packetOnly`, or `:circuitOnly`
`isd_send_ss_data`	Boolean	`true`	No	Send ISD #2 with Supplementary Services data
`isd_send_call_barring`	Boolean	`true`	No	Send ISD #3 with Call Barring data

Example:

config :omniss7,
  isd_network_access_mode: :packetAndCircuit,
  isd_send_ss_data: true,
  isd_send_call_barring: true

CAMEL Configuration

Configuration for CAMEL-based intelligent call routing. For detailed explanation of CAMEL integration and service keys, see CAMEL Integration in HLR Guide.

Parameter	Type	Default	Required	Description
`camel_service_key`	Integer	`11_110`	No	CAMEL service key for SRI responses
`camel_trigger_detection_point`	Atom	`:termAttemptAuthorized`	No	CAMEL trigger point: `:termAttemptAuthorized`, `:tBusy`, `:tNoAnswer`, `:tAnswer`
`camel_gsmscf_gt_address`	String	(uses called GT)	No	Default gsmSCF Global Title for CAMEL responses (can be overridden by GT NAT)

Example:

config :omniss7,
  camel_service_key: 11_110,
  camel_trigger_detection_point: :termAttemptAuthorized

Home VLR Prefixes

Configuration for distinguishing home vs roaming subscribers. For detailed explanation of home/roaming detection and PRN operations, see Roaming Subscriber Handling in HLR Guide.

Parameter	Type	Default	Required	Description
`home_vlr_prefixes`	List	`["5551231"]`	No	VLR GT prefixes considered "home" network

Example:

config :omniss7,
  home_vlr_prefixes: ["5551231", "5551234"]

SMSc Mode Parameters

Configuration for SMS Center mode.

SMSc API Configuration

Parameter	Type	Default	Required	Description
`smsc_api_base_url`	String	`"https://10.5.198.200:8443"`	Yes	Backend SMSc API endpoint URL
`smsc_api_status_path`	String	`"/api/status"`	No	Path appended to `smsc_api_base_url` for the SMSc-links health/status probe (used by the SMSc Links page and the `/smsc-links` REST controller)
`smsc_name`	String	`"{hostname}_SMSc"`	No	SMSc identifier for backend registration
`smsc_service_center_gt_address`	String	-	Yes	Service Center Global Title address

SSL verification: There is no smsc_api_verify_ssl key — it is not read anywhere in the code. TLS certificate verification for backend API calls is governed by the generic :api map's verify_ssl field (see API Backend SSL Verification).

Example:

config :omniss7,
  smsc_api_base_url: "https://10.179.3.219:8443",
  smsc_api_status_path: "/api/status",
  smsc_name: "ipsmgw",
  smsc_service_center_gt_address: "55512341112"

Note: Frontend registration occurs every 5 minutes (hardcoded) via SMS.FrontendRegistry module.

Auto-Flush Configuration

Parameter	Type	Default	Required	Description
`auto_flush_enabled`	Boolean	`true`	No	Enable automatic SMS queue processing
`auto_flush_interval`	Integer	`10_000`	No	Queue processing interval in milliseconds
`auto_flush_dest_smsc`	String	-	Yes	Destination SMSC name for auto-flush
`auto_flush_tps`	Integer	`10`	No	Message processing rate (transactions/second)

Example:

config :omniss7,
  auto_flush_enabled: true,
  auto_flush_interval: 10_000,
  auto_flush_dest_smsc: "ipsmgw",
  auto_flush_tps: 10

STP Mode Parameters

Configuration for M3UA Signal Transfer Point mode. For detailed routing configuration and examples, see the STP Configuration Guide.

Standalone STP Server

Parameter	Type	Default	Required	Description
`sctp_handler.enabled`	Boolean	`false`	No	Enable standalone SCTP SocketHandler server
`sctp_handler.local_ip`	Tuple or List	`{127, 0, 0, 1}`	No	IP address(es) to listen for connections. Single IP: `{10, 0, 0, 1}` or Multiple IPs for SCTP multihoming: `[{10, 0, 0, 1}, {10, 0, 0, 2}]`
`sctp_handler.local_port`	Integer	`2905`	No	Port to listen on
`sctp_handler.point_code`	Integer	-	Yes (if enabled)	This STP's own SS7 point code

Example (Single IP):

config :omniss7,
  sctp_handler: %{
    enabled: true,
    local_ip: {10, 179, 4, 10},
    local_port: 2905,
    point_code: 100
  }

Example (SCTP Multihoming):

config :omniss7,
  sctp_handler: %{
    enabled: true,
    # Multiple IPs for redundancy
    local_ip: [{10, 179, 4, 10}, {10, 179, 4, 11}],
    local_port: 2905,
    point_code: 100
  }

Note: For detailed information on SCTP multihoming configuration and benefits, see SCTP Multihoming in Common Guide.

Global Title Routing

Parameter	Type	Default	Required	Description
`enable_gt_routing`	Boolean	`false`	No	Enable GT routing in addition to PC routing

Example:

config :omniss7,
  enable_gt_routing: true

M3UA/M2PA Peer Configuration

Peers are configured via the m3ua_peers list (supports both M3UA and M2PA protocols). For complete configuration examples, see the STP Configuration Guide and M2PA Protocol Support.

Common Peer Parameters:

Parameter	Type	Default	Required	Description
`peer_id`	Integer	-	Yes	Unique peer identifier
`name`	String	-	Yes	Descriptive peer name
`protocol`	Atom	`:m3ua`	No	Protocol type: `:m3ua` or `:m2pa`
`role`	Atom	`:client`	No	Connection role: `:client`, `:server`, `:asp`, or `:sgp`
`local_ip`	Tuple or List	-	Yes	Local IP address(es) for binding
`local_port`	Integer	-	Yes	Local SCTP port (M3UA: 2905, M2PA: 3565)
`remote_ip`	Tuple or List	-	Yes	Remote IP address(es)
`remote_port`	Integer	-	Yes	Remote SCTP port
`routing_context`	Integer	-	No	M3UA routing context identifier (M3UA only)
`point_code`	Integer	-	Yes	Local point code
`network_indicator`	Atom	`:international`	No	Network indicator: `:international` or `:national`
`initiate_connection`	Boolean	`true`	No	Whether to initiate SCTP connection

M2PA-Specific Parameters:

Parameter	Type	Default	Required	Description
`adjacent_point_code`	Integer	-	Yes (M2PA)	Adjacent peer's point code

Socket Management:

M2PA automatically uses SCTP.SocketHandler for shared socket management. All M2PA peers use the shared socket, which allows multiple peers to efficiently share the same SCTP port. For detailed configuration, see M2PA Socket Requirements.

Example (M3UA Peer):

config :omniss7,
  m3ua_peers: [
    %{
      peer_id: 1,
      name: "HLR_East",
      protocol: :m3ua,
      role: :sgp,
      local_ip: {10, 179, 4, 10},
      local_port: 2905,
      remote_ip: {10, 179, 4, 20},
      remote_port: 2905,
      point_code: 100,
      network_indicator: :international
    }
  ]

Example (M2PA Peer):

config :omniss7,
  sctp_handler: %{
    enabled: true,
    local_ip: {10, 179, 4, 10},
    local_port: 3565,
    point_code: 100
  },
  m3ua_peers: [
    %{
      peer_id: 2,
      name: "M2PA_Link_STP_West",
      protocol: :m2pa,
      role: :client,
      local_ip: {10, 179, 4, 10},
      local_port: 3565,
      remote_ip: {10, 179, 4, 30},
      remote_port: 3565,
      point_code: 100,
      adjacent_point_code: 200
    }
  ]

M3UA Point Code Routes

Point Code routing configuration. Routes define which peer to use for reaching specific destination point codes.

Parameter	Type	Default	Required	Description
`m3ua_routes`	List of Maps	`[]`	No	List of point code routes. If not specified, routes are auto-generated from peer point codes.

Route Format: Each route in m3ua_routes must be a map with:

dest_pc: Destination point code (Integer)
peer_id: Peer ID to route through (Integer)
priority: Route priority - lower value = higher priority (Integer)
network_indicator: Network indicator (Atom): :international or :national

Example:

config :omniss7,
  m3ua_routes: [
    # Route to PC 100 via peer 1 (highest priority)
    %{dest_pc: 100, peer_id: 1, priority: 1, network_indicator: :international},
    # Route to PC 200 via peer 2
    %{dest_pc: 200, peer_id: 2, priority: 1, network_indicator: :international},
    # Load balancing: same dest_pc with different priorities
    %{dest_pc: 300, peer_id: 3, priority: 1, network_indicator: :international},
    %{dest_pc: 300, peer_id: 4, priority: 2, network_indicator: :international}
  ]

M3UA Global Title Routes

Global Title prefix-based routing with advanced SCCP parameter transformation. Longest prefix match is used first, then priority.

Parameter	Type	Default	Required	Description
`m3ua_gt_routes`	List of Maps	`[]`	No	List of Global Title routing rules with optional transformations

Route Format: Each route in m3ua_gt_routes must be a map with:

Basic Parameters:

gt_prefix: Global Title prefix to match (String) - empty string matches all
peer_id: Peer ID to route through (Integer) - use 0 to DROP traffic
priority: Route priority - lower value = higher priority (Integer)
description: Human-readable description (String)

Optional Matching Parameters:

source_ssn: Match source SubSystem Number (Integer)
source_tt: Match source Translation Type (Integer)
source_npi: Match source Numbering Plan Indicator (Integer)
source_nai: Match source Nature of Address Indicator (Integer)

Optional Transformation Parameters:

dest_ssn: Transform SSN in forwarded message (Integer)
dest_tt: Transform Translation Type in forwarded message (Integer)
dest_npi: Transform Numbering Plan Indicator in forwarded message (Integer)
dest_nai: Transform Nature of Address Indicator in forwarded message (Integer)

Common Values:

Translation Type (TT): 0=Unknown, 1=International, 2=National, 3=Network Specific
Numbering Plan (NPI): 0=Unknown, 1=ISDN(E.164), 6=Mobile(E.212)
Nature of Address (NAI): 0=Unknown, 1=Subscriber, 3=National, 4=International
SubSystem Number (SSN): 6=HLR, 7=VLR, 8=MSC, 9=EIR, etc.

Example:

config :omniss7,
  m3ua_gt_routes: [
    # Basic prefix routing
    %{gt_prefix: "1234", peer_id: 1, priority: 1, description: "US numbers"},
    %{gt_prefix: "44", peer_id: 2, priority: 1, description: "UK numbers"},

    # Translation Type transformation
    %{
      gt_prefix: "61",
      peer_id: 3,
      priority: 1,
      description: "Australian numbers: TT 0→1 transformation",
      source_tt: 0,  # Match TT=0 (Unknown)
      dest_tt: 1     # Transform to TT=1 (International)
    },

    # NPI transformation
    %{
      gt_prefix: "49",
      peer_id: 1,
      priority: 1,
      description: "German numbers: Mobile→ISDN NPI conversion",
      source_npi: 6,  # Match NPI=6 (Mobile/E.212)
      dest_npi: 1     # Transform to NPI=1 (ISDN/E.164)
    },

    # Combined transformation with SSN routing
    %{
      gt_prefix: "86",
      source_ssn: 8,   # Match SSN=8 (MSC)
      peer_id: 3,
      dest_ssn: 6,     # Rewrite to SSN=6 (HLR)
      priority: 1,
      description: "Chinese traffic: Full normalization",
      source_tt: 0,
      dest_tt: 2,
      source_npi: 6,
      dest_npi: 1,
      source_nai: 4,
      dest_nai: 3
    },

    # Default/Fallback route
    %{
      gt_prefix: "",
      peer_id: 1,
      priority: 99,
      description: "Default fallback route"
    }
  ]

CAMEL Gateway Mode Parameters

Configuration for CAMEL Gateway (CAP protocol) mode.

CAMEL Mode Flags

Enable CAMEL/CAP features (set cap_client_enabled: true and camelgw_mode_enabled: true in Operational Mode Flags).

CAP Protocol Configuration

Parameter	Type	Default	Required	Description
`cap_version`	Atom	`:v2`	No	CAP protocol version: `:v1`, `:v2`, `:v3`, or `:v4`
`camel_gsmscf_gt_address`	String	(uses called GT)	No	Default gsmSCF Global Title for CAMEL responses

CAP Version Mapping:

:v1 → Application Context OID: 0.4.0.0.1.0.50.0
:v2 → Application Context OID: 0.4.0.0.1.0.50.1 (default - most widely supported)
:v3 → Application Context OID: 0.4.0.0.1.21.3.4
:v4 → Application Context OID: 0.4.0.0.1.23.3.4

Note: Incoming requests are auto-detected from their application context OID and responses match the request version.

Example:

config :omniss7,
  cap_client_enabled: true,
  camelgw_mode_enabled: true,
  cap_version: :v2,
  camel_gsmscf_gt_address: "68988411553"

CGrateS Integration

Real-time charging integration with CGrateS for prepaid/postpaid billing.

Parameter	Type	Default	Required	Description
`cgrates_enabled`	Boolean	`false`	No	Enable CGrateS integration
`cgrates_url`	String	-	Yes (if enabled)	CGrateS JSON-RPC endpoint URL
`cgrates_tenant`	String	`"cgrates.org"`	No	CGrateS tenant identifier
`cgrates_request_type`	String	`"*prepaid"`	No	Charging type: `"prepaid"`, `"postpaid"`, or `"*pseudoprepaid"`
`cgrates_timeout`	Integer	`5000`	No	CGrateS request timeout in milliseconds

Example:

config :omniss7,
  cgrates_enabled: true,
  cgrates_url: "http://localhost:2080/jsonrpc",
  cgrates_tenant: "cgrates.org",
  cgrates_request_type: "*prepaid",
  cgrates_timeout: 5000

CAP M3UA Connection

CAMEL Gateway uses a separate M3UA connection for CAP operations.

Parameter	Type	Default	Required	Description
`cap_client_m3ua`	Map	-	Yes	CAP M3UA connection configuration (same structure as `map_client_m3ua`, including optional `opc` and `dpc` parameters)

Example:

config :omniss7,
  cap_client_m3ua: %{
    mode: "ASP",
    callback: {CapClient, :handle_payload, []},
    process_name: :camelgw_client_asp,
    local_ip: {10, 5, 198, 200},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 4,
    opc: 5013,    # Originating Point Code
    dpc: 5011     # Destination Point Code
  }

Global Title NAT Parameters

Global Title Network Address Translation allows different response GTs based on calling party prefix, called party prefix, or both. Rules are matched by weight (lower = higher priority), then prefix specificity (longer combined prefix = more specific). For detailed explanation and examples, see the Global Title NAT Guide.

Parameter	Type	Default	Required	Description
`gt_nat_enabled`	Boolean	`false`	No	Enable/disable GT NAT feature
`gt_nat_rules`	List of Maps	`[]`	Yes (if enabled)	List of GT NAT rules with prefix matching

Rule Format: Each rule in gt_nat_rules must be a map with:

calling_prefix: String prefix to match against calling GT (optional)
called_prefix: String prefix to match against called GT (optional)
weight: Integer priority (lower = higher priority) - default: 100
response_gt: Global Title to use in responses (required)

Matching Priority:

Rules are matched by weight (lower value = higher priority)
If weights are equal, longer combined prefix length wins
Both calling_prefix and called_prefix can be used together for precise matching

Example:

config :omniss7,
  gt_nat_enabled: true,
  gt_nat_rules: [
    # High priority: Match both calling from "8772" AND called to "555"
    %{calling_prefix: "8772", called_prefix: "555", weight: 1, response_gt: "111111"},

    # Medium priority: Match only calling from "8772"
    %{calling_prefix: "8772", weight: 10, response_gt: "68988411553"},

    # Medium priority: Match only called to "555"
    %{called_prefix: "555", weight: 10, response_gt: "68988411554"},

    # Match only calling from "8773"
    %{calling_prefix: "8773", weight: 10, response_gt: "68988411554"},

    # Wildcard fallback rule (matches everything, highest weight)
    %{weight: 100, response_gt: "68988411555"}
  ]

See Also: GT NAT Guide for detailed usage and examples.

M3UA Connection Parameters

M3UA connection configuration for MAP client mode. For detailed usage and examples, see the MAP Client Guide.

Parameter	Type	Default	Required	Description
`map_client_m3ua.mode`	String	-	Yes	Connection mode: `"ASP"` or `"SGP"`
`map_client_m3ua.callback`	Tuple	-	Yes	Callback module/function: `{MapClient, :handle_payload, []}`
`map_client_m3ua.process_name`	Atom	-	Yes	Process name for registration
`map_client_m3ua.local_ip`	Tuple or List	-	Yes	Local IP address(es) to bind. Single: `{10, 0, 0, 1}` or Multiple for SCTP multihoming: `[{10, 0, 0, 1}, {10, 0, 0, 2}]`
`map_client_m3ua.local_port`	Integer	`2905`	Yes	Local SCTP port
`map_client_m3ua.remote_ip`	Tuple or List	-	Yes	Remote STP/SGW IP address(es). Single: `{10, 0, 0, 10}` or Multiple: `[{10, 0, 0, 10}, {10, 0, 0, 11}]`
`map_client_m3ua.remote_port`	Integer	`2905`	Yes	Remote SCTP port
`map_client_m3ua.routing_context`	Integer	-	Yes	M3UA routing context ID
`map_client_m3ua.opc`	Integer	`5013`	No	Originating Point Code for outgoing MAP requests. If not set, defaults to legacy value `5013`.
`map_client_m3ua.dpc`	Integer	`5011`	No	Destination Point Code for outgoing MAP requests. If not set, defaults to legacy value `5011`.
`map_client_m3ua.receive_watchdog`	Boolean	`true`	No	Enable the ASP receive watchdog. When `true`, the connection is torn down if no SCTP data is received within `receive_watchdog_idle` seconds. Set to `false` to disable entirely. See Receive Watchdog below.
`map_client_m3ua.receive_watchdog_idle`	Integer	`15`	No	Idle threshold in seconds. If no SCTP payload is received within this window, the watchdog tears down the connection and triggers a reconnect. Only applicable when `receive_watchdog: true`.

Example (Single IP):

config :omniss7,
  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :hlr_client_asp,
    local_ip: {10, 179, 4, 11},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 1,
    opc: 5013,    # Originating Point Code (2-114-5)
    dpc: 5011     # Destination Point Code (2-114-3)
  }

Point Code Format: Point codes in X-Y-Z format convert to integers as: (X * 2048) + (Y * 8) + Z. For example, 2-114-5 = (2 * 2048) + (114 * 8) + 5 = 5013.

Example (SCTP Multihoming):

config :omniss7,
  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :hlr_client_asp,
    # Multiple local IPs for redundancy
    local_ip: [{10, 179, 4, 11}, {10, 179, 4, 12}],
    local_port: 2905,
    # Multiple remote IPs for STP redundancy
    remote_ip: [{10, 179, 4, 10}, {10, 179, 4, 20}],
    remote_port: 2905,
    routing_context: 1
  }

Note: For detailed information on SCTP multihoming configuration and benefits, see SCTP Multihoming in Common Guide.

Receive Watchdog

The receive watchdog monitors SCTP connections for zombie sockets — associations that remain in an ESTABLISHED state at the OS level but where the remote end has silently stopped sending data. Without the watchdog, a dead connection may not be detected until the next send attempt fails.

Any received SCTP payload resets the idle timer, including M3UA BEAT responses, NOTIFY messages, and application data. Per RFC 4666 §3.8, M3UA BEAT is optional — SCTP already performs mandatory heartbeating at the transport layer. In environments where the remote SG does not send periodic application-layer traffic (and does not send M3UA BEATs), disabling the watchdog avoids unnecessary reconnect cycles.

Parameter	Type	Default	Description
`receive_watchdog`	Boolean	`true`	Enable or disable the receive watchdog. When `false`, idle connections are never torn down by the watchdog; SCTP transport-layer heartbeating still operates normally.
`receive_watchdog_idle`	Integer	`15`	Seconds of inactivity before the watchdog tears down the connection and triggers a reconnect. Has no effect when `receive_watchdog: false`.

Example — Disabling the watchdog for an ASP client:

config :omniss7,
  map_client_m3ua: %{
    mode: "ASP",
    local_ip: {10, 179, 4, 11},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 1,
    receive_watchdog: false        # Disable — remote SG does not send periodic traffic
  }

Example — Customising the idle threshold:

config :omniss7,
  map_client_m3ua: %{
    mode: "ASP",
    local_ip: {10, 179, 4, 11},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 1,
    receive_watchdog: true,
    receive_watchdog_idle: 30      # Tear down after 30 s of silence (default: 15 s)
  }

SCCP Subsystem Status

OmniSS7 answers SCCP-management Subsystem-Status-Tests (SST) from the real status of the queried local subsystem (ITU-T Q.714 §5.3.4). The local_subsystems key declares which SubSystem Numbers (SSNs) this node actually hosts. An SST for a listed SSN is answered Subsystem-Allowed (SSA); any other SSN is answered Subsystem-Prohibited (SSP).

Parameter	Type	Default	Required	Description
`local_subsystems`	List of Integers or `:all`	`:all`	No	In-service local SCCP SSNs used to answer SST. `:all` (the default) treats every subsystem as available — appropriate for a pure relay that hosts no subsystems. Operators that terminate specific SSNs should list them so SST reflects reality.

Common SSNs: 6 = HLR, 7 = VLR, 8 = MSC, 9 = EIR, 146 = gsmSCF/CAMEL.

Example:

config :omniss7,
  local_subsystems: [6, 7, 8, 146]

Implemented in lib/ss7_logic/subsystem_status.ex.

Gateway Screening

Gateway screening (the SCCP firewall) permits or denies transit traffic before it is routed. Rules match on source peer, OPC, DPC, Service Indicator, SCCP Called/Calling-Party GTA prefix and SSN; the first matching enabled rule (lowest priority) decides allow/deny. When no rule matches, the default action below applies. Denied messages are dropped and counted as m3ua_stp_routing_failures_total{reason="screened"}. See the STP Guide for the full model.

Parameter	Type	Default	Required	Description
`screening_default_action`	`:allow` or `:deny`	`:allow`	No	Action applied to a transit message when no screening rule matches. `:allow` (default) is a default-permit posture; `:deny` is default-deny (allowlist). Setting `:deny` makes screening active even with no rules configured.

Example:

config :omniss7,
  # Default-deny: only traffic matching an explicit allow rule is forwarded.
  screening_default_action: :deny

Rules themselves are held in the ss7_screen_rule Mnesia table and managed programmatically; only the default action is set via config.

Implemented in lib/ss7_logic/screening.ex.

USSD Gateway Parameters

The USSD Gateway bridges network-initiated and mobile-initiated USSD to an HTTP/JSON backend. Enable it with ussd_gateway_enabled: true (see Operational Mode Flags), then configure the ussd_gateway map. For the full callback protocol and session lifecycle, see the USSD Gateway Guide.

Parameter	Type	Default	Required	Description
`ussd_gateway.routes`	List of Maps	`[]`	Yes (if enabled)	Shortcode → callback-URL routing rules. Each entry is `%{pattern: "<prefix>", url: "<callback URL>"}`. Longest matching prefix wins; use `"*"`-style short patterns as catch-all fallbacks.
`ussd_gateway.session_timeout_ms`	Integer	`180_000`	No	Maximum total session lifetime in milliseconds (3 minutes). Session is terminated if exceeded.
`ussd_gateway.turn_timeout_ms`	Integer	`30_000`	No	Maximum time (ms) to wait for a subscriber reply within a multi-turn dialogue.
`ussd_gateway.http_timeout_ms`	Integer	`5_000`	No	HTTP request/connect timeout (ms) for callbacks to your application.
`ussd_gateway.max_text_length`	Integer	`182`	No	Maximum characters in a USSD text string (GSM 7-bit). Longer texts are truncated and a warning is logged.

Routing: When a USSD code arrives, the gateway sorts configured routes by descending pattern length and selects the first whose pattern is a prefix of the dialled code — giving deterministic longest-prefix matching.

Example:

config :omniss7,
  ussd_gateway_enabled: true,
  ussd_gateway: %{
    routes: [
      %{pattern: "*100", url: "http://balance-app:9000/ussd"},
      %{pattern: "*200", url: "http://topup-app:9000/ussd"},
      %{pattern: "*",    url: "http://default-app:9000/ussd"}
    ],
    session_timeout_ms: 180_000,
    turn_timeout_ms: 30_000,
    http_timeout_ms: 5_000,
    max_text_length: 182
  }

Runtime / Supervision Flags

These flags control how much of the supervision tree starts. They are useful for running OmniSS7 headless (as a library dependency) or for stripping the web tier in constrained deployments.

Parameter	Type	Default	Required	Description
`start_web_interfaces`	Boolean	`true`	No	Start the control-panel UI, the `:api_ex` REST server, and the SS7 events logger. When `false`, only the packet-logger (`SS7.Events`) starts. Can be overridden at boot by the `ENABLE_WEB_INTERFACES` environment variable (`true`/`1` or `false`/`0`).
`start_http_server`	Boolean	`true`	No	Start the Plug.Cowboy HTTP server on port 8080 (REST `/api/*`, `/metrics`, `/swagger`). See REST API Server.
`headless`	Boolean	`false`	No	Library-only minimal supervision. When `true`, OmniSS7 starts only the codec/transaction supervisors (MAP, CAP, USSD registries and dynamic supervisors) — no web UI, no license client, no SCTP handler, no M3UA server. Intended for embedding OmniSS7 codecs as a dependency.
`vlr_cache_ttl_seconds`	Integer	`3600`	No	Time-to-live (seconds) for cached VLR lookups in the SMSc delivery path (`lib/sms/smsc_api_client.ex`).

Example (headless library mode):

config :omniss7,
  headless: true

Example (no web tier, REST API only):

config :omniss7,
  start_web_interfaces: false,
  start_http_server: true

Infrastructure Parameters

Configuration for system infrastructure components including licensing, web interface, API server, and logging.

License Configuration

Parameter	Type	Default	Required	Description
`license_client.license_server_api_urls`	List of Strings	-	Yes	License server API endpoint URLs
`license_client.licensee`	String	-	Yes	Licensee organization name

Example:

config :license_client,
  license_server_api_urls: ["https://localhost:10443/api"],
  licensee: "Omnitouch Network Services Pty. Ltd."

Control Panel Web Interface

Parameter	Type	Default	Required	Description
`control_panel.parent_application_readable_name`	String	`"OmniSS7 Stack"`	No	Application name displayed in web UI
`control_panel.use_additional_pages`	List of Tuples	`[]`	No	Additional web UI pages to display
`control_panel.page_order`	List of Strings	`[]`	No	Order of pages in navigation menu
`ControlPanelWeb.Endpoint.url.host`	String	`"0.0.0.0"`	No	Web interface hostname
`ControlPanelWeb.Endpoint.https.port`	Integer	`8087`	No	HTTPS port for web interface
`ControlPanelWeb.Endpoint.https.keyfile`	String	`"priv/cert/omnitouch.pem"`	No	TLS private key file path
`ControlPanelWeb.Endpoint.https.certfile`	String	`"priv/cert/omnitouch.crt"`	No	TLS certificate file path

Example:

config :control_panel, ControlPanelWeb.Endpoint,
  url: [host: "0.0.0.0", path: "/"],
  https: [
    port: 8087,
    keyfile: "priv/cert/omnitouch.pem",
    certfile: "priv/cert/omnitouch.crt"
  ],
  parent_application_readable_name: "OmniSS7 Stack STP"

config :control_panel,
  use_additional_pages: [
    {SS7.Web.EventsLive, "/events", "SS7 Events"},
    {SS7.Web.M3UAStatusLive, "/m3ua", "Peers"}
  ],
  page_order: ["/events", "/m3ua", "/application", "/configuration"]

REST API Server

Parameter	Type	Default	Required	Description
`start_http_server`	Boolean	`true`	No	Enable/disable HTTP server (port 8080)
`api_ex.api.port`	Integer	`8445`	No	API server port
`api_ex.api.listen_ip`	String	`"0.0.0.0"`	No	API server listen IP
`api_ex.api.product_name`	String	`"OmniSS7"`	No	Product name for API
`api_ex.api.title`	String	`"API - OmniSS7"`	No	API title for Swagger UI
`api_ex.api.hostname`	String	`"localhost"`	No	API hostname
`api_ex.api.enable_tls`	Boolean	`true`	No	Enable TLS for API server
`api_ex.api.tls_cert_path`	String	`"priv/cert/omnitouch.crt"`	No	TLS certificate path for API
`api_ex.api.tls_key_path`	String	`"priv/cert/omnitouch.pem"`	No	TLS private key path for API

Example:

config :omniss7,
  start_http_server: true

config :api_ex,
  api: %{
    port: 8445,
    listen_ip: "0.0.0.0",
    product_name: "OmniSS7",
    title: "API - OmniSS7",
    hostname: "localhost",
    enable_tls: true,
    tls_cert_path: "priv/cert/omnitouch.crt",
    tls_key_path: "priv/cert/omnitouch.pem"
  }

Ports and transports at a glance:

Port	Transport	Server	Purpose
8080	HTTP (Plug.Cowboy)	`APIhandler`	MAP/CAP REST `/api/*`, `/metrics`, `/swagger`, `/swagger.json`. Toggled by `start_http_server`.
8087	HTTPS (Bandit/Phoenix)	`ControlPanelWeb.Endpoint`	Web control panel UI. Part of the web tier (`start_web_interfaces`).
8445	HTTPS / TLS	`:api_ex` REST controllers	Status, routing CRUD, links, subscribers, CAMEL/SCTP/M3UA views. Part of the web tier.

API Endpoints:

MAP/CAP REST API + Swagger: http://[server-ip]:8080/... (see API Guide)
:api_ex REST controllers: https://[server-ip]:8445/api/*
Web control panel: https://[server-ip]:8087/
Prometheus metrics: http://[server-ip]:8080/metrics

API Backend SSL Verification

Outbound calls to backend HLR/SMSc APIs do not use per-target *_verify_ssl keys. Certificate verification is controlled by the generic :api map consumed by SS7.Config.api_config/0 (lib/ss7_config.ex):

Parameter	Type	Default	Description
`api.base_url`	String	falls back to `smsc_api_base_url`	Base URL for the generic API client.
`api.timeout`	Integer	`5000`	Request timeout in milliseconds.
`api.verify_ssl`	Boolean	`false`	Whether to verify backend TLS certificates. This is the single SSL-verify switch — there is no `hlr_api_verify_ssl` or `smsc_api_verify_ssl`.

Example:

config :omniss7,
  api: %{
    base_url: "https://10.179.3.219:8443",
    timeout: 5000,
    verify_ssl: false
  }

Logging Configuration

Parameter	Type	Default	Required	Description
`logger.level`	Atom	`:debug`	No	Log level: `:debug`, `:info`, `:warning`, `:error`
`logger.backends`	List	`[:console]`	No	Logger backends (includes `SS7.Web.LoggerBackend` for web UI)
`logger.default_formatter.format`	String	-	No	Log message format string
`logger.default_formatter.metadata`	List	`[]`	No	Metadata fields to include in logs
`logger.default_formatter.truncate`	Atom/Integer	`:infinity`	No	Log message truncation length

Example:

config :logger,
  level: :debug,
  backends: [:console, SS7.Web.LoggerBackend]

config :logger, :default_formatter,
  format: "[$date] [$time] [$level] $message\n",
  metadata: [:error_code, :file],
  truncate: :infinity

Database Parameters

Configuration for Mnesia database persistence.

Parameter	Type	Default	Required	Description
`mnesia_storage_type`	Atom	`:disc_copies`	No	Mnesia storage type: `:disc_copies` or `:ram_copies`

Example:

config :omniss7,
  mnesia_storage_type: :disc_copies  # Production
  # mnesia_storage_type: :ram_copies  # Testing only

Storage Types:

:disc_copies - Persistent disk storage (survives restarts) - Recommended for production
:ram_copies - In-memory only (lost on restart) - For testing only

Mnesia Tables:

m3ua_peer - M3UA peer connections
m3ua_route - Point Code routes
m3ua_gt_route - Global Title routes

Location: Mnesia.{node_name}/ directory

Hardcoded Values

The following values are hardcoded in the source code and cannot be changed via configuration.

Timeouts

Value	Impact	Workaround
MAP request timeout: 10 seconds	All MAP operations timeout after 10s	Modify source code
ISD timeout: 10 seconds	Each ISD message times out after 10s	Modify source code

HTTP Server

Value	Impact	Workaround
HTTP IP: 0.0.0.0	Metrics/Swagger server listens on all interfaces	Modify source code
HTTP Port: 8080	Metrics/Swagger endpoint runs on port 8080	Modify source code

Registration Intervals

Value	Impact	Workaround
Frontend registration: 5 minutes	SMSc registers with backend every 5 min	Modify source code

Web UI Auto-Refresh

Page	Interval
Routing Management	5 seconds
Active Subscribers	2 seconds

Configuration Examples

Minimal HLR Configuration

config :omniss7,
  map_client_enabled: true,
  hlr_mode_enabled: true,
  smsc_mode_enabled: false,

  hlr_api_base_url: "https://10.180.2.140:8443",
  hlr_service_center_gt_address: "55512341111",
  smsc_service_center_gt_address: "55512341112",

  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :hlr_client_asp,
    local_ip: {10, 179, 4, 11},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 1
  }

Minimal SMSc Configuration

config :omniss7,
  map_client_enabled: true,
  hlr_mode_enabled: false,
  smsc_mode_enabled: true,

  smsc_api_base_url: "https://10.179.3.219:8443",
  smsc_name: "ipsmgw",
  smsc_service_center_gt_address: "55512341112",

  auto_flush_enabled: true,
  auto_flush_interval: 10_000,
  auto_flush_dest_smsc: "ipsmgw",
  auto_flush_tps: 10,

  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :stp_client_asp,
    local_ip: {10, 179, 4, 12},
    local_port: 2905,
    remote_ip: {10, 179, 4, 10},
    remote_port: 2905,
    routing_context: 1
  }

STP with Standalone Server

config :omniss7,
  map_client_enabled: true,
  hlr_mode_enabled: false,
  smsc_mode_enabled: false,

  enable_gt_routing: true,
  mnesia_storage_type: :disc_copies,

  sctp_handler: %{
    enabled: true,
    local_ip: {10, 179, 4, 10},
    local_port: 2905,
    point_code: 100
  },

  map_client_m3ua: %{
    mode: "ASP",
    callback: {MapClient, :handle_payload, []},
    process_name: :stp_client_asp,
    local_ip: {10, 179, 4, 10},
    local_port: 2906,
    remote_ip: {10, 179, 4, 11},
    remote_port: 2905,
    routing_context: 1
  }

Summary

Total Configuration Parameters: 85+

By Category:

Operational Mode: 6 parameters
HLR Mode: 17 parameters
SMSc Mode: 8 parameters
STP Mode: 5+ parameters (plus m3ua_peers, m3ua_routes, m3ua_gt_routes lists)
CAMEL GW Mode: 14 parameters
Global Title NAT: 2 parameters
M3UA Connection: 8 parameters
SCCP Subsystem Status: 1 parameter
USSD Gateway: 5 parameters
Runtime / Supervision: 4 parameters
Infrastructure (License, Web, API, Logging): 23 parameters
Database: 1 parameter

Required Parameters by Mode:

HLR Mode:

hlr_api_base_url
hlr_service_center_gt_address
smsc_service_center_gt_address
All map_client_m3ua.* parameters (8)

SMSc Mode:

smsc_api_base_url
smsc_service_center_gt_address
auto_flush_dest_smsc (if auto-flush enabled)
All map_client_m3ua.* parameters (8)

STP Mode:

sctp_handler.point_code (if SCTP handler enabled)
sctp_handler.local_ip
sctp_handler.local_port

CAMEL GW Mode:

cgrates_url (if CGrateS enabled)
All cap_client_m3ua.* parameters (8)

Infrastructure:

license_client.license_server_api_urls
license_client.licensee

HLR Guide - HLR-specific configuration
SMSc Guide - SMSc-specific configuration
STP Guide - STP routing configuration
API Guide - REST API reference
USSD Gateway Guide - USSD Gateway configuration and HTTP callback protocol
Web UI Guide - Web interface documentation

Table of Contents​

Overview​

Where Configuration Lives​

Operational Mode Flags​

HLR Mode Parameters​

HLR API Configuration​

AlertServiceCenter Configuration​

MSISDN ↔ IMSI Mapping​

InsertSubscriberData (ISD) Configuration​

CAMEL Configuration​

Home VLR Prefixes​

SMSc Mode Parameters​

SMSc API Configuration​

Auto-Flush Configuration​

STP Mode Parameters​

Standalone STP Server​

Global Title Routing​

M3UA/M2PA Peer Configuration​

M3UA Point Code Routes​

M3UA Global Title Routes​

CAMEL Gateway Mode Parameters​

CAMEL Mode Flags​

CAP Protocol Configuration​

CGrateS Integration​

CAP M3UA Connection​

Global Title NAT Parameters​

M3UA Connection Parameters​

Receive Watchdog​

SCCP Subsystem Status​

Gateway Screening​

USSD Gateway Parameters​

Runtime / Supervision Flags​

Infrastructure Parameters​

License Configuration​

Control Panel Web Interface​

REST API Server​

API Backend SSL Verification​

Logging Configuration​

Database Parameters​

Hardcoded Values​

Timeouts​

HTTP Server​

Registration Intervals​

Web UI Auto-Refresh​

Configuration Examples​

Minimal HLR Configuration​

Minimal SMSc Configuration​

STP with Standalone Server​

Summary​

Total Configuration Parameters: 85+​

Related Documentation​

Table of Contents

Overview

Where Configuration Lives

Operational Mode Flags

HLR Mode Parameters

HLR API Configuration

AlertServiceCenter Configuration

MSISDN ↔ IMSI Mapping

InsertSubscriberData (ISD) Configuration

CAMEL Configuration

Home VLR Prefixes

SMSc Mode Parameters

SMSc API Configuration

Auto-Flush Configuration

STP Mode Parameters

Standalone STP Server

Global Title Routing

M3UA/M2PA Peer Configuration

M3UA Point Code Routes

M3UA Global Title Routes

CAMEL Gateway Mode Parameters

CAMEL Mode Flags

CAP Protocol Configuration

CGrateS Integration

CAP M3UA Connection

Global Title NAT Parameters

M3UA Connection Parameters

Receive Watchdog

SCCP Subsystem Status

Gateway Screening

USSD Gateway Parameters

Runtime / Supervision Flags

Infrastructure Parameters

License Configuration

Control Panel Web Interface

REST API Server

API Backend SSL Verification

Logging Configuration

Database Parameters

Hardcoded Values

Timeouts

HTTP Server

Registration Intervals

Web UI Auto-Refresh

Configuration Examples

Minimal HLR Configuration

Minimal SMSc Configuration

STP with Standalone Server

Summary

Total Configuration Parameters: 85+

Related Documentation