OpenSS7: SS7 Device

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

# SS7 Device

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

### NAME

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

### SYNOPSIS

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

### DESCRIPTION

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.

### ADDRESS FORMATS

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

### SYSCTLS

These sysctls can be access 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 ETSI 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 socket 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`
  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.

### ERROR HANDLING

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

### EXAMPLES

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

### CAVEATS

### DIAGNOSTICS

### 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 Retransmission) 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 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)

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