'\" t
.\" -*- nroff -*-
.\"
.\" @(#) $Id: ss7raw.7,v 0.7 2000/10/08 23:57:05 brian Exp $
.\"
.\" =========================================================================
.\"
.\" This manpage is Copyright (C) 1997, 1998, 1999, 2000 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.
.\"
.\" Modified $Date: 2000/10/08 23:57:05 $ by $Author: brian $
.\"
.\" =========================================================================
.\"
.\" $Log: ss7raw.7,v $
.\" Revision 0.7  2000/10/08 23:57:05  brian
.\" Added raw SS7 socket man page.
.\"
.\" =========================================================================

.TH SS7RAW  7 "8 October 2000" "Linux Man Page" "Linux Programmer's Manual" 
.SH NAME
ss7raw \- Linux SS7 raw sockets
.SH SYNOPSIS
.B #include <sys/socket.h>
.br
.B #include <netss7/ss7.h>
.br
.BI "raw_socket = socket(PF_SS7, SOCK_RAW, int " protocol ); 
.SH "DESCRIPTION"
.PP
Raw SS7 sockets permit ferry clip testing and other experimentation with the
SS7 protocols in user space.  A raw SS7 socket sends ore receives SS7 PDUs
without invoking the protocol state machine at the specified
.I protocol
level and permits simulation and protocol testing.

Only processes with an effective user id of 0 or the
.B CAP_NET_RAW
capability are allowed to open raw sockets.

All primitives, PDUs or errors matching the
.I protocol
number specified for the raw socket are passed to this socket.

Raw SS7 sockets depend on the
.I protocol
specified.  The following
.I protocol
values are allowed:

.TP
.B SS7_PROT_LINK
This socket provides for the exchange of primitives and PDUs below the SS7
Link Level state machines (i.e. directly with the SS7 Link Interface).  The
socket will generate its own Link Level header (FSN/FIB, BSN/BIB, and LI)
when sending PDUs on the socket unless the
.B SS7_HDRINCL
socket option is enabled on the socket.

.TS
tab(:) allbox expand;
c s s s
c c s s
c a s s.
Level 2 Header Fields Modified on Sending
Field:Action
FSN/FIB:Supplied by socket
BSN/BIB:\^
LI:Calculated by socket
.TE

.sp 1
If
.B SS7_HDRINCL
is specified, all Level 2 header fields must be supplied by the user.

.TP
.B SS7_PROT_NTWK
This socket provides for the exchange of primitives and PDUs below the SS7
Network Level state machines (i.e., directly with the SS7 Link Level state
machines).  The socket will generate an SS7 Routing Label when sending a PDU
unless the
.B SS7_HDRINCL
socket option is enabled on the socket.

.TS
tab(:) allbox expand;
c s s s
c c s s
c a s s.
Level 3 Header Fields Modified on Sending
Field:Action
SI:T{
Supplied by user
T}
NI:\^
MP:\^
DPC:T{
Socket destination address when socket is
bound, otherwise, supplied by user.
T}
OPC:T{
Selected by MTP Routing
T}
SLS:T{
Selected by MTP State Machine
T}
.TE

.sp 1
If
.B SS7_HDRINCL
is specified and the SS7 DPC has a non-zero destination address, then the
destination address of the socket is used to route the primitive or PDU.
When
.B MSG_DONTROUTE
is specified, the destination address should refer to the adjacent address of
a local linkset, otherwise a routing table lookup is done anyways but routes
via Signalling Transfer Points are ignored.

.PP
In OpenSS7 for Linux 2.2 all SS7 header fields and characteristics can be
controlled using SS7 socket options, sysctls and ioctls.  This means that raw
SS7 sockets are usually only needed for simulation and testing.

When a packet is received, it is passed to any raw sockets which have been
bound to its protocol before it is passed to other protocol handlers (e.g.
kernel protocol modules).

.SH "ADDRESS FORMAT"

Raw SS7 sockets use the
.B sockaddr_ss7
address structure defined in
.BR ss7 (7).

.SH "SOCKET OPTIONS"
Raw socket options can be set with
.BR setsockopt (2)
and read with
.BR getsockopt (2)
by passing the 
.I SOL_RAW 
family flag. 

There are no socket options specific to raw SS7 sockets at this time.

In addition all 
.BR ss7 (7)
.B SOL_SS7 
socket options valid for datagram sockets are supported.

.SH "NOTES"

A raw socket can be bound to a specific local address using the 
.BR bind (2)
call.  If it isn't bound all packets with the specified SS7 protocol are
received.  In addition a RAW socket can be bound to a specific SS7 interface
device using
.B SO_BINDTODEVICE;
see 
.BR socket (7).

An
.B IPPROTO_RAW
socket is send only.
If you really want to receive all SS7 packets use a
.BR packet (7)
socket with the
.B ETH_P_SS7
protocol.

If you want to receive all SNTM PDUs for an MTP socket it is often better 
to use
.B SS7_RECVERR
on that particular socket; see
.BR ss7 (7).

Raw sockets may tap all SS7 protocols in Linux, even
protocols like MTP or SCCP which have a protocol module in the kernel. In
this case the packets are passed to both the kernel module and the raw
socket(s). This should not be relied upon in portable programs, other BSD 
socket implementation have differences here.

Linux never changes headers passed from the user when
.B SS7_HDRINCL
is enabled
(except for filling in some
zeroed fields as described for
.BR SS7_HDRINCL ).
This may differ from other implementations of raw sockets for SS7.

RAW sockets are generally rather unportable and should be avoided in programs
intended to be portable.

Sending on raw sockets should take the IP protocol from 
.B sin_port;
this ability was lost in Linux 2.2. Work around is to use
.B IP_HDRINCL.

.SH "ERROR HANDLING"
Errors originating from the network are only passed to the user when the
socket is connected or the 
.B SS7_RECVERR
flag is enabled. For connected sockets only 
.B EMSGSIZE   
and 
.B EPROTO 
are passed for compatibility. With
.B SS7_RECVERR
all network errors are saved in the error queue. 
.SH "ERRORS"
.TP
.B EMSGSIZE 
SS7 raw sockets do not return this error.  This is because it is intended for
testing and the user may send an intentionally long packet.
.TP
.B EPROTO
An ICMP error has arrived reporting a parameter problem.
.TP
.B EFAULT
An invalid memory address was supplied.
.TP
.B EOPNOTSUPP
Invalid flag has been passed to a socket call (like 
.BR MSG_OOB ).
.TP
.B EINVAL
Invalid argument.
.TP
.B EPERM
The user doesn't have permission to open raw sockets. Only processes
with a effective user id of 0 or the 
.B CAP_NET_RAW 
attribute may do that.
.SH "BUGS"
.PP
As this is an ALPHA (experimental) release.  As such, there are probably many
.I unknown
bugs.
.SH "RESTRICTIONS"
.PP
The SS7 raw packet capability was intended for testing the protocol
implementation itself.  Aside from protocol testing and test or simulation
application, raw SS7 sockets serve no purpose.
.SH "HISTORY"
.PP
The OpenSS7 package provides this BSD socket interface for SS7 and was first
provided as a module for Linux 2.2.
.SH "AUTHOR"
.PP
Brian F. G. Bidulock,
.IR "" < bidulock@openswitch.org >.
.PP
This man page borrows literally and heavily from the
.BR row (7)
man page for Linux written by Andi Kleen
.IR "" < ak@muc.de >.
.SH "SEE ALSO"
.PP
.BR ss7device (7),
.BR link (7),
.BR mtp (7),
.BR sccp (7),
.BR isup (7),
.BR tcap (7),
.BR gws (7),
.BR ip (7),
.BR raw (7),
.BR socket (7),
.BR socket (2),
.BR listen (2),
.BR connect (2),
.BR accept (2),
.BR bind (2),
.BR htonl (3),
.BR recvmsg (2),
.BR sendto (2),
.BR write (2),
.BR setsockopt (2),
.BR getsockopt (2),
.BR sysctl (2),
.BR ioctl (2).

.SH "REFERENCES"
.PP
.nf
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,
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 SPCs,
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 SCCP,
ITU-T Rec. Q.712, Definition and function of SCCP 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.
.fi
.PP
.nf
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).
.fi
.PP
.nf
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).
.fi