SS7(7)

NAME
ss7 - Signalling System No. 7 for STREAMS

SYNOPSIS
#include <ss7/ss7.h>
fd = open("/dev/module", flags);
ret = ioctl(fd, cmd, ... /* arg */ );

DESCRIPTION
The OpenSS7 STREAMS package for SS7 consists of a number of loadable drivers and modules for Linux which are based on the LiS (Linux STREAMS) package. These drivers and modules implement the traditional SS7 stack as well as providing some IETF SIGTRAN and other SS7 over IP components. OpenSS7 protocol layers and levels are implemented as STREAMS drivers, modules and multiplexors. The OpenSS7 package provides an open specification of the interface to each of these drivers, modules and multiplexors to permit the mixing and matching of components in the SS7 stack as well as driver and module development at various levels. Also included in OpenSS7 is an SS7 Conifguration Daemon ss7d(8) which is responsible for configuration and intialization of the SS7 stack on the target host. This daemon is normally run from system initialization scripts reads an SS7 configuration file and opens drivers, pushes modules and links the resulting streams under multiplexors to form the entire SS7 stack for a particular configuration. The ss7d(8) is also responsible for interfacing with system level utilitities for collecting statistics and performing maintenance and manual configuration of a running SS7 stack. This man page describes some of the features which are common to the OpenSS7 streasms drivers, modules and multiplexors which are defined in the header file <ss7/ss7.h>.

  Protocol Configuration

Each OpenSS7 module defines a configuration structure (e.g. sl_conf_t) which contains the following two members:

    typedef struct module_config {
        ss7_ulong   pvar;   /* protocol variant */
        ss7_ulong   popt;   /* protocol options */
        ...
        /* additional level specific options */
        ...
    } module_config_t;

pvar
    The OpenSS7 stack provides the capability to run many SS7 protocol variants simultaneously. Therefore, all OpenSS7 stack modules contain a pvar configuration parameter which contains the selected protocol variant. Currently defined protocol variants are as follows:

    SS7_PVAR_ITUT_88 ITU-T Q.700 Series Blue Book
    SS7_PVAR_ITUT_93 ITU-T Q.700 Series White Book
    SS7_PVAR_ITUT_96 ITU-T Q.700 Series Grey Book
    SS7_PVAR_ITUT_00 ITU-T Q.700 Series Black Book
    SS7_PVAR_ETSI_88 ETSI ETS 300 Series (based on Blue Book)
    SS7_PVAR_ETSI_93 ETSI ETS 300 Series (based on White Book)
    SS7_PVAR_ETSI_96 ETSI ETS 300 Series (based on Grey Book)
    SS7_PVAR_ETSI_00 ETSI ETS 300 Series (based on Black Book)
    SS7_PVAR_ANSI_88 ANSI T1.111-1988
    SS7_PVAR_ANSI_92 ANSI T1.111-1992
    SS7_PVAR_ANSI_96 ANSI T1.111-1996
    SS7_PVAR_ANSI_00 ANSI T1.111-2000
    SS7_PVAR_JTTC_94 Japan TTC JQ.700 Series (based on Blue Book)

    These protocol variant parameters are defined in such a way that they can be tested against the following to find the major variant:

    SS7_PVAR_ITUT ITU-T Q.700 Series
    SS7_PVAR_ETSI ETSI ETS 300 Series (based on ITU-T)
    SS7_PVAR_ANSI ANSI T1.111
    SS7_PVAR_JTTC TTC JQ.700 Series

popt
    In addition, each OpenSS7 module can enable or disable a number of major options which are described in the standards specifications. Each OpenSS7 module has a popt configuration parameter which contains a bit vector of the enabled protocol options for that module. For a definition of the options at each level, see the man page for the specific interface.

Each OpenSS7 module recognizes protocol management primitives for configuration. These primitives are invoked by protocol layer management to configure or request configuratoin information from the layer service provider. Any M_DATA block attached to the primitives contains a module_conf_t structure (see above) which represents the configuration parameters. Configuration request should normally be sent as M_PCPROTO messages.

MGMT_CONFIG_SETUP
    Test if the configuration parameters provided in the attached M_DATA block are settable and correct. Any values set to 0xffffffff in the configuration parameters should not be tested for change by the layer service provider. When successful, this request also write locks the configuration until a successful MGMT_CONFIG_COMMIT is executed. This primitive contains only the mgmt_primitive member.

MGMT_CONFIG_COMMIT
    Commits the changes of a previous successful MGMT_CONFIG_TEST operation. No configuration data is associated with this request and any attached M_DATA is ignored. When successful, this request also releases the write locks on the configuration. This primitive contains only the mgmt_primitive member.

MGMT_CONFIG_SET
    Sets the configuration parameters to the values provided in the attached M_DATA block. This request will fail if the configuration is write locked. This primitive contains only the mgmt_primitive member.

MGMT_CONFIG_GET
    Get the configuration parameters. Any attached M_DATA is ignored. If the configuration is write locked, this request will only return the values which have been setup for a commit and not necessarily the current values. This primitive contains only the mgmt_primitive member.

MGMT_OK_ACK
    Upon success, the layer service provider will return a MGMT_OK_ACK to confirm a successful configuration request. The provider attached a M_DATA block which contains the module_conf_t structure with the results of the configuration request. This primitive uses the mgmt_ok_ack_t structure as follows:

    typedef struct {
        mgmt_ulong  mgmt_primitive; /* MGMT_OK_ACK */
        mgmt_ulong  mgmt_state;
        mgmt_ulong  mgmt_correct_primitive;
    } mgmt_ok_ack_t;

    mgmt_state
        Contains the management state of the interface.

    mgmt_correct_primitive
        Contains the request primitive which this response is acknowledging.

MGMT_ERROR_ACK
    Upon failure, the layer service provider will return a MGMT_ERROR_ACK to reject the configuration request due to an error. The provider attaches a M_DATA block which contains a module_conf_t structure with 0xffffffff in any values which are in error. This primitive uses the mgmt_error_ack_t structure as follows:

    typedef struct {
        mgmt_ulong  mgmt_primitive; /* MGMT_ERROR_ACK */
        mgmt_ulong  mgmt_state;
        mgmt_ulong  mgmt_error_primitive;
        mgmt_ulong  mgmt_errno;
        mgmt_ulong  mgmt_reason;
    } mgmt_error_ack_t;

    mgmt_state
        Contains the management state of the interface.

    mgmt_error_primitive
        Contains the request primitive which this response is acknowledging.

    mgmt_errno
        The error number indicating which error occured.

    mgmt_reason
        An additional error reason code.

    Error numbers which are specific to a configuration request rejection are as follows:

    MGMT_CONFLOCKED
        The request attempted to perform an illegal operation on a locked configuration.

    MGMT_NOCONFDATA
        The request was missing configuration data (i.e. missing M_DATA block or M_DATA block too short.

    MGMT_BADCONFDATA
        Some configuration data was invalid. The attached M_DATA block contains 0xffffffff in the data elements which are considered invalid.

SS7 STREAMS INTERFACES
The OpenSS7 stack provides drivers and modules at all levels of the SS7 stack below ISUP and TCAP. That is, it provides SS7 Level 2 (Link), SS7 Level 3 (Network), and SCCP (Signalling Connection Control Part) functionality. These protocol components have been broken into a number of sublevels, starting from the bottom-most, as follows:

sdli(7)
    The Signalling Data Link Interface (SDLI) implements SS7 Level 1 [Q702]. SDLI allows real and emulated transmission channels to be implemented for use under the sdt(8) module. It provides access to the DAEDT and DAEDR functions of the SS7 Signalling Link [Q703]. Header file <sys/sdli.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sdl(8)
        SDL module for use by SDLI compliant drivers.

    sdl_eth(8)
        SDL emulation using raw Ethernet (IEEE 802.2/802.3).

    sdl_ip(8)
        SDL emulation using raw Internet Protocol (IP).

    sdl_udp(8)
        SDL emulation using User Datagram Protocol (UDP).

    sdl_tcp(8)
        SDL emulation using Transmission Control Protocol (TCP).

    sdl_rtp(8)
        SDL emulation using Real-Time Transport Protocol (RTP).

    sdl_sctp(8)
        SDL emulation using Strean Control Transport Protocol (SCTP).

sdti(7)
    The Signalling Data Terminal Interface (SDTI) implements partial SS7 Level 2 [Q703]. SDTI allows real and emulated data terminals to be implemented for use under the sl(8) module. It provides access to the AERM, SUERM, EIM, DAEDR and DAEDT functions of the SS7 Signalling Link [Q703]. Header file <sys/sdti.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sdt(8)
        SDT module for use with SDLI compliant streams.

    vsdt(8)
        SDT module for emulating a virtual SDT.

    acb56t(8)
        SDT driver for the SeaLevel ACB56 ISA card.

    m2tp(8)
        SDT driver for the MTP Level 2 Tunneling Protocol (M2TP).

    soip(8)
        SDT driver for SS7 over IP.

sli(7)
    The Signalling Link Interface (SLI) implements complete SS7 Level 2 [Q703]. SLI allows real and emulated signalling links to be implemented for use under the sls(8) module. It provides access to all SS7 Level 2 state machine functions of the SS7 Signalling Link [Q703]. Header file <sys/sli.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sl(8)
        SL module for use with SDTI compliant streams.

    vsl(8)
        SL module for emulating a virual SL.

    acb56l(8)
        SL driver for the SeaLevel ACB56 ISA card.

    m2pa(8)
        SL driver for the MTP Level 2 Peer Adaptation (M2PA).

    m2ua(8)
        SL driver for the MTP Level User Adaptation (M2UA).

slsi(7)
    The Signalling Link Set Interface (SLSI) implements partial SS7 Level 3 [Q704]. SLSI allows real and emulated signalling link sets to be implemented for use under the mtp(8) multipexor. It provides access to SS7 Level 3 Link Set state machine functions of the SS7 Message Transfer Part [Q704]. Header file <sys/slsi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sls(8)
        SLS multiplexor for use with SLI compliant streams.

    vsls(8)
        SLS module for emulating a virtual SLS.

    m3tp(8)
        SLS driver for the MTP Level 3 Tunelling Protocol (M3TP).

mtpi(7)
    The Message Transfer Part Interface (MTPI) implements complete SS7 Level 3 [Q704]. MTPI allows real and virtual signalling points and signalling transfer points to be implemented for use under the sccp(8) and tcap(8) modules. It provides access to all SS7 Level 3 state machines and functions of SS7 Message Transfer Part [Q704]. Header file <sys/mtpi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    mtp(8)
        MTP multiplexor for use with SLSI compliant streams.

    m3pa(8)
        MTP module for the MTP Level 3 Peer Adaptation (M3PA).

    m3ua(8)
        MTP module for the MTP Level 3 User Adaptation (M3UA).

sccpi(7)
    The Signalling Connection Control Part Interface (SCCPI) implements complete SS7 Level 4 [Q711]. SCCPI allows real and virtual subsystems and global title translations to be implemented for use under the tcap(8) module. It provides access to all SS7 Level 4 state machines of the SS7 Signalling Connnection Control Part [Q711]. Header file <sys/sccpi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    sccp(8)
        SCCP module for use with MTPI compliant streams.

    sua(8)
        SCCP module for the SCCP User Adaptation (SUA).

isupi(7)
    The Integrated Services Digital Network (ISDN) User Part Interface (ISUPI) implements partial SS7 ISUP [Q767]. ISUPI allows call processing agents to attach to specific PC-PC-CIC ranges in control of trunk groups. It provides some basis low-level ISUP state machines (e.g. Unequipped CIC) of the SS7 ISUP [Q767]. Header file <sys/isupi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    isup(8)
        ISUP module for use with MTPI compliant streams.

    iua(8)
        ISUP module for the ISDN User Adaptation (IUA).

tcapi(7)
    The Transaction Capabilities Application Part Interface (TCAPI) implements partion SS7 TCAP [Q7??]. TCAPI allows transaction processing agents to attach to specific subsystem instances in control of database queries. It provides the TC state machines of the SS7 TCAP [Q???]. Header file <sys/tcapi.h> provides definitions for the interface. OpenSS7 drivers planned or released at this interface include:

    tcap(8)
        TCAP module for use with SCCPI compliant streams.

SEE ALSO
isupi(7), mtpi(7), sccpi(7), sdli(7), sdti(7), sli(7), slsi(7), tcapi(7), acb56l(8), acb56t(8), isup(8), iua(8), m2pa(8), m2tp(8), m2ua(8), m3pa(8), m3tp(8), m3ua(8), mtp(8), sccp(8), sdl_eth(8), sdl_ip(8), sdl_rtp(8), sdl_sctp(8), sdl_tcp(8), sdl_udp(8), sdt(8), sl(8), sls(8), soip(8), ss7d(8), sua(8), tcap(8), vsdt(8), vsl(8), vsls(8)

BUGS
Too many to mention.

AUTHOR

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

HISTORY
This STREAMS interface for SS7 is an orignal part of the OpenSS7 package.

REFERENCES

[Q702]
    ITU-T Recommendation Q.702 Signalling Data Link

[Q703]
    ITU-T Recommendation Q.703 Signalling Link

[Q704]
    ITU-T Recommendation Q.704 Message Transfer Part

[Q711]
    ITU-T Recommendation Q.711 Signalling Connection Control Part

[Q767]
    ITU-T Recommendation Q.767 Integrated Services Digital Network (ISDN) User Part

[Q77?]
    ITU-T Recommendation Q.77? Transaction Capabilities Application Part

COPYRIGHT NOTICE

Copyright © 1997-2001 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.