SS7 Device

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

#include <sys/ioctl.h>
#include <ss7/ss7if.h>

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

OpenSS7 supports some standard ioctls to configure SS7 Link level devices. They can be used on any SS7 socket's file descriptor 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_broadaddr;
                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 structure may share memory.

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

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

Default values are really only default-default values, and can be changed by changing the values in the /proc/sys/net/ss7/conf/link/default/* files. Default values are only effective to newly registered SS7 LINK devices. Changing the default values will have an effect on all subsequently registered SS7 LINK devices.

ss7_link_pvar

This sysctl is used to set the protocol variant associated with the SS7 LINK device. The default value is 0, corresponding to ITU-T Recommendation Q.703 (06/93). Protocol variants currently defined are as follows:

Value	Protocol Variant
0	ITU-T Recommendation Q.703 (03/93)
1	ETSI ETS 300 008-1
2	ANSI T1.111.1992

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 ETSI ETS 300 008. Otherwise the link uses the default Basic procedures.

ss7_link_t1, ss7_link_t2, ss7_link_t2l, ss7_link_t2h, ss7_link_t3, ss7_link_t4n, ss7_link_t4e, ss7_link_t5, ss7_link_t6, ss7_link_t7

MTP Level 2 timers for SS7 operation per ITU-T Q.703, ANSI T1.111 and ETSI ETS 300 008-1. Changing a timeout values 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, for 64 kbit/s links) are as follows (minimum and maximum values are per ITU-T Q.703, ANSI T1.111 and ETSI ETS 300 008-1):

ITU-T Recommendation Q.703 (03/93) Timer Values

Timer	Min.	Def.	Max.	Description
ss7_link_t1	40.00	40.00	50.00	Timer ``aligned ready''
ss7_link_t2	5.00	5.00	150.00	Timer ``not aligned''
ss7_link_t2l	5.00	5.00	50.00	(Only used for automatic allocation of signalling data link terminals.)
ss7_link_t2h	70.00	70.00	150.00
ss7_link_t3	1.00	1.00	2.00	Timer ``aligned''
ss7_link_t4n	7.50	8.20	9.50	Normal proving period (64 kbit/s)
ss7_link_t4e	0.40	0.60	0.60	Emergency proving period (64 kbit/s)
ss7_link_t5	0.08	0.12	0.12	Timer ``sending SIB''
ss7_link_t6	0.30	0.60	0.60	Timer ``remote congestion''
ss7_link_t7	0.50	1.00	2.00	Timer ``excessive delay of acknowledgement''

ETSI ETS 300 008-1 Timer Values

Timer	Min.	Def.	Max.	Description
ss7_link_t1	40.00	40.00	50.00	Timer ``aligned ready''
ss7_link_t2	5.00	5.00	150.00	Timer ``not aligned''
ss7_link_t2l	-	-	-	(Not used.)
ss7_link_t2h	-	-	-	(Not used.)
ss7_link_t3	1.00	1.00	2.00	Timer ``aligned''
ss7_link_t4n	7.50	8.20	9.50	Normal proving period (64 kbit/s)
ss7_link_t4e	0.40	0.60	0.60	Emergency proving period (64 kbit/s)
ss7_link_t5	0.08	0.12	0.12	Timer ``sending SIB''
ss7_link_t6	0.30	0.60	0.60	Timer ``remote congestion''
ss7_link_t7	0.50	1.00	2.00	Timer ``excessive delay of acknowledgement''

ANSI T1.111.1992 Timer Values

Timer	Min.	Def.	Max.	Description
ss7_link_t1	13.00	13.00	13.00	Timer ``aligned ready''
ss7_link_t2	11.50	11.50	23.00	Timer ``not aligned''
ss7_link_t2l	-	-	-	(Not used.)
ss7_link_t2h	-	-	-	(Not used.)
ss7_link_t3	11.50	11.50	11.50	Timer ``aligned''
ss7_link_t4n	2.30	2.30	2.30	Normal proving period (64 kbit/s)
ss7_link_t4e	0.60	0.60	0.60	Emergency proving period (64 kbit/s)
ss7_link_t5	0.08	0.12	0.12	Timer ``sending SIB''
ss7_link_t6	0.30	0.60	0.60	Timer ``remote congestion''
ss7_link_t7	0.50	1.00	2.00	Timer ``excessive delay of acknowledgement''

Timer values are set in jiffies (i.e. 10's of milliseconds for Intel Architectures under Linux). Values read and written to these sysctls are in jiffies (seconds x 100).

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

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

Retrieve the interface index of the interface into ifr_ifindex.

SIOCSIFNAME

Changes the name of the interface specified in ifr_ifindex to ifr_newname. 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 of 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):

Device Flags

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 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 true (1).
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	Receive 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; always set false (0).
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 if you attempt to read it and returns EINVAL if you attempt to set it. Eventually this will be used to set an 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 parameters 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 structure as argument to the ioctl. It contains a pointer to an array of ifreq structures in ifc_req and its 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 ifc_len; it 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, SS7IOCIFUNINHIBIT

Inhibits or unihibits the Signalling Data Link associated with this Signalling Data Terminal. This is a privileged 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.

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 return for SOICSIFDSTADDR 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 permission 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.

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

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

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.

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 Retransmission) procedures and the ss7_link_pcr sysctl has no effect.

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

OpenSS7, <openss7@openss7.org>.

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

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

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

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)