MTP(7)

NAME
mtp - Signalling System No. 7 MTP (Message Transfer Part) 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 and ETSI ETS 300 008.

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(7).

SYSCTLS

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

transfer_function
    Enables the optional ITU-T Q.704, ANSI T1.111 or ETSI ETS 300 008 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.113 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.113) 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.113) multiple congestion levels. ITU-T Q.704 provides for multiple congestion levels as a national option. This enables the ANSI T1.113 style congestion levels (four congestion levels 0, 1, 2, and 3).

cluster_routing
    Enables the optional ANSI T1.113 network- and cluster-routing and traffic management procedures. ANSI T1.113 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.113 style SLS rotation and link set load sharing rules. ANSI T1.115 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.

t1t, t2t
    Signalling Link Test timer durations for MTP per ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008. 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. Default values (in milliseconds) are as follows (minimum and maximum values are as per ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008):
    T | ITU-T | ANSI | ETSI | Description
    t1t | ? | ? | ? |
    t2t | ? | ? | ? |

t1, t2, t3, t4, t5, t6, t8, t10, t15, t16, t17, t18, t19, t20, t21
    MTP timers for SS7 operation per ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008. 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. Default values (in seconds) are as follows (minimum and maximum values are as per ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008):
    T | ITU-T | ANSI | ETSI | Description
    t1 | 0.8 | ? | ? | Delay to avoid message mis-sequencing on changeover
    t2 | 1.4 | ? | ? | Waiting for changeover acknowledgement
    t3 | 0.8 | ? | ? | Time controlled diversion-delay to avoid mis-sequencing on changeback
    t4 | 0.8 | ? | ? | Waiting for changeback acknowledgement (first attempt)
    t5 | 0.8 | ? | ? | Waiting for changeback acknowledgement (second attempt)
    t6 | 0.8 | ? | ? | Delay to avoid message mis-sequencing on controlled rerouting
    t7 | 1.5 | ? | ? | Waiting for signalling data link connection acknowledgement
    t8 | 1.0 | ? | ? | Transfer prohibited inhibition timer (transient solution)
    t9 | - | - | - | Not used
    t10 | 45 | ? | ? | Waiting to repeat signalling route set test message
    t11 | 60 | ? | ? | Transfer restricted timer
    t12 | 1.2 | ? | ? | Waiting for uninhibit acknowledgement
    t13 | 1.2 | ? | ? | Waiting for force uninhibit
    t14 | 2.5 | ? | ? | Waiting for inhibition acknowledgement
    t15 | 2.5 | ? | ? | Waiting to start signalling route set congestion test
    t16 | 1.7 | ? | ? | Waiting for route set congestion status update
    t17 | 1.2 | ? | ? | Delay to avoid oscillation of initial alignment failure and link restart
    t18 | 10 | ? | ? | Timer within a signalling point whose MTP restarts for supervising link and link set activation as well as the receipt of routing information
    t19 | 68 | ? | ? | Supervision timer during MTP restart to avoid possible ping-pong of TFP, TFR and TRA messages
    t20 | 60 | ? | ? | Overall MTP restart timer at the signalling point whose MTP restarts
    t21 | 64 | ? | ? | Overall MTP restart timer at a signalling point adjacent to one whose MTP restarts
    t22 | 270 | ? | ? | Local inhibit test timer
    t23 | 270 | ? | ? | Remote inhibit test timer
    t24 | 0.5 | ? | ? | Stabilising timer after removal of local processor outage, used in LPO latching to RPO (national option)

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 ss7dev(7). All of the ioctls which are described in ss7(7) are also applicable to MTP sockets.

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).

SEE ALSO

ss7(7), link(7), ss7device(7), gws(7), socket(7), raw(7), ip(7), udp(7), sysctl(2), getsockopt(2), setsockopt(2), bind(2), connect(2), accept(2), sendto(2), sendmsg(2), recvmsg(2), send(2), write(2).

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.

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.

AUTHOR

Brian F. G. Bidulock, <bidulock@openswitch.org>.

This man page borrows literally and heavily from the upd(7) and tcp(7) man pages for Linux written by Andi Kleen <ak@muc.de>.

HISTORY

OpenSS7 was implemented first for Linux for the Linux 2.2 kernels.

REFERENCES

ITU-T Rec. Q.700, Introduction to CCITT Signalling System No. 7,
ITU-T Rec. Q.701, Functional description of the MTP,
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 SPCs,
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).