  =========================================================================

  @(#) INSTALL,v 0.8.2.2 2002/04/15 04:14:43 brian Exp

  =========================================================================

  This README is Copyright (c) 2001-2002  OpenSS7 Corporation

  All Rights Reserved.

  Permission is granted to make and distribute verbatim copies of this
  README file 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 README
  file 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.

  -------------------------------------------------------------------------

  U.S. GOVERNMENT RESTRICTED RIGHTS.  If you are licensing this Software on
  behalf of the U.S. Government ("Government"), the following provisions
  apply to you.  If the Software is supplied by the Department of Defense
  ("DoD"), it is classified as "Commercial Computer Software" under
  paragraph 252.227-7014 of the DoD Supplement to the Federal Acquisition
  Regulations ("DFARS") (or any successor regulations) and the Government
  is acquiring only the license rights granted herein (the license rights
  customarily provided to non-Government users).  If the Software is
  supplied to any unit or agency of the Government other than DoD, it is
  classified as "Restricted Computer Software" and the Government's rights
  in the Software are defined in paragraph 52.227-19 of the Federal
  Acquisition Regulations ("FAR") (or any success regulations) or, in the
  cases of NASA, in paragraph 18.52.227-86 of the NASA Supplement to the
  FAR (or any successor regulations).

  =========================================================================

  Modified 2002/04/15 04:14:43 by brian

  =========================================================================


                  OPENSS7 STREAMS INSTALLATION INSTRUCTIONS
                  -----------------------------------------

  PRELIMINARY:

  You will need the LiS STREAMS package, version LiS-2.13.17 running on
  a Linux 2.4.x SP kernel.  This release should work fine with SMP
  kernels and SMP machines.  I have tested RH 2.4.7-10, RH 2.4.9-31 and
  Linux 2.4.18.

  UNPACKING:

  To begin with, you should have a copy of the tarred and gzipped source
  in the file strss7-0.8.2.tgz  Unpack it with

        tar -xzvf strss7-0.8.2.tgz

  in some convenient place and it will unpack into a strss7-0.8.2
  directory.


  COMPILING:

  To build the package, simply change to the unpacked strss7-0.8.2
  directory and type:

        make

  Make will run a bash configuration script which will check to make
  sure that you have the LiS STREAMS package properly installed on your
  system and so that it knows where to find the necessary LiS include
  files.  Normally, the script just finds things and it will not need to
  prompt you.  If it cannot locate a necessary directory or file, it
  will prompt you for such things as the location of your LiS source
  directory and library files.

  If there are any compile errors, they are fatal.  You will have to dig
  into the Makefiles and source code if you have a problem.  On a normal
  Linux system, all should go well.

  If there are no errors, make should build all of the necessary modules
  and test programs.

  There are three levels of debugging and assertion checking for which
  the package can be compiled:

        make none       # compile -O3 with debuggin turned off
        make safe       # compile -O2 and essential assertions only
        make debug      # compile -O2 and all tests and traces

  by default, `make' will compile `safe'.  This is the recommended mode
  for running all modules.  If you are interested in running some of the
  test programs, however, you may have to compile `debug' to get the
  additional debug facilities necessary to run the test programs.

  INSTALLATION:

  To run the test programs or load the ss7 or sctp stack for
  applications programs, you must first install the modules and
  development header files.  This can be done by merely typing (as root)

        make install

  If you don't like doing this a root, either use the -n option to make
  install to see what will happen first, or look at the install targets
  in the toplevel and subdirectory Makefiles.  Make install does four
  things:

  1)    Copies the openss7 modules to your /lib/modules directory for
        the running kernel.  These modules are

        -rwxr-xr-x 1 root root  20717 Apr 14 17:30 streams-acb56.o
        -rwxr-xr-x 1 root root  58832 Apr 14 17:30 streams-inet.o
        -rwxr-xr-x 1 root root  67442 Apr 14 17:30 streams-m2pa-sdl.o
        -rwxr-xr-x 1 root root  67442 Apr 14 17:30 streams-m2pa-sl.o
        -rwxr-xr-x 1 root root 179861 Apr 14 17:30 streams-sctp.o
        -rwxr-xr-x 1 root root  23881 Apr 14 17:30 streams-sdl.o
        -rwxr-xr-x 1 root root  29563 Apr 14 17:30 streams-sdl-sctp.o
        -rwxr-xr-x 1 root root  11940 Apr 14 17:30 streams-sdl-udp.o
        -rwxr-xr-x 1 root root  27199 Apr 14 17:30 streams-sdt.o
        -rwxr-xr-x 1 root root  83319 Apr 14 17:30 streams-sl.o
        -rwxr-xr-x 1 root root  12311 Apr 14 17:30 streams-ss7lm.o

  2)    Creates several STREAMS character devices in /dev for you such
        as /dev/ss7-sdl-upd0.  They all begin with ss7- or sctp as follows:

        crw-rw-rw- 1 root root   5,   2 Apr 14 17:42 /dev/ptmx
        crw-rw-rw- 1 root root   5,   0 Apr 14 17:42 /dev/tty
        crw-rw-rw- 2 root root  30,  40 Apr 14 17:30 /dev/idp
        crw-rw-rw- 2 root root  30,  41 Apr 14 17:30 /dev/rawip
        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 /dev/arp
        crw-rw-rw- 2 root root  30,  37 Apr 14 17:30 /dev/egp
        crw-rw-rw- 2 root root  30,  34 Apr 14 17:30 /dev/ggp
        crw-rw-rw- 2 root root  30,  33 Apr 14 17:30 /dev/icmp
        crw-rw-rw- 2 root root  30,  32 Apr 14 17:30 /dev/ip
        crw-rw-rw- 2 root root  30,  35 Apr 14 17:30 /dev/ipip
        crw-rw-rw- 2 root root  30,  38 Apr 14 17:30 /dev/pup
        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 /dev/rip
        crw-rw-rw- 2 root root  30,  36 Apr 14 17:30 /dev/tcp
        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 /dev/udp
        crw-rw-rw- 1 root root 252,   0 Apr 14 17:30 /dev/ss7-sdl-udp0
        crw-rw-rw- 1 root root 248,   0 Apr 14 17:30 /dev/ss7-sdl-acb0
        crw-rw-rw- 1 root root 248,   1 Apr 14 17:30 /dev/ss7-sdl-acb1
        crw-rw-rw- 1 root root 248,   2 Apr 14 17:30 /dev/ss7-sdl-acb2
        crw-rw-rw- 1 root root 248,   3 Apr 14 17:30 /dev/ss7-sdl-acb3
        crw-rw-rw- 1 root root 240,   0 Apr 14 17:30 /dev/sctp_n
        crw-rw-rw- 1 root root 241,   0 Apr 14 17:30 /dev/sctp_t

        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 inet/arp
        crw-rw-rw- 2 root root  30,  37 Apr 14 17:30 inet/egp
        crw-rw-rw- 2 root root  30,  34 Apr 14 17:30 inet/ggp
        crw-rw-rw- 2 root root  30,  33 Apr 14 17:30 inet/icmp
        crw-rw-rw- 2 root root  30,  40 Apr 14 17:30 inet/idp
        crw-rw-rw- 2 root root  30,  32 Apr 14 17:30 inet/ip
        crw-rw-rw- 2 root root  30,  35 Apr 14 17:30 inet/ipip
        crw-rw-rw- 2 root root  30,  38 Apr 14 17:30 inet/pup
        crw-rw-rw- 2 root root  30,  41 Apr 14 17:30 inet/rawip
        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 inet/rip
        crw-rw-rw- 2 root root  30,  36 Apr 14 17:30 inet/tcp
        crw-rw-rw- 6 root root  30,  39 Apr 14 17:30 inet/udp

  3)    Appends character device aliases to your /etc/conf.modules or
        /etc/modules.conf file (whichever exists) to support kmod or
        kerneld automatic loading of the ss7 kernel modules when these
        character devices are opened.  The lines which are appended look
        like:

        alias char-major-240 streams-sctp     # driver sys sctp
        alias char-major-241 streams-sctp     # driver sys sctp
        alias char-major-248 streams-acb56    # driver ss7 acb56
        alias char-major-252 streams-sdl-udp  # driver ss7 sdl udp
        alias char-major-30  streams-inet     # driver sys inet

  4)    Copies the development header files into the /usr/include/ss7
        directory (where you can include them with, say, <ss7/lmi.h>) as
        follows:

        -rwxr-xr-x  1 root  root   5890 Apr 14 15:40 devi.h
        -rwxr-xr-x  1 root  root   6709 Apr 14 23:40 devi_ioctl.h
        -rwxr-xr-x  1 root  root  13252 Apr 14 15:40 lmi.h
        -rwxr-xr-x  1 root  root   4638 Apr 14 15:40 lmi_ioctl.h
        -rwxr-xr-x  1 root  root   6377 Apr 14 15:40 sdli.h
        -rwxr-xr-x  1 root  root   5386 Apr 14 15:40 sdli_ioctl.h
        -rwxr-xr-x  1 root  root  10144 Apr 14 15:40 sdti.h
        -rwxr-xr-x  1 root  root   6580 Apr 14 15:40 sdti_ioctl.h
        -rwxr-xr-x  1 root  root  14804 Apr 14 15:40 sli.h
        -rwxr-xr-x  1 root  root  14182 Apr 14 15:40 sli_ioctl.h

        Coplies the development header files int /usr/include/sys
        directory (normally /usr/src/LiS-2.13.17/include/sys) where you
        can include them with, say, <sys/npi.h> as follows:

        -rwxr-xr-x  1 root root  26709 Apr 14 15:39 npi.h
        -rwxr-xr-x  1 root root   6451 Apr 14 14:56 npi_ip.h
        -rwxr-xr-x  1 root root   6968 Apr 14 13:52 npi_sctp.h
        -rwxr-xr-x  1 root root  26553 Apr 14 23:07 tpi.h
        -rwxr-xr-x  1 root root   3217 Apr 14 14:56 tpi_ip.h
        -rwxr-xr-x  1 root root   3224 Apr 14 13:52 tpi_sctp.h
        -rwxr-xr-x  1 root root  18123 Apr 14 14:56 xti.h
        -rwxr-xr-x  1 root root   2734 Apr 14 14:56 xti_inet.h
        -rwxr-xr-x  1 root root   3476 Apr 14 23:07 xti_ip.h
        -rwxr-xr-x  1 root root   5449 Apr 14 13:52 xti_sctp.h

  TEST PROGRAMS:

  There are several test programs that you can run to check that your
  installation is correct and to serve as an example for how to write a
  user-level STREAMS application based on the SS7 and SCTP TPI and NPI
  interfaces.  These are located in the strss7-0.8.2/test/ directory as
  follows:

        -rwxr-xr-x  1 brian  users  246418 Apr 14 17:25 test-inet_raw
        -rwxr-xr-x  1 brian  users  246294 Apr 14 17:25 test-inet_tcp
        -rwxr-xr-x  1 brian  users  246418 Apr 14 17:25 test-inet_udp
        -rwxr-xr-x  1 brian  users  197118 Apr 14 17:24 test-m2pa
        -rwxr-xr-x  1 brian  users  203784 Apr 14 17:24 test-m2pa-sdl
        -rwxr-xr-x  1 brian  users  198355 Apr 14 17:24 test-m2pa-sl
        -rwxr-xr-x  1 brian  users  217144 Apr 14 17:24 test-q781
        -rwxr-xr-x  1 brian  users   69224 Apr 14 17:24 test-sctp
        -rwxr-xr-x  1 brian  users  228053 Apr 14 17:25 test-sctp_n
        -rwxr-xr-x  1 brian  users   64220 Apr 14 17:23 test-sctp_nc
        -rwxr-xr-x  1 brian  users   65155 Apr 14 17:23 test-sctp_ns
        -rwxr-xr-x  1 brian  users  233254 Apr 14 17:25 test-sctp_t
        -rwxr-xr-x  1 brian  users   59600 Apr 14 17:23 test-sdlacb
        -rwxr-xr-x  1 brian  users  215945 Apr 14 17:24 test-sdlsctp
        -rwxr-xr-x  1 brian  users   70214 Apr 14 17:24 test-sdludp
        -rwxr-xr-x  1 brian  users   71811 Apr 14 17:24 test-sdt
        -rwxr-xr-x  1 brian  users   84436 Apr 14 17:24 test-sl
        -rwxr-xr-x  1 brian  users   47673 Apr 14 17:23 test-tcpc
        -rwxr-xr-x  1 brian  users   47985 Apr 14 17:23 test-tcps
        -rwxr-xr-x  1 brian  users   47520 Apr 14 17:23 test-udpc
        -rwxr-xr-x  1 brian  users   47559 Apr 14 17:23 test-udps

  test-sdludp:
      Opens two of the /dev/ss7-sdl-udp0 Signalling Data Link UDP
      emulations of an SS7 signalling link and exchanges messages
      between the two.  This exercises the SDL, (Signalling Data Link)
      level of the MTP Level 2 stack using the UDP emulation.  You
      should see things like: successful, being printed.

  test-sdt:
      Opens two /dev/ss7-sdl-udp0 ss7 links just as test-sdl-udp, but
      pushes the "sdt" (Signalling Data Terminal) STREAMS module onto
      each half and communicates back and forth.  You should see things
      like: successful, being printed.

  test-sl:
      Opens two /dev/ss7-sdl-udp0 ss7 links just as test-sdl-udp, but
      pushes both a "sdt" and a "sl" (Signalling Link) STREAMS module
      onto each half.  The "sl" module implements the majority of the
      SS7 Level 2 state machines.  The test program send a "Power On"
      primitive to each link and then a "Start" primitive.  The links
      should align (after a few seconds) and then exchange an MSU back
      and forth, "Stop" the links, detach them and close them.  You
      should see things like: successful, being printed.

  test-q781:
      Opens two /dev/ss7-sdl-udp0 ss7 links and pushes a "sdt" and "sl"
      STREAMS module onto one half and uses the other half as a protocol
      tester for performing Q.781 conformance tests.  Running the
      program generates the output of 107 Q.781 test cases and
      demonstrates conformance to 97 test cases.  (The remaining 10 test
      casea are inconclusive because of the inability to "break Tx" on
      UDP.)  The two files:

        -rw-r--r--  1 brian  users  115252 Apr  2 02:22 test/log.shaper
        -rw-r--r--  1 brian  users  116501 Apr  2 02:22 test/log.tick

      show the output of my runs of the test-q781 program.

  test-m2pa:
      Opens three /dev/sctp_n (NPI Interface) streams and pushes the
      "m2pa" STREAMS module over one of them, and uses the other two as
      a protocol tester for performing modified Q.781 conformance tests.
      Running the program generates the output of 107 Q.781 tst cases
      and demonstrates conformance to 73 test cases.  (The remaining 34
      test cases are not applicable to M2PA.  The file:

        -rw-r--r--  1 brian  users   271103 Apr  2 02:22 test/log.m2pa

      shows the output of my runs of the test-m2pa program.

      For more information on the tests and their descriptions, see the
      documentation in strss7-0.8.2/doc/m2pa/

        488354 Apr  8 17:22 draft-bidulock-sigtran-m2pa-test-00.pdf
        301988 Apr  8 17:22 draft-bidulock-sigtran-m2pa-test-00.ps
        235150 Apr  8 17:22 draft-bidulock-sigtran-m2pa-test-00.txt

        458099 Apr  8 19:52 draft-bidulock-sigtran-m2pa-test-01.pdf
        302955 Apr  8 19:52 draft-bidulock-sigtran-m2pa-test-01.ps
        236958 Apr  8 19:52 draft-bidulock-sigtran-m2pa-test-01.txt

      You will also find all the M2PA drafts there as well:

         20197 Apr  2 01:52 draft-george-sigtran-m2pa-interop-00.txt
         39392 Apr  2 01:52 draft-george-sigtran-m2peer-00.txt
         42739 Apr  2 01:52 draft-george-sigtran-m2peer-01.txt
         45128 Apr  2 01:52 draft-george-sigtran-m2peer-02.txt
          1066 Apr  2 01:52 draft-george-sigtran-m2peer-03.txt
         48822 Apr  2 01:52 draft-ietf-sigtran-m2pa-00.txt
         60308 Apr  2 01:52 draft-ietf-sigtran-m2pa-01.txt
         76183 Apr  2 01:52 draft-ietf-sigtran-m2pa-02.txt
         93979 Apr  2 01:52 draft-ietf-sigtran-m2pa-03.txt
         90752 Mar  1 13:33 draft-ietf-sigtran-m2pa-04.txt

  test-acb:
      Opens two /dev/ss7-sdl-acb0 real ss7 links for the ACB56 card,
      just as the UDP test programs do above.  DO NOT USE THIS TEST
      PROGRAM: IT IS A WORK IN PROGRESS.

  test-sctp_n:
      Opens three /dev/sctp_n (NPI Interface) streams and performs
      loopback connection, disconnection and data transfer testing.
      This also performs some noise and disconnection tests as well.
      Sample output from this program can be found in
      strss7-0.8.2/test/log.sctp_n

        -rw-r--r--  1 brian  users  1070460 Apr  2 02:22 test/log.sctp_n

      This file shows the output of my runs of the test-sctp_n program.

  test-sctp_t:
      Opens three /dev/sctp_n (NPI Interface) streams and performs
      loopback connection, disconnection and data transfer testing.
      This also performs some noise and disconnection tests as well.
      Sample output from this program can be found in
      strss7-0.8.2/test/log.sctp_t

        -rw-r--r--  1 brian  users   863599 Apr  2 02:22 test/log.sctp_t

      This file shows the output of my runs of the test-sctp_t program.

  test-sctp_ns
  test-sctp_nc
      Opens three /dev/sctp_n (NPI Interface) streams, one on one host
      (test-sctp_nc) and two on another host (test-sctp_ns).  The two
      programs establish an association and then transfer data back and
      forth between the hosts at full speed.

  test-inet_raw
      Opens two /dev/rawip (TPI Interface) streams and performs looback
      testing of options management, binding and data transfer.  This
      program must be run with root priviledge to open the /dev/rawip
      streams.  It also performs CO access to CL services test by
      performing single-ended connection, disconnection and data
      transfer tests.

      Soon the SCTP and SSCOP drivers will be conveted to multiplexors
      that link several of these streams (ICMP/RAWIP) at boot time.

  test-inet_udp
      Opens two /dev/udp (TPI Interface) streams and performs loopback
      testing of options management, binding and data transfer.  It also
      performs CO access to CL services tests by performing single-ended
      connection, disconnection and data transfer tests.

      Soon the SS7/UDP drivers will be converted to act as a module
      pushed over this interface.

  test-inet_tcp
      Opens three /dev/tcp (TPI Interface) streams and performs loopback
      connection, disconnection and data transfer testing.

      NOTE:  THE TCP DRIVER IS NOT STABLE AT THIS TIME AND RUNNING THIS
      PROGRAM WILL LIKELY CRASH YOUR COMPUTER AT THIS TIME.

      Soon the TALI driver will be converted to a multiplexor that links
      several of these streams (TCP) at boot time.

  test-udps
  test-udpc
      Opens one /dev/udp stream (TPI Interface) each, one on each of
      two hosts.  The two programs transfer data back and forth between
      them at full speed.

      NOTE: THIS PROGRAM IS INCOMPLETE.

  test-tcps
  test-tcpc
      Opens three /dev/tcp (TPI Interface) streams, one on one host
      (test-tcpc), and two on another host (test-tcps).  The two
      programs establish a connection and then transfer data back and
      forth between the hosts at full speed.

      NOTE:  THE TCP DRIVER IS NOT STABLE AT THIS TIME AND RUNNING THIS
      PROGRAM WILL LIKELY CRASH YOUR COMPUTER AT THIS TIME.

  WHAT IF EVERYTHING GOES WRONG?

  Check to make sure that you have LiS STREAMS correctly installed on
  your system and that it can actually run.

  Hit our majordomo mailing list at openss7@openss7.org: to subscribe,
  send mail to majordomo@openss7.org with "subscribe openss7" in the
  body of the message.  Our mail archive is located on our home page at
  www.openss7.org.

  You can mail me at bidulock@openss7.org, but NO WARRANTY.

  Sun Apr 14 20:39:41 CDT 2002
  Brian F. G. Bidulock
  bidulock@openss7.org
