SS7DEV(7)

NAME
ss7dev - Low level access to OpenSS7 SS7 MTP Level 2 (Link) Devices

SYNOPSIS
#include <sys/ioctl.h>
#include <net/ss7if.h>

DESCRIPTION

This man page describes the sockets interface which is used to configure SS7 Link interface devices.

OpenSS7 supports some standards ioctls to configure SS7 Link level devices. They can be used on any SS7 socket, regardless of the family, protocol or socket type. They pass an ifreq structure.

struct ifreq
{
    char     ifr_name[IFNAMSIZE]; /* Interface name */
    union {
             struct sockaddr ifr_addr;
             struct sockaddr ifr_dstaddr;
             struct sockaddr ifr_broadcast;
             struct sockaddr ifr_netmask;
             struct sockaddr ifr_hwaddr;
             short           ifr_flags;
             int             ifr_ifindex;
             int             ifr_metric;
             int             ifr_mtu;
             struct ifmap    ifr_map;
             char            ifr_slave[IFNAMSIZ];
             char            ifr_newname[IFNAMSIZ];
             char *          ifr_data;
    };
}
struct ifconf
{
    int      ifc_len;        /* size of buffer */
    union {
             char *          ifc_buf; /* buffer address */
             struct ifreq *  ifc_req; /* array of structures */
    };
};

Normally, the user specifies which device to affect by setting ifr_name to the name of the interface. All other members of the stucture man share memory.

ADDRESS FORMATS

Addresses (SS7 Point Codes) are formatted as described in ss7(7).

SYSCTLS

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

ss7_link_pcr
    When this sysctl is enabled, the SS7 Link will perform PCR (Preventative Cyclic Retransmission) procedures for transmission and reception as described in ITU-T Q.703, ANSI T1.111 and ETS ETS 300 008. Otherwise, the link uses the default Basic procedures.

SOCKET OPTIONS

There are no device specific socket options. For SS7 socket options applicable to SS7 sockets, see ss7(7); for SS7 link specific options, see link(7).

IOCTLS

If an ioctl is marked as privileged, then using it requires an effective user id of 0 or the CAP_NET_ADMIN capability. If this is not the case EPERM will be returned.

SIOCGIFNAME
    Given the ifr_ifindex, return the name of the interface in ifr_name. This is the only ioctl which returns its result in ifr_name.

SIOCGIFINDEX
    Retreive the interface index of the interface into ifr_ifindex.

SIOCSIFNAME
    Changes the name of the interface specified in ifr_ifindex to ifr_ifnewname. This is a privileged operation.

SIOCGIFADDR, SIOCSIFADDR
    Gets or sets the interface address for the device using ifr_addr. For an SS7 device, this sets the local MTP PC (Point Code) associated with the link. The interface address can only be set on a link which is out-of-service.

SIOCGIFDSTADDR, SIOCSIFDSTADDR
    Gets or sets the destination address for the device using ifr_dstaddr. For an SS7 device, this sets the adjacent MTP PC (Point Code) associated with the link. The destination address can only be set on a link which is out-of-service.

SIOCGIFFLAGS, SIOCSIFFLAGS
    Get or set the active flags word of the device, ifr_flags contains a bit mask of the following values (some values are preset for SS7 vs. IP, and some values are not applicable):

    IFF_UP -
        Interface is running.
        Used normally (similar to IP) for SS7.

    IFF_BROADCAST -
        Valid broadcast address set.
        Not used for SS7; always set false (0).

    IFF_DEBUG -
        Internal debugging flag.
        Used normally (similar to IP) for SS7.

    IFF_LOOPBACK -
        Interface is a loopback interface.
        Not used for SS7; always set false (0).

    IFF_POINTTOPOINT -
        Interface is a point-to-point link.
        Not used for SS7; always set to true (1).

    IFF_RUNNING -
        Resources allocated.
        Used normally (similar to IP) for SS7.

    IFF_NOARP -
        No arp protocol, L2 destination address not set.
        Not used for SS7; always set false (0).

    IFF_PROMISC -
        Interface is in promiscuous mode.
        Not used for SS7; always set false (0).

    IFF_NOTRAILERS -
        Avoid use of trailers.
        Not used for SS7; always set true (1).

    IFF_ALLMULTI -
        Received all multicast packets.
        Not used for SS7; always set false (0).

    IFF_MASTER -
        Master of a load balancing bundle.
        Not used for SS7; always set false (0).

    IFF_SLAVE -
        Slave of a load balancing bundle.
        Not used for SS7; always set false (0).

    IFF_MULTICAST -
        Supports multicast.
        Not used for SS7; always set false (0).

    IFF_PORTSEL -
        Is able to select media type via ifmap.
        Not used for SS7

    IFF_AUTOMEDIA -
        Auto media selection active.
        Not used for SS7; always set false (0).

    IFF_DYNAMIC -
        The addresses are lost when the interface goes down.
        Not used for SS7; always set false (0).

    Setting the active flag word is a privileged operation, but any process may read it.

SIOCGIFMETRIC, SIOCSIFMETRIC
    Get or set the metric of the device using ifr_metric. This is currently not implemented; it sets ifr_metric to 0 of you attempt to read it and returns EINVAL if you attempt to set it. Eventually this will be used to set a SDT (Signalling Data Terminal) priority.

SIOCGIFMTU, SIOCSIFMTU
    Get or set the MTU (Maximum Transfer Unit), or, in SS7 terms, the SIF_MAX of a device using ifr_mtu. Setting the MTU is a privileged operation. Setting the MTU to other than a standard value for the interface (LSL, HSL) will cause non-conforming operation of the interface for SS7.

SIOCGIFMAP, SIOCSIFMAP
    Get or set the interface hardware parameters using ifr_map. Setting the paramters is a privileged operation.

    struct ifmap
    {
        unsigned long  mem_start;
        unsigned long  mem_end;
        unsigned short base_addr;
        unsigned char  irq;
        unsigned char  dma;
        unsigned char  port;
    };
    The interpretation of the ifmap structure depends on the device driver and the architecture.

SIOCGIFXQLEN, SIOCSIFXQLEN
    Get or set the transmit queue length of a device using ifr_qlen. Setting the transmit queue length is a privileged operation.

SIOCGIFCONF
    Return a list of interface (transport layer) addresses. The user passes an ifconf stucture as an argumnent to the ioctl. It contains a pointer to an array of ifreq structures in ifc_req and it length in bytes is ifc_len. The kernel fills the ifreqs with all current L3 interface addresses that are running: ifr_name contains the interface name (ss7link0, etc), ifr_addr the address. The kernel returns with the actual length in ifr_len; if it is equal to the original length, the user should assume that it overflowed and retry with a bigger buffer. When no error occurs, the ioctl returns 0; otherwise -1. Overflow is no error.

The following ioctls do not use the ifreq structure:

SS7IOCIFINHIBIT, SS7IOCIFUNIHIBIT
    Inhibits or unihibits the SDL (Signalling Data Link) associated with this SDT (Signalling Data Terminal). This is a pivileged operation.

Most protocols support their own ioctls to configure protocol specific interface options. See the protocol man pages for description. For configuring MTP Point Codes (PCs), see mtp(7).

In addition, some devices support private ioctls. These are not described here.

ERRORS

EADDRNOTAVAIL
    The requested address is not available. This error is returned in response to SIOCSIFADDR when the local PC (Point Code) does not exist locally; it is also returned for SIOCSIFDSTADDR for a missing adjacent PC (Point Code). One could use the SIOCADDRT ioctl to add the missing address.

EACCES
    The operation is a privileged operation and the caller does not have sufficient access permissions or capabilities to perform the operation.

EINVAL
    A parameter is invalid.

EFAULT
    A system fault occured.

EPERM
    The caller does not have permission to execute the operation on the socket descriptor.

SEE ALSO
ss7(7), link(7), mtp(7), packet(7), proc(7), netdevice(7), sysctl(2).

NOTES

Many of the ioctls which are available for netdevice(7) are ip(7) specific and are not applicable.

The names of interfaces with no addresses or that don't have the IFF_RUNNING flag set can be found via /proc/net/ss7/dev.

BUGS

As this is an ALPHA (experimental) release. As such, there are probably many unknown bugs. The SS7 LINK interface is not capable of performing PCR (Preventative Cyclic Restransmission) procedures and the ss7_link_pcr sysctl has no effect.

RESTRICTIONS

The SS7 LINK interface does not currently support the concept of dynamic assignment of Signalling Data Terminals as described in ITU-T Q.704, ANSI T1.111 and ETSI ETS 300 008. Each Signalling Data Terminal (ss7 device) is bound to a Signalling Data Link (communications path between signalling points).

AUTHOR

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

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

HISTORY

OpenSS7 is a kernel module for Linux written for the Linux 2.2 kernel.

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