SS7 MTP Sockets

NAME	SOCKET OPTIONS	SEE ALSO	RESTRICTIONS
SYNOPSIS	IOCTLS	NOTES	AUTHOR
DESCRIPTION	ERROR HANDLING	CAVEATS	HISTORY
ADDRESS FORMATS	ERRORS	DIAGNOSTICS	REFERENCES
SYSCTLS	EXAMPLES	BUGS

NAME

mtp - SS7 Message Transfer Part (MTP) Protocol

SYNOPSIS

#include <sys/socket.h>
#include <net/ss7.h>
mtp_socket = socket(PF_SS7, SOCK_NTWK_NSEQ, SOCK_PROT_NTWK);

DESCRIPTION

This is an implementation of the SS7 (Signalling System No. 7) MTP (Message Transfer Part) protocol defined in ITU-T Recommendation Q.704, ANSI T1.111.4 and ETSI 300 008-1.

When an MTP socket is created, the MTP Point Code to which it applies is unspecified. PDUs can be sent immediately using sendto(2) or sendmsg(2) with a valid destination address (including DPC - Destination Point Code and UP - User Part) as an argument. When connect(2) is called on the socket, the default destination address is set and datagrams can then be sent using send(2) or write(2) without specifying a destination address. It is still possible to set to other destinations by passing an address to sendto(2) or sendmsg(2).

To receive packets, the socket must be bound to a local address first by using bind(2), when this is not the case the socket layer will deliver messages for any local PC (Point Code) and UP (User Part) which is not already bound to a socket. Although this is analogous to udp(7) operation, it must be used with care and is a privileged operation.

All receive operations return only one packet. When the packet is smaller than the passed buffer, only that much data is returned, when it is bigger, the packet is truncated and the MSG_TRUNC flags is set.

SS7 options may be sent or received using the socket options described in ss7(7). They are only processed by the kernel when the appropriate sysctl is enabled (but still passed to the user even when it is turned off). See ss7(7).

When the MSG_DONTROUTE flag is set on sending, the destination address must refer to a local interface address and the packet is only sent to that interface.

MTP discards the packet when its total length exceeds the interface MTU (Maximum Transfer Unit) or SS7 SIF_MAX.

ADDRESS FORMATS

MTP uses the SS7 sockaddr_ss7 address format described in ss7(2).

SYSCTLS

The following sysctls can be accessed by the /proc/sys/net/ss7/conf/mtp/* files or with the sysctl(2) interface:

Default values are really only default-default values, and can be changed by changing the values in the /proc/sys/net/ss7/conf/mtp/default/* files. Default values are only effective to newly added SS7 MTP signalling points. Changing the default values will have an affect on all subsequently added SS7 MTP signalling points; existing signalling points will be unaffected.

protocol_variant

This sysctl is used to set the protocol variant associated with the SS7 MTP protocol module (signalling point). The default value is zero (0) corresponding to ITU-T Recommendation Q.704 (03/93). Protocol variants currently defined are as follows:

Value	Protocol Variant
`0`	ITU-T Recommendation Q.704 (03/93)
`1`	ETSI ETS 300 008-1
`2`	ANSI T1.111.4 (1992)

When the protocol variant is set, all other sysctls are set to the default values for that protocol variant. Therefore, to customize a protocol variant for other needs, set the protocol variant first, and then customize other sysctls. Default sysctls are set as follows:

Sysctl	Protocol Variant
Sysctl	0 (ITU-T)	1 (ETSI)	2 (ANSI)
`protocol_variant`	0	1	2
`transfer_function`	N (0)	N (0)	N (0)
`transfer_restricted`	N (0)	N (0)	Y (1)
`message_priority`	N (0)	N (0)	Y (1)
`multi_congest_levels`	N (0)	N (0)	Y (1)
`cluster_routing`	N (0)	N (0)	Y (1)
`ansi_sls_rotation`	N (0)	N (0)	Y (1)
`test_timers`	ITU-T values	ETSI values	ANSI values
`timers`	ITU-T values	ETSI values	ANSI values

transfer_function

Enables the optional ITU-T Q.704, ANSI T1.111.4 or ETSI ETS 300 008-1 transfer function (i.e. Signalling Transfer Point (STP) operation) on the specified PC (point code). Without this function enabled, messages which do not have a Destination Point Code (DPC) which corresponds to the Point Code (PC) assigned to the local end of the link will be discarded and logged.

transfer_restricted

Enables the optional ITU-T Q.704 Transfer-Restricted procedure option. Q.704 provides for a transfer-restricted procedure as a national option. ANSI T1.111.4 requires it. This enables this optional transfer-restricted procedure.

(Note that OpenSS7 will always respond with the optional behavior upon the receipt of a transfer-restricted message, this option only controls whether transfer-restricted messages will be generated.)

message_priority

Enables the optional ITU-T Q.704 (or ANSI T1.111.4) multiple message priorities option. Enables the use of the spare bits in the Service Information Octet (SIO) along side the Network Indicator (NI) bits to indicate Message Priority (MP). This is as in the ANSI case, where four levels or message priority are provided (priority 0, 1, 2, and 3).

multi_congest_levels

Enables the optional ITU-T Q.704 (or ANSI T1.111.4) multiple congestion levels. ITU-T Q.704 provides for multiple congestion levels as a national option. This enables the ANSI T1.111.4 style congestion levels (four congestion levels 0, 1, 2, and 3).

cluster_routing

Enables the optional ANSI T1.111.4 network- and cluster-routing and traffic management procedures. ANSI T1.111.4 provides for network- and cluster-routing and cluster transfer procedures for STPs. This enables the cluster-routing procedures. If transfer_function is not enabled, this option has no effect.

(Note that OpenSS7 will always respond with the optional behavior upon the receipt of a transfer-cluster message, this option only controls whether the transfer-cluster messages will be generated.)

ansi_sls_rotation

Enables the optional ANSI T1.111.4 style SLS rotation and link set load sharing rules. ANSI T1.111.5 SLS rotation rules are somewhat different than the ITU-T Q.705 SLS selection and link set load-sharing rules. This enables the ANSI style rules. If it is disabled, the ITU-T Q.705 rules are used.

test_timers

Signalling Link Test timer durations for MTP per ITU-T Q.707, ANSI T1.111.7 and ETSI ETS 300 008-1. Changing a timeout value will be effective upon the next starting of a timer of that type. Timers which are already running are not affected. Timer values are listed in the order indicated in the tables below (i.e. timer T1 and then timer T2). Timer values are set in jiffies (i.e. 10's of milliseconds for Intel Architectures under Linux). Values read and written to these sysctls are in jiffies.

Default values (in seconds) are as follows (minimum and maximum values are as per ITU-T Q.707, ANSI T1.111.7 and ETSI ETS 300 008-1):

T	Timeouts (sec)			Description
T	Min	Def	Max	Description
T1	4	8	12	Signalling link set test acknowledgement
T2	30	60	90	Signalling link set test

Currently, the values of the timeouts for test timers do not vary with protocol variant. The same ranges are used to ITU-T, ETSI and ANSI.

timers

MTP timers for SS7 operation per ITU-T Q.704, ANSI T1.111.4 and ETSI ETS 300 008-1. Changing a timeout value will be effective upon the next starting of a timer of that type. Timers which are already running are not affected. Timer values are listed in the order indicated in the tables below (i.e. starting with timer T1 and ending with timer T30). Timer values are set in jiffies (i.e. 10's of milliseconds for Intel Architectures under Linux). Values read and written to these sysctls are in jiffies.

Default values (in seconds) are as follows (minimum and maximum values are as per ITU-T Q.704, ANSI T1.111.4 and ETSI ETS 300 008-1):

All protocol variants
T	Timeouts (sec)			Description
T	Min	Def	Max	Description
T1	0.5	0.5	1.2	Delay to avoid message mis-sequencing on changeover
T2	0.7	1.4	2.0	Waiting for changeover acknowledgement
T3	0.5	0.8	1.2	Time controlled diversion-delay to avoid mis-sequencing on changeback
T4	0.5	0.8	1.2	Waiting for changeback acknowledgement (first attempt)
T5	0.5	0.8	1.2	Waiting for changeback acknowledgement (second attempt)
T6	0.5	0.8	1.2	Delay to avoid message mis-sequencing on controlled rerouting
T7	1.0	1.5	2.0	Waiting for signalling data link connection acknowledgement
T8	0.8	1.0	1.2	Transfer prohibited inhibition timer (transient solution)
T9	-	0	-	Not used
T10	30	45	60	Waiting to repeat signalling route set test message
T11	30	60	90	Transfer restricted timer
T12	0.8	1.2	1.5	Waiting for uninhibit acknowledgement
T13	0.8	1.2	1.5	Waiting for force uninhibit
T14	2.0	2.5	3.0	Waiting for inhibition acknowledgement
T15	2.0	2.5	3.0	Waiting to start signalling route set congestion test
T16	1.4	1.7	2.0	Waiting for route set congestion status update
T17	0.8	1.2	1.5	Delay to avoid oscillation of initial alignment failure and link restart

ITU-T Recommendation Q.704 (`protocol_variant == 0`)
ETSI ETS 300 008-1 (`protocol_variant == 1`)
T	Timeouts (sec)			Description
T	Min	Def	Max	Description
T18	0	58	59	Timer within a signalling point whose MTP restarts for supervising link and link set activation as well as the receipt of routing information
T19	67	68	69	Supervision timer during MTP restart to avoid possible ping-pong of TFP, TFR and TRA messages
T20	59	60	61	Overall MTP restart timer at the signalling point whose MTP restarts
T21	63	64	65	Overall MTP restart timer at a signalling point adjacent to one whose MTP restarts
T22	180	270	360	Local inhibit test timer
T23	180	270	360	Remote inhibit test timer
T24	0.5	0.5	0.5	Stabilising timer after removal of local processor outage, used in LPO latching to RPO (national option)
T25	-	0	-	Not used
T26	-	0	-	Not used
T27	-	0	-	Not used
T28	-	0	-	Not used
T29	-	0	-	Not used
T30	-	0	-	Not used

ANSI T1.111.4 (1992) (`protocol_variant == 2`)
T	Timeouts (sec)			Description
T	Min	Def	Max	Description
T18	-	0	-	Not used
T19	480	540	600	Supervision timer during MTP restart to avoid possible ping-pong of TFP, TFR and TRA messages
T20	90	100	120	Overall MTP restart timer at the signalling point whose MTP restarts
T21	90	100	120	Overall MTP restart timer at a signalling point adjacent to one whose MTP restarts
T22	(a)	270	(a)	Local inhibit test timer
T23	(a)	270	(a)	Remote inhibit test timer
T24	(a)	0.5	(a)	Stabilising timer after removal of local processor outage, used in LPO latching to RPO (national option)
T25	30.0	32.5	35.0	Timer at SP adjacent to restarting SP, waiting for traffic restart allowed message
T26	12.0	13.5	15.0	Timer at restarting SP waiting to repeat traffic restart waiting mesage
T27	2	3	5	Minimum duration of unavailability for full restart
T28	3	30	35	Timer at SP adjacent to restarting SP waiting for traffic restart waiting message
T29	60.0	62.5	65.0	Timer started when TRA sent in response to unexpected TRA or TRW
T30	30.0	32.5	35.0	Timer to limit sending of TFPs and TFRs in response to unexpected TRA or TRW
Note (a): These ranges and defaults are network dependent. Minimum values is 0 and maximum values is MAXINT.

SOCKET OPTIONS

To set or get an MTP socket option, call getsockopt(2) to read or setsockopt(2) to write the option with the socket family argument set to SOL_MTP. In addition, most SOL_SS7 socket options are valid on MTP sockets. For more information see ss7(7).

MTP_SIFMAX: Set or received the maximum SIF length for incoming and outgoing MTP PDUs. Values greater than the link interface SIF_MAX are ignored and have no effect.

IOCTLS

All of the ioctls described in socket(7) apply to ss7. The ioctls to configure gateway screening are documented in gws(7) from the bgws package. Ioctls to configure generic device parameters and described in ss7device(7). All of the ioctls which are described in ss7(7) are also applicable to MTP sockets.

There are no MTP specific ioctls at this time.

ERROR HANDLING

All fatal errors will be passed to the user as an error return even when the socket is not connected. This behavior differs from many other BSD socket implementations which don't pass any errors unless the socket is connected.

For compatibility with legacy code, it is possible to set the SO_BSDCOMPAT SOL_SOCKET option to receive remote errors only when the socket has been connected (except for EPROTO and EMSGSIZE). It is better to fix the code to handle errors properly than to enable this option. Locally generated errors are always passed.

When the SS7_RECVERR option is enabled, all errors are stored in the socket error queue and can be received by recvmsg(2) with the MSG_ERRQUEUE flag set.

Whan a network error occurs, MTP tries to route around the failure. If MTP is unable to route around the failure, the last received error for this user part is immediately reported.

ERRORS

All errors documented for socket(7) or ss7(7) may be returned by a send or received on an MTP socket.

ENOTCONN: The operation is only defined on a connected socket, but the socket wasn't connected.
EINVAL: Invalid argument passed.
EMSGSIZE: The SS7 PDU is longer than the SS7 MTU (SIF_MAX) on the link and it cannot be fragmented. MTP does not permit fragmentation of packets. Links combined in a link set may have different SS7 MTUs depending on the type of link and interface device. For more information, see link(7).
EACCES: The user tried to execute an operation without the necessary permissions.
EADDRINUSE: Tried to bind to an address already in use. For MTP this means that the specified user part in the address is already bound to another socket for the specified Point Code (PC).
ENOMEM and ENOBUFS: Not enough free memory available. This often means that the memory allocation is limited by the socket buffer limits, not by the system memory, but this is not 100% consistent.
ENOPROTOOPT and EOPNOTSUPP: Invalid socket options passed. Although it is possible to pass many of the socket options which correpsond to ip(7), many ip(7) options are invalid for SS7 and return one of these two errors.
EPERM: Users doesn't have permission to set high priority, change configuration, or send signals to the requested process group.
ESOCKTNOSUPPORT: The socket is not configured or an unknown socket type was requested.
EISCOMM: connect(2) was called on an already connected socket.
EALREADY: A connection operation on a non-blocking socket is already in progress.
ECONNABORTED: A connection was closed during an accept(2).
EPIPE: The connection unexpectedly closed or shut down by the other end. This applies to connected MTP sockets. When a socket is bound to a destination address, when the destination address becomes unavailable (in the MTP sense), this error will be returned and the SIG_PIPE signal raised if the socket options are appropriately set.
ENOENT: SIOCGSTAMP was called on a socket where no packet arrived.
EHOSTUNREACH: No valid routing table entry matches the destination address. This error is generated by SS7 when an attempt is made to send to a prohibited route set to a distant SEP (Signalling End Point) which is not currently accessible. This error can be caused by a transfer-prohibited message from an STP or for a prohibited route in the local routing table.
ENODEV: Network device not available or not capable of sending SS7.
ENOPKG: A kernel subsystem was not configured.

Other errors may be generated by the underlying or overlaying protocols; see ss7(7), raw(7) and socket(7)

EXAMPLES

NOTES

CAVEATS

When an MTP socket is not bound to a local PC (Point Code) and UP (User Part) with the bind(2) call, and a recvmsg(2) or other receive operation is specified, the socket will receive any message which is for any local point code and user part which is not already bound to a socket. This causes problems if multiple sockets are left unbound yet are involved in a receive operation as the kernel only delivers the packet to the first unbound socket. No other unbound socket will received the packet. Because of this, receiving on an unbound socket is a privileged operation.

DIAGNOSTICS

BUGS

As this is an ALPHA (experimental) release. As such, there are probably many unknown bugs.

The sysctls transfer_restricted, message_priority, multi_congest_levels, cluster_routing and ansi_sls_rotation are not implemented and have no effect at this time. The ANSI behavior is always chosen.

RESTRICTIONS

MTP does not really implement SS7_NTWK_NSEQ sockets any differently form SS7_NTKW_ISEQ sockets. The user of the socket must specify an SLS (Signalling Link Selection) code in the destination address which either provides in-sequence delivery or non-guaranteed in-sequence delivery as the user wishes. I do not intend to change this.

When multiple SPCs (Signalling Point Codes) are assigned to a host and the transfer_function option is enabled, it is assumed that there is connectivity for transferring messages between any of the SPCs defined. The gws(7) (Gateway Screening) package can be used to restrict the transfer of messages between local SPCs similar to the ipchains package for ip(7) with ipv4_forward enabled.

MTP sockets only support LSL (Low Speed Links) and not HSL (High Speed Links) nor broadband MTP.

ITU-T Rec. Q.700, Introduction to CCITT Signalling System No. 7,
ITU-T Rec. Q.701, Functional description of the message transfer part (MTP) of Signalling System No. 7,
ITU-T Rec. Q.702, Signalling data link,
ITU-T Rec. Q.703, Signalling link,
ITU-T Rec. Q.704, Signalling network functions and messages,
ITU-T Rec. Q.705, Signalling network structure,
ITU-T Rec. Q.706, Message transfer part signalling performance,
ITU-T Rec. Q.707, Testing and maintenance,
ITU-T Rec. Q.708, Assignment procedures for international signalling point codes,
ITU-T Rec. Q.709, Hypothetical signalling reference connection,
ITU-T Rec. Q.710, Simplified MTP for small systems

ANSI T1.110, General Information,
ANSI T1.111, Message Transfer Part (MTP)

ETSI ETS 300 008-1, Message Transfer Part (MTP),
ETSI ETS 300 008-2, Message Transfer Part (MTP),
ETSI ETS 300 336, Message Transfer Part (MTP),
ETSI ETS 300 346, Message Transfer Part (MTP)