
                                WANPIPE (tm)

        Sangoma Multiprotocol WAN Router for Linux Operating System

                               Release 2.4.2



                           U S E R   M A N U A L



                           Document Version 2.32

                             February 21, 1997


                             Author: Gene Kozin


             Copyright (c) 1995-1996 Sangoma Technologies Inc.
                            All Rights Reserved
                                      
------------------------------------------------------------------------------

                              C O N T E N T S

        Introduction ..........................................

        1. WANPIPE (tm) Basics ................................

        2. Installing SDLA Card ...............................

        3. Installing WANPIPE Software ........................

        4. Configuring WANPIPE ................................

        5. Configuring Protocol-Specific Subsystems ...........
           5.1. Configuring Frame Relay Subsystem .............
           5.2. Configuring Synchronous PPP Subsystem .........

        6. Trouble Shooting and Diagnostics ...................
           6.1. Kernel module load errors .....................
           6.2. Hardware initialization errors ................
           6.3. Protocol-specific configuration errors ........
           6.5. Trouble shooting WAN connections ..............

        7. Technical Support ..................................

        Appendix A. Frame Relay Basics ........................

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

Introduction

This manual is intended for Linux system administrators and defines procedures
required to install and configure Sangoma Synchronous Data Link Adapter (SDLA)
and WANPIPE (tm) software on your system.

Sangoma's WANPIPE (tm) is a server-based routing software that together with
SDLA card turns a PC running Linux operating system into inexpensive, yet high
performance, multiprotocol WAN TCP/IP router alowing you connect branch
offices to the head office over leased lines or wide variety of public data
networks or to get a high throughput Internet connection for your local area
network.

        Conventions Used in this Manual

        Command line syntax conventions used are as follows:

        command         portion of the command line represented as normal
                        text should be entered literally (exactly as printed)

        {argument}      portion of the command line enclosed in curly
                        braces represents variable name and should be
                        substituted by the actual object name, e.g. file name

        [option]        portion of the command line enclosed in square
                        brackets is optional and can be omitted



1. WANPIPE BASICS

WANPIPE (tm) is an add-on product for Linux operating system that together
with Sangoma's SDLA card allows to route TCP/IP traffic over a wide variety of
data links, such as leased lines, frame relay or X.25 public data networks.

WANPIPE (tm) is implemented as a set of kernel loadable modules and related
utilities providing for the full integration of WAN protocols into Linux
protocol stack.  WANPIPE modules form a two-layer hierarchy, as shown
below.

     +-------------- /dev/sdla0
     |  +----------- /dev/sdla1
     |  |  +-------- /dev/sdla2     /\/\/\/\/\/\/\/\/\/\/\/\/\
     |  |  |  . . . . . . . . .     |  Linux protocol stack  |
     |  |  |  .  +-- /dev/sdla7     +------------------------+
     |  |  |  .  |                        ^   ^   ^   ^         LINUX
     |  |  |  .  | ====================== | = | = | = | =================
   +----------------+  +--------------------+ |   |   |
   |                |  |                    | |   |   |
   |                |--| Frame Relay Module |---+ |   |
   |                |  |                    |   | |   |
   |                |  +--------------------+   |---+ |
   |   SDLA Driver  |------|    PPP Module      |   | |    WANPIPE (tm)
   |                |      +--------------------+   |---+
   |                |----------|    X.25 Module     |   |
   |                |          +--------------------+   |
   |                |--------------|     SDLC Module    |
   +----------------+              +--------------------+
     |  |  |  .  |           Protocol-specific modules
     |  |  |  .  | ======================================================
     |  |  |  .  |     +---------+                       SDLA HARDWARE
     |  |  |  .  +-----| SDLA #8 #---> to mainframe
     |  |  |           |___      |
     |  |  |               UUUUUU
     |  |  |           +---------+
     |  |  +-----------| SDLA #3 #---> to X.25 network
     |  |              |___      |
     |  |                  UUUUUU
     |  |              +---------+
     |  +--------------| SDLA #2 #---> to leased line
     |                 |___      |
     |                     UUUUUU
     |                 +---------+
     +-----------------| SDLA #1 #---> to frame relay network
                       |___      |
                           UUUUUU

The SDLA Driver is protocol-independent and responsible for managing SDLA
hardware.  It also provides interface to protocol-specific modules for
user-level applications through device the nodes in /dev directory.

All protocol-dependent functionality is implemented in protocol-specific
modules concerning with WAN protocol specifics and interfacing with Linux
protocol stack.

Modular design of WANPIPE (tm) allows to conserve system resources as modules
can be loaded and unloaded dynamically.  Also new WAN protocols can be easily
added to existing configuration by simply installing additional protocol-
spesific modules.

SDLA Driver can support up to eight SDLA cards allowing you to have up to
eight independent WAN links at the same time.

Sangoma's SDLA is an intelligent multiprotocol communications adapter for IBM
PC-compatible personal computers.  SDLA can provide PC connectivity to
various data links including frame relay, X.25, PPP, HDLC, SDLC, Bisync, etc.

Some of the key features of SDLA are:

    Intelligence
 
    SDLA has its own CPU and memory allowing it to work independently from a
    host PC.  Furthermore, all communications protocols are implemented in
    firmware runnig on the SDLA, thus freeing the host's CPU from routine
    protocol handling tasks.  This is particularly important in multiuser,
    multitasking environments, such as UNIX, where host CPU load is relatively
    high.

    Flexibility

    SDLA firmware is not stored on the adapter permanently.  Instead, it is
    downloaded onto it each time adapter is initialized by a host PC.  This
    allows the same SDLA card to support multiple communications protocols
    such as frame relay, X.25/HDLC, PPP, SDLC, Bisync, etc. by simply loading
    appropriate firmware modules.

    Upgradability and Extendability

    Loadable nature of the SDLA firmware provides for an easy way to upgrade
    and/or add new protocols, as they become available, without replacing or
    reconfiguring hardware, even without rebooting your system.

Currently the SDLA family includes four cards:

    S502A  - low-cost, non interrupt-capable card, up to 64 Kbps 
    S502E  - low-cost, interrupt-capable card, up to 112 Kbps
    S503   - low-cost, interrupt-capable card, up to 128 Kbps
    S508   - high-speed (up to T1/E1), interrupt-capable card, 2 ports

All SDLA cards use 8-kilobyte dual-port memory window to transfer data to and
from the host PC.  No DMA to worry about!  Memory window can be set at almost
any 8 kilobyte boundary within PC address range from A0000 to F0000 (hex).
Memory window location is set in software, not by jumpers.

SDLA cards (excluding S502A) can generate an interrupt request (IRQ) to the
host PC when host's attention is required.  S502E card offers selection of 4
IRQ levels set by jumpers, while S508 allows to choose from 7 software-
settable IRQ levels.

Each SDLA card occupies 3 to 4 consecutive I/O ports (depending on the adapter
type).  These ports are used by the adapter exclusively (i.e. they can not be
shared with other hardware).  S502A and S502E cards can be configured for four
different I/O port addresses allowing to install up to four adapters per PC,
while S508 and S503 give you a choise of 8 different I/O port addresses,
increasing maximum number of installed adapters to eight. 

When multiple SDLA cards are installed in one machine, each card has to be
assigned unique I/O port, memory window and, optionally, IRQ line.  However,
when adapter is shut down, both its memory window and IRQ line are freed and
can be used by other hardware.

All adapters use 8-bit data path.  This is not a limitation, but rather
convenience.  8-bit data bus provides throughput of about 1 Mbyte per second,
which is sufficient even for communications at T-1/E-1 speeds, while allowing
SDLA to be installed in any PC slot, including 8-bit slots found on some older
motherboards.

The following table compares hardware characteristics of different SDLA types.

------------------------------------------------------------------------------
Adapter type                    S502A     S502E      S503       S508
------------------------------------------------------------------------------
Number of communication ports   1         1          1          2
Interface type                  RS232     RS232/V35  RS232/V35  RS232/V35
Maximum speed, kbps             64        112        128        2048
Interrupt generation            no        2,3,5,7    2-5,7      3,4,5,7,10-12
On-board CPU speed, MHz         up to 8   up to 10   up to 10   up to 16
On-board memory size, kbytes    32/64     32/64      64         128/256
Dual-port memory window size    8K        8K         8K         8K
Data path width, bit            8         8          8          8
Max. number of cards installed  4         4          8          8
------------------------------------------------------------------------------



2. INSTALLING SDLA CARD

SDLA card can be installed in any unoccupied ISA bus slot in your system.
Before you begin the installation, select hardware options for your card (I/O
port, IRQ number, memory address, CPU clock rate, interface type and clocking
mode) and set jumpers on the card accordingly.  Fill out the following SDLA
installation checklist you will need to refer to when installing SDLA driver.

        ----------------------------------------------------------------
         Adapter type   |
        ----------------------------------------------------------------
         I/O Port       |
        ----------------------------------------------------------------
         IRQ            |
        ----------------------------------------------------------------
         Memory Address |
        ----------------------------------------------------------------
         CPU Clock Rate |
        ----------------------------------------------------------------
         Interface Type |
        ----------------------------------------------------------------
         Clocking Mode  |
        ----------------------------------------------------------------

When selecting hardware options, consider the following:

Adapter type
------------
There are several SDLA types available (see Chapter 1, "WANPIPE Basics").  In
most cases SDLA driver can autodetect adapter type.  However, you have to know
the type of adapter you are using to choose appropriate firmware module, as
not all modules are compatible with all SDLA types.

If you are not sure of your adapter type, here is some tips:

  S502A 
This older adapter is not properly marked, however it is easy to distinguish
from others as it is a long (full size) card with 8-bit ISA edge connector
and sinlge DB-25 female port.

  S502E
This is short (half size) card with 8-bit ISA edge connector and single DB-25
female port.  Its type is marked near the port on the component side as well
as on the etch side.  Note that these adapters are marked ES502A, which may be
confusing.  

  S503
This is also short (half size) card with 8-bit ISA edge connector and single
DB-25 female port.  It is clearly marked on both sides of the printed circuit
board.

  S508
This is short (half size) card with 16-bit ISA edge connector and two female
ports - DB-25 and DB-9.  It is clearly marked along its top edge on the
component side and on the etch side of the printed circuit board.


I/O ports
---------
Each adapter occupies 3 to 4 consecutive I/O ports.  They must not overlap
with the ports used by any other hardware installed in your system.  You can
find out which ports are in use on your system by typing:

        cat /proc/ioports

Note however, that even if the ports you selected are not listed in the above
command's output, their availability is not guaranteed.

The following I/O port options are available:
        ------------------------------------------------------
        Adapter type    I/O port options (hexadecimal)
        ------------------------------------------------------
        S502A/S502E     250, 300, 350, 360
        S503            250, 254, 300, 304, 350, 354, 360, 364
        S508            250, 270, 280, 300, 350, 360, 380, 390
        ------------------------------------------------------


IRQ
---
Each adapter (with the exception of S502A) requires a single IRQ line for its
operation.  Unlike I/O ports, you can share IRQ lines with other devices, as
long as only one device is active at any given time.  For example, consider
IRQ 7, which is normally used by a parallel printer port.  If your printer is
not connected or it is turned off, you can assign IRQ 7 to the SDLA.  In this
case you will be able to use your printer only when SDLA is inactive (e.g.
when SDLA driver is not loaded).  You can find out which IRQ lines are in use
on your system by typing:

        cat /proc/interrupts

The following IRQ options are available:
                --------------------------------------
                Adapter type    IRQ options (decimal)
                --------------------------------------
                S502E           2, 3, 5, 7
                S503            2, 3, 4, 5, 7
                S508            3, 4, 5, 7, 10, 11, 12
                --------------------------------------


Memory
------
Each adapter uses 8 kilobyte memory window to transfer data to and from the
host PC.  Note, that adapter does *not* consume PC memory.  The memory is
provided by the adapter itself and all that needed is a 'hole' in PC address
space to be 'filled' with adapter's own memory.  These 'holes' are usually
found within address range from A0000 to F0000 (hexadecimal).  Note that when
SDLA is inactive (e.g. SDLA driver is not loaded), the memory address space is
freed and may be used by other hardware.

SDLA driver is smart enough to find usable memory region automatically at
initialization time.  However, if you want to use specific memory region, make
sure no other hardware (such as video cards, hard disk controllers, network
adapters, etc.) uses the same or overlapping region.

The following memory address options are available:
        ---------------------------------------------------------------
        Adapter type    Memory address options (hexadecimal)
        ---------------------------------------------------------------
        S502A           A0000 A2000 A4000 A6000 A8000 AA000 AC000
                        C0000 C2000 C4000 C6000 C8000 CA000 CC000
                        D0000 D2000 D4000 D6000 D8000 DA000 DC000
                        E0000 E2000 E4000 E6000 E8000 EA000 EC000

        S502E/S503/S508 A0000 A2000 A4000 A6000 A8000 AA000 AC000 AE000
                        C0000 C2000 C4000 C6000 C8000 CA000 CC000 CE000
                        D0000 D2000 D4000 D6000 D8000 DA000 DC000 DE000
                        E0000 E2000 E4000 E6000 E8000 EA000 EC000 EE000
        ---------------------------------------------------------------

There is no jumpers associated with memory setting.  If you want to use
particular memory region, just write down its address for future reference.

If your system has a shadow RAM (most of them  do), make sure it is disabled
for the memory region you assigned to SDLA card.  Consult your motherboard and
BIOS documentation on whether there is a shadow RAM in your system and how to
deactivate it.


CPU Clock Rate
-------------- 
Some SDLA cards can run at various CPU clock rates.  This depends on the
chipset used and is not user-configurable.  However, you need to know what the
clock rate is, in order to configure SDLA driver.  If in doubt, ask your
Sangoma dealer for assistance.

The following CPU clock rate options are available:
        ---------------------------------------------------------------
        Adapter type    Available CPU clock rates (kHz)
        ---------------------------------------------------------------
        S502A           3600, 7200
        S502E/S503      3600, 7200, 8000, 10000
        S508            16000
        ---------------------------------------------------------------


Interface Type
--------------
Some adapters can be configured for different physical interface types, such
as RS-232C or V.35 (RS-422/485).  Configuration method depends on adapter type
and may involve installing appropriate interface chips and/or setting the
jumpers.

The following interface type options are available:
        ---------------------------------------------------------------
        Adapter type    Interface type
        ---------------------------------------------------------------
        S502A           RS-232C only
        S502E           RS-232C or V.35 (factory installed)
        S503            RS-232C or V.35 (user configurable)
        S508            Port 1: RS-232C or V.35 (software configurable)
                        Port 2: RS-232C only
        ---------------------------------------------------------------

Since the V.35 interface uses large rectangular connector that can not
possibly fit onto standard ISA card, a special cable is required to connect
SDLA card to V.35 interface.  The cable is available from Sangoma Technologies
(P/N 608).  V.35-specific lines share the same physical connector with the
RS-232C interface.  If you decide to build your own V.35 convertor then its
SDLA side should have a male-type DB-25 plug with the following pinout:

                        Pin #   V.35 Signal
                        -----   -----------
                         10     Tx A
                          9     Tx B
                         12     Rx A
                         11     Rx B
                         19     TxC A
                         21     TxC B
                         23     RxC A
                         25     RxC B
                         13     DTR A
                         14     DTR B
                         18     Aux. Clock A (output)
                         16     Aux. Clock B (output)


Clocking Mode
-------------
SDLA can be configured either for external clocking mode when transmit and
receive clock signals are supplied by an external communication equipment,
such as CSU/DSU, or for internal clocking mode when it generates clocking
signals for itself and, optionally, for the external equipment.

Under normal circumstances the clock signals are provided externally.
However, if your communication equipment needs an external clocking or if you
want to connect two cards back-to-back with a null-modem cable, at least one
of them should be configured to provide the clock (internal clocking mode).
In this case the clock signal is available on pin 24 of DB-25 connector
(RS-232C signaling) or pins 18 and 16 (V.35 signaling, A and B respectively).

Now you are ready to set SDLA configuration jumpers.  Jumper settings vary
depending on the SDLA type, so refer to the appropriate section below.


2.1. S502E (ES502A) Jumper Settings

I/O port address is set by jumper JP3 as follows:
                ---------------------------
                I/O Port (hex)   JP3 Pins
                                1-2     3-4
                ---------------------------
                250             in      in
                300             out     in
                350             in      out
                360             out     out
                ---------------------------

IRQ level is set by jumper JP4.  Only one header should be installed.
Removing the header disables interrupts.
                -----------------------
                IRQ     Header position
                -----------------------
                2               1-2
                3               3-4
                5               5-6
                7               7-8
                -----------------------

Note: Leave jumpers JP1 and JP2 alone!


2.2. S502A Jumper Settings

I/O port address is set by jumpers JP1 and JP2 as follows:
                ---------------------------
                I/O Port (hex)  JP1     JP2
                ---------------------------
                250             in      in
                300             out     in
                350             in      out
                360             out     out
                ---------------------------

Note: Leave jumper JP3 alone!


2.3. S503 Jumper Settings

I/O port address is set by jumper JP3 as follows:
                -----------------------------------
                I/O Port (hex)       JP3 Pins
                                1-2     3-4     5-6
                -----------------------------------
                250             in      in      out
                254             in      in      in
                300             out     in      out
                304             out     in      in
                350             in      out     out
                354             in      out     in
                360             out     out     out
                364             out     out     in
                -----------------------------------

Jumper JP3 also selects interface type:

                -----------------------------------
                Interface Type    JP3 Pins 9-10
                -----------------------------------
                RS-232                  in
                V.35                    out
                -----------------------------------

IRQ level is set by jumper JP2.  Only one header should be installed.
Removing the header disables interrupts.
                -----------------------
                IRQ     Header position
                -----------------------
                2               1-2
                3               3-4
                4               5-6
                5               7-8
                7               9-10
                -----------------------

Note: Leave jumper JP1 alone!


2.4. S508 Jumper Settings

I/O port address is set by jumper JP1 as follows:
        -------------------------------------------
        I/O Port (hex)          JP1 Hearers
                         1       2       3       4      
        -------------------------------------------
        250             in      in      in      out
        270             out     in      in      out
        280             in      out     in      out
        300             out     out     in      out
        350             in      in      out     out
        360             out     in      out     out
        380             in      out     out     out
        390             out     out     out     out
        -------------------------------------------

All other options are software-configurable.



3. INSTALLING WANPIPE SOFTWARE

WANPIPE (tm) software for Linux is distributed as a tar archive on a 3.5"
diskette or, optionally, can be downloaded from Sangoma's FTP site on the
Internet as a gzip'ed tar archive.  The URL is:

        ftp://www.sangoma.com/pub/linux/wanpipe.tgz

Software is distributed under the Sangoma's Limited Use License Agreement and
is not redistributable.  See the /usr/lib/wanpipe/LICENSE for details.

Follow these steps to install WANPIPE (tm) software:

1) If you received your distribution on a diskette, insert it into the disk
   drive, otherwise uncompress downloaded distribution archive using Linux'
   gunzip utility:

        gunzip wanpipe.tgz

   This command will create a file named wanpipe.tar.  To proceed with the
   installation you have to be logged in as a superuser (root) and be in the
   root directory (i.e. '/' , not '/root').

2) Transfer files from the installation media to your system using Linux' tar
   utility:

        tar xf {media}

   where {media} is a name of your floppy disk drive (usually /dev/fd0 or
   /dev/fd1), in case of installation from the distribution disk, or a name of
   the decompressed tar-file you obtained in previous step if you are
   installing from the downloaded tar archive.

   For example, if your uncompressed tar archive is in /home/you directory,
   use the following command:

        tar xf /home/you/wanpipe.tar

3) Change directory to /usr/lib/wanpipe and run WANPIPE installation script:

        ./install

   Follow instructions on the screen.  Installation script will perform the
   folowing functions:

    o create SDLA device nodes
    o install WANPIPE initialization script, if possible
    o recompile WANPIPE modules, if necessary
    o prompt you to run WANPIPE configuration script

WANPIPE distribution includes System V -style initalization script, allowing
bring up and shut down WANPIPE with a single command.  If your system uses
System V -style bootstrap, the WANPIPE installation script will attempt to
install initialization script into appropriate system directories so that
WANPIPE will come up automatically on system boot.

Unfortunately, many Linux distributions use simplified bootstrap procedure and
WANPIPE installation script will warn you that automated installation of
initialization script is not possible.  In this case you will have to add
WANPIPE initialization script to your system boot-time initialization script
manually.  Refer to the next chapter, "Configuring WANPIPE", for detailed
information.

Installation script also checks Linux kernel version number.  Because Linux
kernel modules are version-dependent, you have to recompile them if your
kernel version is not the same as the one the modules were compiled against.
Answer 'y' when asked if you want modules to be recompiled.

Note that WANPIPE modules also have to be recompiled every time you recompile
Linux kernel, e.g. when you change kernel configuration or apply a patch.  To
recompile WANPIPE modules run ./build script from /usr/lib/wanpipe directory.

If installation was successful then WANPIPE installation script will ask if
you want to configure WANPIPE.  Refer to the next chapter, "Configuring
WANPIPE", for more information.

The following is a list of all files installed and/or created during the
WANPIPE installation process.

/usr/lib/wanpipe/README          WANPIPE release notes
/usr/lib/wanpipe/LICENSE         Sangoma's Limited Use License Agreement
/usr/lib/wanpipe/MANUAL          WANPIPE User's Manual (this file)
/usr/lib/wanpipe/install         WANPIPE installation script
/usr/lib/wanpipe/build           WANPIPE build script
/usr/lib/wanpipe/configure       WANPIPE configuration script
/usr/lib/wanpipe/wanpipe         WANPIPE master initialization script
/usr/lib/wanpipe/ifinit          TCP/IP-level initialization script
/usr/lib/wanpipe/init/flip       FLIP subsystem initialization script
/usr/lib/wanpipe/init/sppp       SPPP subsystem initialization script
/usr/lib/wanpipe/conf/flip       FLIP subsystem configuration script
/usr/lib/wanpipe/mod/sdla.mod    SDLA kernel driver module
/usr/lib/wanpipe/mod/flip.mod    Frame relay protocol-specific module
/usr/lib/wanpipe/mod/sppp.mod    Synchronous PPP protocol-specific module
/usr/lib/wanpipe/sfm/fr502.sfm   S502 frame relay firmware module
/usr/lib/wanpipe/sfm/fr508.sfm   S508 frame relay firmware module
/usr/lib/wanpipe/sfm/ppp502.sfm  S502/S503 PPP firmware module
/usr/lib/wanpipe/sfm/ppp508.sfm  S508 PPP firmware module
/usr/lib/wanpipe/sample/*        sample configuration files
/usr/lib/wanpipe/src/sdla/*      SDLA driver source code
/usr/lib/wanpipe/src/flip/*      FLIP driver source code
/usr/lib/wanpipe/src/sppp/*      SPPP driver source code
/usr/lib/wanpipe/src/include/*   Common include files
/usr/sbin/sdlald                 SDLA firmware loader
/usr/sbin/flipcfg                FLIP configuration utility
/usr/sbin/spppcfg                SPPP configuration utility
/var/log/wanpipe                 WANPIPE initialization log file
/etc/wanpipe.rc                  WANPIPE meta-configuration file
/etc/sdla.conf                   SDLA configuration file
/etc/flip.conf                   FLIP subsystem configuration file
/dev/sdla*                       SDLA device nodes



4. CONFIGURING WANPIPE

WANPIPE includes several subsystems, each requiring its own configuration and
initialization.  Typically, bringing up WANPIPE involves the following steps:

  1) Loading SDLA driver
  2) Cofiguring SDLA hardware
  3) Loading SDLA firmware
  4) Loading protocol-specific module(s)
  5) Binding protocol-specific module(s) to SDLA card(s)
  6) Configuring data links
  7) Configuring network interfaces (TCP/IP)

They are performed by WANPIPE initialization script /usr/lib/wanpipe/wanpipe
that relies on WANPIPE configuration file (/etc/sdla.conf).  WANPIPE
configuration file is a plain ASCII text file that can be edited with any text
editor, such as vi.  However, we recommend using an interactive WANPIPE
configuration script (/usr/lib/wanpipe/configure), featuring easy to use
interface and extensive error checking.

To start WANPIPE configuration script log in as a superuser (root), change
directory to /usr/lib/wanpipe and type

        ./configure

During configuration you can view curent SDLA configuration at any time by
selecting "show configuration" from the main menu.


    Defining SDLA Hardware Configuration

This step is needed to inform WANPIPE of the hardware installed in your system
and its configuration.

Select "configure adapter" from the main menu.  You will be asked a number of
questions pertaining to your adapter hardware configuration.  Use the SDLA
configuration checklist you prepared during the SDLA installation to answer
these questions (refer to the Chapter 2, "Installing SDLA Card" for details).

Repeat this step if you want to configure additional SDLA cards.


    Defining WAN Links and Network Interfaces

During this step you will define WAN links used for transferring data and
network interfaces used by Linux protocol stack to route TCP/IP traffic over
those links.  Here, by WAN link we mean physical connection to the network
which includes SDLA card running compatible network protocol firmware and
bound to appropriate WANPIPE protocol-specific module.

Network interface is a standard way for Linux protocol stack to communicate
with various networking devices, such as ethernet cards, asynchronous potrs,
etc.  Interfaces are known to Linux operating systems by their names (you can
view all interfaces configured into your system by issuing command
'cat /proc/net/dev').  Unlike link, interface is a logical category, i.e.
several interfaces can use the same physical link and one interface can use
several physical links.

In trivial case, single network interface is created for each WAN link.
However, many WAN protocols (e.g. frame relay and X.25) support logical
channels, allowing multiplexing of several data streams over a single physical
link.  In this case network interfaces are created on per logical channel
basis to fully exploit network capabilities.

To define a WAN link select "bind adapter" from the main menu.  A list of
configured SDLA cards will appear.  Select a card you want to use for this
link, then select appropriate WAN protocol.  If protocol you selected requires
additional configuration (e.g. selecting logical channels), you will be asked
whether you want to configure link now.  If you decide to skip this step, you
will have to configure links at some point later by selecting "configure link"
from the main menu.

For more information on configuring WANPIPE data links refer to the
appropriate section of the next chapter, "Configuring Protocol-Specific
Subsystems".

Repeat these steps if you want to create additional WAN links.  Finally,
select "q" from the main menu to exit WANPIPE configuration script.

Note that WANPIPE configuration script merely updates WANPIPE configuration
file and does not affect actual state of hardware and WAN links.  For the
configuration changes to take an effect WANPIPE must be restarted (more on
that later).


    Configuring Network Interfaces

When all network interfaces are defined you will have to configure them at the
TCP/IP level.  This is a routine step in any network configuration and it is
accomplished using Linux ifconfig and route utilities.  If you are not
proficient in this area yet, please consult Linux Network Administration Guide
by Olaf Kirch, available at

  ftp://sunsite.unc.edu/pub/Linux/docs/linux-doc-project/network-guide/*

and related Linux HOWTO's:

  ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/NET-2-HOWTO
  ftp://sunsite.unc.edu/pub/Linux/docs/HOWTO/PPP-HOWTO

To simplify TCP/IP-level initialization, WANPIPE offers yet another script,
ifinit, located in /usr/lib/wanpipe directory.  This script uses configuration
files located in /usr/lib/wanpipe/ifi directory and can be quite handy if you
have large number of network interfaces to set up.  Note that this script is
as generic as possible and therefore can be used for setting up any Linux
network interfaces, not just those created by WANPIPE.

For each interface you want configured by ifinit script, simply create a file
named after that interface in /usr/lib/wanpipe/ifi directory (sample files are
included with the distribution).  Edit that file as needed (i.e. specify the
actual IP addresses, network mask, etc.).  Note that although configuration
files in /usr/lib/wanpipe/ifi do not contain executable commands, they are
actually "executed" by Linux shell, so the usual shell script syntax should be
observed (bash shell is currently assumed).

Note that ifinit is run automatically by WANPIPE initialization script, so
that WANPIPE can be completely initialized by single command.


  Bringing Up and Shutting Down WANPIPE

When all configuration files are set up you can start WANPIPE by executing its
initialization script.  If your system uses System V -like bootstrap procedure
and WANPIPE initialization script was properly linked to appropriate system
directories during WANPIPE installation, you may simply reboot your system,
otherwise change directory to /usr/lib/wanpipe and run the script manually:

        ./wanpipe start

If you do not want to type this command manually each time you start WANPIPE
then find a proper system boot-time initialization script and add this command
to the script.  The actual location of this script depends on your particular
Linux distribution.  In most cases it is /etc/rc.d/rc.M.

Note that WANPIPE should be initialized before Linux TCP/IP initialization
script is run (usually /etc/rc.d/rc.inet1).  For more information consult
documentation available for your Linux distribution.

During the execution WANPIPE initialization script displays messages on the
screen and logs more extensive information into WANPIPE log file
(/var/log/wanpipe).  If you encounter errors during WANPIPE initialization
check the log file and refer to chapter 6 "Trouble Shooting and Diagnostics".

To shut down WANPIPE execute the same command with "stop" argument:

        ./wanpipe stop



5. CONFIGURING PROTOCOL-SPECIFIC SUBSYSTEMS

This chapter covers procedures required to configure various protocol-specific
subsystems, available with WANPIPE.


5.1. Configuring Frame Relay Subsystem

WANPIPE frame relay subsystem is named FLIP, after a well-known Serial Line
Internet Protocol (SLIP).  However, unlike SLIP, FLIP is not limited to
routing IP frames.  It implements Multiprotocol Interconnect Over Frame Relay
specification (RFC-1490) and in this respect is closer to the Point-to-Point
Protocol (PPP), allowing mixed protocol traffic (such as TCP/IP, IPX, SNAP,
etc.) travel across the same frame relay link.

Sangoma's frame relay implementation for the S508 adapter can be used in frame
relay networks with either T1.617 Annex D, Q.933 or LMI link management, while
implementation for the S502 card supports T1.617 Annex D ONLY!

WANPIPE FLIP subsystem takes full advantage of frame relay multiplexing
capabilities, i.e. Linux network interfaces are created on per-DLCI basis,
alowing you perform DLCI-based routing.

Setting up FLIP subsystem involves creating configuration file for each frame
relay link and defining network interfaces for each DLCI.  Here we assume that
at least one frame relay link was defined during WANPIPE configuration by
binding SDLA card to frame relay protocol (refer to Chapter 4, "Configuring
WANPIPE" for details).

FLIP configuration files are plain ASCII text files that can by created and
edited with any text editor, such as vi.  They are placed into directory
/usr/lib/wanpipe/cfg and named flip.N, where 'N' is an SDLA card number (0
through 7).  I.e. configuration file flip.0 defines configuration for the
frame relay link connected to SDLA #0 (/dev/sdla0), flip.1 - for SDLA #1
(/dev/sdla1) and so on.  Sample configuration files are included with the
distribution.

Configuration file consists of single-line records of the following format:

        {keyword}={value}

where   {keyword}       is a character string, identifying configuration
                        parameter (record name)
        {value}         numeric or symbolic value representing configuration
                        option to be assigned to this configuration parameter

It also may include comments, identified by the '#' character.  In fact, all
characters following '#' are ignored, so you can append comments to the
configuration records.  Empty lines are ignored as well.

The syntax above shows an equal sign ('=') used as a separator between the
{keyword} and {value} fields.  In fact, you can use any number of whitespace
characters (Space or Tab) instead or in addition to it to separate these
fields.

Valid keywords and corresponding configuration options are listed below:

  KEYWORD       DESCRIPTION
  -------       --------------------------------------------------------------
  Station       This parameter specifies whether the adapter should operate
                as a Customer Premises Equipment (CPE) or emulate a Frame
                Relay switch (Access Node).  The options are:
                  CPE           CPE mode (normal)
                  Node          Access Node mode (switch emulation)

  Signalling	This parameter specifies frame realy link management option
		and is recognized only by the S508 adapter.  The options are:
		  AnnexD	T1.617 Annex D link management (default)
		  Q933		Q.933 link management
		  LMI		LMI link management
		  None		disable in-channel signalling

  PortType      This parameter specifies the type of physical interface.  The
                options are:
                  RS232         RS-232C interface (V.10)
                  V35           V.35 interface (V.11/RS-422/RS-485)

                Note, that this parameter only matters if adapter supports
                software-configurable interface selection (e.g. S508).

  Clocking      This parameter specifies whether the adapter should use the
                trasmit/receive clock signal provided by the external
                communication equipment such as CSU/DSU or generate the clock
                itself.  The options are:
                  Internal      Clock is generated on the board
                  External      Clock is provided by CSU/DSU

  BaudRate      This parameter specifies the speed (in bits per second) at
                which the communication is taking place.  The minimum baud
                rate is 1200 kbps and the maximum one depends on the adapter
                type.  It should be noted, that this parameter is required
                even if external clocking is used.  The typical values are:
                  9600          9.6 kbps
                  19200         19.2 kbps
                  38400         38.4 kbps
                  56000         56 kbps
                  64000         64 kbps
                  128000        128 kbps
                  1544000       1.544 Mbps (T-1)
                  2048000       2 Mbps (E-1)

  CIR           This is your Committed Information Rate.  Its value (in bps)
                should not exceed your baud rate or 512000, whichever is less.

  MTU           This is Maximum Transmit Unit size.  Its value (in bytes)
                determines the maximum size of data packet you can send over
                the Frame Relay link.  Note that this also includes header
                information required for encapsulating higher level protocols
                such as TCP/IP and IPX.  The maximum MTU size supported by
                the adapter is 4096 bytes.

  T391          This is the Link Integrity Verification Timer value in
                seconds. It should be within a range from 5 to 30 and is
                relevant only if adapter is configured as CPE.

  T392          This is the Polling Verification Timer value in seconds. It
                should be within a range from 5 to 30 and is relevant only if
                adapter is configured as Access Node.

  N391          This is the Full Status Polling Cycle Counter. Its value
                should be within a range from 1 to 255 and is relevant only if
                adapter is configured as CPE.

  N392          This is the Error Threshold Counter. Its value should be
                within a range from 1 to 10 and is relevant for both CPE and
                Access Node configurations.

  N393          This is the Monitored Events Counter. Its value should be
                within a range from 1 to 10 and is relevant for both CPE and
                Access Node configurations.


To define define frame relay network interfaces start WANPIPE configuration
script as described in Chapter 4, "Configuring WANPIPE", selecl "configure
link" from the main menu, then select the adapter used by the link you are
configuring.  This will take you to the FLIP confiration script.
Alternatively, you can start this script by entering the following command:

        /usr/lib/wanpipe/conf/flip

Select "add interface" from the FLIP configuration menu.  A list of SDLA
cards defined as frame relay links during the WANPIPE configuration appears.
Select a card you want this interface to be defined for.  Enter DLCI number
for this interface.  And finally, enter a number that will be used to
construct interface name.

All FLIP interfaces are named flipN, where N is an arbitrary decimal number
from 0 to 999 you assign to this interface.  An interface named 'flip'
(without a number appended to it) is always created when FLIP module is
loaded.  This interface is used exclusively by the FLIP configuration utility
(flipcfg) located in /usr/sbin directory to dynamically configure FLIP driver
and can not be used to transmit and receive data.

Repeat these steps until all interfaces for all frame relay links are defined
then enter "q" to exit the configuration script.

Note that FLIP configuration script merely modifies subsystem configuration
file (/etc/flip.conf) and does not affect current state of configured links
and interfaces.  For the configuration changes to take an effect FLIP
subsystem must be restarted by executing the following commands:

        /usr/lib/wanpipe/init/flip stop
        /usr/lib/wanpipe/init/flip start

Note that if there already were FLIP network interfaces configured, you have
to down them before restarting FLIP subsystem.

Alternatively, you can restart entire WANPIPE as described in Chapter 4,
"Configuring WANPIPE".



5.2. Configuring Synchronous PPP Subsystem

Point-to-point protocol (PPP) is by far the most well-known and widely used
WAN protocol these days.  Few people know, however, that PPP is not limited to
asynchronous communications.  In fact, traditional asynchronous PPP mimics the
HDLC (high-level data link control) protocol, to bring the benefits of
synchronous frame-oriented communications to the character-oriented world of
asynchronous ones.

When used in native synchronous communications enviroment, the benefits of PPP
are even greater.  The main is speed.  Asynchronous protocols need at least 10
bits to transfer a byte (8 bits of data + 1 start bit + at least 1 stop bit),
while synchronous protocols transfer data as a stream of bits, without a need
to mark byte boundaries.  This alone makes synchronous protocols at least 20%
faster than asychronous protocols with the same line speed.

Consider 19.2 kbps line.  The maximum data transfer rate you can achive with
asynchronous protocol is 1.92 kilobytes per second (19.2 divided by 10).  With
synchronous communications the maximum data trasfer rate is 2.4 kilobytes per
second (19.2 devided by 8), resulting in additional 3.26 kbps throughput.  The
higher the line speed, the bigger the savings.  With 64 kbps line, switching
to synchronous protocol saves the bandwidth of 12.8 kbps.

Sangoma's PPP implementation is compliant with RFCs 1661, 1662, 1663 and can
be used to connect to many PPP routers or to another Sangoma card running PPP
firmware (drivers for SCO Unix, Novell NetWare (tm), Windows NT (tm) and
Windows (tm) 95 are available).  Although synchronous PPP is most suited for
communications over the leased lines, regular telephone lines can also be used
(provided that modem supports synchronous mode).

Since PPP, unlike frame relay, is not multiplexing protocol (i.e. only one
logical channel exists for each physical link), SPPP subsystem configuration
is much simplier than that of the FLIP subsystem.  Setting up SPPP subsystem
is limited to creating configuration files for each PPP link.  Single Linux
network interface is created for each link atomatically.  (Mind you that data
links are defined by binding SDLA cards to protocol-specific modules using
WANPIPE configuration script.  Refer to Chapter 4, "Configuring WANPIPE" for
details.)

Syncronous PPP network interfaces are named 'spppN', where 'N' is a number of
SDLA card (0 - 7) used by this interface.  I.e. if synchronous PPP link was
defined for SDLA card #3 (/dev/sdla3), the corresponding interface is named
sppp3.

SPPP configuration files are plain ASCII text files that can by created and
edited with any text editor, such as vi.  They are placed into directory
/usr/lib/wanpipe/cfg and named 'sppp.N', where 'N' has the same meaning as in
interface names (i.e. configuration file sppp.3 defines configuration for the
PPP link connected to SDLA #3, i.e. /dev/sdla3).  Sample configuration files
are included with the distribution.

Configuration file consists of single-line records of the following format:

        {keyword}={value}

where   {keyword}       is a character string, identifying configuration
                        parameter (record name)
        {value}         numeric or symbolic value representing configuration
                        option to be assigned to this configuration parameter

It also may include comments, identified by the '#' character.  In fact, all
characters following '#' are ignored, so you can append comments to the
configuration records.  Empty lines are ignored as well.

The syntax above shows an equal sign ('=') used as a separator between the
{keyword} and {value} fields.  In fact, you can use any number of whitespace
characters (Space or Tab) instead or in addition to it to separate these
fields.

Valid keywords and corresponding configuration options are listed below:

  KEYWORD       DESCRIPTION
  -------       --------------------------------------------------------------
  PortType      This parameter specifies the type of physical interface.  The
                options are:
                  RS232         RS-232C interface (V.10)
                  V35           V.35 interface (V.11/RS-422/RS-485)

                Note, that this parameter only matters if adapter supports
                software-configurable interface selection (e.g. S508).

  Clocking      This parameter specifies whether the adapter should use the
                trasmit/receive clock signal provided by an external
                communication equipment such as CSU/DSU or generate the clock
                itself.  The options are:
                  Internal      Clock is generated on the board
                  External      Clock is provided by CSU/DSU

  BaudRate      This parameter specifies the speed (in bits per second) at
                which the communication is taking place.  The minimum baud
                rate is 1200 kbps and the maximum one depends on the adapter
                type.  It should be noted, that this parameter is required
                even if external clocking is used.  The typical values are:
                  9600          9.6 kbps
                  19200         19.2 kbps
                  38400         38.4 kbps
                  56000         56 kbps
                  64000         64 kbps
                  128000        128 kbps
                  1544000       1.544 Mbps (T-1)
                  2048000       2 Mbps (E-1)


  RestartTimer  This is time in 10ths of a second between successive
                retransmissions of Configure-Request or Terminate-Request
                packets.
                Range: 1-2621.  Recommended value is 30.

  AuthRestart   This is time in 10ths of a second between successive
                retransmissions of Authenticate-Request or Challenge packets
                (PAP and CHAP).
                Range: 1-2621.  Recommended value is 30.

  AuthWait      This is time in 10ths of a second for PAP or CHAP to wait for
                a reply or a request before terminating the link.
                Range: 1-2621.  Recommended value is 300.

  ModemTimeout  This is time in 10ths of a second to wait since DCD or CTS
                dropped before declaring the link disconnected.
                Range: 1-2621.  Recommended value is 10.


  DTRDropTimer  This is minimum time in 10ths of a second to keep DTR and CTS
                low during disconnection.  This is normally greater than
                ModemTimeout.
                Range: 1-2621.  Recommended value is 15.

  ConnectTimeout
                This is time in 10ths of a second to wait for DCD to go high
                during a connection attempt before dropping DTR to hang up.
                If this peer must wait for incoming connections, this should
                be set to zero.
                Range: 0-2621.

  ConfigureRetry
                This is number of Configure-Request packets sent without
                receiving a reply before terminating the link.
                Range: 1-65535.  Recommended value is 10.

  TerminateRetry
                Number of Terminate-Request packets sent without receiving a
                reply before terminating the link.
                Range: 1-65535.  Recommended value is 2.

  MaxConfReject Number of Configure-Nak packets sent without sending a
                Configure-Ack before assuming the configuration is not
                converging.  In some cases, the Configure-Nak packets are then
                converted to Configure-Reject packets; otherwise the link will
                be immediately terminated.
                Range: 1-65535.  Recommended value is 5.

  AuthRetry     Number of Authenticate-Request or Challenge packets sent
                without receiving a reply before terminating the link.
                Range: 1-65535.  Recommended value is 10.

        

6. TROUBLE SHOOTING AND DIAGNOSTICS

Errors may occur during different stages of WANPIPE initialization.  If this
happens, the error message will be displayed on system console and/or logged
into /var/log/wanpipe file.

WANPIPE initialization errors can be classified as follows:

 o kernel module load errors
 o hardware initialization errors
 o protocol-specific configuration errors


6.1. Kernel Module Load Errors

WANPIPE initialization scripts use Linux insmod utility to load WANPIPE
modules (drivers).  If insmod fails, you will see a message identifying the
problem.  In most cases this is due to incorrect kernel version.  WANPIPE
modules were compiled against Linux kernel version 1.2.8 and if your kernel
version is different, you will have to recompile the modules.  Normally,
WANPIPE installation script detects this situation and prompts you to
recompile modules when you install this product.  If you skipped this step or
upgraded your Linux kernel, log in as a superuser (root), go to directory
/usr/lib/wanpipe and run WANPIPE build script:

        ./build

If insmod displays messages saying '<symbol_name> undefined', then your kernel
was compiled with CONFIG_MODVERSIONS option set to YES.  To correct the
situation you will have to recompile the kernel and answer NO when asked if
you want CONFIG_MODVERSIONS.  Refer to /usr/src/linux/README file or any other
documentation included with your kernel distribution on how to recompile and
configure the Linux kernel.

        NOTE:
        When recompiling the kernel, make sure you answer YES when asked if
        you want IP forwarding enabled!


6.2. Hardware Initialization Errors

WANPIPE initialization script uses sdlald utility located in /usr/sbin
directory to configure SDLA card (set shared memory window, IRQ vector, etc.),
load SDLA firmware onto adapter and bind it to a protocol-specific module.  If
sdlald fails, it outputs an error message in the following format:

        sdlald error X: {error message text}

Errors fall into one of three groups:
        o system errors
        o SDLA driver errors
        o miscellaneous

System error are most frequently caused by a failed file operation such as an
attempt to open non-existent file, file read error or wrong permissions.  They
all have error code 1 followed by standard system error message.  Refer to
your system documentation for more details.

SDLA driver errors occur when driver control function can not be carried out.
Driver errors have error code 10 and can be as follows:

        [Wrong SDLA driver version]
        SDLA driver version does not match the one expected by sdlald.
        Upgrade either to the latest version.

        [Conflicting hardware option]
        At least one of the hardware configuration options specified on thei
        sdlald command line (I/O port, IRQ or memory address) is used by
        other hardware.  Choose alternative configuration option.

        [Unknown adapter type]
        [Adapter not found]
        Driver was unable to autodetect adapter type or the type you have
        specified is not supported.  Verify adapter type and I/O port options
        you selected.

        [Invalid hardware option]
        At least one of the hardware configuration options specified on the
        sdlald command line is illegal for this adapter type.  Make sure all
        options you specify are supported by this adapter type.

        [Memory window area unusable]
        [Adapter memory test failed]
        Memory area you selected is unusable due to the conflict with other
        hardware or because of enabled shadow RAM.  Choose alternative memory
        address option and/or disable shadow RAM.

        [Invalid adapter state]
        Requested control function is not compatible with the current adapter
        state.  Verify adapter state using sdlald with '-s' switch.

Driver also prints its own diagnostic messages using printk() routine.  Its
output usually goes to /var/log/messages file.  Check it out.

Miscellaneous errors include invalid sdlald command line syntax or
unrecognized command line option, attempt to acces non-SDLA device, etc.

        [Incompatible adapter hardware]
        The firmware you are trying to load is incompatible with this adapter
        type.  Verify adapter type, its memory size and CPU clock rate using
        sdlald command with '-s' switch and check hardware requirements for
        the firmware you are loading.  To display firmware module header info
        use sdlald with '-m' option.

        [Not an SFM file]
        The file you are attempting to load onto SDLA is not in SDLA Firmware
        Module (SFM) format.

        [Invalid SFM file version]
        SFM format version is not supported by your version of sdlald.
        Upgrage either to the latest version.

        [Corrupted SFM file]
        SDLA Firmware Module has been tampered with and can not be loaded.


6.3. Protocol-Specific Configuration Errors

This type of errors occurs when protocol-specific initialization script
attempts to configure links and create network interfaces.  Most protocol-
specific modules use configuration utilities in /usr/sbin directory to
configure links, create network interfaces, etc.  These utilities are:

        flipcfg    - frame relay link configuration utility
        spppcfg    - synchronous PPP link configuration utility

If configuration utility fails, it outputs an error message in the following
format:

        xxxxcfg error X: {error message text}

All configuration errors fall into one of three categories:

        o System errors
        o Driver errors
        o Miscellaneous

System error are most frequently caused by a failed file operation such as an
attempt to open non-existent file, file read error or wrong permissions.  They
all have error code 1 followed by a standard system error message.  Refer to
your system documentation for more details.

Driver errors occur when driver control function requested by the utility can
not be carried out. These errors have error code 10 and can be as follows:

        [Incompatible driver version]
        Driver version does not match the one expected by the utility.
        Upgrade either to the latest version.

        [Invalid device state]
        Requested control function is not compatible with the current adapter
        state.

        [IOCTL failure]
        Driver prints its own diagnostic messages using printk() routine.  Its
        output usually goes to /var/log/messages file.  Check it out.

The rest is miscellaneous errors, most of them are self-explanatory.  Some of
them are:

        [Invalid command line option]
        [Invalid command line syntax]
        These error messages indicate that the utility did not quite
        understand you.  Check its command line syntax and edit your command
        as needed.



6.4. Trouble Shooting WAN Connections

When WANPIPE initialization is complete, all network interfaces you defined
during link-level configuration should appear in 'cat /proc/net/dev' command
output.  If not, verify configuration and check WANPIPE log file for error
messages.

Make sure, interface flags displayed by 'ifconfig {name}' command include
RUNNING and UP.  If not, verify TCP/IP-level configuration and correct it if
necessary.  Then view routing table by executing 'route' command and make sure
all network and host addresses are correct.  Consult Linux Network
Administration Guide by Olaf Kirch if you have any problems.

If all the above looks ok, you should be able to ping remote host.  If not,
do the following (we assume you are using frame relay interface named flip0
associated with DLCI 16 on SDLA card 0):

1) Make sure your link level is up by viewing link-level status.  To obtain
frame relay link-level statistics use the following command:

        flipcfg s {N}

        where   {N}     is a SDLA card number this interface is bound to.

This command will print miscellaneous status and statistical information.  The
first line (Link status) should read "DCD UP : CTS UP : LINK UP".  If either
CTS or DCD is DOWN verify connection to your modem or CSU/DSU (cable, pinout,
interface type).  If both of them up but LINK is DOWN verify your link-level
configuration (baud rate, clocking, etc.).

Check list of active DLCIs.  Your DLCI should be listed there.  If not, verify
DLCI number and contact your service provider, if necessary.

2) Verify network interface configuration by typing 'ifconfig flip0'.  You
should see something like this:

flip0   Link encap:UNSPEC       HWaddr blah-blah-blah (whatever)
        inet addr: Your_IP_addr P-t-p: Other_IP_addr Mask: ..
        UP POINTOPOINT RUNNING NOARP    MTU:1500        Metric:1
        Rx packets:0    errors:0        dropped:0       overruns:0
        Tx packets:0    errors:0        dropped:0       overruns:0
        Interrupt:0 Base address:0x0

Make sure Your_IP_addr and Other_IP_addr are correct and interface flags
UP, POINTOPOINT and RUNNING are set.

3). Verify routing table by typing 'route'.  You should see an entry in the
routing table for Other_IP_addr as follows:

Destination     Gateway Genmask         Flags   MSS     Window  Use     Iface
Other_IP_addr   *       255.255.255.0   UH      1436    0       0       flip0

4) Start pinging remote system and take a look at interface statistics
reported by 'ifconfig flip0' command.

If 'Tx packets' count goes up, then your network interface and routing table
are set up correctly and you can proceed to step 5.

If 'Tx packets' remains 0, but 'Tx errors' and/or 'Tx dropped' grow, then
check /var/log/messages file (see Driver Error Log later in this chapter).

If neither of these statistics changes, return to step 1 and verify interface
configuration and routing table.

5) If you are connected to DSU/CSU which has LEDs on it, the transmit LED
should flicker approximately once a second while you are pinging.  If it does
not then check your connection to DSU/CSU (cable).

6) If you see transmit LED flicker, but not receive LED, then remote system is
not responding.  Make sure your destination IP address is correct and remote
system is up and running.

7) If both transmit and receive LEDs flicker approximately once a second, take
a look at interface statistics reported by 'ifconfig flip0' command again.

If neither 'Rx packets' nor 'Rx errors' counts change, check SDLA interrupt
count by looking at the output of 'cat /proc/interrupts' command.  If it is 0
then chances are that IRQ settings on the board and in SDLA driver
configuration do not match.  Verify IRQ jumper settings.

If 'Rx packets' remains 0, but any of the receive error counts grows, then
check /var/log/messages file (see Driver Error Log later in this chapter).

It may be useful to look at TCP/IP-level statistics on both ends.  To obtain
these statistics under Linux use 'cat /proc/net/snmp'.  The output is not
formatted, but it is fairly easy to interprete.  Treat it as a table
consisting of four two-line entries (long lines are wrapped).  Each entry
consists of two lines starting with the protocol name (Ip:, Icmp:, Tcp: and
Udp:).  The first line is the list of statistics names, the second one is
their values.  Note that these are global statistics, i.e. they are not
associated with any particular interface.  So if you have several network
interfaces (e.g. Ethernet) they will all contribute to these statistics.


    Driver Error Log

FLIP driver calls on firmware running on the adapter to send and receive data,
set adapter configuration, etc.  If firmware command fails for one reason or
another, the driver logs an error message into the /var/log/messages file.
The error messages have the following format:

        flip: command XXX returned YYY on port ZZZ

where   XXX     - firmware command code (hex)
        YYY     - firmware error code (hex)
        ZZZ     - SDLA card number (dec)

Firmware command and error codes are defined in /usr/src/sangoma/fr502.h
header file.  Some of the firmware commands are:

        0x01    - send a frame
        0x10    - set adapter configuration
        0x14    - read status
        0x15    - read statistics
        0x17    - list active DLCIs

And some of the firmware error codes are:

        0x02    - DLCI is inoperative
        0x03    - DLCI is inactive
        0x04    - DLCI is not configured
        0x07    - transmit throughput has exceeded CIR
        0x08    - transmit buffers full
        0x10    - physical link down (DCD and/or CTS low)
        0x11    - channel became inoperative (notification)
        0x12    - channel became operative (notification)
        0x13    - DLCI status changed (notification)
        0xFF    - adapter command timeout
        0xFD    - adapter mailbox in use

For example, a message

        flip: command 0x01 returned 0x03 on port 0

means that adapter /dev/sdla0 could not transmit a frame because DLCI was
inactive.  In this case you have to verify that you specified correct DLCI
number when configuring the interface.



7. TECHNICAL SUPPORT

Sangoma Technologies Inc. provides free technical support for the WANPIPE
product to those customers who purchased SDLA card(s) directly from Sangoma
Technologies Inc.

The preferable way for receiving thechnical support is via the Internet
e-mail.  Please forward your requests to 74604.152@compuserve.com.  You may
also send your requests by FAX at (905) 474-9223.

When submitting your request for technical support, please provide us with
the following information:

        o Adapter type(s) and serial number(s)
        o System type (CPU, speed, RAM size)
        o Linux kernel version number
        o WANPIPE version number
        o Communications link type and parameters (e.g. line speed)
        o Interface type (RS-232/V.35), DSU/CSU type (if any), etc.
        o Detailed description of the problem

Depending on the nature of the problem, the following information may also be
required to diagnose and trouble shoot the problem:

        o Contents of the system log file (/var/log/messages)

        o Contents of the WANPIPE initialization log file
          (/var/log/wanpipe)

        o Contents of the following WANPIPE configuration files:
                /etc/sdla.conf
                /etc/flip.conf
                /usr/lib/wanpipe/cfg/*
                /usr/lib/wanpipe/ifi/*

        o Adapter status as reported by the 'sdlald -s {device}' command.

        o Link-level status and statistics as reported by a protocol-specific
          configuration utiliry.  Refer to appropriate section in chapter 6
          "Trouble Shooting and Diagnostics" for more information on how to
          obtain link-level status and statistics.

        o Network interface statistics as reported by the 'ifconfig {name}'
          command for the interface in question.

        o Contents of the routing table as reported by the 'route' command.

All requests for technical support are normally replied to within 24 hours
(excluding weekends and holydays).

Please note that our 800 number is mainly for product ordering and general
inquiries.  If you need on-line assistance or would like to discuss your
problem with the support engineer, please indicate so in your request and we
will contact you as soon as possible.  Don't forget to include your voice
number.

Thank you.  We appreciate your business and your co-operation.

------------------------------------------------------------------------------
Appendix A

                             Frame Relay Basics

Frame Relay is basically a simplified form of Packet Switching in which
synchronous frames of data are routed to different destinations depending on
header information.


  Framing

Frame Relay uses synchronous HDLC frames up to 4 kbytes in length.  Each frame
starts and ends with a Flag character (7E).  The first 2 bytes of each frame
following the flag contain the information required for multiplexing across
the link.  The last 2 bytes of the frame are always generated by a Cyclic
Redundancy Check (CRC) of the rest of the bytes between the flags.  This
allows easy checking of the data integrity.  The rest of the frame contains
the user data.


  Virtual Circuits

Packets are routed through one or more Virtual Circuits known as Data Link
Connection Identifiers (DLCIs).  Each DLCI has a permanently configured
switching path to a certain destination.  Thus, by having a system with
several DLCIs configured, you can communicate simultaneously with several
different sites.  Currently, only permanent virtual circuit connections are
supported.


  Flow Control and Information Rates

There is no flow control on Frame Relay.  The network simply discards frames
it cannot deliver.

When you subscribe, you will set the line speed (e.g. 56 kbps) and also,
typically, you will be asked to specify a Committed Information Rate (CIR) for
each DLCI. This value specifies the maximum average data rate that the network
undertakes to deliver under "normal conditions".  If you send faster than that
on a given DLCI, the network will flag some frames with a Discard Eligibility
(DE) bit.  The network will do its best to deliver all packets but will
discard any DE packets if there is congestion.

Frame Relay provides indications that the network is becoming congested by
means of the Forward Explicit Congestion Notification (FECN) and Backward
Explicit Congestion Notification (BECN).  These are used to tell the
application to slow down, hopefully before packets start to be discarded. 

Frame Relay is cost effective, partly due to the fact that the network
buffering requirements are carefully optimized.  Many inexpensive Frame Relay
services are based on a CIR of zero.  This means that every frame is a DE
frame, and the network will throw them away when it needs to.


  Status Polling

The Frame Relay Customer Premises Equipment (CPE) polls the switch at set
intervals to find out the status of the network and DLCI connections.  A Link
Integrity Verification (LIV) packet exchange takes place about every 10
seconds, which basically verifies that the connection is still good.  It also
provides information to the network that the CPE is active, and this status is
reported at the other end.

About every minute, a Full Status (FS) exchange occurs, which passes
information on which DLCIs are configured and active.  Until the first FS
exchange has occurred, the CPE does not know which DLCIs are active, and
so no data transfer can take place. 

NOTE:     You may have to wait for up to 2 minutes after first boot up before
          you try any kind of data communication.  Such communication may
          fail if the first FS exchange has not yet occurred.

-----< END OF TEXT >----------------------------------------------------------
