
                   WAN Router for Linux Operating System

			       Release 1.0.3



			  U S E R'S   M A N U A L



			    Document Version 2.0

			      January 30, 1997


			     Author: Gene Kozin

	     Copyright (c) 1995-1997 Sangoma Technologies Inc.

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

			      C O N T E N T S

	Introduction ..........................................
	1. WAN Router Basics ..................................
	2. Installing WAN Tools Package .......................
		1) Unpack distribution archive.................
		2) Run WAN Tools Setup script..................
		3) Configure Linux Kernel......................
		4) Re-build Linux Kernel.......................
	3. Configuring WAN Router .............................
		1) Meta-Configuration file.....................
		2) Main router configuration file..............
		3) Interface configuration files...............
	4. Starting and Stopping WAN Router ...................
	5. Using the FPIPEMON and PPIPEMON monitors ...........
	6. Trouble Shooting and Diagnostics ...................
	7. Technical Support ..................................

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

Introduction

Wide Area Networks (WANs), such as X.25, frame relay and leased lines, are
used to interconnect Local Area Networks (LANs) over vast distances with data
transfer rates significantly higher than those achievable with commonly used
dial-up (modem) connections.  Usually, a quite expensive external device
called a 'WAN router' is needed to connect to a WAN.

As an alternative, WAN router can be build into one of the local machines
(hosts) on your local network (so called 'host-based router').  All that
needed to do this is some kind of WAN interface card and support from the
operating system.  Many modern multitasking operating systems have add-on
supplements acting as WAN routers.  Novell has MultiProtocol Router with WAN
Extensions for NetWare, IBM has Communications Server for OS/2 and Microsoft
has Multivendor Protocol Router for Windows NT.

Most external routers use some sort of stripped down Unix-like operating
system, so it is natural to built WAN routing services into Linux.  This
manual explains how to install and configure WAN Router into your Linux
system.


	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. WAN ROUTER BASICS

WAN router (or WAN gateway) is a device that interconnects two or more local
area networks (e.g. Ethernet or Token Ring) using some other media suitable
for transferring data over vast distances, such as leased line or digital data
network (e.g. X.25, frame relay, ISDN, ATM, etc.).  WAN router operates at the
network layer of the OSI reference model, i.e. connected networks may have
dissimilar physical and media layers, as long as the network layer is the
same.

For example, WAN router can connect two TCP/IP networks over the X.25 network,
regardless of whether each of them uses Ethernet or Token Ring as media layer
and whether a twisted pair or a coaxial cable is used as physical layer.
Multi-protocol router allows more than one network protocol (e.g. TCP/IP and
IPX) traverse the WAN link at the same time.

WAN router's job is to convert LAN protocol-layer packets destined to the
nodes belonging to other LAN into format apporriate for the WAN media used for
connecting those networks and transfer them via the WAN link.  This conversion
may involve encapsulation/decapsulation and fragmentation/defragmentation of
the packets.  Beside format conversion, router is also responsible for
accessing WAN media, i.e. physical and logical connection establishment and
implementing WAN protocols, which can as complex as LAN networking protocols,
such as TCP/IP.

Linux WAN Router is a kernel loadable module extending Linux networking
capabilities to allow routing of the network traffic (e.g. TCR/IP or IPX) over
wide area communication links such as leased lines or public data networks
(e.g. X.25 or frame relay).  It interfaces with the Linux protocol stack at
the top end and provides interface for WAN Link Drivers at the bottom end, as
shown on the diagram below.

          +----- /proc/net/router
          |
    +----------+  /\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\
    |          |  |        Linux protocol stack (TCP/IP, IPX, etc.)        |
    |   /proc  |  |                                                        |
    |          |  |          N e t w o r k   i n t e r f a c e s           |
    |Filesystem|  |                                                        |
    |          |  | wan0  wan1..wanN            eth0               ppp0    |
    +----------+  +--------------------------------------------------------+
          |          |     |     |               |                  |
    +================================+  +-----------------+  +-------------+
    |           WAN Router           |  | Ethernet Driver |  |  PPP Driver |
    +================================+  +-----------------+  +-------------+
                     |     |     |              |                  |
    +-------------------+  |     |      +-----------------+  +-------------+
    |  WAN Link Drivers |-----+  |      |  Ethernet Card  |  | Serial Port |
    +-------------------+     |-----+   +-----------------+  +-------------+
       |  +-------------------+     |            |                  |
       |     |  +-------------------+          to LAN            to modem
       |     |     |
       |     |     |  +----------+
       |     |     +--| WAN Card #--> to X.25 network
       |     |        |____      |
       |     |             UUUUUU
       |     |        +----------+
       |     +--------| WAN Card #--> to frame relay network
       |              |____      |
       |                   UUUUUU
       |              +----------+
       +--------------| WAN Card #--> to leased line
                      |____      |
                           UUUUUU

WAN Router provides WAN Link Drivers with user-level interface and common
services, such as device and network interface management, protocol
encapsulation/decapsulation, etc. and is completely hardware-independent.

User-level interface to the WAN Router and drivers is via the Linux /proc
filesystem.  For each adapter registered by the WAN drivers (drivers can
register more than one adapter) router creates an entry in /proc/net/router
directory.  These entries represent WAN links, i.e. physical connections to
the network and are used by the WAN Tools package to configure drivers,
obtain device status and statistics, etc.

For each WAN link, router dynamically creates one or more network interfaces.
Network interface is a standard way for Linux protocol stack to communicate
with various networking devices, such as ethernet cards, asynchronous ports,
etc.  Interfaces are known to Linux operating systems by their names (e.g.
eth0 for ethernet card).  You can view all network interfaces that currently
exist in your system by typing 'cat /proc/net/dev' at the command prompt.

In case of WAN Router, network interfaces represent not physical devices, but
rather logical channels on WAN links.  This allows to exploit multiplexing
capabilities of WAN protocols such as frame relay and X.25.  These protocols
provide for 'splitting' a physical connection to the network into multiple
logical channels, called data link connections (DLC) in frame relay and
virtual circuits (VC) in X.25.  Each such channel can lead to different
geographical location (site) and is represented by its own network interface,
allowing you to create a separate route to local network located at that site.

Considering very few commonalities between different types of WAN links, most
of the router functionality is delegated to the WAN Link Drivers.  They are
fully responsible for interacting with hardware, managing physical and logical
connections, implementing WAN protocols and providing functionality of network
interfaces.



2. INSTALLING WAN TOOLS PACKAGE

WAN Tools is a software package designed to support Linux kernel-based WAN
Router.  It includes the following components:

	o Router installation script (/usr/lib/router/Setup)
	o Router configuration script (/usr/lib/router/Configure)
	o Router start-up script (/usr/sbin/router)
	o Router configuration utility (/usr/sbin/wanconfig)
	o Router configuration files (/etc/router.conf and /etc/router.rc)
	o Interface configuration files (/usr/lib/router/interfaces/*)

Additionally, until WAN Router becomes a part of standard Linux distribution,
this package includes kernel patches you will have to apply to your Linux
source code.  Applying patches is done by the router installation script, so
usually, you won't have to worry about it, even if you never applied kernel
patches before.

There are few things, however, you should know about.  First, make sure that
kernel patches are available for your version of Linux kernel.  All supported
kernel versions are listed in Release Notes (/usr/lib/router/README).  Don't
confuse kernel version with the distribution version, as each distributor
keeps its own version numbering.  If you don't know what your kernel version
is, type 'uname -r' at the command prompt.

If your kernel version is not listed, you can install one of the versions that
is.  Most Linux distributions on CD-ROMs contain several kerenel versions to
choose from.  If you can't find one of the supported versions on the CD, you
can always download it from the Internet.  If your version is close to one of
the supported ones and you are experienced user, you can apply patches
manually.  Remember though, that in this case you're at your own peril.  But
again, you're experinced user and know what you're doing...

Second, you must have full Linux source code and development system (i.e. GNU
C compiler, make utility, etc.) installed on your system.  Linux source tree
is usually found in /usr/src/linux directory.  If there is no such directory
on your machine, or if it's empty, install Linux source code off your Linux
CD-ROM or download it from the 'Net first.

Third, you must be prepared to re-configure and re-complile Linux kernel after
the installation is complete.  If you never compiled Linux kernel before, ask
someone who did for assistance or read the README file found in /usr/src/linux
directory.

And finally, always back up your Linux source code before applying patches.
Remember, that unlike files, patches are not easily removable, in case you
decide to uninstall this product.

Provided that all above requirements are met, follow these steps to install
WAN Router and WAN Tools package:


1) Unpack distribution archive.

If you already unpacked WAN Tools distribution archive, procced to step 2.

WAN Tools package is distributed as a tar archive on a 3.5" diskette or,
optionally, it can be downloaded from the "/linux" directory located at 
Sangoma's FTP site (ftp.sangoma.com). 

To unpack the distribution, log in as superuser (root) and change your current
directory to the root directory by executing 'cd /' command.  Note, that this
is the topmost directory in the filesystem, NOT the user root home directory
(which is usually /root).

If you received your distribution on a diskette, insert it into a disk drive
and execute the following command:

        tar xf /dev/fd0

The above command assumes that the diskette is in the primary disk drive
(known as drive A: in MS DOS).  If you want to use secondary drive (drive B:),
substitute 'fd0' for 'fd1'. 

WARNING: THIS WILL OVERWRITE THE "/usr/lib/router" DIRECTORY.

If you downloaded WAN Tools package from the FTP site, use command:

        tar xzf {tarfile}

where {tarfile} is the name (including path) of the tar archive.  For example,
if you placed downloaded distribution wantools-1.0.0.tgz into derectory
/home/you, the command would look as follows:

        tar xzf /home/you/wantools-1.0.0.tgz

WARNING: THIS WILL OVERWRITE THE "/usr/lib/router" DIRECTORY.


2) Run WAN Tools Setup script.

Change current directory to /usr/lib/router and execute the following command:

        ./Setup

This script will perform the folowing functions:

        o verify distribution integrity and fix file permissions
        o apply kernel patches
        o install router start-up script (if possible)
        o create configuration files

When applying kernel patches, the Setup script will check the running kernel
version and select appropriate patch.  If patch is not available, the script
will display a warning.  You may still continue installation and then apply
the patch manually after the installation is complete.  The Setup script uses
Linux' patch utility when applying kernel patches.  If patch fails, you may
also continue and then examine reject files (*.rej) and attempt to fix the
problem.  For more information please read patch manual page ('man patch').

WAN Tools package includes a start-up script, allowing to bring the router up
and shut it down with a single command.  If your system uses System V-style
bootstrap procedure, the Setup script will offer you to link the start-up
script to appropriate system directories so that the router will come up
automatically when system enters multi-user mode and will be stopped when
entering single-user or when system is shut down.

Note, that this feature is optional.  If your system does not use System
V-style bootstrap or if you chose not to link start-up script, you can always
start and stop router manually by executing 'router start' and 'router stop'
commands respectively.


3) Configure Linux kernel.

To configure Linux kernel, change your current directory to /usr/src/linux and
run 'make config'.  Alternatively, you can run 'make menuconfig' for menu-
driven configuration or 'make xconfig', if you are running X-Windows.

If you never configured Linux kernel before, please read /usr/src/linux/README
or ask someone who did for assistance.  In short, Linux configuration script
will ask you a series of questions regarding your system configuration.  Most
question require single-letter answer: 'y' to enable feature, 'n' to disable
it or 'm' to implement feature as a module.  Entering 'h' brings up a help
text (if available).

When configuring kernel, make sure you answer negatively (i.e. 'n' ) to the
following questions:

      	Set version information on all symbols for modules (CONFIG_MODVERSIONS)
	Frame relay DLCI support (EXPERIMENTAL) (CONFIG_DLCI) 

When configuring kernel, make sure you answer positively (i.e. 'y' ) to the
following questions:

        Enable loadable module support (CONFIG_MODULES)
        Kernel daemon support (CONFIG_KERNELD)
        Networking support (CONFIG_NET)
        TCP/IP networking (CONFIG_INET)
        IP: forwarding/gatewaying (CONFIG_IP_FORWARD)
        IP: optimize as router not host (CONFIG_IP_ROUTER)
        WAN Router (CONFIG_WAN_ROUTER)
        Network device support (CONFIG_NETDEVICES)
        WAN Drivers (CONFIG_WAN_DRIVERS)
        ...
	/proc filesystem support (CONFIG_PROC_FS)

After enabling WAN Drivers you will be presented with the list of available
WAN drivers.  Select appropriate driver for your hardware and driver-specific
configuration options.  Refer to the driver documentation for details.


4) Re-build Linux kernel.

If you never compiled Linux kernel before, please read /usr/src/linux/README
or ask someone who did for assistance.  Note that if your machine is slow
and/or has little memory, re-building Linux kernel may take several hours.

Re-building Linux kernel involves executing 'make' command several times with
different arguments:

        run 'make dep' to rebuild source code dependencies,
        run 'make clean' to delete all stale object files,
        run 'make zlilo' or 'make zImage' to build new kernel,
        run 'make modules' to build kernel modules,
        run 'make modules_install' to install modules.

When all this done, reboot your machine.



3. CONFIGURING WAN ROUTER

There are several configuration files associated with the WAN Router.  They
are all in ASCII text format and can be edited with any text editor, such as
vi.  However, we recommend to use an interactive configuration script
(/usr/lib/router/Configure), where applicable, to set up and edit
configuration files, as it ensures correct syntax and can prevent from
misconfigurations.


1) Meta-configuration file

Router meta-configuration file /etc/router.rc defines location of other files,
such as start-up log file, main router configuration file, etc., and is used
by the router start-up script.  This file is set up by the router setup script
during the installation and rarely needs to be edited.

Meta-configuration file is actually a shell script, although it does not
contain any executable commands, only shell variable definitions.  Still,
usual shell syntax must be observed when editing this file.

The following variables are defined in the meta-configuration file:

    ROUTER_BOOT
        Defines whether to start router (YES) or not (NO).  It is useful if
        you want to prevent router from starting without unlinking start-up
        script or altering main configuration file.
        Default is ROUTER_BOOT=YES

    ROUTER_CONF
        Defines name and location of the main router configuration file.
        Default is ROUTER_CONF=/etc/router.conf

    ROUTER_LOG
        Defines name and location of the router start-up log file.  Log file
        is created by the router start-up script and can be used to
        troubleshoot router configuration.
        Default is ROUTER_LOG=/var/log/router

    ROUTER_LOCK
        Defines name and location of the router lock file.  Lock file is
        created by the start-up script when the router is started and removed
        when it is stopped.
        Default is ROUTER_LOCK=/var/lock/router

    WAN_DRIVERS
        Lists WAN driver to be loaded by the start-up script.  Note, that the
        list must be enclosed in double-quotes and driver names must be
        separated by a space character.
        Default is WAN_DRIVERS=""

You can add/remove drivers to/from the drivers list interactively, using WAN
Router configuration script (/usr/lib/router/Configure).


2) Main router configuration file

Main router configuration file /etc/router.conf defines WAN links and network
interfaces and is used by the wanconfig, router configuration utility, to
configure WAN drivers.  Because contents of this file is mostly driver-
specific, only a template is installed by the setup script.  You will have to
edit this file manually according to your driver requirements.

Here we describe only general syntax of the router configuration file and some
common configuration options.  For the driver-specific configuration options
please refer to your driver documentation.

Router configuration file consists of several sections.  Each section includes
unique section name enclosed in square brackets and number of single-line
records of the following format:

        {keyword}={value}[,{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

For example:

        [section]
        option1=100,200
        option2=yes

Note the following:

        o section name can not contain spaces

        o section names and symbolic values are case-sensitive, while keywords
          are case-insensitive

        o numeric values can be ether decimal or hexadecimal.  Hexadecimal
          numbers should start with '0x', for example 0xFE00 of 0xabcd.

        o there can be any number of whitespace (i.e. space or horisontal
          tabulation) characters between the keyword, values and separation
          characters (i.e. '=' and ',')

        o configuration file may include comments, identified by the '#'
          character.  In fact, all characters following '#' are ignored, so
          comments can be appended to the configuration records.

        o empty lines are ignored

There are two sections that must always be present in router configuration
file: [devices] and [interfaces].  Optionally there may also be a private
section for each device and interface defined in those two sections.  Private
configuration section must have the name identical to the name of the device
or the interface it corresponds to.

The [devices] section defines physical WAN connections (links). Each statement
in this section has the following format:

        {device}={config_id}[,{description}]

where:
        {device}        WAN device name as it appears in /proc/net/router
                        directory.  It is also used to locate a configuration
                        section for this device.  See WAN driver documentation
                        for valid device names

        {config_id}     identifier used for decoding configuration section.
                        Currently defined the following IDs:
                                WAN_X25 generic X.25 configuration
                                WAN_PPP generic PPP configuration
                                WAN_FR  generic frame realy configuration

        {description}   verbal description of this device (optional)

The [interfaces] section defines Linux network interfaces, created by the
router.  Each statement of the configuraton section has the following format:

        {name}={device}[,{media_addr},{description}]

where:
        {name}          interface name as it appears in /proc/net/dev
                        directory.  It is also used to locate configuration
                        section for this interface.

        {device}        name of the WAN device (from the [devices] section)
                        this interface is associated with

        {media_addr}    media address for this logical channel, if applicable.

        {description}   verbal description of this interface (optional)

You can use any string (up to 15 characters long) as an interface name, as
long as it is unique and does not contain spaces.  This allows you to give
network interfaces descriptive names (for example, associated with
geographical locations).

Media address syntax is device- and media-specific.  Proposed convention is
as follows:

  ---------------------------------------------------------------------------
  Media type                            | Media adress
  --------------------------------------+------------------------------------
  X.25 permanent virtual circuit        | PVC number in decimal notation
                                        |
  X.25 switched virtual circuit         | '@' character followed by the X.25
                                        | destination address in decimal
                                        | notation
                                        |
  Frame relay permanent virtual circuit | DLCI number in decimal notation
                                        |
  Frame relay switched virtual circuit  | to be defined
  ---------------------------------------------------------------------------

Contents of the device and interface private configuration sections are
device-specific.  There are, however, some common keywords and configuration
options defined for the device private configuration sections:

    IOPort
        Adapter I/O port address

    IRQ
        Adapter interrupt request level (if applicable)

    DMA
        Adapter direct memory access request level (if applicable)

    MemAddr
        Address of the adapter shared memory window (if applicable)

    OptionX (where X = 1..4)
        Other adapter hardware options

    Firmware
        Name of the arbitrary data file (e.g. adapter firmware)

    Interface
        Physical interface type. Available options are:
                RS232   RS-232C interface (V.10)
                V35     V.35 interface (V.11/RS-422/RS-485)

    Clocking
        Source of the adapter transmit and receive clock signals.  Available
        options are:
                External        Clock is provided externally (e.g. by the
                                modem or CSU/DSU)
                Internal        Clock is generated on the adapter

    BaudRate
        Data transfer rate in bits per second.  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)

    MTU
        Maximum transmit unit size (in bytes).  This value limits the maximum
        size of the data packet that can be sent over the WAN link, including
        any encapsulation header that router may add.  It usually has to be
        not less then the largest MTU of all interfaces configured for this
        link plus WAN media header size (if any), unless WAN driver can
        perform fragmentation of data packets.

Here is an example ot the WAN Router configuration file:

        [devices]
        device1=WAN_PPP, Leased line to the head office
        device2=WAN_X25, X.25 link
        device3=WAN_FR, Frame relay link

        [interfaces]
        wan0=device1
        wan1=device2, 1, X.25 PVC connection to the branch 1
        wan2=device2, @123456, X.25 SVC connection to the branch 2
        wan3=device3, 16, frame relay connection to the branch 3
        wan4=device3, 17, frame relay connection to ISP

        [device1]
        IOPort=0x300
        IRQ=2
        Interface=RS232
        Clocking=External
        MTU=1600
        (other device-specific options)

        [device2]
        IOPort=0x320
        IRQ=5
        Interface=RS232
        Clocking=External
        MTU=512
        (other device-specific options)

        [device3]
        IOPort=0x360
        IRQ=12
        Interface=V35
        Clocking=External
        MTU=4000
        (other device-specific options)

        [wan1]
        (device-specific options)

        [wan2]
        (device-specific options)

        [wan3]
        (device-specific options)

        [wan4]
        (device-specific options)

This configurqation file defines three WAN links (device1, device2, device3)
and five interfaces (wan0 through wan4).  Interface wan0 is associated with
the PPP link on device 'device1'.  Since PPP is not multiplexing, there can be
only one interface on this link and no media address is necessary.

Interfaces wan1 and wan2 are associated with the X.25 link on device 'device2'
and represent a permanent virtual circuit (PVC) and a switched virtual circuit
(SVC), respectively.  Note that media address of the interface wan2 starts
with a character '@' followed by the X.25 destination address, while media
address of the wan1 is merely a PVC number.

Interfaces wan3 and wan4 are associated with the frame relay link on device
'device3'.  Their media addresses are the Data Link Connection Identifiers
(DLCIs) of the corresponding frame relay logical channels.


3) Interface configuration files

Once network interfaces defined in the WAN Router configuration file has been
created by the router, they have to be configured at the protocol level (i.e.
TCP/IP or IPX).  Configuring WAN Router interfaces is not much different from
configuring any other Linux network interface (e.g. Ethernet or PPP) and is
done using ifconfig utility.

If you are not familiar with Linux network interface configuration, please
read 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, etc.

Considering multiplexing capabilities of WANs, it is possible to have dozens
and even hundreds of interfaces defined in the router configuration file.
Configuring all these interfaces manually with ifconfig can be a daunting
task.  To simplify multiple interface configurations, WAN Tools package
provides interface configuration files, allowing to configure interfaces and
create static routes automatically, each time router is started and shut them
down when it is stopped.

Interface configuration files are put into /usr/lib/router/interfaces
directory and must have the same names as corresponding network interfaces
defined in the router configuration file.  Like router meta-configuration file
we discussed earlier, these files are the shell scripts merely defining some
environment variables.  They are 'included' by the router start-up script,
which then calls 'ifconfig' and 'route' utilities to perform actual interface
configuration.

The following variables are defined in the interface configuration file:

    ONBOOT
        Defines whether to configure this interface (yes) or not (no).  It is
        useful if you want to disable interface temporary without deleting
        configuration file.  Default is ONBOOT=yes

    IPADDR
        Defines IP address for this interface.  IP addresses are written as
        four dot-separated decimal numbers from 0 to 255 (e.g. 192.131.56.1).
        Usually this address is assigned to you by your network administrator
        or by the Internet service provider.

    NETMASK
        Defines network address mask used to separate host portion of the IP
        address from the network portions.  Usually, TCP/IP protocol stack can
        do it by looking at the address itself and deciding whether it belongs
        to address class A, class B or class C.  However, there are situations
        when you may want to override this (e.g. when you create sub-nets
        within your particular address class).  In this case you have to
        supply a netmask.  Like the IP address, the netmask is written as four
        dot-separated decimal numbers from 0 to 255 (e.g. 255.255.255.192).

    POINTOPOINT
        Most WAN links are of point-to-point type, which means that there is
        only one machine connected to the other end of the link and its
        address is known in advance.  This option is address of the 'other
        end' of the link and is usually assigned by the network administrator
        or Internet service provider.  If peer address is not known, then it
        will have to be resolved dynamically using inversed ARP or other
        protocol and must be supported by both WAN driver and peer machine.
        Like any other IP address, poit-to-point address is written as four
        dot-separated decimal numbers from 0 to 255 (e.g. 192.131.56.2).

    BROADCAST
        This option is reserved for media supporting broadcast addressing,
        such as Ethernet

    NETWORK
        This is the address of the network you are connecting to used to set
        up kernel routing tables.  By supplying this address you instruct
        kernel to direct all network traffic destined to that network to this
        interface.  Like any other IP address, network address is written as
        four dot-separated decimal numbers from 0 to 255 (e.g. 192.131.56.0).
        Alternatively, you can use symbolic network name from the
        /etc/networks file in place of the numeric address.  A special case is
        the network address 0.  This will create a default route, meaning that
        all network traffic with no specific route found in the routing table
        will be forwarded to this interface.  Default route is useful for
        connections to the 'outside world', such as Internet service provider.

    GATEWAY
        If the network you are connecting to is not directly reachebale, you
        may also specify a gateway address.  Note however, that gateway has to
        be reacheble, i.e. a static route to the gateway must exist.  Gateway
        address also follows usual IP address notation or can be replaced with
        the symbolic name from the /etc/host file.

Although you can create interface configuration files manually (a sample file
/usr/lib/router/interface is included in the WAN Tools package), we suggest
you use WAN Router configuration script (/usr/lib/router/Configure) which
allows you to create, delete and view them interactively.

Note that use of interface configuration files is optional.  In fact, they can
accomodate only very basic configurations.  More sophisticated cases involving
multiple gateways and extensive subnetting will require manual configuration.
On the other hand this feature is not limited to interfaces created by the WAN
Router.  Interface configuration file can be created for any existing Linux
interface, such as SLIP, PLIP or PPP.  Bear in mind though, that in this case
initialization and tearing down of these interfaces will be synchronized with
starting and stopping WAN Router.



4. STARTING AND STOPPING WAN ROUTER

The easiest way to start and stop WAN Router is using router start-up script.
Enter 'router start' at the command prompt to bring the router up or 'router
stop' to shut it down.

The start-up script will first read meta-configuration file /etc/router.rc to
set up its operational environment.  Then it will check to see if router lock
file already exists.  If it does, then the start-up script will assume that
the router is already running and terminate with appropriate error message.
A little hint here: the start-up script relies on the lock file being deleted
either by the start-up script itself (when executing 'router stop') or by the
system initialization script if system is rebooted without stopping the router.
If neither is true, you will see an error message next time you start the
router and will have to remove the lock file manualy.  Location of the lock
file is stored in the ROUTER_LOCK variable in the /etc/router.rc file (default
is /var/lock/router).

Next, the start-up script will load WAN drivers listed in the WAN_DRIVERS
variable in the /etc/router.rc file using Linux' modprobe utility.  This will
atomatically load the router module and other necessary kernel modules.  Note
that modprobe relies on module dependencies being up-to-date.  If router
module or some other modules don't load, you may try to re-build module
dependencies with 'depmod -a' command.

When all WAN drivers are loaded, the start-up script runs wanconfig utility
to configure WAN drivers and create network interfaces.  Configuration file
used by wanconfig is defined by the ROUTER_CONF variable in the /etc/router.rc
file (default is /etc/router.conf).  wanconfig is run by the start-up script
in verbose mode and its standard output is redirected to the router log file,
defined by the ROUTER_LOG variable in the /etc/router.rc file (default is
/var/log/router).  You can check this file to verify driver configuration.

And finally, the start-up script configures network interfaces (TCP/IP level)
and sets up static routes using Linux' ifconfig and route utilities.  When
doing so, it uses configuration files found in /usr/lib/router/interfaces
directory.  These files can be created manually or using router configuration
script as described in previous section.

When router is shut down with 'router stop' command, the start-up script
shuts down all nework interfaces, then unloads WAN drivers, thus returning
system to its initial state.



5. USING THE FPIPEMON AND PPIPEMON MONITORS

Included with the drivers are two UDP management monitors, fpipemon and
ppipemon, for Frame Relay and PPP respectively.  You must be superuser (root)
to run these monitors. Simply invoking the command name (either 'fpipemon' or
'ppipemon') will give the command line usage.  The UDP management port to be
utilized can be configured with the UDPPORT option in the router.conf
configuration file.

Notice that there are two ways in which to use the monitor to talk to the
driver.  The first is through the actual link provided by the driver.  ie.
Either the Frame Relay or PPP link (underneath).  In this instance the IP
address to be specified could be any address on the sub-network, provided it
is forwarded to the driver.  The other method to talk to the driver is from 
'above' or from the system.  This method allows the use of a feature called
line tracing.  To use the monitor from 'above' you must either run the monitor
on the machine with the Sangoma card, or you must have another network
connection to this machine (eg. Ethernet).  The IP address to specify in
this instance must not be the actual IP address of the card.  Any other IP
address on the sub-network will work, since the system tries to forward
the packet through the driver.

Using these two methods to communicate with the driver makes these monitors
extremely versatile.  For example, you may monitor Sangoma cards installed
in non-Linux systems.  In the same way you can monitor the Linux cards from
non-linux systems (provided you have the monitors for that platform).  Since
the monitors rely on UDP, you can use them over any IP network (such as the
Internet) to reliably monitor your Sangoma cards.  Also by assigning your
cards to different UDP ports, you can monitor all cards from one monitoring
station.



6. TROUBLE SHOOTING AND DIAGNOSTICS

If you encounter errors during router installation and/or start-up, try to
determine which command, utility or process causes the error.  Carefully
record and examine all warnings and error messages.  Read appropriate section
of this manual again and make sure you have not missed anything important.

When Router initialization is complete, all WAN devices defined in the
[devices] section of the router configuration file (/etc/router.conf) should
appear in the /proc/net/router directory.  Similarly, all network interfaces
defined in the [interfaces] section should appear in the /proc/net/dev
directory (provided that corresponding WAN device was successfully
configured).

If some of the devices and/or interfaces can not be found then verify router
configuration file and check WAN Router log file (/var/log/router) for
warnings and/or error messages.  It may also be helpful to monitor system log
file (/var/log/messages) during Router start-up.  To do this, switch to
another virtual console by pressing Alt-F2 (or open new terminal window, if
running X-Windows) and enter the following command:

	tail -f /var/log/messages

Then switch back to the original console by pressing Alt-F1 and start WAN
router by executing 'router start' command.  Switch to the second console
again and watch Router and driver(s) initialization messages for any errors
and/or warnings.

To verify WAN device configuration, use Config and Status pseudo-files found
in /proc/net/router directory.  Doing 'cat' on these files reveals current
device state and configuration.  The sample output is shown below:

	cat /proc/net/router/Config

 Device name | port |IRQ|DMA|mem.addr|mem.size|option1|option2|option3|option4
 wanpipe2    |0x364 |  5|  0|0xEC000 |0x2000  |   5030|   7200|  65536|   6200
 wanpipe1    |0x300 | 12|  0|0xEE000 |0x2000  |   5080|  16000| 131072|   5800

	cat /proc/net/router/Status

 Device name |station|interface|clocking|baud rate| MTU |ndev|link state
 wanpipe2    | DCE   | RS-232  |external|    56000| 1600|  2 |connected
 wanpipe1    | DTE   | RS-232  |external|    56000|  256|  2 |connecting

To obtain device statistics, do 'cat' on WAN device entry in /proc/net/router
directory as follows:

	cat /proc/net/router/{device}

	 total frames received:            0
       receiver overrun errors:            0
		    CRC errors:            0
	   frame length errors:            0
	   frame format errors:            0
       aborted frames received:            0
       reveived frames dropped:            0
	  other receive errors:            0

      total frames transmitted:            0
    aborted frames transmitted:            0
       transmit frames dropped:            0
	   transmit collisions:            0
	 other transmit errors:            0

To verify TCP/IP configuration of WAN interfaces, use Linux' ifconfig and
route utilities.  Interface status and statistics can be viewed with
'ifconfig {interface}' command.  The output should look similar to this:

	wan0    Link encap:UNSPEC       HWaddr (whatever)
		inet addr:<your_ip_addr> P-t-p:<other_ip_addr> Mask:<netmask>
		UP POINTOPOINT RUNNING  MTU:1500  Metric:1
		Rx packets:0 errors:0 dropped:0 overruns:0
		Tx packets:0 errors:0 dropped:0 overruns:0
		Interrupt:9 Base address:0x360 Memory ee000-effff

Make sure that IP address and netmask are correct and that RUNNING and UP
flags are set.  If interace exists, but does not appear to be configured,
then run router configuration script (/usr/lib/router/Configure), select 'Show
interfaces' from the main menu and view configuration for the interface in
question.  If configuration file does not exist, create it by selecting 'Add
interface' from the main menu.

View routing table by typing 'route' at the command prompt and make sure that
routes to all remote networks and hosts exist.  The output should look similar
to this:

        Destination     Gateway Genmask         Flags   Window  Use     Iface
        <other_ip_addr> *       255.255.255.0   UH      0       0       wan0

If all the above looks ok, you should be able to ping remote host.  If pings
are not getting through, try to determine which part of the connection fails.
There can be at least four possibilites:

        o pings are not being transmitted by the local machine
        o pings are not being received by the remote machine
        o pings are not being replied to by the remote machine
        o replies are not being received by the local machine

Quite often you can tell which part of the connection is not functioning by
simply looking at the interface statistics output by the ifconfig utility at
both local and remote machines.

It may be also 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.



7. TECHNICAL SUPPORT

If you are unable to diagnose and/or fix a problem yourself, you can ask
Sangoma Technologies Inc. for technical support via fax or e-mail:

        FAX:    (905)474-9223
        E-mail: jaspreet@sangoma.com or dm@sangoma.com

When sending your request, please provide us with the following information:

        o Detailed description of the problem
        o System type (CPU, speed, RAM size)
        o Linux kernel version number
        o WAN Router version number
        o WAN Driver name and version number
        o WAN Adapter type
        o Communications link type and parameters (e.g. line speed)
        o Interface type (RS-232/V.35), DSU/CSU type (if any), etc.
        o Contents of the following files:
                /etc/router.rc
                /etc/router.conf
                /var/log/router
                /var/log/messages
                /usr/lib/router/interfaces/*
        o Output of the following commands
		cat /proc/interrupts
		cat /proc/ioports
		cat /proc/net/dev
		cat /proc/net/router/Config
		cat /proc/net/router/Status
		cat /proc/net/router/{device}
		ifconfig {interface}
                route

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

-----< THE END >--------------------------------------------------------------
