pMINK MNO
Project MINK framework + Mobile Network Operator Compoents
-
Core components
-
Mobile Network Operator components
R14P protocol library
R14P is a stateful stream based application layer protocol used for data communication between various pMINK nodes. It is defined using ASN.1 syntax notation and carried by wire in binary Basic Encoding Rules (BER) format. At the moment, R14P uses SCTP for reliable data transfer, although it can be easily ported to TCP. Correct order of packets and statefulness is maintained by both SCTP and R14P to ensure maximum quality of packet delivery.
The overall design of the protocol was influenced by TCAP but with various enhancements and differences. R14P supports label based application layer routing; every end-point is defined by a two part string label. The first part, named id, is a unique pMINK node identifier string, similar to IP address of a machine. The second part is a type string, used mainly for grouping of various nodes for redundancy and load balancing purposes. pMINK framework comes with a specialized node called Routing daemon (routingd) which is used mainly for R14P label-based routing and Weighted round robin (WRR) load balancing.
All R14P messages consist of two basic parts; a Header and a Body. Header is mandatory and is handled by the libr14p library and mostly not used by the end-user. The body of the message is where the actual data resides; there are many different types of message bodies and most of them are specialized and used internally by pMINK framework. User generated data is transferred in a ServiceMessage body; every service message stream contains a user defined service-id value used for data classification.
-- ============
-- R14P Message
-- ============
-- header - packet header
-- body - packet body
R14PMessage ::= SEQUENCE {
header Header,
body Body OPTIONAL,
...
}
-- ===========
-- R14P Header
-- ===========
-- version - R14P version
-- source - source information
-- destination - destination information
-- uuid - universally unique identifier (UUID)
-- sequence-num - sequence number
-- sequence-flag - packet sequence information (stateful/stateless/etc.)
-- enc-info - encryption information
-- hop-info - hop counter
-- status - error code
Header ::= SEQUENCE {
version [0] INTEGER,
source [1] EndPointDescriptor,
destination [2] EndPointDescriptor,
uuid [3] OCTET STRING,
sequence-num [4] INTEGER,
sequence-flag [5] SequenceFlag,
enc-info [6] EncryptionInfo OPTIONAL,
hop-info [7] HopInfo OPTIONAL,
status [8] ErrorCode OPTIONAL,
...
}
-- =========
-- R14P Body
-- =========
-- encrypted-data - Encrypted R14P body, used only when content is encrypted (header.encryption)
-- packet-fwd - General packet forwarding, used for routing and failovers
-- filter - Filtering service, mostly used but not limited to SMS
-- data-retention - Data retention service, used for DB storage
-- general - Reserved for custom daemons and/or future use
-- conf - Configuration daemon service
-- stats - Statistical data exchange
-- auth - Authentication messages, used for daemon authentication
-- reg - Registration messages, used for daemon discovery and various
-- registration procedures
-- ntfy - Various notification/alarm/etc. messages
-- data - payload data exchange
-- routing - routing related messages
-- service-msg - service related messages
-- state-msg - statefulness related messages
Body ::= CHOICE {
encrypted-data [1] OCTET STRING,
packet-fwd [2] PacketFwdMessage,
filter [3] FilterMessage,
data-retention [4] DataRetentionMessage,
conf [6] ConfigMessage,
stats [7] StatsMessage,
auth [8] AuthMessage,
reg [9] RegistrationMessage,
ntfy [10] NotifyMessage,
data [11] DataMessage,
routing [12] RoutingMessage,
service-msg [13] ServiceMessage,
state-msg [14] StateMessage,
...
}
Configuration parser library
pMINK Configuration parser library is a core component used primarily by Configuration daemon (configd). When designing a system on top of pMINK framework, configuration definition is always a good starting point. There are two types of configuration files used by configd; definition and contents.
Definition file is used to describe the structure of data stored in the contents file. Proper definition ensures data
integrity and avoids unnecessary implementations of custom data validators in user specific daemons. Both types
of configuration files share a similar structure and are parsed using the same grammar. Default extension for pMINK
configuration files is .pmink; a standard naming convention used in this project is to add a _def suffix to
base name of definition file (e.g. pmink_def.pmcfg for definition and pmink.pmcfg for contents).
The following example shows a simple configuration showing 3 main types of configuration items:
- primitive
- single field container whose type is defined in the TYPES section of configuration definition file
- block
- a storage container similar to a file system directory, defined with CONST keyword and used mostly for grouping
- dynamic block
- special storage container identified by a "*" (star) symbol; serves a purpose of being a template node for dynamic creation of block nodes
Configuration definition "pmink_def.pmcfg"
// data types
TYPES {
// each type is defined by perl-type regex
"INT" PTRN\d+PTRN "Number type"
"STRING" PTRN.*PTRN "Alphanumeric type"
}
// config structure
CONFIG {
// global parameter
test_global "INT" "Global INT parameter"
// static sub node
local CONST "Local group" {
test_local "INT" "Local INT parameter"
}
// dynamic nodes
dynamic CONST "Dynamic container node" {
dynamic_child * "STRING" "Dynamic child node" {
test "INT" "Test INT parameter"
}
}
}Configuration contents "pmink.pmcfg"
test_global "10"
local {
test_local "666"
}
dynamic {
node_1 {
test "10"
}
node_2 {
test "20"
}
}Configuration daemon
Configuration daemon is a pMINK daemon used for configuration management and is a central most important service of this framework. These are the main features of configd:
- configuration file management
- replication of configuration data
- ACID like properties for configuration transactions (COMMIT/DISCARD/ROLLBACK)
- real-time distribution of configuration data to all affected daemons
- each pMINK daemon attaches itself to its own subset of configuration nodes; smart configuration definition will play a vital role in minimizing bandwith usage for configuration data
- when configuration data is changed in some way (using pMINK Command Line Interface), all connected daemons that are affected with that particular modification, are notified
- configuration data can grow quite a bit and is therefore advised for each daemon to attach itself to its own subset of configuration defintion (e.g. STP daemon should not get any configuration data related to R14P routing)
configd command line arguments
config_daemon - pMINK Configuration daemon
Copyright (c) 2012 Release14.org
Options:
-? help
-i unique daemon id
-p R14P inbound port
-d configuration definition file
-c configuration contents file
-r routing daemon address (ipv4:port)
-n other config daemon id
-t user timeout in seconds
-D debug mode
-R enable routing
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 1000)
--r14p-stimeout R14P Stream timeout in seconds (default = 5configd example
$ ./configd -i cfg1 -p 10000 -d /tmp/test_def.pmcfg -c /tmp/test.pmcfg -RThis will start configd with the following parameters set:
- pMINK unique daemon id = cfg1
- SCTP listening port = 10000
- configuration definition file = /tmp/test_def.pmcfg
- configuration contents file = /tmp/test.pmcfg
- -R flag is used when configd should accept connections directly and not via routingd
CLI client shell
pMINK Command Line Service (CLI) is a specialized shell used for interaction with configd; it features a powerful TAB activated auto-complete and was inspired by CISCO and Vyatta command line interfaces.
cli_service command line arguments
cli_service - pMINK CLI service
Copyright (c) 2012 Release14.org
Options:
-i unique service id
-f cli definition file
-c config daemon address (ipv4:port)cli_service example
$ ./cli_service -i cli1 -f /tmp/cli_default.pmcfg -c 127.0.0.1:10000This will start cli_service with the following parameters set:
- pMINK unique daemon id = cli1
- CLI definition file = /tmp/cli_default.pmcfg
- configd IP address and listening port = 127.0.0.1:10000
CLI definition file is used for defining commands and modules available to the user. At the moment, cli_service uses only one available plugin; pm_plg_cli_cfg.so module is used for cli <---> configd communication. The file cli_default.pmcfg used in this example is a default CLI definition; it is created during installation (make install)
R14P Routing daemon
Routing daemon is a general purpose R14P router; it is used for label based R14P routing and load balancing. The most common type of setup assumes the following:
- two routing daemons (or one if redundancy is not an issue)
- one config daemon
- any number of user daemons
In this setup, routingd connects directly to configd while other daemons involved in this setup connect only to routingd. Routing daemon facilitates all daemon-to-daemon communication, takes care of load balancing (if used), and creates an extra layer of security for configd. Direct connection to configd is established only by routing, all other daemons communicate with configd via routingd.
routingd command line arguments
routingd - pMINK Routing daemon
Copyright (c) 2012 Release14.org
Options:
-? help
-i unique daemon id
-c config daemon address (ipv4:port)
-p R14P inbound port
-D start in debug mode
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 1000)
--r14p-stimeout R14P Stream timeout in seconds (default = 5)routingd example
$ ./routingd -i rtr1 -c 127.0.0.1:10000 -p 15000This will start routingd with the following parameters set:
- pMINK unique daemon id = rtr1
- configd IP address and listening port = 127.0.0.1:10000
- SCTP listening port = 15000
Config daemon client
Configuration daemon client is an alternative interface to configd. Unlike cli_service which is interactive, configdc is a script based client used by 3rd party applications like WEB GUIs and shell scripts. Script format used by configdc is a simple text file containing a list of commands to be sent to configd. Commands are processed sequentially and results are outputted to standard output. The resulting output is generated for each command found in a script file; commands are outputted with a : (colon) prefix and their results follow in the next line, unmodified. If an error occurs, configd will do an automatic discard of the whole transaction, and the resulting output will start with "ERROR:", followed by the actual error message generated by configd.
configdc command line arguments
cfgdc - pMINK Config daemon client
Copyright (c) 2012 Release14.org
Options:
========
-? help
-i unique daemon id
-f config daemon command script file
-r routing daemon address (ipv4:port)
-D start in debug mode
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 1000)
--r14p-stimeout R14P Stream timeout in seconds (default = 5)configdc example (success)
$ cat /tmp/test.txt
configuration
show dyn node_1 test
$ ./configdc -i cfgc1 -r 127.0.0.1:10000 -f /tmp/test.txt
: configuration
test_global "10"
local {
test_local "666"
}
dynamic {
node_1 {
test "10"
}
node_2 {
test "20"
}
}
: show dyn node_1 test
test = 10This will start configdc with the following parameters set:
- pMINK unique daemon id = cfgc1
- configd (or routingd) IP address and listening port = 127.0.0.1:10000
- script file with the list of commands to send to configd = /tmp/test.txt
configdc example (error)
$ cat /tmp/test_err.txt
configuration
show dyn node_1 testbla
$ ./configdc -i cfgc1 -r 127.0.0.1:10000 -f /tmp/test_err.txt
: configuration
test_global "10"
local {
test_local "666"
}
dynamic {
node_1 {
test "10"
}
node_2 {
test "20"
}
}
: show dyn node_1 testbla
ERROR: Unknown item or command "testbla"!This will start configdc with the following parameters set:
- pMINK unique daemon id = cfgc1
- configd (or routingd) IP address and listening port = 127.0.0.1:10000
- script file with the list of commands to send to configd = /tmp/test_err.txt
R14P trap client
R14P Trap client is a tool used for fetching pMINK performance counters. Daemons can expose various counters which are usually required for performance tracking and trouble shooting. pMINK framework uses its own system for counters; it is an R14P protocol extension quite similar but not as powerful as SNMP. Most production environments use their own 3rd party monitoring tools; creating wrapper scripts to convert r14ptrapc output to SNMP compatible data should not be a big issue.
r14ptrapc command line arguments
r14ptrapc - pMINK R14P trap client
Copyright (c) 2012 Release14.org
Options:
-c target daemon address (ipv4:port)
-t target daemon type
-i target daemon id
-s target trap id (0 for ALL)
-a unique client id
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 10)
--r14p-stimeout R14P Stream timeout in seconds (default = 5)
--r14p-smsg-pool R14P Service message pool (default = 10)
--r14p-sparam-pool R14P Service message parameter pool (default = 1000)r14ptrapc example (specific counter)
$ ./r14ptrapc -c 127.0.0.1:15000 -t routingd -i rtr1 -s R14P_IN_config_daemon_cfg1_BYTES -a trapc1
Trap Id Trap Value
-------------------------------------------------------------
R14P_IN_config_daemon_cfg1_BYTES 140
This will start r14ptrapc with the following parameters set:
- routingd IP address and listening port = 127.0.0.1:10000
- type label of target daemon to fetch counters from = routingd
- id label of target daemon to fetch counters from = rtr1
- counter id (multiple -s supported) to fetch = R14P_IN_config_daemon_cfg1_BYTES
- trap client's unique daemon id = trapc1
r14ptrapc example (all counters)
$ ./r14ptrapc -c 127.0.0.1:15000 -t routingd -i rtr1 -s 0 -a trapc1
Trap Id Trap Value
----------------------------------------------------------------------------
R14P_IN_%routingd_%rtr1_BYTES 441
R14P_IN_%routingd_%rtr1_DISCARDED 0
R14P_IN_%routingd_%rtr1_MALFORMED 0
R14P_IN_%routingd_%rtr1_PACKETS 5
R14P_IN_%routingd_%rtr1_POOL_ERR 0
R14P_IN_%routingd_%rtr1_SOCKET_ERR 0
R14P_IN_%routingd_%rtr1_STREAMS 1
R14P_IN_%routingd_%rtr1_STREAM_BYTES 192
R14P_IN_%routingd_%rtr1_STREAM_ERR 0
R14P_IN_%routingd_%rtr1_STREAM_LOOPBACK 0
R14P_IN_%routingd_%rtr1_STREAM_TIMEOUT 0
R14P_IN_r14ptrapc_trapc117815_BYTES 0
R14P_IN_r14ptrapc_trapc117815_DISCARDED 0
R14P_IN_r14ptrapc_trapc117815_MALFORMED 0
R14P_IN_r14ptrapc_trapc117815_PACKETS 0
R14P_IN_r14ptrapc_trapc117815_POOL_ERR 0
R14P_IN_r14ptrapc_trapc117815_SOCKET_ERR 0
R14P_IN_r14ptrapc_trapc117815_STREAMS 0
R14P_IN_r14ptrapc_trapc117815_STREAM_BYTES 0
R14P_IN_r14ptrapc_trapc117815_STREAM_ERR 0
R14P_IN_r14ptrapc_trapc117815_STREAM_LOOPBACK 0
R14P_IN_r14ptrapc_trapc117815_STREAM_TIMEOUT 0
R14P_OUT_%routingd_%rtr1_BYTES 815
R14P_OUT_%routingd_%rtr1_DISCARDED 0
R14P_OUT_%routingd_%rtr1_MALFORMED 0
R14P_OUT_%routingd_%rtr1_PACKETS 7
R14P_OUT_%routingd_%rtr1_POOL_ERR 0
R14P_OUT_%routingd_%rtr1_SOCKET_ERR 0
R14P_OUT_%routingd_%rtr1_STREAMS 0
R14P_OUT_%routingd_%rtr1_STREAM_BYTES 0
R14P_OUT_%routingd_%rtr1_STREAM_ERR 0
R14P_OUT_%routingd_%rtr1_STREAM_LOOPBACK 0
R14P_OUT_%routingd_%rtr1_STREAM_TIMEOUT 0
R14P_OUT_r14ptrapc_trapc117815_BYTES 0
R14P_OUT_r14ptrapc_trapc117815_DISCARDED 0
R14P_OUT_r14ptrapc_trapc117815_MALFORMED 0
R14P_OUT_r14ptrapc_trapc117815_PACKETS 0
R14P_OUT_r14ptrapc_trapc117815_POOL_ERR 0
R14P_OUT_r14ptrapc_trapc117815_SOCKET_ERR 0
R14P_OUT_r14ptrapc_trapc117815_STREAMS 0
R14P_OUT_r14ptrapc_trapc117815_STREAM_BYTES 0
R14P_OUT_r14ptrapc_trapc117815_STREAM_ERR 0
R14P_OUT_r14ptrapc_trapc117815_STREAM_LOOPBACK 0
R14P_OUT_r14ptrapc_trapc117815_STREAM_TIMEOUT 0
This will start r14ptrapc with the following parameters set:
- routingd IP address and listening port = 127.0.0.1:10000
- type label of target daemon to fetch counters from = routingd
- id label of target daemon to fetch counters from = rtr1
- counter id (multiple -s supported) to fetch = 0
- trap client's unique daemon id = trapc1
ASN.1 c++ compiler
pMINK ASN.1 c++ compiler translates ASN.1 syntax notation into c++ soure code. The generated code is intended to be used with pMINK asn.1 library, but it can also be of value to 3rd party applications and/or libraries. R14P protocol definition (r14p.asn) was also compiled using asn1c.
Project MINK MNO (Mobile Network Operator) implementation consists of many ASN.1 defined protocols, some most important ones are Transaction Capabilities Application Part (TCAP) and Mobile Application Part (MAP). All of these were compiled using asn1c, only minor modifications were needed. ASN.1 syntax notation is sometimes difficult to parse due to its complexity; pMINK's asn1c compiler tries to cover most of syntax variations but it is not 100% ASN.1 compatible. Minor tweaks are sometimes needed in order to accommodate for syntax variations.
asn1c command line arguments
asn1c - pMINK ASN.1 C++ compiler
Copyright (c) 2012 Release14.org
Usage: asn1c [options]
Options:
-f specify asn.1 input file
-p print asn.1 structure
-g generate c++ code
-t redirect code generation to stdout
-c syntax check asn.1 definition
-o specify output directory
-? help
asn1c example
$ ./asn1c -f src/asn1/r14p/r14p.asn -g -o /tmp
Generating header file "r14p.h"...
Finished generating header file "/tmp/r14p.h"
Generating src file "/tmp/r14p.h"...
Finished generating src file "/tmp/r14p.h"This will start asn1c with the following parameters set:
- asn.1 input file = src/asn1/r14p/r14p.asn
- -g = generate c++ header and source file
- output directory for c++ generated files = /tmp
Signalling Gateway Node daemon
Project MINK's implementation of Signal Transfer Point (STP) deviates from a standard STP blueprint in which a single software process is used for both connection handling and routing.
Signalling Gateway Node (SGN) and Signal Transfer Point (STP) included in pMINK framework utilize a different approach; the former is responsible for connection management (sockets and state machines), while the latter specializes in data routing and translations.
There are two types of signalling categories available in pMINK; internal and external. External signalling is context dependant and can vary greatly; pMINK platform uses SGN as the main data entry point and signalling converter. After successful conversion, external signalling is classified as internal signalling and transferred freely between various nodes using context free R14P protocol.
This type of approach creates a layer of abstraction around various external signalling protocols, and allows pMINK user daemons (e.g. STP and FGN) to focus on implementation of logic, and not data formats and conversions.
The following types of connections are currently implemented in SGN:
- M3UA - MTP Level 3 (MTP3) User Adaptation Layer
- SMPP - Short Message Peer-to-Peer
- PCAP - Passive packet capture (M3UA and SMPP)
- both libpcap and PF_RING are supported (
--with-pfringconfigure flag)
- both libpcap and PF_RING are supported (
User data protocols currently supported:
- SCCP - Signalling Connection Control Part
- Unitdata (UDT) and Extended Unitdata (XUDT)
- TCAP - Transaction Capabilities Application Part
- GSM MAP 3GPP TS 29.002 - GSM Mobile Application Part
- Supported application contexts:
- 0.4.0.0.1.0.25.3 - shortMsgMT-RelayContext-v3
- 0.4.0.0.1.0.25.2 - shortMsgMT-RelayContext-v2
- 0.4.0.0.1.0.20.3 - shortMsgGatewayContext-v3
- 0.4.0.0.1.0.20.2 - shortMsgGatewayContext-v2
- 0.4.0.0.1.0.20.1 - shortMsgGatewayContext-v1
- 0.4.0.0.1.0.21.3 - shortMsgMO-RelayContext-v3
- 0.4.0.0.1.0.21.2 - shortMsgMO-RelayContext-v2
- 0.4.0.0.1.0.21.1 - shortMsgRelayContext-v1
- Supported opcodes:
- 44 - mt-forward-SM
- 46 - mo-forward-SM
- 45 - sendRoutingInfoForSM
- Supported application contexts:
- SMS TPDU 3GPP TS 23.040
- SMPP v3.4 - Short Message Peer-to-Peer
M3UA notes:
Definition from Wikipedia:
M3UA stands for MTP Level 3 (MTP3) User Adaptation Layer as defined by the IETF SIGTRAN working group in RFC 4666 (which replaces and supersedes RFC 3332). M3UA enables the SS7 protocol's User Parts (e.g. ISUP, SCCP and TUP) to run over IP instead of telephony equipment like ISDN and PSTN. It is recommended to use the services of SCTP to transmit M3UA.
- Signalling Gateway Node (SGN) supports M3UA carried by SCTP; user part of M3UA indicated by Service Indicator is currently limited to SCCP (SI = 3)
Connection configuration
SGN connection configuration is organized using M3UA principles and terminology; Application Server Process (ASP) and Application Server (AS) are used for both SMPP and M3UA configuration.
AS Definition from M3UA RFC:
Application Server (AS) - A logical entity serving a specific Routing Key. An example of an Application Server is a virtual switch element handling all call processing for a unique range of PSTN trunks, identified by an SS7 SIO/DPC/OPC/CIC_range. Another example is a virtual database element, handling all HLR transactions for a particular SS7 DPC/OPC/SCCP_SSN combination. The AS contains a set of one or more unique Application Server Processes, of which one or more is normally actively processing traffic. Note that there is a 1:1 relationship between an AS and a Routing Key.
ASP Definition from M3UA RFC:
Application Server Process (ASP) - A process instance of an Application Server. An Application Server Process serves as an active or backup process of an Application Server (e.g., part of a distributed virtual switch or database). Examples of ASPs are processes (or process instances) of MGCs, IP SCPs or IP HLRs. An ASP contains an SCTP endpoint and may be configured to process signalling traffic within more than one Application Server.
sgnd command line arguments
sgnd - pMINK Signalling daemon
Copyright (c) 2012 Release14.org
Options:
-? help
-i unique daemon id
-t daemon type override
-r routing daemon address (ipv4:port)
-D start in debug mode
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 10000)
--r14p-stimeout R14P Stream timeout in seconds (default = 5)
--r14p-smsg-pool R14P Service message pool (default = 1000)
--r14p-sparam-pool R14P Service message parameter pool (default = 100000)
Dev Options:
=============
--dev-m3ua-sm Enable/Disable m3ua state machine (0 - Disable, 1 - Enable)
--dev-smpp-sm Enable/Disable smpp state machine (0 - Disable, 1 - Enable)sgnd example
$ ./sgnd -i sgn-test-01 -r 127.0.0.1:10000This will start sgnd with the following parameters set:
- routingd IP address and listening port = 127.0.0.1:10000
- pMINK unique daemon id = sgn-test-01
M3UA Connection
ASP/AS configuration example
The following configuration excerpts show a simple 1 AS with 1 ASP setup; ASP TEST-ASP-01 is assigned a 192.168.0.10:2906 local ip/port combination, and is connected to a 192.168.0.100:2906 remote peer. SCTP timers in this example are also defined explicitly, and M3UA opc/dpc is set to 1234/5678.
Each Application Server Process has to be assigned to one or more Application Servers; in this example, we have created an ASP named TEST-ASP-01 and an AS named TEST-AS-01. The second step needed to properly activate an ASP, is to add it to the Application Server's list of active Application Server Processes.
ASP configuration subset (mno/sgn/sgn-test-01/m3ua/asp)
TEST-ASP-01 {
sctp {
local {
ip1 "192.168.0.10"
port "2906"
}
remote {
ip1 "192.168.0.100"
port "2906"
}
timers {
hb-interval "3000"
max-init-retransmit "8"
path-max-retrans "5"
rto-initial "100"
rto-max "500"
rto-min "150"
sack-timeout "0"
sack-freq "1"
valid-cookie-life "60000"
}
}
m3ua {
opc "1234"
dpc "5678"
hbeat "1000"
}
mode "0"
shutdown "1"
description "Testing ASP TEST-ASP-01"
} AS configuration subset (mno/sgn/sgn-test-01/m3ua/as)
TEST-AS-01 {
asp {
TEST-ASP-01 {
active "1"
}
}
routing-key {
routing-context "111"
}
traffic-mode {
type "2"
}
description "Testing AS TEST-AS-01"
}Step by step ASP/AS activation process using the pMINK CLI:
- Create new ASP named TEST-ASP-01 on an SGN node named sgn-test-01
-
create a new empty ASP node:
set mno sgn sgn-test-01 m3ua asp TEST-ASP-01 -
set a new root node for easier editing:
edit mno sgn sgn-test-01 m3ua asp TEST-ASP-01 -
set ASP connection parameters:
set sctp local ip1 192.168.0.10 set sctp local port 2906 set sctp remote ip1 192.168.0.100 set sctp remote port 2906 set sctp timers hb-interval 3000 set sctp timers max-init-retransmit 8 set sctp timers path-max-retrans 5 set sctp timers rto-initial 100 set sctp timers rto-max 500 set sctp timers rto-min 150 set sctp timers sack-timeout 0 set sctp timers sack-freq 1 set sctp timers valid-cookie-life 60000 set m3ua opc 1234 set m3ua dpc 5678 set m3ua hbeat 1000 set mode 0 set shutdown 1 set description "Testing ASP TEST-ASP-01"
-
- commit changes:
commit
- Create new AS named TEST-AS-01 on an SGN node named sgn-test-01
-
create a new empty AS node:
set mno sgn sgn-test-01 m3ua as TEST-AS-01 -
set a new root node for easier editing:
edit mno sgn sgn-test-01 m3ua as TEST-AS-01 -
set AS parameters and link it with ASP:
set asp TEST-ASP-01 active 1 set routing-key routing-context 111 set traffic-mode type 2 set description "Testing AS TEST-AS-01"
-
commit changes:
commit
SMPP Connection
ASP/AS configuration example
The following configuration excerpts show a simple 1 AS with 1 ASP setup; ASP TEST-SMPP-ASP-01 is assigned a 192.168.0.10:2775 local ip/port combination, and is connected to a 192.168.0.100:2775 remote peer. SMPP BIND method, username and password used in the following example, are respectively Bind_transceiver, testuser and 12345678.
Each Application Server Process has to be assigned to one or more Application Servers; in this example, we have created an ASP named TEST-SMPP-ASP-01 and an AS named TEST-SMPP-AS-01. The second step needed to properly activate an ASP, is to add it to the Application Server's list of active Application Server Processes.
ASP configuration subset (mno/sgn/sgn-test-01/smpp/asp)
TEST-SMPP-ASP-01 {
tcp {
local {
ip "192.168.0.10"
port "2775"
}
remote {
ip "192.168.0.100"
port "2775"
}
}
smpp {
timers {
enquire_link_timer "10"
}
users {
testuser {
password "12345678"
}
}
}
mode "0"
description "Testing ASP TEST-SMPP-ASP-01"
} AS configuration subset (mno/sgn/sgn-test-01/smpp/as)
TEST-SMPP-AS-01 {
asp {
TEST-SMPP-ASP-01 {
active "1"
}
}
description "Testing AS TEST-SMPP-AS-01"
}Step by step ASP/AS activation process using the pMINK CLI:
- Create new ASP named TEST-SMPP-ASP-01 on an SGN node named sgn-test-01
-
create a new empty ASP node:
set mno sgn sgn-test-01 smpp asp TEST-SMPP-ASP-01 -
set a new root node for easier editing:
edit mno sgn sgn-test-01 smpp asp TEST-SMPP-ASP-01 -
set ASP connection parameters:
set tcp local ip 192.168.0.10 set tcp local port 2775 set tcp remote ip 192.168.0.100 set tcp remote port 2775 set smpp bind_method 9 set smpp timers enquire_link_timer 10 set smpp users testuser password 12345678 set mode 0 set description "Testing ASP TEST-SMPP-ASP-01"
-
- commit changes:
commit
- Create new AS named TEST-SMPP-AS-01 on an SGN node named sgn-test-01
-
create a new empty AS node:
set mno sgn sgn-test-01 smpp as TEST-SMPP-AS-01 -
set a new root node for easier editing:
edit mno sgn sgn-test-01 smpp as TEST-SMPP-AS-01 -
set AS parameters and link it with ASP:
set asp TEST-SMPP-ASP-01 active "1" set description "Testing AS TEST-SMPP-AS-01"
-
commit changes:
commit
Signal Transfer Point daemon
Signal Transfer Point (STP) is a rule based routing engine used for packet routing and translations. Some implementation details were already mentioned in the previous chapter; STP was designed to be used in combination with SGN, the former focuses on routing while the latter keeps connections alive and deals with sockets, state machines and data conversions.
Although Filter Gateway Node (FGN) and Signal Transfer Point (STP) both share the same rule engine, FGN capabilities exceed basic routing and offer increased flexibility and customization. More information regarding STP's rule engine can be found in FGN user's manual; please note that unlike FGN, STP support is limited to basic matching and section 8.2.4 of the manual is not supported.
Packet routing protocols available to STP's routing engine:
- M3UA
- SCCP
- TCAP
- GSM MAP 3GPP TS 29.00
- Supported application contexts:
- 0.4.0.0.1.0.25.3 - shortMsgMT-RelayContext-v3
- 0.4.0.0.1.0.25.2 - shortMsgMT-RelayContext-v2
- 0.4.0.0.1.0.20.3 - shortMsgGatewayContext-v3
- 0.4.0.0.1.0.20.2 - shortMsgGatewayContext-v2
- 0.4.0.0.1.0.20.1 - shortMsgGatewayContext-v1
- 0.4.0.0.1.0.21.3 - shortMsgMO-RelayContext-v3
- 0.4.0.0.1.0.21.2 - shortMsgMO-RelayContext-v2
- 0.4.0.0.1.0.21.1 - shortMsgRelayContext-v1
- Supported opcodes:
- 44 - mt-forward-SM
- 46 - mo-forward-SM
- 45 - sendRoutingInfoForSM
- Supported application contexts:
- SMS TPDU 3GPP TS 23.040
- SMPP v3.4
stpd command line arguments
stpd - pMINK Signalling Transfer Point daemon
Copyright (c) 2012 Release14.org
Options:
-? help
-i unique daemon id
-r routing daemon address (ipv4:port)
-D start in debug mode
R14P Options:
=============
--r14p-streams R14P Session stream pool (default = 10000)
--r14p-stimeout R14P Stream timeout in seconds (default = 5)
--r14p-smsg-pool R14P Service message pool (default = 1000)
--r14p-sparam-pool R14P Service message parameter pool (default = 100000)stpd example
$ ./stpd -i stp-test-01 -r 127.0.0.1:10000This will start stpd with the following parameters set:
- routingd IP address and listening port = 127.0.0.1:10000
- pMINK unique daemon id = stp-test-01
STP Routing
Configuration example
The following configuration excerpt shows a simple 1 rule routing; all traffic having an SCCP GT Calling Address set to 12345678 will be routed back to Application Server (AS) named TEST-AS-01, configured on pMINK daemon whose daemon type is set to sgnd.
Routing destinations consist of priority value and two destinations; R14P (Level 1 routing) and AS (Level 2 routing). They are processed in the following way:
1. Level 1 routing
- destinations are sorted by their
priorityvalue and processed sequentially; if data transmission fails, next destination will be used until successful transmission is achieved or there are no more available destinations - data is first sent to a pMINK daemon whose daemon_type (configurable with
-tswitch for some daemons, e.g. SGN) is set to a value pointed out by ther14pconfiguration field
2. Level 2 routing
- SGN daemon will receive the data and examine the destination (
dest_1) which was used for current data transfer - destination used consists of two destinations (
r14pandas); the former was already consumed by the sending daemon, and the latter will be processed by the receiving SGN daemon - SGN daemon will forward the data to the Application Server (AS) pointed
out by the
asfield of the current destination (dest_1) - if data transmission fails while sending the data to the destination AS (
as), SGN daemon will use the next available destination and repeat the whole Level 1 routing procedure
Routing rules configuration subset (mno/stp/stp-test-01/routing)
rule_1 {
hunt-stop "1"
description "Test rule #1"
priority "0"
route {
match {
sccp {
cgpa {
gt {
address "12345678"
}
}
}
}
destination {
dest_1 {
priority "0"
as "TEST-AS-01"
r14p "sgnd"
}
}
}
}Step by step STP Rule activation process using the pMINK CLI:
- Create new rule named rule_1 on an STP node named stp-test-01
-
create empty rule node:
set mno stp stp-test-01 routing rule_1 -
set a new root node for easier editing:
edit mno stp stp-test-01 routing rule_1 -
set basic parameters:
set hunt-stop 1 set description "Test rule #1" set priority 0
-
- Create match section for rule_1 on an STP node named stp-test-01
-
set a new root node for easier editing:
edit route -
create match section
set match sccp cgpa gt address 12345678
-
- Create destination section for rule_1 with dest_1 destination
-
create new empty destination node:
set destination dest_1 -
set a new root node for easier editing:
edit destination dest_1 -
set destination parameters
set priority 0 set as TEST-AS-01 set r14p sgnd
-
commit changes:
commit
-
STP Translations
Configuration example
Routing of traffic is one of the two most prominent features of Signal Transfer Point daemon; the second one is the ability to modify live traffic, or in terms of STP, to do translations. More information about the relationship between match and translate sections of routing rules can be found in chapters 8.2 and 8.2.5 of the FGN user's manual.
The following configuration excerpt shows a modified version of rule_1 with one extra translation added to the rule definition. SCCP translation used in this example will cause the packet to be re-encoded with Calling GT Address changed to 99999999.
Routing rules configuration subset (mno/stp/stp-test-01/routing/rule_1/route)
match {
sccp {
cgpa {
gt {
address "12345678"
}
}
}
}
translate {
sccp {
cgpa {
gt {
address "99999999"
}
}
}
}
destination {
dest_1 {
priority "0"
as "TEST-AS-01"
r14p "sgnd"
}
}Step by step Rule translation activation using the pMINK CLI:
-
Create new SCCP translation in rule_1 on an STP node named stp-test-01
- set a new root node for easier editing:
edit mno stp stp-test-01 routing rule_1 route translate - set translation parameters:
set sccp cgpa gt address 99999999
- commit changes:
commit
- set a new root node for easier editing:
Data Retention daemon
Project MINK offers two solutions for passive traffic monitoring; Data Retention daemon (DRD) and Signalling Gateway Node (SGN). Although they both provide a useful set of features when it comes to passive monitoring, there are some major differences to consider:
- SGN supports both SIGTRAN and SMPP; DRD is, for the moment, limited to SIGTRAN
- SGN send passive data to STP; additional rule based routing is required on STP in order to forward the data to some other user daemon responsible for data storage
- SGN uses libpcap or PF_RING to capture data; DRD can only receive data via R14P (e.g. from SGN)
- DRD was designed for passive SMS TPDU 3GPP TS 23.04 and SRI-for-SM monitoring
- DRD was designed to work with SGN when M3UA ASPs are used for receiving a copy of live traffic; this feature is provided by some 3d party STPs and is usually used for debugging
- DRD uses MySQL database for data storage
- DRD implements various levels of data correlation and tracking (TCAP, GSM MAP, SCCP); it is perfect for Qos monitoring
Data Retention daemon (DRD) data fields for SMS:
+------------------------------------------------------------------------+
| Field name | Field value |
+------------------------------------------------------------------------+
| DirectionId | MO, MT |
| SmsSizeTypeId | SINGLE, CONCATENATED |
| SmsStatusId | OK, Error |
| CalledGt | SCCP Called Party GT |
| CallingGt | SCCP Calling Party GT |
| Scda | GSM MAP Service Centre Destination address |
| Scoa | GSM MAP Service Centre Originating address |
| Imsi | GSM MAP IMSI |
| Msisdn | GSM MAP MSISDN |
| SmsDestination | SMS TPDU TP-Destination-Address |
| SmsOriginating | SMS TPDU TP-Originating-Address |
| SmsText | SMS TPDU TP-User-Data |
| SmsTextEncId | GSM 7bit, 8bit, UCS2 |
| SmsDestinationEncId | SMS TPDU TP-Destination-Address Type-Of-Number |
| SmsOriginatingEncId | SMS TPDU TP-Originating-Address Type-Of-Number |
| DestinationPointCode | M3UA DPC |
| OriginatingPointCode | M3UA OPC |
| TcapSid | TCAP Source Transaction ID |
| TcapDid | TCAP Destination Transaction ID |
| AppCtxOid | TCAP Dialogue application context OID |
| SmsPartnum | CONCATENATED SMS Part number |
| SmsParts | CONCATENATED SMS Total parts |
| SmsMessageId | CONCATENATED SMS Message ID |
| ErrorTypeId | Error type |
| ErrorCode | Error code |
+------------------------------------------------------------------------+
Data Retention daemon (DRD) data fields for SRI-for-SM:
+--------------------------------------------------------------+
| Field name | Field value |
+--------------------------------------------------------------+
| OriginatingPointCode | M3UA OPC |
| DestinationPointCode | M3UA DPC |
| CalledGt | SCCP Called Party GT |
| CallingGt | SCCP Calling Party GT |
| TcapSid | TCAP Source Transaction ID |
| TcapDid | TCAP Destination Transaction ID |
| AppCtxOid | TCAP Dialogue application context OID |
| Imsi | GSM MAP IMSI |
| Msisdn | GSM MAP MSISDN |
| Nnn | GSM MAP Network Node Number |
| An | GSM MAP Additional Number |
| Sca | GSM MAP Service Centre Address |
| ErrorTypeId | Error type |
| ErrorCode | Error code |
+--------------------------------------------------------------+
Data Retention daemon (DRD) offers detailed error tracking for SMS TPDU 3GPP TS 23.04 and SRI-for-SM; the following error types are available:
+--------------------------------------------+
| Error type |
+--------------------------------------------+
| TCAP Component error national |
| TCAP Component error private |
| TCAP P-Abort error |
| TCAP Dialogue error user |
| TCAP Dialogue error service provider |
| TCAP Component Reject-General problem |
| TCAP Component Reject-Invoke problem |
| TCAP Component Reject-ReturnResult problem |
| TCAP Component Reject-ReturnError problem |
| GSM MAP Error |
| No reply |
| SMPP Error |
| SCCP Error |
| Unknown error |
+--------------------------------------------+
Filtering Gateway Node daemon
Filtering Gateway Node is a versatile rule based packet filtering system currently used for SMS (SIGTRAN and SMPP) filtering.
- FGN documentation is distributed separately due to its complexity and size; user manual can be found here: smsf.pdf
Pattern Detection Node daemon
Still in development, documentation coming soon...
License
This software is licensed under the GPL v3 license