'\" t .\" Don't change the line above. it tells man that tbl is needed. .\" -*- nroff -*- .\" .\" @(#) $Id: ss7.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: ss7.7,v $ .\" Revision 0.7 2000/10/08 10:18:29 brian .\" Added man pages. .\" .\" ========================================================================= .TH SS7 7 "7 October 2000" "Linux Man Page" "Linux Programmer's Manual" .SH NAME ss7 \- Signalling System No. 7 Protocol .SH SYNOPSIS .in +0.5i .B #include .br .B #include .br .B ss7_socket = socket(PF_SS7, .IB socket_type ", " protocol ");" .SH DESCRIPTION .PP This is an implementation of the MTP (Message Transfer Part) protocol defined in the ITU-T Q.700 series recommendations, the ANSI T1.11x standards and the ETSI ETS 300.00x technical specifications. .B SS7 contains an SS7 Level 2 (Link Level) implementation conforming to ITU-T Rec. Q.703, ANSI T1.1111 and ETSI ETS 300 008 as well as an SS7 Level 3 (Network Level) implementation conforming to ITU-T Rec. Q.704, ANSI T1.111 and ETSI ETS 300 008 and an SS7 SCCP (Signalling Connection Control Part) implementation conforming to ITU-T Rec. Q.711-714, ANSI T1.112 and ETSI ETS 300 009. .PP The programmer's interface is BSD sockets compatible. For more information on sockets, see .BR socket (7). .PP An SS7 socket is created by calling the .BR socket (2) function as .sp 1 .in +0.5i .nf ss7_socket = socket(PF_SS7, socket_type, protocol); .fi .in -0.5i .PP Valid protocols and socket types are as follows: .TP .B SS7_PROT_LINK This protocol setting selects a socket using the SS7 Link Level protocol conforming to ITU-T Rev. Q.703, ANSI T1.111 and ETSI ETS 300 008. The following .BR link (7) socket types are supported: .RS .in +5 .TP .BR SS7_LINK_RAW " or " SOCK_RAW The socket is a .BR raw "(7) " link (7) socket. .RE .TP .B SS7_PROT_NTWK This protocol setting selects a socket using the SS7 Network Level protocol conforming to ITU-T Rec. Q.704, ANSI T1.111 and ETSI ETS 300 008. The following .BR mtp (7) socket types are supported: .RS .in +5 .TP .BR SS7_NTWK_NSEQ " or " SOCK_RDM The socket is a non-sequenced .BR mtp (7) socket. .TP .BR SS7_NTWK_ISEQ " or " SOCK_SEQPACKET The socket is a sequenced .BR mtp (7) socket. .TP .BR SS7_NTWK_RAW " or " SOCK_RAW The socket is a .BR raw "(7) " mtp (7) socket. .RE .TP .B SS7_PROT_SCCP This protocol setting selects a socket using the SS7 SCCP (Signalling Connection Control Part) protocol conforming to ITU-T Rec. Q.711-14, ANSI T1.112 and ETSI ETS 300 009. The following .BR sccp (7) socket types are supported: .RS .in +5 .TP .BR SS7_SCCP_CC_0 " or " SOCK_DGRAM The socket is a connection class 0 .BR sccp (7) socket. .TP .BR SS7_SCCP_CC_1 " or " SOCK_RDM The socket is a connection class 1 .BR sccp (7) socket. .TP .BR SS7_SCCP_CC_2 " or " SOCK_SEQPACKET The socket is a connection class 2 .BR sccp (7) socket. .TP .BR SS7_SCCP_CC_3 " or " SOCK_STREAM The socket is a connection class 3 .BR sccp (7) socket. .RE .PP When a process wants to receive new incoming packets or connections, it whould bind a socket to a local Message Transfer Part (MTP) or Signalling Connection Control Part (SCCP) using .BR bind (2). Only on SS7 socket may be bound to any given MTP (address, user-part) pair. When SS7ADDR_ANY is specified in the bind call, the socket will be bound to all user parts (MTP) or subsystem numbers (SCCP). When .BR listen "(2) or " connect (2) are called on an unbound socket, the socket is not automatically bound and an error will result. .PP An SCCP connection class 2 or 3 socket address that has been bound is unavailable for some time after closing, unless the .B SO_REUSEADDR flag has been set. Care should be taken when using this flag as it makes SCCP Connection Class 2 and 3 less reliable. .SH "ADDRESS FORMATS" .PP An MTP socket address is defined as a combination of a Service Indicator (SI), a Network Indicator (NI), and optional Message Priority (MP), a Destination Point Code (DPC), and a Signalling Link Selection (SLS). .sp 1 .in +0.5i .nf struct sockaddr_ss7 { sa_family_t ss7_family; /* address family: AF_SS7 */ unsigned char ss7_user_part; /* MTP user part */ unsigned char ss7_sls; /* signalling link to use */ struct ss7_addr ss7_addr; /* point code */ }; /* SS7 Point Code */ struct ss7_addr { u_int32_t s_addr; /* address in network byte order */ }; .fi .PP .I ss7_family is always set to .BR AF_SS7 . This is required; in Linux 2.2 most networking functions return .B EINVAL when this is missing. .I ss7_user_part contains the MTP User Part. MTP User Parts below 3 are reserved for MTP Management. Only processes with effective user id 0 or the .B CAP_NET_BIND_SERVICE capability may .BR bind (2) to these sockets. Note that the raw MTP protocol as such has no concept of an MTP User Part, they are only implemented by higher protocols like .BR sccp (7) and .BR isup (7). .PP .I ss7_addr is the SS7 Point Code (PC). The .I s_addr member of .I struct ss7_addr contains the SS7 Point Code (PC) in network byte order. .I ss7_addr must be accessed using the .BR htonl (3) library function. SS7 addresses are divided into Network, Cluster and Member addresses. Network addresses specify all signalling end points (SEPs) on a network, a cluster all SEPs within a cluster, and a member, a single SEP. Although the Signalling Point Code is placed in a 32-bit unsigned integer, the actual Point Code may be smaller depending on the SS7 Protocol Variant which is being used. For additional information, see .BR mtp (7). .PP Note that the point code and user part are always stored in network order. In particular, this means that you need to call .BR htonl (3) on the SS7 Point Code. .PP There are no special addresses in SS7. .SH "SYSCTLS" .PP These sysctls can be accessed by the .B /proc/sys/net/ss7/* files or with the .BR sysctl (2) interface. .PP No SS7 common sysctls are supported. For LINK specific sysctls see .BR link (7); for MTP, see .BR mtp (7); for SCCP, see .BR sccp (7); for ISUP, see .BR isup (7); for TCAP, see .BR tcap (7). .SH "SOCKET OPTIONS" .PP SS7 supports some protocol specific socket options that can be set with .BR setsockopt (2) and read with .BR getsockopt (2). The socket option level for SS7 is .BR SOL_SS7 . .TP .BR SS7_OPTIONS .TP .BR SS7_RECVERR Enable extended reliable error messag passing. When enabled on an MTP or SCCP connection class 0 or 1 socket, all generated errors will be queued in a per-socket error queue. When the user receives an error from a socket operation, the error can be received by calling .BR recvmsg (2) with the .B MSG_ERRQUEUE flag set. The .B sock_extended_err structure describing the error will be passed in an ancilliary message with the type .B SS7_RECVERR and the level .BR SOL_SS7 . This is useful for reliable error handling on unconnected sockets. The received data portion of the error queue contains the error packet. SS7 uses the .B sock_extended_error structure as follows: .I ee_origin is set to SO_EE_ORIGIN_SS7 for errors received from the remote MTP or SCCP protocol level and SO_EE_ORIGIN_LOCAL for locally generated errors. .IR ee_type " and " ee_code are set as follows: XXX. .I ee_info contains the MTU for .B EMSGSIZE errors. .I ee_data is currently not used. When the error originated from the network, all SS7 options enabled on the socket are contained in the error packet ad passed as control messages. The payload of the packet causing the error is returned as normal data. On SCCP connection class 2 and 3 sockets, .B SS7_RECVERR has slightly different semantics. Instead of saving the errors for the next timeout, it passes all incoming errors immediately to the user. This might be useful for very short-lived SCCP connections which need fast error handling. Use this option with care: it makes SCCP unreliable by not allowing it to recover properly from GTT routing shifts and other normal conditions and breaks the protocol specification. Note that SCCP connection class 2 and 3 has no error queue: .B MSG_ERRQUEUE is illegal on .BR SS7_SCCP_CC_2 " and " SS7_SCCP_CC_3 sockets. Thus all erros are returned by socket function return or .B SO_ERROR only. For raw sockets, .B SS7_RECVERR enables passing of all received errors to the application, otherwise, errors are only reported on connected sockets. It sets or retreives an integer boolean flag. .B SS7_RECVERR defaults to off. .TP .B SS7_SIF_MAX Retreive the current maximum message size for the current socket. Only valid when a link selection criteria has been provided. Returns an integer. Only valid as a .BR getsockopt (2). .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 are described in .BR ss7dev (7). .PP These ioctls can be accessed using .BR ioctl (2). The correct syntax is: .in +5 .nf int value; error = ioctl(mtp_socket, ioctl_type, &value); .fi .TP .B FIONREAD Returns the amount of queued unread data in the receive buffer. Argument is a pointer to an integer. .TP .B TIOCOUTQ Returns the amount of unsent data in the socket send queue in the passed integer value pointer. .SH "ERROR HANDLING" .PP When a network error occurs, SS7 tries to route around the failure. If MTP is unable to route around the failure, the last received error for this user part is returned in the return value fo the .BR send (2) or .BR recv (2) operation, unless the .B SS7_RECVERR options is set. If an SCCP packet is returned on error, the error is reported on the error queue when the .B SS7_RECVERR option is set. .SH "NOTES" .PP Many of the socket options, sysctls and ioctls which are provided with the NET4 package can also be applied to the SS7 subsystem; however, many of the non-applicable socket options, sysctls and ioctls will return .BR ENOPROTOPT " or " EOPNOTSUPP . .SH "ERRORS" .TP .B ENOTCONN The operation is only defined on a connected socket, but the socket wasn't connected. .TP .BR EINVAL Invalid argument passed. .TP .BR EMSGSIZE The SS7 PDU is longer than the SS7 MTU .BR "" ( SIF_MAX ) link and it cannot be fragmented. This normally only applies to .BR mtp (7) sockets. .BR mtp (7) does not permit fragmentation of packets; .BR sccp (7) does. .TP .B EACCES The user tried to execute an operation without the necessary permissions. .TP .BR EADDRINUSE Tried to bind to an address already in use. For .BR mtp (7) this means that the specified user part in the address is already bound to another socket for the specified Point Code (PC). For .BR sccp (7) this means that the specified subsystem number in the address is already bound to another socket for the specified Point Code (PC). For .BR isup (7) this means that the specified CIC (Circuit Identification Code) range is already bound to another socket for the specificed (local PC, remote PC) pair. .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 EISCONN .BR connect (2) was called on an already connected socket. This only really applies to .BR sccp (7) connection class 2 and 3 sockets. (Connection class 2 and 3 .BR sccp (7) sockets are not currently implemented.) .TP .BR EALREADY A connection operation on a non-blocking socket is already in progress. This only really applies to .BR sccp (7) connection class 2 and 3 sockets. (Connection class 2 and 3 .BR sccp (7) sockets are not currently implemented.) .TP .B ECONNABORTED A connection was closed during an .BR accept (2). This only really applies to .BR sccp (7) connection class 2 and 3 sockets. (Connection class 2 and 3 .BR sccp (7) sockets are not currently implemented.) .TP .B EPIPE The connection unexpectedly closed or shut down by the other end. This applies to connection-less as well as connection-oriented SS7 sockets. When a socket is bound to a destination address, when the destination address becomes unavailable (in the SS7 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 .BR ENOPKG A kernel subsystem was not configured. .PP In addition to the above error codes (which are the same as the error codes returned by .BR ip (7), SS7 provides the following protocol specific error codes: .PP Other errors may be generated by the overlaying protocols; see .BR mtp (7), .BR sccp (7), .BR raw (7) and .BR socket (7). .SH "BUGS" .PP As this is an ALPHA (experimental) release. As such, there are probably many .I unknown bugs. .SH "RESTRICTIONS" .PP I don't know that I ever intend to develop SCCP Connection Classes 2 and 3. These are not used very much (or at least not as much as Connection Classes 0 and 1). .SH "HISTORY" .PP The OpenSS7 package provides this BSD socket interface for SS7 and was first provided as a module for Linux 2.2. .SH "AUTHOR" .PP Brian F. G. Bidulock, .IR "" < bidulock@openswitch.org >. .PP This man page borrows literally and heavily from the .BR ip (7) man page for Linux written by Andi Kleen .IR "" < ak@muc.de >. .SH "SEE ALSO" .PP .BR ss7device (7), .BR link (7), .BR mtp (7), .BR sccp (7), .BR isup (7), .BR tcap (7), .BR gws (7), .BR ip (7), .BR raw (7), .BR socket (7), .BR socket (2), .BR listen (2), .BR connect (2), .BR accept (2), .BR bind (2), .BR htonl (3), .BR recvmsg (2), .BR sendto (2), .BR write (2), .BR setsockopt (2), .BR getsockopt (2), .BR sysctl (2), .BR ioctl (2). .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, ITU-T Rec. Q.711, Functional description of the SCCP, ITU-T Rec. Q.712, Definition and function of SCCP messages, ITU-T Rec. Q.713, Signalling connection control part formats and codes, ITU-T Rec. Q.714, Signalling connection control part procedures, ITU-T Rec. Q.715, Signalling connection control part user guide, ITU-T Rec. Q.716, Signalling connection control part performance. .fi .PP .nf ANSI T1.110, General Information, ANSI T1.111, Message Transfer Part (MTP), ANSI T1.112, Signalling Connection Control Part (SCCP), ANSI T1.113, Integrated Services Digital Network (ISDN) User Part, ANSI T1.114, Transaction Capability Application Part (TCAP), ANSI T1.116, Operations, Maintenance and Administration Part (OMAP). .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), ETSI ETS 300 009-1, Signalling Connection Control Part (SCCP), ETSI ETS 300 009-2, Signalling Connection Control Part (SCCP), ETSI ETS 300 009-3, Signalling Connection Control Part (SCCP), ETSI ETS 301 008, Signalling Connection Control Part (SCCP). .fi