OpenSS7: SS7 Protocol

OpenSS7 | Brian F. G. Bidulock, © Copyright 2000, Brian F. G. Bidulock, All Rights Reserved.
All OpenSS7 website, www.openss7.org resources have provided as a courtesy of the OpenSwitch Project and Herlein Engineering.

# SS7

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

### NAME

ss7 - Signalling System No. 7 Protocol

### SYNOPSIS

    #include <sys/socket.h>
    #include <net/ss7.h>
    ss7_socket = socket(PF_SS7, socket_type, protocol);

### DESCRIPTION

This is an implementation of the MTP protocol defined in the ITU-T Q.700 series recommendations, the ANSI T1.11x standards and the ETSI 300 00x specifications. `ss7` contains an SS7 Level 2 (Link Level) implementation conforming to ITU-T Rec. Q.703, ANSI T1.111 and ETSI 300 008 as well as an SS7 Level 3 (Network Level) implementation conforming to ITU-T Rec. Q.704, ANSI T1.111 and ETSI 300 008 and an SS7 SCCP (Signalling Connection Control Part) implementation conforming to ITU-T Rec. Q.711-714, ANSI T1.112 and ETSI 300 009.

The programmer's interface is BSD sockets compatible. For more information on sockets, see `socket(7)`.

An SS7 socket is created by calling the `socket(2)` function as

    ss7_socket = socket(PF_SS7, socket_type, protocol).

Valid protocols and socket types are as follows:

`SS7_PROT_LINK`
  This protocol setting selects a socket using the SS7 Link Level protocol conforming to ITU-T Rec. Q.703, ANSI T1.111 and ETS 300 008. The following `link(7)` socket types are supported:

  `SS7_LINK_RAW` or `SOCK_RAW`
    The socket is a `raw(7)` `link(7)` socket.

`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 ETS 300 008. The following `mtp(7)` socket types are supported:

  `SS7_NTWK_NSEQ` or `SOCK_RDM`
    The socket is a non-sequenced `mtp(7)` socket.
  `SS7_NTWK_ISEQ` or `SOCK_SEQPACKET`
    The socket is a sequential `mtp(7)` socket.
  `SS7_NTWK_RAW` or `SOCK_RAW`
    The socket is a `raw(7)` `mtp(7)` socket.

`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 ETS 300 009. The following `sccp(7)` socket types are supported:

  `SS7_SCCP_CC_0` or `SOCK_DGRAM`
    The socket is a connection class 0 `sccp(7)` socket.
  `SS7_SCCP_CC_1` or `SOCK_RDM`
    The socket is a connection class 1 `sccp(7)` socket.
  `SS7_SCCP_CC_2` or `SOCK_SEQPACKET`
    The socket is a connection class 2 `sccp(7)` socket.
  `SS7_SCCP_CC_3` or `SOCK_STREAM`
    The socket is a connection class 3 `sccp(7)` socket.

When a process wants to receive new incoming packets or connections, it should bind a socket to a local Message Transfer Part (MTP) or Signalling Connection Control Part (SCCP) using `bind(2)`. Only one 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 `listen(2)` or `connect(2)` are called on an unbound socket, the socket is not automatically bound and an error will result.

An SCCP connection class 2 or 3 socket address that has been bound is unavailable for some time after closing, unless the `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.

### ADDRESS FORMATS

An MTP socket address is defined as a combination of a Service Indicator (SI), a Network Indicator (NI), an optional Message Priority (MP), a Destination Point Code (DPC), and a Signalling Link Selection (SLS).

    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 */
    };

`ss7_family` is always set to `AF_SS7`. This is required; in Linux 2.2 most networking functions return `EINVAL` when this is missing. `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 `CAP_NET_BIND_SERVICE` capability may `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 `sccp(7)` and `isup(7)`.

`ss7_addr` is the SS7 Point Code (PC). The `s_addr` member of `struct ss7_addr` contains the SS7 Point Code (PC) in network byte order. `ss7_addr` must be accessed using the `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 `mtp(7)`.

Note that the point code and user part are always stored in network order. In particular, this means that you need to call `htonl(3)` on the SS7 Point Code.

There are no special addresses in SS7.

### SYSCTLS

These sysctls can be accessed by the `/proc/sys/net/ss7/*` files or with the `sysctl(2)` interface.

No SS7 common sysctls are supported. For LINK specific sysctls see `link(7)`; for MTP, see `mtp(7)`; for SCCP, see `sccp(7)`; for ISUP, see `isup(7)`; for TCAP, see `tcap(7)`.

### SOCKET OPTIONS

SS7 supports some protocol specific socket options that can be set with `setsockopt(2)` and read with `getsockopt(2)`. The socket option level for SS7 is `SOL_SS7`.

`SS7_OPTIONS`
``
`SS7_RECVERR`
  Enable extended reliable error message 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 errors can be received by calling `recvmsg(2)` with the `MSG_ERRQUEUE` flag set. The `sock_extended_err` structure describing the error will be passed in an ancilliary message with the type `SS7_RECVERR` and the level `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 `sock_extended_error` structure as follows: 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. ee_type and ee_code are set as follows: XXX. ee_info contains the MTU for `EMSGSIZE` errors. 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 are 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, `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; `MSG_ERRQUEUE` is illegal on `SS7_SCCP_CC_2` and `SS7_SCCP_CC_3` sockets. Thus all errors are returned by socket function return or `SO_ERROR` only.

  For raw sockets, `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. `SS7_RECVERR` defaults to off.

`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 `getsockopt(2)`.
``

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

These ioctls can be accessed using `ioctl(2)`. The correct syntax is:

        int value;
        error = ioctl(mtp_socket, ioctl_type, &value);

`FIONREAD`
  Returns the amount of queued unread data in the receive buffer. Argument is a pointer to an integer.
`TIOCOUTQ`
  Returns the amount of unsent data in the socket send queue in the passed integer value pointer.

### ERROR HANDLING

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 return in the return value of the `send(2)` or `recv(2)` operation, unless the `SS7_RECVERR` option is set. If an SCCP packet is returned on error, the error is reported on the error queue when the `SS7_RECVERR` option is set.

### NOTES

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 `ENOPROTOOPT` or `EOPNOTSUPP`.

### ERRORS

`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. This normally only applies to `mtp(7)` sockets. `mtp(7)` does not permit fragmentation of packets; `sccp(7)` does.
`EACCES`
  The user tried to execute an operation without the necessary permissions.
`EADDRINUSE`
  Tried to bind to an address already in use. For `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 `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 `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.
`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.
`EISCONN`
  `connect(2)` was called on an already connected socket. This only really applies to `sccp(7)` connection class 2 and 3 sockets. (Connection class 2 and 3 `sccp(7)` sockets are not currently implemented.)
`EALREADY`
  A connection operation on a non-blocking socket is already in progress. This only really applies to `sccp(7)` connection class 2 and 3 sockets. (Connection class 2 and 3 `sccp(7)` sockets are not currently implemented.)
`ECONNABORTED`
  A connection was closed during an `accept(2)`. This only really applies to `sccp(7)` connection class 2 and 3 sockets. (Connection class 2 and 3 `sccp(7)` sockets are not currently implemented.)
`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 `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.

In addition to the above error codes (which are the same as the error codes returned by `ip(7)`), SS7 provides the following protocol specific error codes:

``

Other errors may be generated by the overlaying protocols; see `mtp(7)`, `sccp(7)`, `raw(7)` and `socket(7)`

### BUGS

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

### RESTRICTIONS

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

### HISTORY

The OpenSS7 package provides this BSD socket interface for SS7 and was first provided as a module for Linux 2.2.

### AUTHOR

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

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

### SEE ALSO

`ss7device(7)`, `link(7)`, `mtp(7)`, `sccp(7)`, `isup(7)`, `tcap(7)`, `gws(7)`, `ip(7)`, `raw(7)`, `socket(7)`, `socket(2)`, `listen(2)`, `connect(2)`, `accept(2)`, `bind(2)`, `htonl(3)`, `recvmsg(2)`, `sendto(2)`, `write(2)`, `setsockopt(2)`, `getsockopt(2)`, `sysctl(2)`, `ioctl(2)`

### REFERENCES

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,
ITU-T Rec. Q.711, Functional description of the Signalling Connection Control Part,
ITU-T Rec. Q.712, Definition and function of signalling connection control part 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

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)

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)

OpenSS7 | Brian F. G. Bidulock, © 2000, Brian F. G. Bidulock, All Rights Reserved. Last modified: $Date: 2000/10/05 07:45:37 $