Skip Navigation

ss7box 0.1 User Guide

(Draft E)




Michael J. Mueller



Foreword

This is the user guide for the ss7box r0.1 system developed and maintained by Xygnada Technology, Inc.

How to contact the author of this document:

Revision History
Revision 0.0.draft_E2005 January 04Revised by: mjm
Applications chapter added; added a description of the UDP crosslink
Revision 0.0.draft_D2004 November 23Revised by: mjm
Additional material for Local API; started cabling section
Revision 0.0.draft_C2004 November 2Revised by: mjm
Additional material for Local API and ss7box.conf
Revision 0.0.draft_B2004 October 28Revised by: mjm
Additional Local API material
Revision 0.0.draft_A2004 October 18Revised by: mjm
First draft release


Chapter 1. Introduction

This document describes ss7box, a Linux hosted SS7 signaling gateway application. ss7box uses Sangoma S-series and A-series WAN adapter cards for PCI bus to access the physical layer of ITU and ANSI SS7 links. ss7box manages SS7 MTP1-MTP3 and provides a layer 4 interface service to client applications.

ss7box MTP1-MTP3 protocols and operating environment is not available in source code form. The world's SS7 network providers require predictable functionality and accountability in the equipment they connect with. Releasing the ss7box base system in binary form helps to achieve this goal.


Chapter 2. Applications

ss7box has both end node and transfer node functions. A transfer node is similar to an IP router in that it interchanges messages amoung multiple linksets based on address information contained in each message, routing tables, and various resource status.

End node applications are implemented as separate processes that run either on the ss7box platform or a separate platform. The application and ss7box communicate using an application program interface (API) that is described in this document. Applications can be programmed in any language that supports Berkeley sockets. It is common to use languages such a C, C++, Python, and Perl.

Several applications have been developed an are in commercial operation. Others are currently being developed, and still others are in the planning stage. The remainder of this section will introduce these applications.

Application source code and the API are supplied in source code form.


Signal Transfer Point

The Signal Transfer Point (STP) is an interchange between SS7 linksets. Message signal units (MSU) arrive on one linkset and leave on another. The STP function is the basis for all ss7box applications.

Figure 2-1. ss7box Signal Transfer Point System Internals


Application Access

Application access is a system that is modeled on M3UA (RFC 3332) where an SS7 level 4 application communicates with the SS7 network using the ss7box Local API described in Chapter 6.

Figure 2-2. ss7box Local API System Internals


LIDB Access


CNAM Access


Signal Gateway

The SS7 Gateway is an interchange between the SS7 network and an SCTP/IP network. In the SS7 to SCTP direction, MTP3 payloads are placed into M3UA payloads. The opposite occurs in the reverse direction. Routing between SS7 and SCTP is the result of appropriate datafill in the ss7box routing tables described in Chapter 4

Figure 2-3. ss7box SS7 Gateway System Internals


SS7 Backhaul


Asterisk SS7


Chapter 3. Installation

Linux host platform

ss7box will run under most well-known and recent GNU/Linux distributions using the 2.4.x kernel. ss7box is a soft realtime application that must have full control of all user space run time and memory in order to keep the WAN adapter's bitstreams serviced. To satisfy the realtime requirements, the GNU/Linux installation must not have any graphical user interface installed, nor any other application with high or constant demands for the system's CPU or memory. This requirement does not apply to the ss7box client application which is discussed in more detail later in this document.


ss7box Installation

The ss7box binary can reside anywhere in the file system. To run the ss7box program one must have root user priviledges.


Sangoma WAN Interface Installation

The ss7box package includes a tarball for Sangoma WAN interface installation. The tarball Sangoma_Xyg_2_3_2_beta3.tgz includes

  • wanpipe-beta3-2.3.2.tgz : The driver package from Sangoma.

  • wanupd-oct12-04.tgz : The latest Xilinx download for the AFT-series cards. In the installation process the card will report its firmware revision level. If the revision is not corrent then customer support at Sangoma will assist in downloading the new Xilinx revision to the card.

The Sangoma driver originals are found in Sangoma's download repository.


Chapter 4. Configuration

ss7box

The configuration file for ss7box is kept in a single text file at /etc/ss7box/ss7box.conf. It's structure and order must be rigidly adhered to. The ss7box configuration file is discussed in detail in the following sections. This document maintains the correct order of sections.

All information in the configuration file is composed of alphanumeric characters from the XXXXXXXX character set. As with most Linux configuration files, blanks lines and lines whose first non-whitespace character is '#' are ignored. The '#' lines are often used to include comments.

In some sections the parameters are laid out in the form of a table. These tables have a uniform structure. A comment line identifies the columns and each row begins with an integer. The first column entry of each table is the Index which serves as a row identifier. The Index value of the first entry in a table is usually "0". Each subsequent row that is added must have an Index value that represents an integer that is one more the the previous index value. For example, for an entry whose Index is "9", then subsequent entry, if it exists, must have an Index value of "10".

Note

It is important to understand in the distinction between representing the integer ten as 10 or "10". The quoted representation, in this discussion, should be interpreted as a string of characters '1' followed by '0'. These matters are more difficult to describe than to do.

Tables contain a finite number of entries. Each section containin a tables indentifies the starting and ending Index values. In some cases tables are truncated with the string "end". Examples of table truncation are shown below.

Caution

This configuration file cross-references many parameters between tables and with Wanpipe configuration files. If the cross-referencing is incorrect the system will malfunction. It is best to start with a simple template configuration file that is known to be correct and make incremental changes. Using some form of version control will allow reversion to a known working version when problems arise.


GLOBAL

The GLOBAL section contains the SS7 Protocol and Self Point Code parameters. The SS7 protocol must be specified so that the program can make the appropriate distinctions in data and procedure. The differences between SS7 protocols are minor. Currently ss7box supports two flavors of the SS7 protocol: ITU and ANSI. One difference between ITU and ANSI SS7 that affects the user is the structure of the Point Codes whose definitions are found the Glossary.

The Self Point Code is the point code of the ss7box itself.

 
# This is the configuration file for Xygnada ss7box release 0.1
# Copyright 2004, Michael J. Mueller

# This a comment line

# The order of elements, the bracketed elements, and the order and type
# of information elements must adhere to the pattern specified.

# All index values must be sequential with a skip value of one (1).

[GLOBAL]
#
# SS7 Protocol: ITU/ANSI
#
# Self Point Code: 
#	ITU format is 14 bit unsigned integer
#	ANSI format is <network> <cluster> <member>
#		network is an 8 bit unsigned integer
#		cluster is an 8 bit unsigned integer
#		network is an 8 bit unsigned integer
#
# SS7 Protocol	Self Point Code
# ITU		822
  ANSI          5 102 254

 


FACILITIES

 

[FACILITIES]
#
# Card Name: 
#       wanpipeX where X is 1..n; see Sangoma documentation for more information;
#
# Interface Name: 
#       see Sangoma documentation for more information; 
#
# Facility Type: 
#       T1
#       E1
#       DDS
#
# Frame/Packet: 
#       50 for T1 
#       40 for E1 
#       50 for DDS if used with T1 (note that for DDS this value is actually octets/packet)
#       40 for DDS if used with E1 
#       50/40 for DDS if used without T1/E1
#
# Index Card Name       Interface Name		Facility Type	Frame/Packet
  0     wanpipe1        wp1bstrm1		T1		50
  1     wanpipe2        wp2bstrm1		T1		50
  end
# No more than four facilities supported at this time.


 


CROSSLINK

The crosslink is a UDP socket connection between two ss7boxes operating in the dual-mode configuration. In dual-mode, two ss7boxes present themselves as a single SS7 node to the SS7 network. The crosslink is most often implemented on eth0. As a root priviledged user, use the ifconfig command to obtain the eth0 IP address of each ss7box. The crosslink port is any port that is unused on both platforms.

The following example illustrates how to configure the dual-mode crosslink for two Linux hosts named apple and orange. As shown in Figure 4-1 apple's eth0 IP address is 192.168.1.21 and orange's eth0 IP address is 192.168.1.22. The crosslink configuration is shown in Table 4-1.

Figure 4-1. Dual-Mode ss7box Configuration

Table 4-1. Crosslink Attribute Assignments

Host IdMy IP AddrMate IP AddrCrosslink Port
apple192.168.1.21192.168.1.2254020
orange192.168.1.22192.168.1.2154020

If single-mode is being used, then set CROSSLINK_PORT to -1.

 

[CROSSLINK]

# MY_IP_ADDR            MATE_IP_ADDR            CROSSLINK_PORT  
  192.168.1.21          192.168.1.22            54020

 


MTP2LINKS

 


[MTP2LINKS]
# Index Fac     Slot	LSet	Link	T1	T2	T3	T4e	T4n	T5	T6	T7
  0	0	0	0	0	13.00	11.50	11.50	0.60	2.30	0.12	3.00	1.00
  1	1	0	1	0	13.00	11.50	11.50	0.60	2.30	0.12	3.00	1.00
  end
# Up to 93 links may be configured.

 


MTP3TIMERS

 

[MTP3TIMERS]
#
# Timer	Value
  1	0.80
  2	1.40
  3	0.80
  4	0.80
  5	0.80
  6	0.80
  7	1.50
  8	1.20
  9	0.00
  10	30.00
  11	30.00
  12	1.50
  13	1.50
  14	3.00
  15	3.00
  16	2.00
  17	1.50
  18	20.00
  19	600.00
  20	120.00
  21	120.00
  22	15.00
  23	15.00
  24	15.00
  25	35.00
  26	15.00
  27	5.00
  28	35.00
  29	65.00
  30	35.00
  31	120.00
  32	120.00
  33	600.00
  34	120.00
# Periodic Facility Check Timer
  35    5.00
# Periodic Signaling Link Test Message Timer
  36    120.00    

 


MTP3LINKSETS

 

[MTP3LINKSETS]
#
# Index: table row index
# APC (Adjacent Point Code): point code of node on remote end of linkset
# Path: Index in MTP3ROUTEPATHS section where linkset is used
# Links in Linkset: listed in order of SLC (0..15), entered value is index into the
#     MTP2LINKS section table
#					Links in Linkset (associated MTP2 link indices)
# Index	APC		Path	SLC: 	0  1  2  3  4  5  6  7  8  9  10 11 12 13 14 15
  0	130 0 5		1		0  na na na na na na na na na na na na na na na
  1	130 0 6		2		0  na na na na na na na na na na na na na na na
  end

 


MTP3ROUTEPATHS

 

[MTP3ROUTEPATHS]
#
# Index: table row index
#
# Index		Transport Method	Linkset A	Linkset B
  0		CROSSLINK		na		na	
  1		MTP3			0		na
  2		MTP3			1		na
  end

 


MTP3ROUTES

 

[MTP3ROUTES]
#
# Must enter routes for adjacent and non-adjacent nodes.
#
# Index		Destination Point Code	Primary Path	Secondary Path
  0		132 0 4			1		0
  1		130 0 5			1		0
  2		130 0 6			2		na
  end

 


LOCAL_API

 

[LOCAL_API]
#
#
#
CONFIGURED	1
PORT		54000
SS7BOX_IP	127.0.0.25
AS_IP		127.0.0.27

 


Sangoma WAN Interfaces

This user guide summarizes the procedures for configuring the Sangoma WAN interfaces when used with ss7box. This procedure corresponds to the Sangoma Linux driver release 2.3.2 beta1. The S-series cards support T1, E1, and DDS links. The AFT-series cards are preferred for E1 and T1 links.

Sangoma provides a configurator tool called wancfg_adv that is run by a user with root priviledges. This tool creates configuration files from information supplied by the user. The configuration files are written to /etc/wanpipe/wanpipeX.conf where X is an integer in 1..4. The upper bound of 4 is set by the ss7box application. In each case below we are configuring the Sangoma driver to create a transparent bitstream API interface between a user program and the specified WAN links (T1, E1, or in the case of S-Series cards, DDS). The user program described in this document is ss7box.


AFT Series T1/E1 WAN Interfaces

Default values are used for configuration parameters except where noted in this procedure. Several pieces of information in the AFT configuration must correlate with information entered into the ss7box configuration file described in the Section called ss7box.

The steps for configuring an AFT card for E1 or T1 links are as follows:

  1. Start configurator:

    	# wancfg_adv
    	

  2. Select wanpipeX. It is best to start with wanpipe1 and increment in order. Each port is assigned a wanpipeX designator. Each port is a physical link (either T1 or E1).

  3. Select "Wan Protocol Definition"; select "AFT TE1 Protocols"; use "back" to return to the main menu

  4. Select "Hardware Setup"; select "Probe Hardware"; use arrows keys to choose card and port; use "back" to return to the main menu

  5. Select "T1/E1 Hardware Setup"; select "MEDIA" as T1 or E1; select the value "ALL" for "Act. channels"; select appropriate values for other options; use "back" to return to the main menu

  6. Select "Network Interface Setup"; Enter "1" in response to the query "Please specify the number of interfaces supported on TE1 AFT connection."; select "Interface 1"; select "Operation Mode"; select "API"; select "HDLC Streaming"; select "Disable HDLC Streaming (Default)"; select "Iface MTU"; backspace over the existing value and enter 1200; select "Iface MRU"; backspace over the existing value and enter 1200; use "back" two times to return to the main menu

  7. Select "Exit"; select "YES : Proceed to EXIT with an option to save." select "YES : Save Configuration and Exit" select "Exit"; choose "Back" to exit the "Wanpipe Script Configuraiton" menu (misspelling intentional)

  8. Inspect the /etc/wanpipe/wanpipeX.conf file that was just created.


S514 T1/E1 WAN Interfaces


S514 DDS56/64 WAN Interfaces


Chapter 5. Operation

Starting the ss7box is accomplished by a user with root priviledges as follows:

# cd /myss7boxdir
# ./Tail
# ./ss7box


Chapter 6. Local Application Program Interface

Note

This functionality covered in this section is under development and may change or be expanded.

This section describes the Local API between ss7box and a level 4 application server. The application server can run either on the ss7box host machine or on a separate machine on the same IP network as ss7box.


Managing the Socket to ss7box

The Local API is based on a UDP socket connection established between ss7box and the application server. The unreliable UDP protocol is an acceptable transport protocol between two processes on the same machine. Experience shows that it is also acceptable in some cases where two machines are connected on a very small private LAN with very little traffic.

The application server should establish a UDP connection to ss7box during its initialization procedure. Select a port number from the upper range of available port numbers. The address in the bind operation is the address of the application server. If the application server coresides on the same machine as ss7box then choose an IP address in the range 127.0.0.n where n is 1-128. Ensure the address you choose is not the 127.0.0.n address assigned to ss7box.

struct sockaddr_in      myaddr;
unsigned int		port = 55000;
char			my_ip_addr[16]="192.168.1.9";

//create a UDP socket
int udpsock = socket(AF_INET, SOCK_DGRAM, 0);

// bind the address to the socket
bzero(&myaddr, sizeof(myaddr));
myaddr.sin_family = AF_INET;
myaddr.sin_port = htons(port);
r = inet_pton(AF_INET, my_ip_addr, &myaddr.sin_addr.s_addr);

It is the application server designer's decision to use blocking or non-blocking access to the socket. The next two sections describe how to send and receive information using the socket.


Communication Procedure

This section borrows heavily from the spcification for M3UA (RFC 3332).


Starting Communication

When the application server (a/s) first establishes the socket to ss7box it should send an ASP_UP message to ss7box. ss7box will respond with an ASP_UP_ACK message.

When the a/s is ready to exchange traffic with ss7box, the application server should send the ASP_ACTIVE message to ss7box. ss7box will repond with an ASP_ACTIVE_ACK message.


In Service Communication

The application server (a/s) and ss7box both use DATA_TRANSFER messages to exchange signaling traffic.

Both the a/s and ss7box may use, at their discretion, the HEARTBEAT and HEARTBEAT_ACK to ensure each other are responsive.

Both the a/s and the ss7box use the ERROR message to indicate problems with an incoming message.

The ss7box sends a destination unavailable (DUNA) to the a/s when the a/s has sent a message to ss7box with a DPC that is currently unreachable by the ss7box. The ss7box sends a destination restricted (DRST) message to the a/s if DPC is in a restricted state from the point of view of ss7box. The a/s may send an destination state audit message (DAUD) message to ss7box enquire regarding the current state of a DPC. The reponse to a DAUD by the ss7box will either be a DUNA, DRST, or a destination available (DAVA) message. The ss7box sends a DAVA autonomously when a destination becomes available.

The ss7box and a/s information each other regarding congestion using the SCON message. Congestion can be reported from ss7box to a/s regarding congestion on the SS7 network. The a/s can also report congestion to ss7box regarding the communications between them.


Ending Communication

When the application server (a/s) wants to stop exchanging traffic with ss7box, the a/s should send the ASP_INACTIVE message to ss7box. ss7box will repond with an ASP_INACTIVE_ACK message.

When the a/s wants to close the socket to ss7box it should first use the procedure to stop traffic and then send the ASP_DOWN message to ss7box and wait for ss7box to send the ASP_DOWN_ACK.


Message Format

The Local API is based on the L4-L3 interface described in Q.704 with message structure being influenced by the M3UA (RFC 3332) implementation on ss7box. The M3UA protocol's support for reliability and fault tolerance is unneeded for client applications that co-reside on the same machine as ss7box. The Local API message structure, which is taken from M3UA, presents MTP3 fields on octet boundries instead of mid-octet bit boundries. This slight improvement assists level 4 programmers in a small way and it also allows ss7box to have some commonality between its Local API and its M3UA implementation.

The general structure of messages in the Local API conforms to the structure of M3UA messages that consist of a Common Message Header and 0-n parameters as defined by the message type. The Local API will also overlay requirements on the optional parameters defined in M3UA. Most often this means that optional parameters are disallowed. Rigid message structures of the Local API reduce and simplify the more general interface defined in the M3UA specification.


ASP_UP Message

The ASP_UP message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_UP;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_UP_ACK Message

The ASP_UP_ACK message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_UP_ACK;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_DOWN Message

The ASP_DOWN message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_DN;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_DOWN_ACK Message

The ASP_DOWN_ACK message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_DN_ACK;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


HEARTBEAT Message

The HEARTBEAT message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_BEAT;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


HEARTBEAT_ACK Message

The HEARTBEAT_ACK message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_STATE_MTC;
	noparm_msg.message_type = M3UA_MT_ASPSM_BEAT_ACK;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_ACTIVE Message

The ASP_ACTIVE message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_TRAF_MTC;
	noparm_msg.message_type = M3UA_MT_ASPTM_AC;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_ACTIVE_ACK Message

The ASP_ACTIVE_ACK message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_TRAF_MTC;
	noparm_msg.message_type = M3UA_MT_ASPTM_AC_ACK;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_INACTIVE Message

The ASP_INACTIVE message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_TRAF_MTC;
	noparm_msg.message_type = M3UA_MT_ASPTM_IA;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


ASP_INACTIVE_ACK Message

The ASP_INACTIVE_ACK message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 
	t_common_msg_hdr  noparm_msg;

	noparm_msg.version = M3UA_PV_REL_1_0;
	noparm_msg.reserved = 0;
	noparm_msg.message_class = M3UA_MC_ASP_TRAF_MTC;
	noparm_msg.message_type = M3UA_MT_ASPTM_IA_ACK;
	noparm_msg.message_length = sizeof(t_common_msg_hdr);

	/* send the message using sendto; the size of the message for sendto is 
	   found in noparm_msg.message_length */
 


DUNA Message

The DUNA message format is shown in the Section called SS7 Signaling Network Message Data Structure. The encoding of the message is as follows:

 
	t_ssnm_1		duna_msg;

	duna_msg.cmh.version = M3UA_PV_REL_1_0;
	duna_msg.cmh.reserved = 0;
	duna_msg.cmh.message_class = M3UA_MC_SS7_SNM;
	duna_msg.cmh.message_type = M3UA_MT_SSNM_DUNA;
	duna_msg.cmh.message_length = sizeof (t_ssnm_1);
	duna_msg.affected_pc.vlph.tag = 0x0012; /* (per RFC 3332) */
	duna_msg.affected_pc.vlph.length = sizeof (t_pc);
#if PROTOCOL == ITU_SS7
	duna_msg.affected_pc.pc = 822;
#elif PROTOCOL == ANSI_SS7
	duna_msg.affected_pc.pc = (pc.network << 16) + (pc.cluster << 8) + (pc.member);
#endif

	/* send the message using sendto; the size of the message for sendto is 
	   found in duna_msg.cmh.message_length */
 


DRST Message

The DRST message consists of the Common Message Header described in the Section called Common Message Header Structure and no parameters. The encoding of the message is as follows:

 

	code segment here

 


DAVA Message

The DAVA message format is shown in the Section called SS7 Signaling Network Message Data Structure. The encoding of the message is as follows:

 
	t_ssnm_1		dava_msg;

	dava_msg.cmh.version = M3UA_PV_REL_1_0;
	dava_msg.cmh.reserved = 0;
	dava_msg.cmh.message_class = M3UA_MC_SS7_SNM;
	dava_msg.cmh.message_type = M3UA_MT_SSNM_DAVA;
	dava_msg.cmh.message_length = sizeof (t_ssnm_1);
	dava_msg.affected_pc.vlph.tag = 0x0012; /* (per RFC 3332) */
	dava_msg.affected_pc.vlph.length = sizeof (t_pc);
#if PROTOCOL == ITU_SS7
	dava_msg.affected_pc.pc = 822;
#elif PROTOCOL == ANSI_SS7
	dava_msg.affected_pc.pc = (pc.network << 16) + (pc.cluster << 8) + (pc.member);
#endif

	/* send the message using sendto; the size of the message for sendto is 
	   found in dava_msg.cmh.message_length */
 


DUPU Message

The DUPU message consists of the Common Message Header and XXX parameters. The encoding of the message is as follows:

 

	code segment here

 


SCON Message

The DAVA message consists of the Common Message Header and XXX parameters. The encoding of the message is as follows:

 

	code segment here

 


DATA_TRANSFER Message

The DATA_TRANSFER message is described in the Section called Simple Protocol Data Structure. The encoding of the message is as follows:

 
	t_user_prot_data_simple		mtp3_msg;
	unsigned int 			user_data_size;

	/* call user application function to build SCCP message; pass in 
	   address of the buffer space in mtp3_msg; pass by reference a 
	   variable to hold the octet count of the SCCP message */
	   
	if (! build_sccp_message (&mtp3_msg.ud, &user_data_size))
	{
		return;
	}

	/* build the common message header */
	mtp3_msg.cmh.version = M3UA_PV_REL_1_0;
	mtp3_msg.cmh.reserved = 0;
	mtp3_msg.cmh.message_class = M3UA_MC_SS7_SNM;
	mtp3_msg.cmh.message_type = M3UA_MT_SSNM_SCON;
	mtp3_msg.cmh.message_length = sizeof(t_common_msg_hdr) + sizeof(t_mtp3_protocol_data) + user_data_size;

	/* build the Protocol Data variable length parameter */
	mtp3_msg.mtp3d.vlph.tag = 0x0210; /* from RFC 3332 */
	mtp3_msg.mtp3d.vlph.length = sizeof(t_mtp3_protocol_data) + user_data_size;
	mtp3_msg.mtp3d.opc = 822;
	mtp3_msg.mtp3d.dpc = 999;
	mtp3_msg.mtp3d.si = SI_SCCP;
	mtp3_msg.mtp3d.ni = NI_NATIONAL;
	mtp3_msg.mtp3d.mp = MP_3;
	mtp3_msg.mtp3d.sls = get_sls(); /* user app function to determine SLS */

	/* send the message using sendto; the size of the message for sendto is 
	   found in mtp3_msg.cmh.message_length */
 


ERROR Message

The encoding of the message is as follows:

 

	code segment here

 


m3ua.h

 
/****************************************************************************
m3ua.h : 

M3UA and Local API interface definitions.
Reference: RFC3332 September 2002

Copyright (C) 2004  Xygnada Technology, Inc.

****************************************************************************/
#include <stdint.h>

 
The "packed" attribute is used to ensure the data structure elements are assembled by the compiler exactly as written without any extra padding. This is necessary for communications between systems that may have been compiled using different compilers with varying defaults rules on how to map structures into octet ranges.
 

#ifndef PACKED
#define PACKED __attribute__ ((packed))
#endif

 


Common Message Header Structure

 
typedef struct
{
	uint8_t		version 	PACKED;
	uint8_t		reserved 	PACKED;
	uint8_t		message_class 	PACKED;
	uint8_t		message_type	PACKED;
	uint32_t	message_length	PACKED;
} t_common_msg_hdr;

enum	e_m3ua_protocol_version
{
	M3UA_PV_REL_1_0		= 1,
};

enum	e_m3ua_message_class
{
	M3UA_MC_MGMT		= 0,
	M3UA_MC_TRANSFER	= 1,
	M3UA_MC_SS7_SNM		= 2,
	M3UA_MC_ASP_STATE_MTC	= 3,
	M3UA_MC_ASP_TRAF_MTC	= 4,
	M3UA_MC_RSVD_5		= 5,
	M3UA_MC_RSVD_6		= 6,
	M3UA_MC_RSVD_7		= 7,
	M3UA_MC_RSVD_8		= 8,
	M3UA_MC_ROUTE_KEY_MGMT	= 9,
};

enum	e_m3ua_message_type_mgmt
{
	M3UA_MT_MGMT_ERR	= 0,
	M3UA_MT_MGMT_NTFY	= 1,
};

enum	e_m3ua_message_type_transfer
{
	M3UA_MT_X4_RSVD_0	= 0,
	M3UA_MT_X4_DATA		= 1,
};

enum	e_m3ua_message_type_ssnm
{
	M3UA_MT_SSNM_RSVD_0	= 0,
	M3UA_MT_SSNM_DUNA	= 1,
	M3UA_MT_SSNM_DAVA	= 2,
	M3UA_MT_SSNM_DAUD	= 3,
	M3UA_MT_SSNM_SCON	= 4,
	M3UA_MT_SSNM_DUPU	= 5,
	M3UA_MT_SSNM_DRST	= 6,
};

enum	e_m3ua_message_type_asp_state_mtc
{
	M3UA_MT_ASPSM_RSVD_0	= 0,
	M3UA_MT_ASPSM_UP	= 1,
	M3UA_MT_ASPSM_DN	= 2,
	M3UA_MT_ASPSM_BEAT	= 3,
	M3UA_MT_ASPSM_UP_ACK	= 4,
	M3UA_MT_ASPSM_DN_ACK	= 5,
	M3UA_MT_ASPSM_BEAT_ACK	= 6,
};

enum	e_m3ua_message_type_asp_traffic_mtc
{
	M3UA_MT_ASPTM_RSVD_0	= 0,
	M3UA_MT_ASPTM_AC	= 1,
	M3UA_MT_ASPTM_IA	= 2,
	M3UA_MT_ASPTM_AC_ACK	= 3,
	M3UA_MT_ASPTM_IA_ACK	= 4,
};

enum	e_m3ua_message_type_route_key_mgmt
{
	M3UA_MT_RKM_RSVD_0	= 0,
	M3UA_MT_RKM_REG_REQ	= 1,
	M3UA_MT_RKM_REG_RSP	= 2,
	M3UA_MT_RKM_DEREG_REQ	= 3,
	M3UA_MT_RKM_DEREG_RSP	= 4,
};
 


Variable Length Parameter Structures

 

typedef struct
{
	uint16_t	tag		PACKED;
	uint16_t	length		PACKED;
} t_var_len_parm_hdr;

typedef struct
{
	t_var_len_parm_hdr	vlph		PACKED;
	/* the size of ud is arbitrary */
	uint8_t			ud[1500]	PACKED;
} t_generic_var_len_parm;

 


MTP3 Protocol Data Structure

 
typedef struct
{
	t_var_len_parm_hdr	vlph		PACKED;
	uint32_t		opc		PACKED;
	uint32_t		dpc		PACKED;
	uint8_t			si		PACKED;
	uint8_t			ni		PACKED;
	uint8_t			mp		PACKED;
	uint8_t			sls		PACKED;
} t_mtp3_protocol_data;
 


Simple Protocol Data Structure

It is composed of a Common Message Header (described in the Section called Common Message Header Structure) and a single variable length parameter called the Protocol Data and is described in RFC 3332 Section 3.3.1. and and in the Section called MTP3 Protocol Data Structure.

 
typedef struct
{
	t_common_msg_hdr	cmh		PACKED;
	t_mtp3_protocol_data	mtp3d		PACKED;
	/* the size of ud is arbitrary */
	uint8_t			ud[1500]	PACKED;
} t_user_prot_data_simple;
 


Point Code Parameter

 
typedef struct
{
	t_var_len_parm_hdr	vlph		PACKED;
	uint32_t		pc		PACKED;
} t_pc;
 


SS7 Signaling Network Message Data Structure

 
typedef struct
{
	t_common_msg_hdr	cmh		PACKED;
	t_pc			affected_pc	PACKED;
} t_ssnm_1;
 


ss7box Configuration

ss7box configuration (ref. Chapter 3) is modified to enable application server support, assign the communication parameters, and to define routes used by the application server

The LOCAL_API section of the ss7box configuration file contains four items.

  • CONFIGURED: takes values of either 0 (feature disabled) or 1 (feature enabled).

  • PORT: The port used by ss7box and the application server. The most common method of port assignment is maintained by the Internet Assigned Numbers Authority. Making a choice in the range from 49152 through 65535 is probably safe.

  • SS7BOX_IPV4: The IPv4 address of ss7box known to the application server.

  • AS_IPV4: The IPv4 address on the application server known to ss7box.

The relevant section of the ss7box configuration file is shown below:
[LOCAL_API]
#
# 
#
CONFIGURED	1
PORT		54000
SS7BOX_IP	127.0.0.25
AS_IP		127.0.0.27


Sample Application Server


Chapter 7. MTP3 User Adpatation Layer (M3UA) Interface

Note

Under development. Not currently available.


Appendix A. Cabling

This section specifies the data connections between Sangoma T1/E1 cards and DDS56/64 cards.


The Basics

First we review some concepts and terms used to describe the cables that are specified in this Appendix.


The Miniature 8-Position Modular Connector

The miniature 8 position modular non-keyed connector (plugs and jacks) specified in ISO 8877 and T1.403 is widely and incorrectly known as the RJ45 connector. It is used for all Sangoma WAN port connections described in this document.

Figure A-1. 8 Position Modular Connector - Male

Figure A-2. 8 Position Modular Connector - Female


Universal Service Order Codes

This section decribes the RJ48C and RJ48S Universal Service Order Codes. It should become clear after reading this section why the 8 position modular connector is not an RJ45 connector. The same connector is used for both RJ45 and RJ48 applications.

The T1/E1/DDS circuits all have a transmit circuit and a recieve circuit. The transmit and the receive circuits each have two connections called tip and ring which correspond to polar orientation with respect to ground. Tip is positive and ring is negative. Each of the four connections has a unique label that associates it with the transmit or receive circuit, and identifies its polar association.

In both Figure A-3 and Figure A-4 T and R are tip and ring respectively, and comprise the receive circuit. T1 and R1 are the tip and ring or the transmit circuit.

It is important to keep in mind the network point of reference when identifying transmitters and receivers in pinout diagrams. Note that in both diagrams the connection is described for the DTE. Of course, at the opposite end of a DTE transmitter you must have a DCE receiver. The rules of connecting T1/E1/DDS circuits is to 1) connect transmitters to receivers, 2) connect tips to tips, and 3) connect rings to rings.

Table A-1. Basic 4-Wire Serial Connection Rules

DTEDCE
rx ringtx ring
rx tiptx tip
tx ringrx ring
tx tiprx tip

Figure A-3. RJ48C - T1/E1 DTE Connections

Figure A-4. RJ48S - DDS56/64 DTE Connections


Sangoma Network Cables

This section specifies the network cables between a Sangoma port as the DTE and a network DCE.


Sangoma T1/E1 Network Cable

Figure A-5. Sangoma T1/E1 Network Cable Pinouts


Sangoma DDS Network Cable


Sangoma Back-to-Back Cables

This section specifies the back-to-back cables between two Sangoma ports.


Sangoma T1/E1 Back-to-Back Cable


Sangoma DDS Back-to-Back Cable


Sangoma Tap Monitor Cables

This section specifies the tap monitor cables for using a Sangoma dual port card as a passive monitor.


Sangoma T1/E1 Tap Monitor Cable

The monitor tap is composed of special cabling shown in Figure A-6 and a dual port Sangoma T1 card.

In Figure A-6 a "twist", or "cross-over", or "rolled" cable is shown along with the tap points. The twist cable is used to connect two DSU/CSU back-to-back. This is exactly how two Sangoma ports are connected to each other in the lab. All Sangoma cables in the lab are in the twist configuration unless otherwise noted.

The tap monitor is composed of a dual-port T1/E1 card and a modified twist cable as shown in Figure A-6. The receivers on each port of the tap-monitor card are used to listen to each side of the T1 cable.

Figure A-6. Sangoma T1/E1 Tap Monitor Cable Pinouts

Figure A-7. Sangoma T1/E1 Tap Monitor Cable Photo


Sangoma DDS Tap Monitor Cable


Sangoma T1/E1/DDS Loopback Cable

This section describes the general loopback cable.

Figure A-8. Pin Outs for the T1/E1/DDS Loopback Cable

Glossary

Adjacent Point Code
(APC)

A point code that represents the node that is on the opposite end (the remote end) of a linkset.

Destination Point Code
(DPC)

A point code that represents the node that is the intended recipient of a signal unit.

Point Code
(PC)

A unique numerical label for a SS7 network terminating node.

The ITU point code is a 14 bit unsigned integer. The ITU point code often is divided into subfields but ss7box only treats it as a single unsigned integer.

The ANSI point code is a 24 bit unsigned integer. This point code is always divided into three octets named network, cluster, and member and is written in documentation in the order: network-cluster-member.

Origination Point Code
(OPC)

A point code that represents the node that is the originator of a signal unit.

Self Point Code
(SPC)

A point code that represents the "self", or local node. The network and routing is described from the point of view of self point code.


Index

This is the Index.