PageRenderTime 22ms CodeModel.GetById 14ms app.highlight 2ms RepoModel.GetById 2ms app.codeStats 0ms

Plain Text | 622 lines | 486 code | 136 blank | 0 comment | 0 complexity | 0ee83fbb2f26b920f5a46fcd01e304a2 MD5 | raw file
  2Linux WAN Router Utilities Package
  4Version 2.2.1 
  5Mar 28, 2001
  6Author: Nenad Corbic <>
  7Copyright (c) 1995-2001 Sangoma Technologies Inc.
 12Wide Area Networks (WANs) are used to interconnect Local Area Networks (LANs)
 13and/or stand-alone hosts over vast distances with data transfer rates
 14significantly higher than those achievable with commonly used dial-up
 17Usually an external device called `WAN router' sitting on your local network
 18or connected to your machine's serial port provides physical connection to
 19WAN.  Although router's job may be as simple as taking your local network
 20traffic, converting it to WAN format and piping it through the WAN link, these
 21devices are notoriously expensive, with prices as much as 2 - 5 times higher
 22then the price of a typical PC box.
 24Alternatively, considering robustness and multitasking capabilities of Linux,
 25an internal router can be built (most routers use some sort of stripped down
 26Unix-like operating system anyway). With a number of relatively inexpensive WAN
 27interface cards available on the market, a perfectly usable router can be
 28built for less than half a price of an external router.  Yet a Linux box
 29acting as a router can still be used for other purposes, such as fire-walling,
 30running FTP, WWW or DNS server, etc.
 32This kernel module introduces the notion of a WAN Link Driver (WLD) to Linux
 33operating system and provides generic hardware-independent services for such
 34drivers.  Why can existing Linux network device interface not be used for
 35this purpose?  Well, it can.  However, there are a few key differences between
 36a typical network interface (e.g. Ethernet) and a WAN link.
 38Many WAN protocols, such as X.25 and frame relay, allow for multiple logical
 39connections (known as `virtual circuits' in X.25 terminology) over a single
 40physical link.  Each such virtual circuit may (and almost always does) lead
 41to a different geographical location and, therefore, different network.  As a
 42result, it is the virtual circuit, not the physical link, that represents a
 43route and, therefore, a network interface in Linux terms.
 45To further complicate things, virtual circuits are usually volatile in nature
 46(excluding so called `permanent' virtual circuits or PVCs).  With almost no
 47time required to set up and tear down a virtual circuit, it is highly desirable
 48to implement on-demand connections in order to minimize network charges.  So
 49unlike a typical network driver, the WAN driver must be able to handle multiple
 50network interfaces and cope as multiple virtual circuits come into existence
 51and go away dynamically.
 53Last, but not least, WAN configuration is much more complex than that of say
 54Ethernet and may well amount to several dozens of parameters.  Some of them
 55are "link-wide"  while others are virtual circuit-specific.  The same holds
 56true for WAN statistics which is by far more extensive and extremely useful
 57when troubleshooting WAN connections.  Extending the ifconfig utility to suit
 58these needs may be possible, but does not seem quite reasonable.  Therefore, a
 59WAN configuration utility and corresponding application programmer's interface
 60is needed for this purpose.
 62Most of these problems are taken care of by this module.  Its goal is to
 63provide a user with more-or-less standard look and feel for all WAN devices and
 64assist a WAN device driver writer by providing common services, such as:
 66 o User-level interface via /proc file system
 67 o Centralized configuration
 68 o Device management (setup, shutdown, etc.)
 69 o Network interface management (dynamic creation/destruction)
 70 o Protocol encapsulation/decapsulation
 72To ba able to use the Linux WAN Router you will also need a WAN Tools package
 73available from
 77where vX.Y.Z represent the wanpipe version number.
 79For technical questions and/or comments please e-mail to
 80For general inquiries please contact Sangoma Technologies Inc. by
 82	Hotline:	1-800-388-2475	(USA and Canada, toll free)
 83	Phone:		(905) 474-1990  ext: 106
 84	Fax:		(905) 474-9223
 85	E-mail:	(David Mandelstam)
 86	WWW:
 91Please read the WanpipeForLinux.pdf manual on how to 
 92install the WANPIPE tools and drivers properly. 
 95After installing wanpipe package: /usr/local/wanrouter/doc. 
 96On the : /linux/current_wanpipe/doc
101This program is free software; you can redistribute it and/or modify it under
102the terms of the GNU General Public License as published by the Free Software
103Foundation; either version 2, or (at your option) any later version.
105This program is distributed in the hope that it will be useful, but WITHOUT
106ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
107FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
109You should have received a copy of the GNU General Public License along with
110this program; if not, write to the Free Software Foundation, Inc., 675 Mass
111Ave, Cambridge, MA 02139, USA.
117This product is based on the WANPIPE(tm) Multiprotocol WAN Router developed
118by Sangoma Technologies Inc. for Linux 2.0.x and 2.2.x.  Success of the WANPIPE
119together with the next major release of Linux kernel in summer 1996 commanded
120adequate changes to the WANPIPE code to take full advantage of new Linux
123Instead of continuing developing proprietary interface tied to Sangoma WAN
124cards, we decided to separate all hardware-independent code into a separate
125module and defined two levels of interfaces - one for user-level applications
126and another for kernel-level WAN drivers.  WANPIPE is now implemented as a
127WAN driver compliant with the WAN Link Driver interface.  Also a general
128purpose WAN configuration utility and a set of shell scripts was developed to 
129support WAN router at the user level.
131Many useful ideas concerning hardware-independent interface implementation
132were given by Mike McLagan <> and his implementation
133of the Frame Relay router and drivers for Sangoma cards (dlci/sdla).
135With the new implementation of the APIs being incorporated into the WANPIPE,
136a special thank goes to Alan Cox in providing insight into BSD sockets.
138Special thanks to all the WANPIPE users who performed field-testing, reported
139bugs and made valuable comments and suggestions that help us to improve this
146	o Updated the WANCFG utility
147		Calls the pppconfig to configure the PPPD
148		for async connections.
150	o Added the PPPCONFIG utility
151		Used to configure the PPPD dameon for the
152		WANPIPE Async PPP and standard serial port.
153		The wancfg calls the pppconfig to configure
154		the pppd.
156	o Fixed the PCI autodetect feature.  
157		The SLOT 0 was used as an autodetect option
158		however, some high end PC's slot numbers start
159		from 0. 
161	o This release has been tested with the new backupd
162	  daemon release.
167/etc: (or user defined)
168	wanpipe1.conf	default router configuration file
171	wanrouter.o	router kernel loadable module
172	af_wanpipe.o	wanpipe api socket module
175	sdladrv.o	Sangoma SDLA support module
176	wanpipe.o	Sangoma WANPIPE(tm) driver module
179	Config		reads current router configuration
180	Status		reads current router status
181	{name}		reads WAN driver statistics
184	wanrouter	wanrouter start-up script
185	wanconfig	wanrouter configuration utility
186	sdladump	WANPIPE adapter memory dump utility
187        fpipemon        Monitor for Frame Relay
188        cpipemon        Monitor for Cisco HDLC
189	ppipemon 	Monitor for PPP
190	xpipemon 	Monitor for X25
191	wpkbdmon        WANPIPE keyboard led monitor/debugger
194	README		this file
195	COPYING		GNU General Public License
196	Setup		installation script
197	Filelist	distribution definition file
198	wanrouter.rc	meta-configuration file 
199			(used by the Setup and wanrouter script)
202	wanpipeForLinux.pdf 	WAN Router User's Manual
205	wanrouter-v2213.gz  	patch for Linux kernels 2.2.11 up to 2.2.13.
206	wanrouter-v2214.gz	patch for Linux kernel 2.2.14. 
207	wanrouter-v2215.gz	patch for Linux kernels 2.2.15 to 2.2.17.
208	wanrouter-v2218.gz	patch for Linux kernels 2.2.18 and up.
209	wanrouter-v240.gz	patch for Linux kernel 2.4.0.  
210	wanrouter-v242.gz	patch for Linux kernel 2.4.2 and up.
211	wanrouter-v2034.gz	patch for Linux kernel 2.0.34
212	wanrouter-v2036.gz 	patch for Linux kernel 2.0.36 and up. 
215	Sources of the latest WANPIPE device drivers.
216	These are used to UPGRADE the linux kernel to the newest
217	version if the kernel source has already been pathced with
218	WANPIPE drivers.
221	interface	sample interface configuration file
222	wanpipe1.cpri 	CHDLC primary port
223     	wanpipe2.csec 	CHDLC secondary port
224   	Frame Relay protocol
225     	wanpipe1.ppp  	PPP protocol ) 
226	wanpipe1.asy	CHDLC ASYNC protocol
227	wanpipe1.x25	X25 protocol
228	wanpipe1.stty	Sync TTY driver (Used by Kernel PPPD daemon)
229	wanpipe1.atty	Async TTY driver (Used by Kernel PPPD daemon)
230	wanrouter.rc	sample meta-configuration file
233	*		wan-tools utilities source code
236	*		x25 api sample programs.
238	*		chdlc api sample programs.
240	*		fr api sample programs.
242	wancfg		WANPIPE GUI configuration program.
243                        Creates wanpipe#.conf files. 
245	cfgft1		GUI CSU/DSU configuration program.
248	wanrouter.h	router API definitions
249	wanpipe.h	WANPIPE API definitions
250	sdladrv.h	SDLA support module API definitions
251	sdlasfm.h	SDLA firmware module definitions
252	if_wanpipe.h	WANPIPE Socket definitions
253	if_wanpipe_common.h	WANPIPE Socket/Driver common definitions.
254	sdlapci.h	WANPIPE PCI definitions
258	*		wanrouter source code
261	wanrouter	wanrouter start-up log (created by the Setup script)
263/var/lock:  (or /var/lock/subsys for RedHat)
264	wanrouter	wanrouter lock file (created by the Setup script)
267	fr514.sfm	Frame relay firmware for Sangoma S508/S514 card
268	cdual514.sfm	Dual Port Cisco HDLC firmware for Sangoma S508/S514 card
269	ppp514.sfm      PPP Firmware for Sangoma S508 and S514 cards
270	x25_508.sfm	X25 Firmware for Sangoma S508 card.
2751.0.0	December 31, 1996	Initial version
2771.0.1	January 30, 1997	Status and statistics can be read via /proc
278				filesystem entries.
2801.0.2   April 30, 1997          Added UDP management via monitors.
2821.0.3	June 3, 1997		UDP management for multiple boards using Frame
283				Relay and PPP
284				Enabled continuous transmission of Configure 
285				Request Packet for PPP (for 508 only)
286				Connection Timeout for PPP changed from 900 to 0
287				Flow Control Problem fixed for Frame Relay
2891.0.4	July 10, 1997		S508/FT1 monitoring capability in fpipemon and
290				ppipemon utilities.
291				Configurable TTL for UDP packets.
292				Multicast and Broadcast IP source addresses are
293				silently discarded.
2951.0.5	July 28, 1997		Configurable T391,T392,N391,N392,N393 for Frame
296				Relay in router.conf.
297				Configurable Memory Address through router.conf 
298				for Frame Relay, PPP and X.25. (commenting this
299 				out enables auto-detection).
300				Fixed freeing up received buffers using kfree()
301 				for Frame Relay and X.25.
302				Protect sdla_peek() by calling save_flags(),
303				cli() and restore_flags().
304				Changed number of Trace elements from 32 to 20
305				Added DLCI specific data monitoring in FPIPEMON. 
3062.0.0	Nov 07, 1997		Implemented protection of RACE conditions by 
307				critical flags for FRAME RELAY and PPP.
308				DLCI List interrupt mode implemented.
309				IPX support in FRAME RELAY and PPP.
310				IPX Server Support (MARS)
311				More driver specific stats included in FPIPEMON
312				and PIPEMON.
3142.0.1	Nov 28, 1997		Bug Fixes for version 2.0.0.
315				Protection of "enable_irq()" while 
316				"disable_irq()" has been enabled from any other
317				routine (for Frame Relay, PPP and X25).
318				Added additional Stats for Fpipemon and Ppipemon
319				Improved Load Sharing for multiple boards
3212.0.2	Dec 09, 1997		Support for PAP and CHAP for ppp has been
322				implemented.
3242.0.3	Aug 15, 1998		New release supporting Cisco HDLC, CIR for Frame
325				relay, Dynamic IP assignment for PPP and Inverse
326				Arp support for Frame-relay.  Man Pages are 
327				included for better support and a new utility
328				for configuring FT1 cards.
3302.0.4	Dec 09, 1998	        Dual Port support for Cisco HDLC.
331				Support for HDLC (LAPB) API.
332				Supports BiSync Streaming code for S502E 
333				and S503 cards.
334				Support for Streaming HDLC API.
335				Provides a BSD socket interface for 
336				creating applications using BiSync
337   				streaming.        
3392.0.5   Aug 04, 1999 		CHDLC initializatin bug fix.
340				PPP interrupt driven driver: 
341  				Fix to the PPP line hangup problem.
342				New PPP firmware
343				Added comments to the startup SYSTEM ERROR messages
344				Xpipemon debugging application for the X25 protocol
345				New USER_MANUAL.txt
346				Fixed the odd boundary 4byte writes to the board.
347				BiSync Streaming code has been taken out.  
348				 Available as a patch.
349				Streaming HDLC API has been taken out.  
350				 Available as a patch.                 
3522.0.6   Aug 17, 1999		Increased debugging in statup scripts
353				Fixed insallation bugs from 2.0.5
354				Kernel patch works for both 2.2.10 and 2.2.11 kernels.
355				There is no functional difference between the two packages         
3572.0.7   Aug 26, 1999		o  Merged X25API code into WANPIPE.
358				o  Fixed a memeory leak for X25API
359				o  Updated the X25API code for 2.2.X kernels.
360				o  Improved NEM handling.   
3622.1.0	Oct 25, 1999		o New code for S514 PCI Card
363				o New CHDLC and Frame Relay drivers
364				o PPP and X25 are not supported in this release    
3662.1.1	Nov 30, 1999		o PPP support for S514 PCI Cards
3682.1.3   Apr 06, 2000		o Socket based x25api 
369				o Socket based chdlc api
370				o Socket based fr api
371				o Dual Port Receive only CHDLC support.
372				o Asynchronous CHDLC support (Secondary Port)
373				o cfgft1 GUI csu/dsu configurator
374				o wancfg GUI configuration file 
375				  configurator.
376				o Architectual directory changes.
378beta-2.1.4 Jul 2000		o Dynamic interface configuration:
379					Network interfaces reflect the state
380					of protocol layer.  If the protocol becomes
381					disconnected, driver will bring down
382					the interface.  Once the protocol reconnects
383					the interface will be brought up. 
385					Note: This option is turned off by default.
387				o Dynamic wanrouter setup using 'wanconfig':
388					wanconfig utility can be used to
389					shutdown,restart,start or reconfigure 
390					a virtual circuit dynamically.
392					Frame Relay:  Each DLCI can be: 
393						      created,stopped,restarted and reconfigured
394						      dynamically using wanconfig.
396						      ex: wanconfig card wanpipe1 dev wp1_fr16 up
398				o Wanrouter startup via command line arguments:
399					wanconfig also supports wanrouter startup via command line
400					arguments.  Thus, there is no need to create a wanpipe#.conf
401					configuration file.  
403				o Socket based x25api update/bug fixes.
404					Added support for LCN numbers greater than 255.
405					Option to pass up modem messages.
406					Provided a PCI IRQ check, so a single S514
407					card is guaranteed to have a non-sharing interrupt.
409				o Fixes to the wancfg utility.
410				o New FT1 debugging support via *pipemon utilities.
411				o Frame Relay ARP support Enabled.
413beta3-2.1.4 Jul 2000		o X25 M_BIT Problem fix.
414				o Added the Multi-Port PPP
415				  Updated utilites for the Multi-Port PPP.
4172.1.4	Aut 2000
418				o In X25API:
419					Maximum packet an application can send
420					to the driver has been extended to 4096 bytes.
422					Fixed the x25 startup bug. Enable 
423					communications only after all interfaces
424					come up.  HIGH SVC/PVC is used to calculate
425					the number of channels.
426					Enable protocol only after all interfaces
427					are enabled.
429				o Added an extra state to the FT1 config, kernel module.
430				o Updated the pipemon debuggers.
432				o Blocked the Multi-Port PPP from running on kernels
433				  2.2.16 or greater, due to syncppp kernel module
434				  change. 
436beta1-2.1.5 	Nov 15 2000
437				o Fixed the MulitPort PPP Support for kernels 2.2.16 and above.
438				  2.2.X kernels only
440				o Secured the driver UDP debugging calls
441					- All illegal netowrk debugging calls are reported to
442					  the log.
443					- Defined a set of allowed commands, all other denied.
445				o Cpipemon
446					- Added set FT1 commands to the cpipemon. Thus CSU/DSU
447					  configuraiton can be performed using cpipemon.
448					  All systems that cannot run cfgft1 GUI utility should
449					  use cpipemon to configure the on board CSU/DSU.
452				o Keyboard Led Monitor/Debugger
453					- A new utilty /usr/sbin/wpkbdmon uses keyboard leds
454					  to convey operatinal statistic information of the 
455					  Sangoma WANPIPE cards.
456					NUM_LOCK    = Line State  (On=connected,    Off=disconnected)
457					CAPS_LOCK   = Tx data     (On=transmitting, Off=no tx data)
458					SCROLL_LOCK = Rx data     (On=receiving,    Off=no rx data
460				o Hardware probe on module load and dynamic device allocation
461					- During WANPIPE module load, all Sangoma cards are probed
462					  and found information is printed in the /var/log/messages.
463					- If no cards are found, the module load fails.
464					- Appropriate number of devices are dynamically loaded 
465					  based on the number of Sangoma cards found.
467					  Note: The kernel configuraiton option 
468						CONFIG_WANPIPE_CARDS has been taken out.
470				o Fixed the Frame Relay and Chdlc network interfaces so they are
471				  compatible with libpcap libraries.  Meaning, tcpdump, snort,
472				  ethereal, and all other packet sniffers and debuggers work on
473				  all WANPIPE netowrk interfaces.
474					- Set the network interface encoding type to ARPHRD_PPP.
475					  This tell the sniffers that data obtained from the
476					  network interface is in pure IP format.
477				  Fix for 2.2.X kernels only.
479				o True interface encoding option for Frame Relay and CHDLC
480					- The above fix sets the network interface encoding
481					  type to ARPHRD_PPP, however some customers use
482					  the encoding interface type to determine the
483					  protocol running.  Therefore, the TURE ENCODING
484					  option will set the interface type back to the
485					  original value.  
487					  NOTE: If this option is used with Frame Relay and CHDLC
488						libpcap library support will be broken.  
489						i.e. tcpdump will not work.
490					Fix for 2.2.x Kernels only.
492				o Ethernet Bridgind over Frame Relay
493					- The Frame Relay bridging has been developed by 
494					  Kristian Hoffmann and Mark Wells.  
495					- The Linux kernel bridge is used to send ethernet 
496					  data over the frame relay links.
497					For 2.2.X Kernels only.
499				o Added extensive 2.0.X support. Most new features of
500				  2.1.5 for protocols Frame Relay, PPP and CHDLC are
501				  supported under 2.0.X kernels. 
503beta1-2.2.0 	Dec 30 2000
504				o Updated drivers for 2.4.X kernels.
505				o Updated drivers for SMP support.
506				o X25API is now able to share PCI interrupts.
507				o Took out a general polling routine that was used
508				  only by X25API. 
509				o Added appropriate locks to the dynamic reconfiguration
510				  code.
511				o Fixed a bug in the keyboard debug monitor.
513beta2-2.2.0	Jan 8 2001
514				o Patches for 2.4.0 kernel
515				o Patches for 2.2.18 kernel
516				o Minor updates to PPP and CHLDC drivers.
517				  Note: No functinal difference. 
519beta3-2.2.9	Jan 10 2001
520				o I missed the 2.2.18 kernel patches in beta2-2.2.0
521				  release.  They are included in this release.
523Stable Release
5242.2.0		Feb 01 2001
525				o Bug fix in wancfg GUI configurator.
526					The edit function didn't work properly.
529bata1-2.2.1	Feb 09 2001
530			o WANPIPE TTY Driver emulation. 
531			  Two modes of operation Sync and Async.
532				Sync: Using the PPPD daemon, kernel SyncPPP layer
533				      and the Wanpipe sync TTY driver: a PPP protocol 
534				      connection can be established via Sangoma adapter, over
535				      a T1 leased line.
537				      The 2.4.0 kernel PPP layer supports MULTILINK
538				      protocol, that can be used to bundle any number of Sangoma
539				      adapters (T1 lines) into one, under a single IP address.
540				      Thus, efficiently obtaining multiple T1 throughput. 
542				      NOTE: The remote side must also implement MULTILINK PPP
543					    protocol.
545				Async:Using the PPPD daemon, kernel AsyncPPP layer
546				      and the WANPIPE async TTY driver: a PPP protocol
547				      connection can be established via Sangoma adapter and
548				      a modem, over a telephone line.
550				      Thus, the WANPIPE async TTY driver simulates a serial
551				      TTY driver that would normally be used to interface the 
552				      MODEM to the linux kernel.
554			o WANPIPE PPP Backup Utility
555				This utility will monitor the state of the PPP T1 line.
556				In case of failure, a dial up connection will be established
557				via pppd daemon, ether via a serial tty driver (serial port), 
558				or a WANPIPE async TTY driver (in case serial port is unavailable).
560				Furthermore, while in dial up mode, the primary PPP T1 link
561				will be monitored for signs of life.  
563				If the PPP T1 link comes back to life, the dial up connection
564				will be shutdown and T1 line re-established.
567			o New Setup installation script.
568				Option to UPGRADE device drivers if the kernel source has
569				already been patched with WANPIPE.
571				Option to COMPILE WANPIPE modules against the currently 
572				running kernel, thus no need for manual kernel and module
573				re-compilatin.
575			o Updates and Bug Fixes to wancfg utility.
577bata2-2.2.1	Feb 20 2001
579			o Bug fixes to the CHDLC device drivers.
580				The driver had compilation problems under kernels
581				2.2.14 or lower.
583			o Bug fixes to the Setup installation script.
584				The device drivers compilation options didn't work
585				properly.
587			o Update to the wpbackupd daemon.  
588				Optimized the cross-over times, between the primary
589				link and the backup dialup.
591beta3-2.2.1	Mar 02 2001
592			o Patches for 2.4.2 kernel.
594			o Bug fixes to util/ make files.
595			o Bug fixes to the Setup installation script.
597			o Took out the backupd support and made it into
598			  as separate package.
600beta4-2.2.1     Mar 12 2001
602		o Fix to the Frame Relay Device driver.
603			IPSAC sends a packet of zero length
604			header to the frame relay driver.  The
605			driver tries to push its own 2 byte header
606			into the packet, which causes the driver to
607			crash.
609		o Fix the WANPIPE re-configuration code.
610			Bug was found by trying to run  the cfgft1 while the
611			interface was already running.  
613		o Updates to cfgft1.
614			Writes a wanpipe#.cfgft1 configuration file
615			once the CSU/DSU is configured. This file can
616			holds the current CSU/DSU configuration.
620>>>>>> END OF README <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<