path: root/Documentation/networking/wan-router.txt
diff options
Diffstat (limited to 'Documentation/networking/wan-router.txt')
1 files changed, 622 insertions, 0 deletions
diff --git a/Documentation/networking/wan-router.txt b/Documentation/networking/wan-router.txt
new file mode 100644
index 000000000000..aea20cd2a56e
--- /dev/null
+++ b/Documentation/networking/wan-router.txt
@@ -0,0 +1,622 @@
+Linux WAN Router Utilities Package
+Version 2.2.1
+Mar 28, 2001
+Author: Nenad Corbic <ncorbic@sangoma.com>
+Copyright (c) 1995-2001 Sangoma Technologies Inc.
+Wide Area Networks (WANs) are used to interconnect Local Area Networks (LANs)
+and/or stand-alone hosts over vast distances with data transfer rates
+significantly higher than those achievable with commonly used dial-up
+Usually an external device called `WAN router' sitting on your local network
+or connected to your machine's serial port provides physical connection to
+WAN. Although router's job may be as simple as taking your local network
+traffic, converting it to WAN format and piping it through the WAN link, these
+devices are notoriously expensive, with prices as much as 2 - 5 times higher
+then the price of a typical PC box.
+Alternatively, considering robustness and multitasking capabilities of Linux,
+an internal router can be built (most routers use some sort of stripped down
+Unix-like operating system anyway). With a number of relatively inexpensive WAN
+interface cards available on the market, a perfectly usable router can be
+built for less than half a price of an external router. Yet a Linux box
+acting as a router can still be used for other purposes, such as fire-walling,
+running FTP, WWW or DNS server, etc.
+This kernel module introduces the notion of a WAN Link Driver (WLD) to Linux
+operating system and provides generic hardware-independent services for such
+drivers. Why can existing Linux network device interface not be used for
+this purpose? Well, it can. However, there are a few key differences between
+a typical network interface (e.g. Ethernet) and a WAN link.
+Many WAN protocols, such as X.25 and frame relay, allow for multiple logical
+connections (known as `virtual circuits' in X.25 terminology) over a single
+physical link. Each such virtual circuit may (and almost always does) lead
+to a different geographical location and, therefore, different network. As a
+result, it is the virtual circuit, not the physical link, that represents a
+route and, therefore, a network interface in Linux terms.
+To further complicate things, virtual circuits are usually volatile in nature
+(excluding so called `permanent' virtual circuits or PVCs). With almost no
+time required to set up and tear down a virtual circuit, it is highly desirable
+to implement on-demand connections in order to minimize network charges. So
+unlike a typical network driver, the WAN driver must be able to handle multiple
+network interfaces and cope as multiple virtual circuits come into existence
+and go away dynamically.
+Last, but not least, WAN configuration is much more complex than that of say
+Ethernet and may well amount to several dozens of parameters. Some of them
+are "link-wide" while others are virtual circuit-specific. The same holds
+true for WAN statistics which is by far more extensive and extremely useful
+when troubleshooting WAN connections. Extending the ifconfig utility to suit
+these needs may be possible, but does not seem quite reasonable. Therefore, a
+WAN configuration utility and corresponding application programmer's interface
+is needed for this purpose.
+Most of these problems are taken care of by this module. Its goal is to
+provide a user with more-or-less standard look and feel for all WAN devices and
+assist a WAN device driver writer by providing common services, such as:
+ o User-level interface via /proc file system
+ o Centralized configuration
+ o Device management (setup, shutdown, etc.)
+ o Network interface management (dynamic creation/destruction)
+ o Protocol encapsulation/decapsulation
+To ba able to use the Linux WAN Router you will also need a WAN Tools package
+available from
+ ftp.sangoma.com/pub/linux/current_wanpipe/wanpipe-X.Y.Z.tgz
+where vX.Y.Z represent the wanpipe version number.
+For technical questions and/or comments please e-mail to ncorbic@sangoma.com.
+For general inquiries please contact Sangoma Technologies Inc. by
+ Hotline: 1-800-388-2475 (USA and Canada, toll free)
+ Phone: (905) 474-1990 ext: 106
+ Fax: (905) 474-9223
+ E-mail: dm@sangoma.com (David Mandelstam)
+ WWW: http://www.sangoma.com
+Please read the WanpipeForLinux.pdf manual on how to
+install the WANPIPE tools and drivers properly.
+After installing wanpipe package: /usr/local/wanrouter/doc.
+On the ftp.sangoma.com : /linux/current_wanpipe/doc
+This program is free software; you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation; either version 2, or (at your option) any later version.
+This program is distributed in the hope that it will be useful, but WITHOUT
+ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License along with
+this program; if not, write to the Free Software Foundation, Inc., 675 Mass
+Ave, Cambridge, MA 02139, USA.
+This product is based on the WANPIPE(tm) Multiprotocol WAN Router developed
+by Sangoma Technologies Inc. for Linux 2.0.x and 2.2.x. Success of the WANPIPE
+together with the next major release of Linux kernel in summer 1996 commanded
+adequate changes to the WANPIPE code to take full advantage of new Linux
+Instead of continuing developing proprietary interface tied to Sangoma WAN
+cards, we decided to separate all hardware-independent code into a separate
+module and defined two levels of interfaces - one for user-level applications
+and another for kernel-level WAN drivers. WANPIPE is now implemented as a
+WAN driver compliant with the WAN Link Driver interface. Also a general
+purpose WAN configuration utility and a set of shell scripts was developed to
+support WAN router at the user level.
+Many useful ideas concerning hardware-independent interface implementation
+were given by Mike McLagan <mike.mclagan@linux.org> and his implementation
+of the Frame Relay router and drivers for Sangoma cards (dlci/sdla).
+With the new implementation of the APIs being incorporated into the WANPIPE,
+a special thank goes to Alan Cox in providing insight into BSD sockets.
+Special thanks to all the WANPIPE users who performed field-testing, reported
+bugs and made valuable comments and suggestions that help us to improve this
+ o Updated the WANCFG utility
+ Calls the pppconfig to configure the PPPD
+ for async connections.
+ o Added the PPPCONFIG utility
+ Used to configure the PPPD dameon for the
+ WANPIPE Async PPP and standard serial port.
+ The wancfg calls the pppconfig to configure
+ the pppd.
+ o Fixed the PCI autodetect feature.
+ The SLOT 0 was used as an autodetect option
+ however, some high end PC's slot numbers start
+ from 0.
+ o This release has been tested with the new backupd
+ daemon release.
+/etc: (or user defined)
+ wanpipe1.conf default router configuration file
+ wanrouter.o router kernel loadable module
+ af_wanpipe.o wanpipe api socket module
+ sdladrv.o Sangoma SDLA support module
+ wanpipe.o Sangoma WANPIPE(tm) driver module
+ Config reads current router configuration
+ Status reads current router status
+ {name} reads WAN driver statistics
+ wanrouter wanrouter start-up script
+ wanconfig wanrouter configuration utility
+ sdladump WANPIPE adapter memory dump utility
+ fpipemon Monitor for Frame Relay
+ cpipemon Monitor for Cisco HDLC
+ ppipemon Monitor for PPP
+ xpipemon Monitor for X25
+ wpkbdmon WANPIPE keyboard led monitor/debugger
+ README this file
+ COPYING GNU General Public License
+ Setup installation script
+ Filelist distribution definition file
+ wanrouter.rc meta-configuration file
+ (used by the Setup and wanrouter script)
+ wanpipeForLinux.pdf WAN Router User's Manual
+ wanrouter-v2213.gz patch for Linux kernels 2.2.11 up to 2.2.13.
+ wanrouter-v2214.gz patch for Linux kernel 2.2.14.
+ wanrouter-v2215.gz patch for Linux kernels 2.2.15 to 2.2.17.
+ wanrouter-v2218.gz patch for Linux kernels 2.2.18 and up.
+ wanrouter-v240.gz patch for Linux kernel 2.4.0.
+ wanrouter-v242.gz patch for Linux kernel 2.4.2 and up.
+ wanrouter-v2034.gz patch for Linux kernel 2.0.34
+ wanrouter-v2036.gz patch for Linux kernel 2.0.36 and up.
+ Sources of the latest WANPIPE device drivers.
+ These are used to UPGRADE the linux kernel to the newest
+ version if the kernel source has already been pathced with
+ WANPIPE drivers.
+ interface sample interface configuration file
+ wanpipe1.cpri CHDLC primary port
+ wanpipe2.csec CHDLC secondary port
+ wanpipe1.fr Frame Relay protocol
+ wanpipe1.ppp PPP protocol )
+ wanpipe1.asy CHDLC ASYNC protocol
+ wanpipe1.x25 X25 protocol
+ wanpipe1.stty Sync TTY driver (Used by Kernel PPPD daemon)
+ wanpipe1.atty Async TTY driver (Used by Kernel PPPD daemon)
+ wanrouter.rc sample meta-configuration file
+ * wan-tools utilities source code
+ * x25 api sample programs.
+ * chdlc api sample programs.
+ * fr api sample programs.
+ wancfg WANPIPE GUI configuration program.
+ Creates wanpipe#.conf files.
+ cfgft1 GUI CSU/DSU configuration program.
+ wanrouter.h router API definitions
+ wanpipe.h WANPIPE API definitions
+ sdladrv.h SDLA support module API definitions
+ sdlasfm.h SDLA firmware module definitions
+ if_wanpipe.h WANPIPE Socket definitions
+ if_wanpipe_common.h WANPIPE Socket/Driver common definitions.
+ sdlapci.h WANPIPE PCI definitions
+ * wanrouter source code
+ wanrouter wanrouter start-up log (created by the Setup script)
+/var/lock: (or /var/lock/subsys for RedHat)
+ wanrouter wanrouter lock file (created by the Setup script)
+ fr514.sfm Frame relay firmware for Sangoma S508/S514 card
+ cdual514.sfm Dual Port Cisco HDLC firmware for Sangoma S508/S514 card
+ ppp514.sfm PPP Firmware for Sangoma S508 and S514 cards
+ x25_508.sfm X25 Firmware for Sangoma S508 card.
+1.0.0 December 31, 1996 Initial version
+1.0.1 January 30, 1997 Status and statistics can be read via /proc
+ filesystem entries.
+1.0.2 April 30, 1997 Added UDP management via monitors.
+1.0.3 June 3, 1997 UDP management for multiple boards using Frame
+ Relay and PPP
+ Enabled continuous transmission of Configure
+ Request Packet for PPP (for 508 only)
+ Connection Timeout for PPP changed from 900 to 0
+ Flow Control Problem fixed for Frame Relay
+1.0.4 July 10, 1997 S508/FT1 monitoring capability in fpipemon and
+ ppipemon utilities.
+ Configurable TTL for UDP packets.
+ Multicast and Broadcast IP source addresses are
+ silently discarded.
+1.0.5 July 28, 1997 Configurable T391,T392,N391,N392,N393 for Frame
+ Relay in router.conf.
+ Configurable Memory Address through router.conf
+ for Frame Relay, PPP and X.25. (commenting this
+ out enables auto-detection).
+ Fixed freeing up received buffers using kfree()
+ for Frame Relay and X.25.
+ Protect sdla_peek() by calling save_flags(),
+ cli() and restore_flags().
+ Changed number of Trace elements from 32 to 20
+ Added DLCI specific data monitoring in FPIPEMON.
+2.0.0 Nov 07, 1997 Implemented protection of RACE conditions by
+ critical flags for FRAME RELAY and PPP.
+ DLCI List interrupt mode implemented.
+ IPX support in FRAME RELAY and PPP.
+ IPX Server Support (MARS)
+ More driver specific stats included in FPIPEMON
+ and PIPEMON.
+2.0.1 Nov 28, 1997 Bug Fixes for version 2.0.0.
+ Protection of "enable_irq()" while
+ "disable_irq()" has been enabled from any other
+ routine (for Frame Relay, PPP and X25).
+ Added additional Stats for Fpipemon and Ppipemon
+ Improved Load Sharing for multiple boards
+2.0.2 Dec 09, 1997 Support for PAP and CHAP for ppp has been
+ implemented.
+2.0.3 Aug 15, 1998 New release supporting Cisco HDLC, CIR for Frame
+ relay, Dynamic IP assignment for PPP and Inverse
+ Arp support for Frame-relay. Man Pages are
+ included for better support and a new utility
+ for configuring FT1 cards.
+2.0.4 Dec 09, 1998 Dual Port support for Cisco HDLC.
+ Support for HDLC (LAPB) API.
+ Supports BiSync Streaming code for S502E
+ and S503 cards.
+ Support for Streaming HDLC API.
+ Provides a BSD socket interface for
+ creating applications using BiSync
+ streaming.
+2.0.5 Aug 04, 1999 CHDLC initializatin bug fix.
+ PPP interrupt driven driver:
+ Fix to the PPP line hangup problem.
+ New PPP firmware
+ Added comments to the startup SYSTEM ERROR messages
+ Xpipemon debugging application for the X25 protocol
+ Fixed the odd boundary 4byte writes to the board.
+ BiSync Streaming code has been taken out.
+ Available as a patch.
+ Streaming HDLC API has been taken out.
+ Available as a patch.
+2.0.6 Aug 17, 1999 Increased debugging in statup scripts
+ Fixed insallation bugs from 2.0.5
+ Kernel patch works for both 2.2.10 and 2.2.11 kernels.
+ There is no functional difference between the two packages
+2.0.7 Aug 26, 1999 o Merged X25API code into WANPIPE.
+ o Fixed a memeory leak for X25API
+ o Updated the X25API code for 2.2.X kernels.
+ o Improved NEM handling.
+2.1.0 Oct 25, 1999 o New code for S514 PCI Card
+ o New CHDLC and Frame Relay drivers
+ o PPP and X25 are not supported in this release
+2.1.1 Nov 30, 1999 o PPP support for S514 PCI Cards
+2.1.3 Apr 06, 2000 o Socket based x25api
+ o Socket based chdlc api
+ o Socket based fr api
+ o Dual Port Receive only CHDLC support.
+ o Asynchronous CHDLC support (Secondary Port)
+ o cfgft1 GUI csu/dsu configurator
+ o wancfg GUI configuration file
+ configurator.
+ o Architectual directory changes.
+beta-2.1.4 Jul 2000 o Dynamic interface configuration:
+ Network interfaces reflect the state
+ of protocol layer. If the protocol becomes
+ disconnected, driver will bring down
+ the interface. Once the protocol reconnects
+ the interface will be brought up.
+ Note: This option is turned off by default.
+ o Dynamic wanrouter setup using 'wanconfig':
+ wanconfig utility can be used to
+ shutdown,restart,start or reconfigure
+ a virtual circuit dynamically.
+ Frame Relay: Each DLCI can be:
+ created,stopped,restarted and reconfigured
+ dynamically using wanconfig.
+ ex: wanconfig card wanpipe1 dev wp1_fr16 up
+ o Wanrouter startup via command line arguments:
+ wanconfig also supports wanrouter startup via command line
+ arguments. Thus, there is no need to create a wanpipe#.conf
+ configuration file.
+ o Socket based x25api update/bug fixes.
+ Added support for LCN numbers greater than 255.
+ Option to pass up modem messages.
+ Provided a PCI IRQ check, so a single S514
+ card is guaranteed to have a non-sharing interrupt.
+ o Fixes to the wancfg utility.
+ o New FT1 debugging support via *pipemon utilities.
+ o Frame Relay ARP support Enabled.
+beta3-2.1.4 Jul 2000 o X25 M_BIT Problem fix.
+ o Added the Multi-Port PPP
+ Updated utilites for the Multi-Port PPP.
+2.1.4 Aut 2000
+ o In X25API:
+ Maximum packet an application can send
+ to the driver has been extended to 4096 bytes.
+ Fixed the x25 startup bug. Enable
+ communications only after all interfaces
+ come up. HIGH SVC/PVC is used to calculate
+ the number of channels.
+ Enable protocol only after all interfaces
+ are enabled.
+ o Added an extra state to the FT1 config, kernel module.
+ o Updated the pipemon debuggers.
+ o Blocked the Multi-Port PPP from running on kernels
+ 2.2.16 or greater, due to syncppp kernel module
+ change.
+beta1-2.1.5 Nov 15 2000
+ o Fixed the MulitPort PPP Support for kernels 2.2.16 and above.
+ 2.2.X kernels only
+ o Secured the driver UDP debugging calls
+ - All illegal netowrk debugging calls are reported to
+ the log.
+ - Defined a set of allowed commands, all other denied.
+ o Cpipemon
+ - Added set FT1 commands to the cpipemon. Thus CSU/DSU
+ configuraiton can be performed using cpipemon.
+ All systems that cannot run cfgft1 GUI utility should
+ use cpipemon to configure the on board CSU/DSU.
+ o Keyboard Led Monitor/Debugger
+ - A new utilty /usr/sbin/wpkbdmon uses keyboard leds
+ to convey operatinal statistic information of the
+ Sangoma WANPIPE cards.
+ NUM_LOCK = Line State (On=connected, Off=disconnected)
+ CAPS_LOCK = Tx data (On=transmitting, Off=no tx data)
+ SCROLL_LOCK = Rx data (On=receiving, Off=no rx data
+ o Hardware probe on module load and dynamic device allocation
+ - During WANPIPE module load, all Sangoma cards are probed
+ and found information is printed in the /var/log/messages.
+ - If no cards are found, the module load fails.
+ - Appropriate number of devices are dynamically loaded
+ based on the number of Sangoma cards found.
+ Note: The kernel configuraiton option
+ CONFIG_WANPIPE_CARDS has been taken out.
+ o Fixed the Frame Relay and Chdlc network interfaces so they are
+ compatible with libpcap libraries. Meaning, tcpdump, snort,
+ ethereal, and all other packet sniffers and debuggers work on
+ all WANPIPE netowrk interfaces.
+ - Set the network interface encoding type to ARPHRD_PPP.
+ This tell the sniffers that data obtained from the
+ network interface is in pure IP format.
+ Fix for 2.2.X kernels only.
+ o True interface encoding option for Frame Relay and CHDLC
+ - The above fix sets the network interface encoding
+ type to ARPHRD_PPP, however some customers use
+ the encoding interface type to determine the
+ protocol running. Therefore, the TURE ENCODING
+ option will set the interface type back to the
+ original value.
+ NOTE: If this option is used with Frame Relay and CHDLC
+ libpcap library support will be broken.
+ i.e. tcpdump will not work.
+ Fix for 2.2.x Kernels only.
+ o Ethernet Bridgind over Frame Relay
+ - The Frame Relay bridging has been developed by
+ Kristian Hoffmann and Mark Wells.
+ - The Linux kernel bridge is used to send ethernet
+ data over the frame relay links.
+ For 2.2.X Kernels only.
+ o Added extensive 2.0.X support. Most new features of
+ 2.1.5 for protocols Frame Relay, PPP and CHDLC are
+ supported under 2.0.X kernels.
+beta1-2.2.0 Dec 30 2000
+ o Updated drivers for 2.4.X kernels.
+ o Updated drivers for SMP support.
+ o X25API is now able to share PCI interrupts.
+ o Took out a general polling routine that was used
+ only by X25API.
+ o Added appropriate locks to the dynamic reconfiguration
+ code.
+ o Fixed a bug in the keyboard debug monitor.
+beta2-2.2.0 Jan 8 2001
+ o Patches for 2.4.0 kernel
+ o Patches for 2.2.18 kernel
+ o Minor updates to PPP and CHLDC drivers.
+ Note: No functinal difference.
+beta3-2.2.9 Jan 10 2001
+ o I missed the 2.2.18 kernel patches in beta2-2.2.0
+ release. They are included in this release.
+Stable Release
+2.2.0 Feb 01 2001
+ o Bug fix in wancfg GUI configurator.
+ The edit function didn't work properly.
+bata1-2.2.1 Feb 09 2001
+ o WANPIPE TTY Driver emulation.
+ Two modes of operation Sync and Async.
+ Sync: Using the PPPD daemon, kernel SyncPPP layer
+ and the Wanpipe sync TTY driver: a PPP protocol
+ connection can be established via Sangoma adapter, over
+ a T1 leased line.
+ The 2.4.0 kernel PPP layer supports MULTILINK
+ protocol, that can be used to bundle any number of Sangoma
+ adapters (T1 lines) into one, under a single IP address.
+ Thus, efficiently obtaining multiple T1 throughput.
+ NOTE: The remote side must also implement MULTILINK PPP
+ protocol.
+ Async:Using the PPPD daemon, kernel AsyncPPP layer
+ and the WANPIPE async TTY driver: a PPP protocol
+ connection can be established via Sangoma adapter and
+ a modem, over a telephone line.
+ Thus, the WANPIPE async TTY driver simulates a serial
+ TTY driver that would normally be used to interface the
+ MODEM to the linux kernel.
+ o WANPIPE PPP Backup Utility
+ This utility will monitor the state of the PPP T1 line.
+ In case of failure, a dial up connection will be established
+ via pppd daemon, ether via a serial tty driver (serial port),
+ or a WANPIPE async TTY driver (in case serial port is unavailable).
+ Furthermore, while in dial up mode, the primary PPP T1 link
+ will be monitored for signs of life.
+ If the PPP T1 link comes back to life, the dial up connection
+ will be shutdown and T1 line re-established.
+ o New Setup installation script.
+ Option to UPGRADE device drivers if the kernel source has
+ already been patched with WANPIPE.
+ Option to COMPILE WANPIPE modules against the currently
+ running kernel, thus no need for manual kernel and module
+ re-compilatin.
+ o Updates and Bug Fixes to wancfg utility.
+bata2-2.2.1 Feb 20 2001
+ o Bug fixes to the CHDLC device drivers.
+ The driver had compilation problems under kernels
+ 2.2.14 or lower.
+ o Bug fixes to the Setup installation script.
+ The device drivers compilation options didn't work
+ properly.
+ o Update to the wpbackupd daemon.
+ Optimized the cross-over times, between the primary
+ link and the backup dialup.
+beta3-2.2.1 Mar 02 2001
+ o Patches for 2.4.2 kernel.
+ o Bug fixes to util/ make files.
+ o Bug fixes to the Setup installation script.
+ o Took out the backupd support and made it into
+ as separate package.
+beta4-2.2.1 Mar 12 2001
+ o Fix to the Frame Relay Device driver.
+ IPSAC sends a packet of zero length
+ header to the frame relay driver. The
+ driver tries to push its own 2 byte header
+ into the packet, which causes the driver to
+ crash.
+ o Fix the WANPIPE re-configuration code.
+ Bug was found by trying to run the cfgft1 while the
+ interface was already running.
+ o Updates to cfgft1.
+ Writes a wanpipe#.cfgft1 configuration file
+ once the CSU/DSU is configured. This file can
+ holds the current CSU/DSU configuration.
+>>>>>> END OF README <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<