The Dialogic® DSI M3UA module is a software implementation of the IETF SIGTRAN, SS7 MTP3 User Adaptation Layer (M3UA). This Programmer's Manual is intended for users choosing to develop their own application programs that will interface with and use the functionality provided by the M3UA module.
Function Description:
The M3UA module uses the services provided by the Stream Control Transmission Protocol (SCTP) to exchange signaling messages with M3UA Signaling Gateway Processes (SGP), M3UA Application Server Processes (ASP), or M3UA IP Signaling Processes (IPSP). It can be used as part of an ASP or IPSP system. The M3UA module is part of the Dialogic® DSI Signaling Protocol product range and is implemented in a similar message-based, event-driven manner to the other protocols in the product range. It is intended to be used in conjunction with other DSI Signaling Protocols SCTP, ISUP, and SCCP, either as part of a pre-integrated systems product or integrated with third-party applications and hardware. The well-defined message interface allows the M3UA module to be used with alternative implementations if required.
The manual provides an overview of the internal operation of the M3UA module and defines the message-based APIs for configuration, management, and applications to use.
Key features of the M3UA module include:
- Implementation of IETF MTP3 User Adaptation Layer RFC 3332 and RFC 4666 [1].
- Message-based interface common with other Dialogic® DSI Signaling Protocols.
- May be used as part of an ASP or IPSP.
- May be used as part of a single Local AS or can support Multiple Local AS.
- Fully automatic or full user control of ASP / AS Activation as required.
- Supports Single Exchange Activation.
- Supports 14, 16, and 24-bit Point Codes.
- Supports MTP3 User interface to route messages based on DPC.
- Load-shares across two Signaling Gateways (STPs).
- Load-shares across ASPs within a RAS and SGPs within an SG.
- Load-shares across multiple streams within an SCTP Association.
- Buffers messages while rerouting.
- Supports connections to multiple peer ASs.
- Diagnostic tracing of messages exchanged with SCTP and MTP3 User.
- Supports SNMP for Links, RAS, and Routes.
- Supports Routing Key Management procedures in ASP mode.
Important Technical Specifications:
The M3UA module implements the SS7 MTP3-User Adaptation Layer as defined in the IETF RFC 4666. The module interface is message-based. It reads messages from a single message input queue and sends responses and indications to the message input queues of other modules in the system. The M3UA module interfaces with SCTP using the User Primitives defined in the Dialogic© DSI SCTP Programmer's Manual.
Throughput Monitoring:
The M3UA license model allows specific data throughput rates to be used. The available M3UA licenses and their capabilities are detailed in a table, showing throughput in kilobits per second, maximum associations, and TDM Link Equivalents. For example, licenses range from 312kb/s (4 associations, 4 TDM links) to 78,648kb/s (384 associations, 1024 TDM links). This comparison assumes the use of 64kb/s links at a maximum loading of 0.6 Erlang. Individual user deployments may exhibit different characteristics, requiring capacity adjustments.
When the module starts, it reads its license to determine the exact data rate it can use. M3UA provides mechanisms for good visibility and control of the system:
- Read current rate and read peak rate: M3UA supports message type MGT_MSG_R_LIC_STATUS, which returns licensing information including the licensed data rate in Kbytes/s. It also supports MGT_MSG_R_THR_STATS, which returns the maximum throughput experienced since the last Restart or Stats Reset, and reports total Data transmitted and received. These messages help users see average and peak throughputs and the proportion of system capacity being used.
- Notification when license limit exceeded: If the system exceeds its licensed limit, a warning indication (MGT_MSG_LIC_EVENT) is issued, allowing the user to throttle the throughput. If the rate continues to exceed the limit, M3UA will indicate it is throttling. Once the rate abates, another MGT_MSG_LIC_EVENT indication is sent. These indications enable dynamic throttling by the Customer Application.
- Notification when 80% of license limit exceeded: An additional MGT_MSG_LIC_EVENT is generated when peak throughput exceeds 80% of the licensed limit. This helps administrators identify systems nearing their rated throughput, potentially requiring a license upgrade. This alarm persists until throughput drops below 40% of the licensed limit.
Load Sharing:
M3UA data messages from a User Part for transmission are formatted with the MTP3 Routing Label, which includes the Signaling Link Selector (SLS). The SS7 network uses SLS for load sharing, and M3UA also uses it. Messages from MTP3 Users are expected to have an approximately even distribution of SLS values.
When transmitting messages to the SS7 network via Signaling Gateways, M3UA performs the following load sharing steps:
- Select between two Signaling Gateways using the highest bit in the SLS.
- Select between up to sixteen SGPs in the SG using the SLS bits.
- Select an SCTP Stream in the Association using the lowest bits in the SLS.
When transmitting messages to an IPSP system configured for load share mode, the following steps are taken:
- Select between up to sixteen ASPs in the RAS using the SLS bits.
- Select an SCTP Stream in the Association using the lowest bits in the SLS.
Dual Resilient Systems:
Details on configuring and using M3UA in a Dual Resilient system can be found in [6] Enabling Dual-Chassis Fault Tolerance with Dialogic® SIGTRAN Protocols, available from the Dialogic Web Site.
Usage Features:
Module Configuration:
The Configuration interface uses the same message passing environment as the User and Management API. Each configuration message instantiates a new element and sets its parameters, including a logical ID. Referenced elements must be configured first. The first message sent to the module must be M3U_MSG_CONFIG, which configures SCTP module location and where to send maintenance and management messages. Lower layer protocols (e.g., SCTP) should be configured before M3UA, ISUP, or SCCP.
System Activation:
After configuration, system associations and servers must be brought into service. This is achieved by sending an M3U_MSG_ACTIVATE request for each association. M3UA will then:
- Activate the association.
- Wait for the association to come into service (indicated by M3U_MSG_ASS_STATUS_IND).
- Send an ASP UP Request to the peer SGP or IPSP.
- Wait for an ASP UP Acknowledgement or retransmit (indicated by M3U_MSG_ASP_UP_CON or M3U_MSG_ASP_UP_IND).
- Optionally perform RKM REG_REQ and handle REG_RSP (ASP only).
- Send an ASP Activate Request to the peer SGP or IPSP.
- Wait for an ASP Active Acknowledgement or retransmit (indicated by M3U_MSG_ASP_ACT_CON or M3U_MSG_ASP_UP_IND).
- The Association is now ready for SS7 messages.
If M3U_MSG_ACTIVATE is used, M3UA automatically reactivates the association if it fails. For manual activation, users can activate the association (M3U_MSG_ACT_ASSOC), wait for it to come into service, send an ASP UP Request (M3U_MSG_ASP_UP_REQ), wait for acknowledgement, and then send an ASP Activate Request (M3U_MSG_ASP_ACT_REQ). If RKM is configured, a RKM REG_REQ will be initiated. Manual activation can pause indefinitely until M3UA is notified of dual partner unit availability. Options are available on ASP UP and ASP Activate request messages for automatic return to previous activation state after network failure. Associations can be deactivated using M3U_MSG_DEACTIVATE.
Configuration Model:
- System Configuration: M3UA operates in a message passing environment with parameters controlling inter-module communication. M3U_MSG_CONFIG sets essential parameters. M3UA uses timers with default values, which can be changed via M3U_MSG_CNF_TIMERS.
- Local Application Server (LAS): At least one Local AS must be defined using M3U_MSG_CNF_NC, mapping a Network Context directly to a Local AS. Four Network Contexts (0-3) are supported, each with a different point code format for routing label decoding and encoding.
- Association: M3UA uses SCTP Associations for transport to peer M3UA Nodes. An association configuration message (M3U_MSG_CNF_ASSOC) is required for each association, detailing SCTP Association ID, and whether local/remote nodes are Signaling Gateways or Application Hosts. SCTP provides reliable sequenced delivery for telecoms signaling. An Application Host may connect to multiple Signaling Gateways or peer application hosts. Each SCTP association must be established, and M3UA peers must start communication with ASP UP and ASP UP Ack messages. If the peer uses the optional Network Appearance parameter, M3UA requires M3U_MSG_MAP_NA for each association.
- Server: A Server is a logical entity controlling SS7 traffic routing between a Signaling Gateway and an SS7 Point Code, or between two different SS7 Point Codes for IPSPs. Once M3UA peers establish communication, Application End Points and Signaling Gateways indicate readiness for SS7 Data traffic by sending/receiving ACTIVE requests. An active Server allows M3UA peers to send/receive SS7 traffic. A Server relationship is configured between a LAS and a remote server. Each Signaling Gateway or Remote Point Code requires a unique Server relationship. A Server relationship can use multiple Associations, mapped via a separate configuration message that specifies the Routing Context.
- Routes: A Route maintains the availability status of a remote Point Code in the SS7 network via one or more Signaling Gateways. Each LAS connecting to Signaling Gateways requires Route configuration for each Remote Signaling Point Code. Route configuration uses two message types: one to declare a new Remote Point Code for a LAS, and one to add a Signaling Gateway to the list of Signaling Gateways. LAS automatically synchronize Route State with Signaling Gateways and generate PAUSE and RESUME primitive indications to User Parts.
Example Message Sequence:
The manual includes an example message sequence for a single SG and ASP connection, illustrating the flow of configuration, association, and data messages between User Application, Management, M3UA, and SGW/ASP.
Message Reference:
The user interface is a superset of MTP3 User interface messages, using MTP3 Routing Label information.
- API_MSG_TX_REQ (0xcf00): Sent by User Part to M3UA for Message Transfer Request service. Contains MSU data in binary format with Service Indicator Octet (SIO) and Routing Label.
- API_MSG_RX_IND (0x8f01): Sent by M3UA to User Part indicating reception of a Message Signal Unit. Contains MTP label format (14, 16, or 24-bit point codes) and MSU data.
- MTP_MSG_PAUSE (0x8403): Sent by M3UA to User Part indicating inability to provide MTP service to a specified destination.
- MTP_MSG_RESUME (0x8404): Sent by M3UA to User Part indicating ability to provide MTP service to a specified destination.
- MTP_MSG_STATUS (0x8405): Sent by M3UA to User Part indicating partial inability or change in network congestion level for a specified destination.
Management Interface:
Primitives at the M3UA / management interface are message-based. M3UA sends primitives to the management module specified in M3U_MSG_CONFIG. If rsp_req is set, M3UA confirms receipt by sending the message back with the REQUEST bit cleared. M3UA returns confirmation messages with status values like NONE (success), M3UE_BAD_ID, M3UE_BAD_MSG, M3UE_BAD_PARAM, M3UE_BAD_TYPE, or M3UE_LIC_ERR.
Specific Management Messages:
- ASP UP Request (M3U_MSG_ASP_UP_REQ, 0x72d4): Initiates ASP UP procedures.
- ASP DOWN Request (M3U_MSG_ASP_DOWN_REQ, 0x72d7): Initiates ASP DOWN procedures.
- ASP ACT Request (M3U_MSG_ASP_ACT_REQ, 0x72da): Initiates AS Activation procedures for an association.
- ASP INACT Request (M3U_MSG_ASP_INACT_REQ, 0x72dd): Initiates AS Deactivation procedures for an association.
- SS7 Signaling Network Management Event Request (M3U_MSG_SSNM_EVENT, 0xc2e5): Requests transmission of DAVA, DUNA, DAUD, or DRST messages.
- SS7 Network Congestion State (M3U_MSG_SSNM_SCON, 0xc2e6): Causes M3UA to generate an SS7 network congestion state message.
- Activate Association (M3U_MSG_ACT_ASSOC, 0x72ce): Activates an SCTP association.
- Deactivate Association (M3U_MSG_DEACT_ASSOC, 0x72cf): Deactivates an SCTP association.
- M3U_MSG_ACTIVATE Request (0x72f5): One-shot message to activate an Association, ASP UP, and AS, setting AUTO Activate options.
- M3U_MSG_DEACTIVATE Request (0x72f8): One-shot message to deactivate an SCTP association and clear AUTO Activate flags.
- ASP UP Indication (M3U_MSG_ASP_UP_IND, 0x02d5): Indicates peer ASP is UP.
- ASP UP Confirmation (M3U_MSG_ASP_UP_CON, 0x02d6): ASP Up confirmation received.
- ASP DOWN Indication (M3U_MSG_ASP_DOWN_IND, 0x02d8): Peer ASP is DOWN.
- ASP DOWN Confirmation (M3U_MSG_ASP_DOWN_CON, 0x02d9): Peer ASP has confirmed local M3UA is DOWN.
- ASP ACT Indication (M3U_MSG_ASP_ACT_IND, 0x02db): Peer has asked for an ASP to become active.
- ASP ACT Confirmation (M3U_MSG_ASP_ACT_CON, 0x02dc): Peer has responded to request for Application server process to be made active.
- ASP INACT Indication (M3U_MSG_ASP_INACT_IND, 0x02de): Peer has asked for an Application Server process to be made inactive.
- ASP INACT Confirmation (M3U_MSG_ASP_INACT_CON, 0x02df): Peer has responded to request for Application Server process to be made inactive.
- AS ACT Indication (M3U_MSG_AS_ACT_IND, 0x02e0): Indicates a relationship with a Remote Application server has become active.
- AS INACT Indication (M3U_MSG_AS_INACT_IND, 0x02e1): Indicates an Application server has become inactive.
- Association Status Indication (M3U_MSG_ASS_STATUS_IND, 0x02e2): Indicates a change in Association status (deactivated, up, down, congestion abate/onset/discard).
- Route Status Indication (M3U_MSG_ROUTE_STATUS_IND, 0x02e3): Indicates status/congestion level of a Route (unavailable, available, restricted).
- Routing Key Registration Indication (M3U_MSG_RK_REG_IND, 0x02b0): Indicates an attempt to register a routing key.
- RK Deregistration Indication (M3U_MSG_RK_DEREG_IND, 0x02b1): Indicates an attempt to deregister a routing key.
Non-primitive Interface Messages:
- Configure M3UA Module (M3U_MSG_CONFIG, 0x72c0): Configures global parameters like module IDs for Management, Trace, Maintenance, and maximum associations, servers, routes, and throughput.
func_options enable IPSP/SGW functionality and fine-tune load-sharing behavior.
- Configure M3UA Association (M3U_MSG_CNF_ASSOC, 0x72c1): Configures an association with an IPSP or SG, including SCTP Association ID, instance number, module ID, default network context, and optional ASP ID. Options include SGP to ASP, ASP to SGP, ASP to ASP (IPSP), RSP Status messages, default Network Context presence, ASP ID presence, auto-activate, Heartbeats, SNMP indications, and ignoring Network Appearance.
- Configure LAS-Server Relationship (M3U_MSG_CNF_SERVER, 0x72c2): Configures a new relationship between a Local AS and a remote server entity (SG or RAS). Options include peer AS, host AS, AS Status messages, SPMC all, multiple users, DAUD messages, SNMP, use RX SERV, and RKM enable. Also defines default and permitted traffic modes (override, loadshare, broadcast), number of ASPs, user part module IDs, and local traffic mode.
- Configure M3UA Route (M3U_MSG_CNF_ROUTE, 0x72c3): Configures a Destination Point Code for routing messages. Options include assume available, loadshare, default route, and SNMP indications.
- Configure Network Context (M3U_MSG_CNF_NC, 0x72c4): Declares a new Network Context with Point Code format and options. Each NC maps 1:1 to a Local AS. Options include SLS bit rotation (8-bit for ANSI), and using Local AS OPC for outgoing traffic.
- Configure Routing Key (M3U_MSG_CNF_RK, 0x72fe): Configures Routing Key parameters for registration with a remote SG. Not supported for RAS (IPSP mode). Options include OPC presence, CICs range presence, and Service Indicator presence.
- Add Server to an Association (M3U_MSG_ADD_SERV_ASSOC, 0x72c5): Associates a LAS-Server relationship with an Association.
- Add Route to a Server (M3U_MSG_ADD_ROUTE_SERV, 0x72c6): Identifies an SG that a configured Route may use to forward messages.
- Map Network Context to Network Appearance (M3U_MSG_MAP_NA, 0x72c7): Creates a mapping between Network Context and M3UA Network Appearance for an Association.
- M3UA Timer Configuration Message (M3U_MSG_CNF_TIMERS, 0x72fc): Configures M3UA timer values (Ack, Recovery, Daud, Heartbeat, Daud_cong).
- Remove M3UA Association (M3U_MSG_REM_ASSOC, 0x72c8): Removes an association configuration.
- Remove LAS-Server Relationship (M3U_MSG_REM_SERVER, 0x72c9): Removes a LAS-Server relationship configuration.
- Remove M3UA Route (M3U_MSG_REM_ROUTE, 0x72ca): Removes a route configuration.
- Remove Network Context (M3U_MSG_REM_NC, 0x72f1): Removes a Network Context and its associated Point Code format.
- Remove Routing Key (M3U_MSG_REM_RK, 0x72ff): Removes an existing routing key.
- Remove Server from an Association (M3U_MSG_REM_SERV_ASSOC, 0x72cb): Removes a Server from an Association.
- Remove Route from a Server (M3U_MSG_REM_ROUTE_SERV, 0x72cc): Removes an SG from a Route.
- Remove Network Context to Network Appearance Mapping (M3U_MSG_UNMAP_NA, 0x72cd): Removes the mapping between Network Context and Network Appearance.
- Read Global Traffic Statistics (M3U_MSG_R_GL_STATS, 0x62b2): Retrieves global high-level traffic measurements (rx_octets, rx_msu, tx_octets, tx_msu).
- Read Association Traffic Statistics (M3U_MSG_R_LK_STATS, 0x62b3): Retrieves per-association traffic measurements (rx_octets, rx_msu, tx_octets, tx_msu, oos_count, oos_duration).
- Read Global Peak Usage Statistics (M3U_MSG_R_GL_PEAK_USAGE, 0x62b4): Retrieves global peak usage measurements for the M3UA module (rxoct_5min, rxoct_1hour, rxoct_1day, rxmsu_5min, rxmsu_1hour, rxmsu_1day, txoct_5min, txoct_1hour, txoct_1day, txmsu_5min, txmsu_1hour, txmsu_1day).
- Read Association Peak Usage Statistics (M3U_MSG_R_LK_PEAK_USAGE, 0x62b5): Retrieves peak usage measurements for a specific association.
- Read Association Statistics (M3U_MSG_R_ASSOC_STATS, 0x62d0): Retrieves statistics kept on a per-association basis (data_tx, asp_up_tx, asp_up_ack_tx, asp_dn_tx, asp_dn_ack_tx, asp_ac_tx, asp_ac_ack_tx, asp_ia_tx, asp_ia_ack_tx, error_tx, notify_tx, duna_tx, dava_tx, daud_tx, scon_tx, dupu_tx, drst_tx, beat_tx, beat_act_tx, data_rx, asp_up_rx, asp_up_ack_rx, asp_dn_rx, asp_dn_ack_rx, asp_ac_rx, asp_ac_ack_rx, asp_ia_rx, asp_ia_ack_rx, error_rx, notify_rx, duna_rx, dava_rx, daud_rx, scon_rx, dupu_rx, drst_rx, beat_rx, beat_ack_rx, period, beat_failure).
- Read Server Statistics (M3U_MSG_R_SERVER_STATS, 0x62d1): Retrieves statistics for a specific Server (data_tx, period).
- Read Route Statistics (M3U_MSG_R_ROUTE_STATS, 0x62d2): Retrieves statistics for a specific Route (data_tx, period).
- Trace Mask Configuration Request (M3U_MSG_TRACE_MASK, 0x52d3): Configures M3UA to trace specified messages and events using
op_evt_mask (output events) and ip_evt_mask (input events).
- M3UA Application Server Process Status (M3U_MSG_R_RSP_STATUS, 0x62e8): Returns the current status of the specified ASP / SGP (unconfigured, deactivated, unavailable, wait up, available, wait closed).
- M3UA Server Status (M3U_MSG_R_RS_STATUS, 0x62e9): Returns the status of the specified RAS or SG relationship, including overall status and status on a specific ASP or SGP (unconfigured, unavailable, available, available insufficient RSP). Also returns traffic mode.
- M3UA Route Status (M3U_MSG_R_ROUTE_STATUS, 0x62ea): Returns the current overall status of the specified route (unavailable, available, restricted).
- M3UA Error Indication (M3U_MSG_M3U_ERROR, 0x02ef): Indicates a software error or protocol event to management, with
error_id, instance, err_val1, and err_val2. Error types include bad state, config, resource, timer tick, LMSG alloc, and MSG FMT.
- M3UA Event Indication (M3U_MSG_M3U_EVENT, 0x02ee): Signals an internal event warning to management, including M3UA protocol violations, M3UA ERROR message reception, and Heartbeat failures.
- M3UA Notify Indication (M3U_MSG_NOTIFY_IND, 0x02f0): Indicates a change in state of a peer server, with
status_type (Application Server State Change, Other) and status_info (Inactive, Active, Pending, Insufficient ASP Resources Active, Alternate ASP Active).
- M3UA Audit Destination Indication (M3U_MSG_AUDIT_DEST_IND, 0x02f3): Indicates the peer requires an update of the status of a destination point code.
- MTP Update Level 4 Request (MTP_MSG_UPDATE_L4, 0x731f): Requests a broadcast of current route status to all local user parts for a specified destination.
Maintenance Features:
- Throughput Alarm Set (MGT_MSG_SET_THR_ALARM, 0x5f27): Sets throughput alarm thresholds. The
Onset threshold defines the percentage of licensed throughput at which the alarm triggers (default 80%). The Abate threshold defines the percentage at which the alarm abates (default 40%). These alarms provide early warning of nearing maximum capacity, potentially requiring a larger license.
- License Event Indication (MGT_MSG_LIC_EVENT, 0x0f23): Sent from M3UA to Layer Management to indicate license-related events, including throughput congestion onset, abatement, or enforcement.
- Request Licensing State (MGT_MSG_R_LIC_STATUS, 0x6f22): Requests the current license state, including version, licensed protocol, throughput rate, links, sessions, options, configured values, current throughput credit, active links/sessions, congestion state, and throughput alarm state.
The M3UA module provides comprehensive configuration, management, and diagnostic tools to ensure reliable and efficient operation within a signaling network.
Need help?
To Next Page
General