'\" t
.\" Don't change the line above. it tells man that tbl is needed.
.\" -*- nroff -*-
.\"
.\" @(#) $Id: mtp.7,v 0.7 2000/10/08 10:18:29 brian Exp $
.\"
.\" =========================================================================
.\"
.\" This manpage is Copyright (C) 1997, 1998, 1999, 2000 Brian Bidulock.
.\"
.\" All Rights Reserved.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\" 
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\" 
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" Modified $Date: 2000/10/08 10:18:29 $ by $Author: brian $
.\"
.\" =========================================================================
.\"
.\" $Log: mtp.7,v $
.\" Revision 0.7  2000/10/08 10:18:29  brian
.\" Added man pages.
.\"
.\" =========================================================================
.TH MTP 7 "7 October 2000" "Linux Man Page" "Linux Programmer's Manual" 
.SH "NAME"
mtp \- Signalling System No. 7 MTP (Message Transfer Part) Protocol
.SH "SYNOPSIS"
.in +5
.nf
#include <sys/socket.h>
#include <net/ss7.h>
mtp_socket = socket(PF_SS7, SOCK_NTWK_NSEQ, SOCK_PROT_NTWK);
.fi
.SH "DESCRIPTION"
.PP
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.
.PP
When an MTP socket is created, the MTP Point Code to which it applies is
unspecified.  PDUs can be sent immediately using
.BR sendto (2)
or
.BR sendmsg (2)
with a valid destination address (including
DPC - Destination Point Code and UP - User Part) as an argument.  When
.BR connect (2)
is called on the socket, the default destination address is set and datagrams
can then be sent using
.BR send (2)
or
.BR write (2)
without specifying a destination address.  It is still possible to set to
other destinations by passing an address to
.BR sendto (2)
or
.BR sendmsg (2).
.PP
To receive packets, the socket must be bound to a local address first by using
.BR 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
.BR udp (7)
operation, it must be used with care and is a privileged operation.
.PP
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
.B MSG_TRUNC
flags is set.
.PP
SS7 options may be sent or received using the socket options described in
.BR 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
.BR ss7 (7).
.PP
When the
.B 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.
.PP
MTP discards the packet when its total length exceeds the interface MTU
(Maximum Transfer Unit) or SS7
.BR SIF_MAX .
.SH "ADDRESS FORMATS"
.PP
MTP uses the SS7
.B sockaddr_ss7
address format described in
.BR ss7 (7).
.SH "SYSCTLS"
.PP
The following sysctls can be accessed by the
.B /proc/sys/net/ss7/mtp/*
files or with the
.BR sysctl (2)
interface:
.TP
.B 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.
.TP
.B 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.)
.TP
.B 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).
.TP
.B 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).
.TP
.B 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
.B 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.)
.TP
.B 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.
.TP
.BR 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):

.TS H
expand ;
c c c c c s s
r ne ne ne l s s.
T	ITU-T	ANSI	ETSI	Description
_
.TH
t1t	?	?	?	T{
T}
t2t	?	?	?	T{
T}
.TE

.TP
.BR 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):

.TS H
expand ;
c c c c c s s
r ne ne ne l s s.
T	ITU-T	ANSI	ETSI	Description
_
.TH
t1	0.8	?	?	T{
Delay to avoid message mis-sequencing on changeover
T}
t2	1.4	?	?	T{
Waiting for changeover acknowledgement
T}
t3	0.8	?	?	T{
Time controlled diversion-delay to avoid mis-sequencing on changeback
T}
t4	0.8	?	?	T{
Waiting for changeback acknowledgement (first attempt)
T}
t5	0.8	?	?	T{
Waiting for changeback acknowledgement (second attempt)
T}
t6	0.8	?	?	T{
Delay to avoid message mis-sequencing on controlled rerouting
T}
t7	1.5	?	?	T{
Waiting for signalling data link connection acknowledgement
T}
t8	1.0	?	?	T{
Transfer prohibited inhibition timer (transient solution)
T}
t9	\-	\-	\-	T{
Not used
T}
t10	45	?	?	T{
Waiting to repeat signalling route set test message
T}
t11	60	?	?	T{
Transfer restricted timer
T}
t12	1.2	?	?	T{
Waiting for uninhibit acknowledgement
T}
t13	1.2	?	?	T{
Waiting for force uninhibit
T}
t14	2.5	?	?	T{
Waiting for inhibition acknowledgement
T}
t15	2.5	?	?	T{
Waiting to start signalling route set congestion test
T}
t16	1.7	?	?	T{
Waiting for route set congestion status update
T}
t17	1.2	?	?	T{
Delay to avoid oscillation of initial alignment failure and link restart
T}
t18	10	?	?	T{
Timer within a signalling point whose MTP restarts for supervising link and link set activation as well as the receipt of routing information
T}
t19	68	?	?	T{
Supervision timer during MTP restart to avoid possible ping-pong of TFP, TFR and TRA messages
T}
t20	60	?	?	T{
Overall MTP restart timer at the signalling point whose MTP restarts
T}
t21	64	?	?	T{
Overall MTP restart timer at a signalling point adjacent to one whose MTP restarts
T}
t22	270	?	?	T{
Local inhibit test timer
T}
t23	270	?	?	T{
Remote inhibit test timer
T}
t24	0.5	?	?	T{
Stabilising timer after removal of local processor outage, used in LPO latching to RPO (national option)
T}
.TE
.SH "SOCKET OPTIONS"
.PP
To set or get an MTP socket option, call
.BR getsockopt (2)
to read or
.BR setsockopt (2)
to write the option with the socket family argument set to
.B SOL_MTP
In addition, most
.B SOL_SS7
socket options are valid on MTP sockets.  For more information see
.BR ss7 (7).
.TP
.B MTP_SIFMAX
Set or received the maximum SIF length for incoming and outgoing MTP PDUs.
Values greater than the link interface
.B SIF_MAX
are ignored and have no effect.
.SH "IOCTLS"
.PP
All of the ioctls described in
.BR socket (7)
apply to ss7.  The ioctls to configure gateway screening are documented in
.BR gws (7)
from the
.B bgws
package.  Ioctls to configure generic device parameters and described in
.BR ss7dev (7).
All of the ioctls which are described in
.BR ss7 (7)
are also applicable to MTP sockets.
.SH "ERROR HANDLING"
.PP
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.
.PP
For compatibility with legacy code, it is possible to set the
.B SO_BSDCOMPAT
.I SOL_SOCKET
option to receive
remote errors only when the socket has been connected (except for
.B EPROTO
and
.BR EMSGSIZE ).
It is better to fix the code to handle errors properly than to enable this
option.  Locally generated errors are always passed.
.PP
When the
.B SS7_RECVERR
option is enabled, all errors are stored in the socket error queue and can be
received by
.BR recvmsg (2)
with the
.B MSG_ERRQUEUE
flag set.
.PP
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.
.SH "ERRORS"
.PP
All errors documented for
.BR socket (7)
or
.BR ss7 (7)
may be returned by a send or received on an MTP socket.
.TP
.B ENOTCONN
The operation is only defined on a connected socket, but the socket wasn't
connected.
.TP
.B EINVAL
Invalid argument passed.
.TP
.B EMSGSIZE
The SS7 PDU is longer than the SS7 MTU
.BR "" ( 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 
.BR link (7).
.TP
.B EACCES
The user tried to execute an operation without the necessary permissions.
.TP
.B 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).
.TP
.BR 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.
.TP
.BR ENOPROTOOPT " and " EOPNOTSUPP
Invalid socket options passed.  Although it is possible to pass many of
the socket options which correpsond to
.BR ip (7)
many 
.BR ip (7)
options are invalid for SS7 and return one of these two errors.
.TP
.B EPERM
Users doesn't have permission to set high priority, change configuration,
or send signals to the requested process group.
.TP
.B ESOCKTNOSUPPORT
The socket is not configured or an unknown socket type was requested.
.TP
.B EISCOMM
.BR connect (2)
was called on an already connected socket.
.TP
.B EALREADY
A connection operation on a non-blocking socket is already in progress.
.TP
.B ECONNABORTED
A connection was closed during an
.BR accept (2).
.TP
.B 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
.B SIG_PIPE
signal raised if the socket options are appropriately set.
.TP
.B ENOENT
.B SIOCGSTAMP
was called on a socket where no packet arrived.
.TP
.B 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.
.TP
.B ENODEV
Network device not available or not capable of sending SS7.
.TP
.B ENOPKG
A kernel subsystem was not configured.
.PP
Other errors may be generated by the underlying or overlaying protocols; see
.BR ss7 (7),
.BR raw (7)
and
.BR socket (7).
\".SH "EXAMPLES"
.SH "SEE ALSO"
.PP
.BR ss7 (7),
.BR link (7),
.BR ss7device (7),
.BR gws (7),
.BR socket (7),
.BR raw (7),
.BR ip (7),
.BR udp (7),
.BR sysctl (2),
.BR getsockopt (2),
.BR setsockopt (2),
.BR bind (2),
.BR connect (2),
.BR accept (2),
.BR sendto (2),
.BR sendmsg (2),
.BR recvmsg (2),
.BR send (2),
.BR write (2).
\".SH "NOTES"
.SH "CAVEATS"
.PP
When an MTP socket is not bound to a local PC (Point Code) and UP (User Part)
with the
.BR bind (2)
call, and a
.BR 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.
\".SH "DIAGNOSTICS"
.SH "BUGS"
.PP
As this is an ALPHA (experimental) release.  As such, there are probably many
.I unknown
bugs.
.PP
The sysctls
.BR transfer_restricted ,
.BR message_priority ,
.BR multi_congest_levels ,
.B cluster_routing
and
.B ansi_sls_rotation
are not implemented and have no effect at this time.  The ANSI behavior is
always chosen.
.SH "RESTRICTIONS"
.PP
MTP does not really implement
.B SS7_NTWK_NSEQ
sockets any differently form
.B 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.
.PP
When multiple SPCs (Signalling Point Codes) are assigned to a host and the
.B transfer_function
option is enabled, it is assumed that there is connectivity for transferring
messages between any of the SPCs defined.  The
.BR gws (7)
(Gateway Screening) package can be used to restrict the transfer of messages
between local SPCs similar to the
.B ipchains
package for
.BR ip (7)
with
.B ipv4_forward
enabled.
.PP
MTP sockets only support LSL (Low Speed Links) and not HSL (High Speed Links)
nor broadband MTP.
.SH "AUTHOR"
.PP
Brian F. G. Bidulock,
.IR "" < bidulock@openswitch.org >.
.PP
This man page borrows literally and heavily from the
.BR upd (7)
and
.BR tcp (7)
man pages for Linux written by Andi Kleen
.IR "" < ak@muc.de >.
.SH "HISTORY"
.PP
OpenSS7 was implemented first for Linux for the Linux 2.2 kernels.
.SH "REFERENCES"
.PP
.nf
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.
.fi
.PP
.nf
ANSI T1.110, General Information,
ANSI T1.111, Message Transfer Part (MTP).
.fi
.PP
.nf
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).
.fi