Configuration Reference
This document covers every configuration parameter for OmniMSC. Configuration is specified in Elixir config files (config.exs, dev.exs, runtime.exs) and can be overridden at runtime via environment variables.
For a quick start example, see the Operations Guide.
MSC Identity
config :omnimsc, :msc
Defines the MSC's SS7 network identity, used for SCCP addressing, MAP operations, Location Area identification, and CDR generation. The active MSC identity parameters are visible in the System page of the control panel — for more, see Control Panel Guide.
config :omnimsc, :msc,
point_code: 500,
global_title: "14155550100",
name: "OMNIMSC01",
msc_number: "14155550100",
vlr_number: "14155550100",
mcc: 999,
mnc: 99,
lac: 0x1092,
allowed_a5: [:a5_1, :a5_3]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
point_code | integer or [integer, integer, integer] | Yes | 0 | SS7 point code. May be specified as a flat integer or in 14-bit ITU format [a, b, c] (encoded as a*2048 + b*8 + c). |
global_title | string | Yes | "00000000000" | SCCP Global Title (E.164 number) for MAP routing to HLR, SMSc, and peer nodes. |
name | string | Yes | "OMNIMSC01" | Logical MSC name. Used in CDR recording_entity field, alarm descriptions, and log messages. |
msc_number | string | Yes | -- | E.164 address of the MSC, sent to the HLR in MAP Update Location and used for MT call routing. |
vlr_number | string | Yes | -- | E.164 address of the co-located VLR, sent to the HLR in MAP Update Location. Typically the same as msc_number. |
mcc | integer | Yes | -- | Mobile Country Code (3 digits). Combined with mnc and lac to form the Location Area Identity (LAI) broadcast in System Information. |
mnc | integer | Yes | -- | Mobile Network Code (2 or 3 digits). |
lac | integer | Yes | -- | Location Area Code (16-bit). Identifies the location area served by this MSC/VLR. |
allowed_a5 | list(atom) | No | [:a5_1, :a5_3] | Permitted A5 cipher algorithms for air-interface encryption. Valid values: :a5_0, :a5_1, :a5_2, :a5_3. Algorithm negotiation prefers A5/3 > A5/1 > A5/0 (3GPP TS 48.008). |
HLR
config :omnimsc, :hlr
Configures the remote HLR address for MAP operations (Send Authentication Info, Update Location, Insert Subscriber Data, Purge MS).
config :omnimsc, :hlr,
address: "14155550200",
point_code: [3, 14, 2]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | Yes | -- | HLR Global Title (E.164 number) for MAP routing. |
point_code | integer or [integer, integer, integer] | No | -- | HLR SS7 point code for direct MTP3 routing when Global Title Translation is not used. May be a flat integer or ITU 14-bit format [a, b, c]. |
VLR
config :omnimsc, :vlr
Controls Visitor Location Register behavior including authentication policy, TMSI management, and lab/guest modes.
config :omnimsc, :vlr,
hlr_adapter: Omnimsc.VLR.HLR.Live,
auth_required: true,
tmsi_realloc: true,
num_auth_vectors: 1
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
hlr_adapter | module | No | Omnimsc.VLR.HLR.Default | HLR adapter module. The compiled-in default when unset is Omnimsc.VLR.HLR.Default, a no-op logging adapter. Omnimsc.VLR.HLR.Live sends real MAP operations over SS7. Omnimsc.VLR.HLR.Mock provides a built-in HLR simulator for lab testing. The shipped config.exs sets Omnimsc.VLR.HLR.Live explicitly. |
auth_required | boolean | No | true | Whether to require GSM A3/A8 authentication before granting service. When false, Location Update proceeds without Send Authentication Info. |
tmsi_realloc | boolean | No | true | Whether to reallocate a new TMSI after each successful Location Update. Enhances subscriber identity confidentiality. |
num_auth_vectors | integer | No | 1 | Number of authentication vectors to request from the HLR per Send Authentication Info (1--4 per 3GPP TS 29.002). Higher values reduce MAP signalling at the cost of memory. |
lab_mode | boolean | No | false | When true, accepts any SRES/XRES authentication response. Intended for lab testing with SIM cards whose Ki does not match the HLR. |
guest_mode | boolean | No | false | When true, allows subscribers unknown to the HLR to attach with a randomly-assigned MSISDN. Useful for demonstration networks. |
M3UA / STP
config :omnimsc, :m3ua_asp
Configures the M3UA ASP (Application Server Process) connection to a Signalling Transfer Point. All SS7 signalling (A-interface, MAP to HLR/SMSc, ISUP) is routed through this link.
config :omnimsc, :m3ua_asp,
enabled: true,
local_ip: {10, 5, 198, 200},
local_port: 0,
remote_ip: {10, 179, 4, 10},
remote_port: 2905,
routing_context: 10,
receive_watchdog: false,
receive_watchdog_idle: 15
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Whether to start the M3UA ASP client. When false, no STP connection is established. |
local_ip | tuple | No | {0, 0, 0, 0} | Local SCTP bind IP address as an Erlang tuple. |
local_port | integer | No | 0 | Local SCTP bind port. Use 0 to let the OS assign an ephemeral port. |
remote_ip | tuple | Yes | -- | STP SCTP IP address as an Erlang tuple. |
remote_port | integer | No | 2905 | STP SCTP port. Port 2905 is the IANA-assigned M3UA port. |
routing_context | integer | No | -- | M3UA routing context value. Must match the STP's AS configuration for this ASP. |
receive_watchdog | boolean | No | true | Whether to enable the M3UA heartbeat watchdog. When true, the ASP monitors for missing BEAT-Ack and triggers link recovery. |
receive_watchdog_idle | integer | No | 15 | Idle interval in seconds before the receive watchdog considers the link stalled. |
The local point code is taken from :msc point_code; a point_code set under :m3ua_asp is not read. The MTP3 network indicator is not configurable here.
Direct SCTP listeners (for BSC connections without an STP) are configured under config :omnimsc, :sctp:
config :omnimsc, :sctp,
listeners: [
[name: :a_interface, ip: {0, 0, 0, 0}, port: 2905, ppid: 3]
]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | atom | Yes | -- | Logical listener name for SCTP association lookups and control panel display. |
ip | tuple | No | {0, 0, 0, 0} | Bind IP address. Use {0, 0, 0, 0} for all interfaces. |
port | integer | No | 2905 | SCTP bind port. |
ppid | integer | No | 3 | SCTP Payload Protocol Identifier. Value 3 indicates M3UA (RFC 4666). |
Runtime override: Set SCTP_LISTEN_IP and SCTP_LISTEN_PORT environment variables.
SIP
config :omnimsc, :sip
Configures the SIP listener and SIP peer gateways for VoIP interconnection.
config :omnimsc, :sip,
signaling_address: "10.5.198.200",
listen_ip: {0, 0, 0, 0},
listen_port: 5060,
transport: :udp,
peers: [
[name: "Default-GW", address: "10.1.1.50", port: 5060,
transport: :udp, codecs: [:pcmu, :pcma],
max_channels: 100, options_interval: 60],
[name: "International-GW", address: "10.1.1.51", port: 5062,
transport: :udp, codecs: [:pcmu, :pcma, :amr, :amr_wb]]
]
SIP Listener Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
signaling_address | string | No | -- | IP address used in SIP Contact headers and SDP c= lines. Must be reachable by SIP peers. Falls back to the SCTP listener address if not set. |
listen_ip | tuple | No | {0, 0, 0, 0} | SIP listener bind address. |
listen_port | integer | No | 5060 | SIP listener port. |
transport | atom | No | :udp | Default transport protocol. One of :udp, :tcp, :tls. |
SIP Peer Parameters
Each peer in the peers list accepts the following:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | -- | Logical peer name. Referenced in route table entries with type :sip. |
address | string | Yes | -- | Peer IP address or hostname. |
port | integer | No | 5060 | Peer SIP port. |
transport | atom | No | :udp | Transport for this peer: :udp, :tcp, or :tls. |
codecs | list(atom) | No | [:pcmu, :pcma] | Supported audio codecs. Valid values: :pcmu, :pcma, :amr, :amr_wb. |
max_channels | integer | No | 100 | Maximum concurrent calls to this peer. New calls are rejected with max_channels_reached when the limit is hit. |
options_interval | integer or nil | No | nil | Interval in seconds for SIP OPTIONS keepalive probes. Peer status transitions to :down if OPTIONS responses cease. Set to nil to disable. |
For routing configuration that references these peers, see Routing Configuration. For SIP OPTIONS keepalive behavior and peer health states, see SIP Trunking.
MGCP / Media
config :omnimsc, :mgcp and config :omnimsc, :media
MGCP (Media Gateway Control Protocol, RFC 3435) is used to control media gateways for bearer path setup. The MSC acts as the MGCP Call Agent, issuing CRCX, MDCX, and DLCX commands to gateways. The :media key selects which media control protocol to use.
config :omnimsc, :mgcp,
listen_port: 2727,
gateways: [
%{name: "MGW-01", address: "10.1.1.50", port: 2427, domain: "mgw"}
]
config :omnimsc, :media,
gateway: "MGW-01",
mode: :mgcp
MGCP Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
listen_port | integer | No | 2727 | Local UDP port for the MGCP Call Agent (RFC 3435 Sec 2.2). Set to 0 to disable the MGCP transport (e.g., in test). |
gateways | list(map) | No | [] | List of managed media gateways. |
Gateway Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | -- | Logical gateway identifier used for lookups and control panel display. |
address | string | Yes | -- | IP address of the media gateway. |
port | integer | No | 2427 | MGCP port on the gateway. |
domain | string | Yes | -- | Gateway domain name used in endpoint naming (e.g., aaln/1@mgw). Required — there is no default. |
endpoints | list | No | [] | Pre-declared endpoint identifiers on the gateway. |
max_connections | integer | No | 1000 | Maximum concurrent connections the MSC will place on this gateway. |
Media Mode
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
gateway | string | No | "MGW-01" | Name of the default gateway (must match a gateway name from the MGCP or Megaco config). |
mode | atom | No | :megaco | Media control protocol: :mgcp for RFC 3435 or :megaco for ITU-T H.248. The compiled-in fallback when unset is :megaco; the shipped config.exs sets :mgcp explicitly. |
Megaco Transport
config :omnimsc, :megaco
Used when :media mode is :megaco (ITU-T H.248).
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
listen_port | integer | No | 2944 | Local UDP port for the Megaco/H.248 Media Gateway Controller. |
SMSc
config :omnimsc, :smsc
Configures the Short Message Service Centre address for MAP MT-ForwardSM and MO-ForwardSM operations.
config :omnimsc, :smsc,
address: "14155550300"
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
address | string | Yes | -- | SMSc Global Title (E.164 number) for MAP routing. |
CDR
config :omnimsc, :cdr
CDR records are generated per 3GPP TS 32.250 by the CDR Collector and written to files in ASN.1 BER format (3GPP TS 32.298) by the CDR Writer. File naming follows the pattern <NodeID>_<YYYYMMDD>_<HHMMSS>_<SeqNum>.dat.
config :omnimsc, :cdr,
output_dir: "/var/cdr/omnimsc",
max_file_size: 10_000_000,
max_records: 100_000,
rotation_interval: 3600
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
output_dir | string | Yes | "/tmp/omnimsc/cdr" | Directory for CDR output files. Must be writable by the BEAM process. Created automatically if it does not exist. |
max_file_size | integer | No | 10,000,000 | Maximum CDR file size in bytes (approximately 10 MB). A new file is created when this size is exceeded. |
max_records | integer | No | 100,000 | Maximum number of CDR records per file. |
rotation_interval | integer | No | 3600 | Time-based file rotation interval in seconds. A new CDR file is created after this period regardless of size or record count. |
Routes
config :omnimsc, :routes
Defines prefix-based routing rules that map dialed number prefixes to destinations. The route table uses longest-prefix match with priority as a tiebreaker.
config :omnimsc, :routes, [
%{prefix: "000", type: :sip, peer: "Default-GW", priority: 100},
%{prefix: "04", type: :local, priority: 50},
%{prefix: "02", type: :local, priority: 50},
%{prefix: "001", type: :sip, peer: "International-GW", priority: 10},
%{prefix: "", type: :sip, peer: "Default-GW", priority: 1}
]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
prefix | string | Yes | -- | Number prefix to match. Empty string "" acts as a catch-all default route. |
type | atom | Yes | -- | Destination type: :local, :sip, :isup, :transit, :gmsc, :sip_i, or :sip_with_failover. |
priority | integer | No | 10 | Route priority. Higher values take precedence when multiple routes match the same prefix. |
peer | string | Conditional | -- | SIP peer name (required when type is :sip, :sip_i, or :sip_with_failover). Must match a peer name from the SIP configuration. |
trunk_group | string | Conditional | -- | ISUP trunk group name (required when type is :isup). |
point_code | [integer, integer, integer] | Conditional | [0, 0, 0] | Destination point code for ISUP routing. |
cic_range | {integer, integer} | No | {1, 31} | Inclusive range of Circuit Identification Codes for ISUP trunks. |
transport | atom | No | :udp | SIP transport override for this route. |
Routes can also be managed at runtime via the REST API (POST /routes, DELETE /routes) and the Web UI. For detailed routing examples, see Routing Configuration.
MM Information
config :omnimsc, :mm_info
Controls the MM INFORMATION message sent to the mobile station after Location Update Accept (3GPP TS 24.008 section 9.2.15a). Contains the network name, time, and timezone.
config :omnimsc, :mm_info,
network_name: "Omnitouch",
short_name: "OT",
timezone_offset: 0
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
network_name | string | No | "Omnitouch" | Full network name displayed on the handset. Encoded in GSM 7-bit default alphabet (3GPP TS 24.008 10.5.3.5a). |
short_name | string or nil | No | nil | Short network name. Omitted from the MM INFORMATION message when nil. |
timezone_offset | integer | No | 0 | UTC offset in quarter-hours. For example, UTC+5:30 (India) is 22, UTC-5 (US Eastern) is -20. Encoded in BCD per 3GPP TS 24.008 10.5.3.8. |
MSC Pool
config :omnimsc, :pool
Configures MSC-in-Pool operation per 3GPP TS 23.236. Pool mode enables multiple MSC instances to share BSCs via A-Flex, providing load distribution and resilience.
config :omnimsc, :pool,
enabled: true,
pool_id: "POOL-01",
nri_bitlength: 10,
nri_values: [1, 2],
members: [
%{name: "MSC-02", nri_values: [3, 4], address: "10.1.1.2", port: 2905},
%{name: "MSC-03", nri_values: [5, 6], address: "10.1.1.3", port: 2905}
]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Whether to enable MSC pool operation. When false, the MSC operates in standalone mode. |
pool_id | string | Conditional | nil | Pool area identifier. Required when enabled is true. |
nri_bitlength | integer | No | 10 | Number of bits for the Network Resource Identifier field extracted from the TMSI. Must be identical across all pool members. |
nri_values | list(integer) | Conditional | [] | NRI values owned by this MSC instance. Must not overlap with other pool members. Required when enabled is true. |
null_nri | integer | No | 0 | NRI value indicating an unassigned TMSI. Triggers NRI-based re-routing to the correct pool member. |
members | list(map) | No | [] | Other MSC instances in the pool. Each member has name, nri_values, address, and port. |
For pool architecture and NRI bit layout details, see MSC Pool & NRI.
Overload
config :omnimsc, Omnimsc.Overload
Overload protection thresholds. When any threshold is exceeded, new service requests (calls, paging, Location Updates) are rejected with GSM cause 42 (switching equipment congestion). The admit?/0 function provides lock-free reads via persistent_term for minimal overhead in the hot path.
config :omnimsc, Omnimsc.Overload,
max_calls: 10_000,
max_subscribers: 50_000,
max_process_count: 500_000,
max_paging_rate: 1_000,
check_interval: 5_000
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
max_calls | integer | No | 10,000 | Maximum concurrent active calls before entering overload state. |
max_subscribers | integer | No | 50,000 | Maximum VLR registered subscribers before overload. |
max_process_count | integer | No | 500,000 | Maximum BEAM VM process count before overload. Monitors total VM process pressure. |
max_paging_rate | integer | No | 1,000 | Maximum paging requests per second before overload. |
check_interval | integer | No | 5,000 | Interval in milliseconds between overload threshold checks. |
Overload state transitions emit telemetry events [:omnimsc, :overload, :state_change] for external monitoring. See Metrics Reference.
SGs / CSFB
config :omnimsc, :sgs
Configures the SGs-AP interface for Circuit-Switched Fallback (CSFB) and SMS over SGs with LTE MMEs per 3GPP TS 29.118.
config :omnimsc, :sgs,
listen_port: 29118,
vlr_name: "vlr.omnimsc.local"
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
listen_port | integer | No | 29118 | SCTP listen port for SGs-AP connections from MMEs. Port 29118 is the 3GPP-assigned default. Set to 0 to disable SGs. |
vlr_name | string | No | "vlr.omnimsc.local" | VLR name (FQDN) sent to MMEs in SGs-AP Location Update Accept. The MME uses this to identify and route to this VLR instance. |
For SGs protocol details, association states, and CSFB call flows, see SGs / CSFB.
USSD
config :omnimsc, :ussd
Configures external USSD gateways for routing Unstructured Supplementary Service Data requests. Each gateway handles specific USSD service codes (e.g. *100# for balance). A gateway with codes: :all acts as the default fallback for unmatched codes.
config :omnimsc, :ussd,
gateways: [
%{name: "Balance", address: "14155550300", ssn: 147, codes: ["*100"]},
%{name: "Recharge", address: "14155550301", ssn: 147, codes: ["*123"]},
%{name: "Default", address: "14155550302", ssn: 147, codes: :all}
]
USSD Gateway Parameters
Each gateway in the gateways list accepts the following:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | No | "unnamed" | Logical gateway name for logging and control panel display. |
address | string | Yes | -- | Gateway Global Title (E.164 number) for MAP USSD routing. |
ssn | integer | No | 147 | SCCP Subsystem Number for the gateway. SSN 147 is the standard USSD SSN. |
codes | list(string) or :all | No | :all | USSD service codes handled by this gateway (e.g. ["*100", "*101"]). Set to :all for a catch-all default gateway. |
For USSD protocol details and relay behavior, see USSD.
Emergency
config :omnimsc, Omnimsc.Emergency
Configures emergency number detection, service category classification, and PSAP routing per 3GPP TS 22.101.
Emergency Setup messages (3GPP TS 24.008 §9.3.8) do not carry a Called Party BCD Number IE — unlike regular CC SETUP, the handset does not include the dialed digits. OmniMSC uses the configured psap_address as the called number for route table lookup and the outgoing SIP INVITE Request-URI. This value must match a prefix in the route table so that the call can be routed to the appropriate SIP peer or trunk.
config :omnimsc, Omnimsc.Emergency,
numbers: ["112", "911", "999", "000", "110", "119"],
psap_address: "000",
allow_without_sim: true
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
numbers | list(string) | No | ["112", "911", "999", "000", "110", "119"] | Recognized emergency numbers. Calls to these numbers bypass authentication, ciphering, and call barring. |
psap_address | string | No | "112" | Called number used for emergency call routing. Because Emergency Setup messages carry no called number, this value is used as the called party for route table lookup and the outgoing trunk (SIP INVITE Request-URI or ISUP IAM Called Party Number). Set this to a number that matches an emergency route prefix in the route table. |
allow_without_sim | boolean | No | true | Whether to allow emergency calls from mobile stations with no SIM inserted (IMSI absent). Per 3GPP TS 22.101, networks should permit this. |
Node & Runtime
Top-level config :omnimsc keys that control node identity and the supervision tree.
config :omnimsc,
node_id: "OMNIMSC01",
point_code: 500,
max_restarts: 3,
overload_monitor: true
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
node_id | string | No | "OMNIMSC01" | Node identifier used in CDR recording_entity, CDR filenames, and system status. |
point_code | integer | No | 500 | Local SS7 point code used as the CDR collector's local_msc_id. |
max_restarts | integer | No | 3 | Maximum restarts of the top-level supervisor within its restart window before the node shuts down. |
overload_monitor | boolean | No | true | Whether to start the periodic overload/process-count monitor. Set to false in test. |
Paging
config :omnimsc, :paging
Controls the paging retry behavior for mobile-terminated procedures.
config :omnimsc, :paging,
max_retries: 2,
retry_interval_ms: 5_000
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
max_retries | integer | No | 2 | Number of paging retransmissions before giving up on a mobile-terminated request. |
retry_interval_ms | integer | No | 5_000 | Interval in milliseconds between paging retransmissions. |
EIR
config :omnimsc, :eir
Configures Equipment Identity Register IMEI checking.
config :omnimsc, :eir,
enabled: false,
check_on: [:location_updating, :cm_service_request],
backend: Omnimsc.EIR.Backend.Default
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
enabled | boolean | No | false | Whether IMEI checking is performed. When false, all equipment is treated as white-listed. |
check_on | list(atom) | No | [:location_updating, :cm_service_request] | Procedures on which an IMEI check is triggered. |
backend | module | No | Omnimsc.EIR.Backend.Default | EIR backend module used to resolve IMEI status. |
Handover
config :omnimsc, :handover
Configures the Handover Number pool used for inter-MSC handover.
config :omnimsc, :handover,
ho_number_prefix: "8888",
ho_number_count: 100
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
ho_number_prefix | string | No | "8888" | Prefix for allocated Handover Numbers. |
ho_number_count | integer | No | 100 | Number of Handover Numbers in the allocation pool. |
SRVCC (Sv Interface)
config :omnimsc, :srvcc
Configures the Sv interface (SRVCC GTPv2-C) for Single Radio Voice Call Continuity.
config :omnimsc, :srvcc,
sv_enabled: false,
sv_port: 2123,
local_ip: {0, 0, 0, 0}
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
sv_enabled | boolean | No | false | Whether to start the SRVCC Sv (GTPv2-C) transport. |
sv_port | integer | No | 2123 | UDP port for the Sv interface. Port 2123 is the GTP-C default. |
local_ip | tuple | No | -- | Local bind IP for the Sv transport as an Erlang tuple. |
LCS
config :omnimsc, :lcs
Configures Location Services.
config :omnimsc, :lcs,
default_location: {0.0, 0.0}
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
default_location | {number, number} | No | {0.0, 0.0} | Fallback {latitude, longitude} in decimal degrees returned for a cell-based fix when no precise SMLC result is available. |
Security
config :omnimsc, :security
Configures authentication-failure barring.
config :omnimsc, :security,
auth_failure_threshold: 3
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
auth_failure_threshold | integer | No | 3 | Number of consecutive authentication failures after which a subscriber is barred. |
Routing (Number Analysis)
config :omnimsc, :routing
Configures number analysis for national/international prefix handling and emergency detection. This is distinct from the prefix-based route table (:routes).
config :omnimsc, :routing,
international_prefix: "00",
national_prefix: "0",
emergency_numbers: ["112", "911", "110"],
country_code: "",
area_code: "",
short_codes: []
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
international_prefix | string | No | "00" | Dialing prefix indicating an international number. |
national_prefix | string | No | "0" | Dialing prefix indicating a national (trunk) number. |
emergency_numbers | list(string) | No | ["112", "911", "110"] | Numbers classified as emergency by number analysis. |
country_code | string | No | "" | Country code prepended when normalizing national numbers to E.164. |
area_code | string | No | "" | Area code used when normalizing subscriber-local numbers. |
short_codes | list | No | [] | Short-code entries as {code, destination} tuples. |
SCCP
config :omnimsc, :sccp
config :omnimsc, :sccp,
local_subsystems: [7, 8]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
local_subsystems | list(integer) | No | [7, 8] | SCCP Subsystem Numbers that this node hosts locally (used by SCCP management for SSA/SSP handling). |
CAMEL
Top-level config :omnimsc keys for CAMEL (Customized Applications for Mobile networks Enhanced Logic) service triggering.
config :omnimsc, :camel_service_keys, %{}
config :omnimsc, :camel_default_scp_address, "14155550400"
config :omnimsc, :camel_timers, %{}
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
camel_service_keys | map | No | %{} | Map of CAMEL service keys to SCP addressing overrides. |
camel_default_scp_address | string | No | -- | Default gsmSCF (SCP) Global Title used when a service key has no explicit address. |
camel_timers | map | No | %{} | CAMEL timer overrides. |
VLR Reaper
config :omnimsc, :vlr_reaper
Configures the periodic reaper that purges stale VLR subscriber records.
config :omnimsc, :vlr_reaper,
scan_interval_ms: 60_000,
notify_hlr: true,
hlr: Omnimsc.VLR.HLR.Default
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
scan_interval_ms | integer | No | 60_000 | Interval in milliseconds between reaper scans for expired subscribers. |
notify_hlr | boolean | No | true | Whether to send MAP Purge MS to the HLR when a subscriber is reaped. |
hlr | module | No | Omnimsc.VLR.HLR.Default | HLR adapter used by the reaper to send Purge MS. |
SIP-I
config :omnimsc, :sip_i
Configures SIP-I peers (SIP with encapsulated ISUP, ITU-T Q.1912.5) for inter-MSC and PSTN interconnect.
config :omnimsc, :sip_i,
peers: [
%{name: "InterMSC-01", address: "10.1.1.60", port: 5060,
transport: :tcp, isup_version: :itu_t92,
trunk_group_id: "TG-InterMSC-01", point_code: [3, 14, 5],
codecs: [:pcmu, :pcma], max_channels: 100}
]
Each peer in the peers list accepts the following:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name | string | Yes | -- | Logical peer name. Referenced in route table entries with type :sip_i. |
address | string | Yes | -- | Peer IP address or hostname. |
port | integer | No | 5060 | Peer SIP port. |
transport | atom | No | :tcp | Transport for this peer: :udp, :tcp, or :tls. |
isup_version | atom | No | :itu_t92 | ISUP variant carried in the encapsulated body: :itu_t92 or :ansi. |
trunk_group_id | string or nil | No | -- | Trunk group identifier used for routing (e.g. "TG-InterMSC-01"). |
point_code | [integer, integer, integer] or integer or nil | No | -- | Remote SS7 point code for the ISUP routing context. |
codecs | list(atom) | No | [:pcmu, :pcma] | Supported audio codecs. |
max_channels | integer | No | 100 | Maximum concurrent calls to this peer. |
Web UI
config :omnimsc, OmnimscWeb.Endpoint
The web control panel is served by a Phoenix endpoint with LiveView. It provides real-time dashboards for subscribers, calls, connections, routing, and alarms.
config :omnimsc, OmnimscWeb.Endpoint,
http: [ip: {0, 0, 0, 0}, port: 4000],
url: [host: "localhost"],
secret_key_base: "generate-with-mix-phx-gen-secret",
server: true,
pubsub_server: Omnimsc.PubSub,
live_view: [signing_salt: "oMnImScLv"]
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
http.ip | tuple | No | {0, 0, 0, 0} | HTTP bind address. Use {127, 0, 0, 1} to restrict to localhost. |
http.port | integer | No | 4000 | HTTP listen port for the control panel. |
url.host | string | No | "localhost" | Hostname for URL generation. Set to the public hostname in production. |
secret_key_base | string | Yes | -- | Phoenix session signing key. Generate with mix phx.gen.secret. Required in production (read from SECRET_KEY_BASE environment variable). |
server | boolean | No | true | Whether to start the HTTP server. Set to false to disable the control panel. |
check_origin | boolean | No | true (prod) | Whether to check WebSocket origin headers. Set to false in development. |
pubsub_server | atom | No | Omnimsc.PubSub | PubSub server name for LiveView broadcasts. |
live_view.signing_salt | string | No | "oMnImScLv" | LiveView session signing salt. |
Runtime override: Set SECRET_KEY_BASE, PHX_HOST, and PORT environment variables. In production, HTTPS with port 443 is configured automatically.
REST API
config :api_ex
The REST API is served by api_ex on a separate port, providing programmatic access to subscribers, calls, routes, SIP peers, connections, and system health.
config :api_ex,
api: %{
port: 8444,
listen_ip: "0.0.0.0",
product_name: "Omnitouch MSC",
title: "API - Omnitouch MSC",
hostname: "localhost",
enable_tls: false
}
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
port | integer | No | 8444 | HTTP listen port for the REST API. |
listen_ip | string | No | "0.0.0.0" | Bind IP address for the API listener. |
product_name | string | No | "Omnitouch MSC" | Product name displayed in the Swagger UI. |
title | string | No | "API - Omnitouch MSC" | Page title for the Swagger UI. |
hostname | string | No | "localhost" | Hostname for API URL generation. |
enable_tls | boolean | No | false | Whether to enable TLS for the API endpoint. |
Available API Endpoints
| Path | Methods | Description |
|---|---|---|
GET /subscribers | GET, DELETE | List or remove VLR subscribers. |
POST /subscribers/:id/actions | POST | Trigger subscriber actions (paging, detach). |
GET /calls | GET, DELETE | List or release active calls. |
GET /sms | GET | List SMS transactions. |
GET /routes | GET, POST, DELETE | Manage the route table. |
GET /routes/lookup | GET | Look up a route by dialed number. |
GET /sip/peers | GET, PATCH | List or update SIP peer configuration. |
GET /mgw | GET | List media gateway status. |
GET /ran/connections | GET | List active RAN (A-interface) connections. |
GET /ran/bscs | GET | List connected BSCs. |
GET /stp | GET | Show STP connection status. |
GET /health | GET | System health check. |
GET /status | GET | System status summary. |
POST /paging | POST | Trigger a paging request. |
POST /silent | POST | Initiate a silent call or silent SMS. |
Complete Production Configuration Example
# config/runtime.exs
import Config
config :omnimsc, :msc,
point_code: 500,
global_title: "14155550100",
name: "OMNIMSC01",
msc_number: "14155550100",
vlr_number: "14155550100",
mcc: 999,
mnc: 99,
lac: 0x1092,
allowed_a5: [:a5_1, :a5_3]
config :omnimsc, :hlr,
address: "14155550200",
point_code: [3, 14, 2]
config :omnimsc, :vlr,
hlr_adapter: Omnimsc.VLR.HLR.Live,
auth_required: true,
tmsi_realloc: true,
num_auth_vectors: 1
config :omnimsc, :m3ua_asp,
enabled: true,
local_ip: {10, 5, 198, 200},
local_port: 0,
remote_ip: {10, 179, 4, 10},
remote_port: 2905,
routing_context: 10,
receive_watchdog: true,
receive_watchdog_idle: 15
config :omnimsc, :sip,
signaling_address: "10.5.198.200",
listen_ip: {0, 0, 0, 0},
listen_port: 5060,
transport: :udp,
peers: [
[name: "Default-GW", address: "10.1.1.50", port: 5060,
transport: :udp, codecs: [:pcmu, :pcma],
max_channels: 100, options_interval: 60],
[name: "International-GW", address: "10.1.1.51", port: 5062,
transport: :udp, codecs: [:pcmu, :pcma, :amr, :amr_wb],
max_channels: 500]
]
config :omnimsc, :mgcp,
listen_port: 2727,
gateways: [
%{name: "MGW-01", address: "10.1.1.50", port: 2427, domain: "mgw"}
]
config :omnimsc, :media,
gateway: "MGW-01",
mode: :mgcp
config :omnimsc, :smsc,
address: "14155550300"
config :omnimsc, :cdr,
output_dir: "/var/cdr/omnimsc",
max_file_size: 10_000_000,
max_records: 100_000,
rotation_interval: 3600
config :omnimsc, :routes, [
%{prefix: "000", type: :sip, peer: "Default-GW", priority: 100},
%{prefix: "04", type: :local, priority: 50},
%{prefix: "02", type: :local, priority: 50},
%{prefix: "001", type: :sip, peer: "International-GW", priority: 10},
%{prefix: "", type: :sip, peer: "Default-GW", priority: 1}
]
config :omnimsc, :mm_info,
network_name: "Omnitouch",
short_name: "OT",
timezone_offset: 0
config :omnimsc, Omnimsc.Overload,
max_calls: 10_000,
max_subscribers: 50_000,
max_process_count: 500_000,
max_paging_rate: 1_000,
check_interval: 5_000
config :omnimsc, Omnimsc.Emergency,
numbers: ["112", "911", "999", "000", "110", "119"],
psap_address: "000",
allow_without_sim: true
config :omnimsc, :sgs,
listen_port: 29118,
vlr_name: "vlr.omnimsc.local"
config :omnimsc, :ussd,
gateways: []
config :omnimsc, :pool,
enabled: false