| blob | bc2ab419a74aff2f60f147860cc66ff9713ef60f |
1 ------------------------------------------------------------------------------
2 Linux WAN Router Utilities Package
3 ------------------------------------------------------------------------------
4 Version 2.2.1
5 Mar 28, 2001
6 Author: Nenad Corbic <ncorbic@sangoma.com>
7 Copyright (c) 1995-2001 Sangoma Technologies Inc.
8 ------------------------------------------------------------------------------
10 INTRODUCTION
12 Wide Area Networks (WANs) are used to interconnect Local Area Networks (LANs)
13 and/or stand-alone hosts over vast distances with data transfer rates
14 significantly higher than those achievable with commonly used dial-up
15 connections.
17 Usually an external device called `WAN router' sitting on your local network
18 or connected to your machine's serial port provides physical connection to
19 WAN. Although router's job may be as simple as taking your local network
20 traffic, converting it to WAN format and piping it through the WAN link, these
21 devices are notoriously expensive, with prices as much as 2 - 5 times higher
22 then the price of a typical PC box.
24 Alternatively, considering robustness and multitasking capabilities of Linux,
25 an internal router can be built (most routers use some sort of stripped down
26 Unix-like operating system anyway). With a number of relatively inexpensive WAN
27 interface cards available on the market, a perfectly usable router can be
28 built for less than half a price of an external router. Yet a Linux box
29 acting as a router can still be used for other purposes, such as fire-walling,
30 running FTP, WWW or DNS server, etc.
32 This kernel module introduces the notion of a WAN Link Driver (WLD) to Linux
33 operating system and provides generic hardware-independent services for such
34 drivers. Why can existing Linux network device interface not be used for
35 this purpose? Well, it can. However, there are a few key differences between
36 a typical network interface (e.g. Ethernet) and a WAN link.
38 Many WAN protocols, such as X.25 and frame relay, allow for multiple logical
39 connections (known as `virtual circuits' in X.25 terminology) over a single
40 physical link. Each such virtual circuit may (and almost always does) lead
41 to a different geographical location and, therefore, different network. As a
42 result, it is the virtual circuit, not the physical link, that represents a
43 route and, therefore, a network interface in Linux terms.
45 To further complicate things, virtual circuits are usually volatile in nature
46 (excluding so called `permanent' virtual circuits or PVCs). With almost no
47 time required to set up and tear down a virtual circuit, it is highly desirable
48 to implement on-demand connections in order to minimize network charges. So
49 unlike a typical network driver, the WAN driver must be able to handle multiple
50 network interfaces and cope as multiple virtual circuits come into existence
51 and go away dynamically.
53 Last, but not least, WAN configuration is much more complex than that of say
54 Ethernet and may well amount to several dozens of parameters. Some of them
55 are "link-wide" while others are virtual circuit-specific. The same holds
56 true for WAN statistics which is by far more extensive and extremely useful
57 when troubleshooting WAN connections. Extending the ifconfig utility to suit
58 these needs may be possible, but does not seem quite reasonable. Therefore, a
59 WAN configuration utility and corresponding application programmer's interface
60 is needed for this purpose.
62 Most of these problems are taken care of by this module. Its goal is to
63 provide a user with more-or-less standard look and feel for all WAN devices and
64 assist 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
72 To ba able to use the Linux WAN Router you will also need a WAN Tools package
73 available from
75 ftp.sangoma.com/pub/linux/current_wanpipe/wanpipe-X.Y.Z.tgz
77 where vX.Y.Z represent the wanpipe version number.
79 For technical questions and/or comments please e-mail to ncorbic@sangoma.com.
80 For 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: dm@sangoma.com (David Mandelstam)
86 WWW: http://www.sangoma.com
89 INSTALLATION
91 Please read the WanpipeForLinux.pdf manual on how to
92 install the WANPIPE tools and drivers properly.
95 After installing wanpipe package: /usr/local/wanrouter/doc.
96 On the ftp.sangoma.com : /linux/current_wanpipe/doc
99 COPYRIGHT AND LICENSING INFORMATION
101 This program is free software; you can redistribute it and/or modify it under
102 the terms of the GNU General Public License as published by the Free Software
103 Foundation; either version 2, or (at your option) any later version.
105 This program is distributed in the hope that it will be useful, but WITHOUT
106 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
107 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
109 You should have received a copy of the GNU General Public License along with
110 this program; if not, write to the Free Software Foundation, Inc., 675 Mass
111 Ave, Cambridge, MA 02139, USA.
115 ACKNOWLEDGEMENTS
117 This product is based on the WANPIPE(tm) Multiprotocol WAN Router developed
118 by Sangoma Technologies Inc. for Linux 2.0.x and 2.2.x. Success of the WANPIPE
119 together with the next major release of Linux kernel in summer 1996 commanded
120 adequate changes to the WANPIPE code to take full advantage of new Linux
121 features.
123 Instead of continuing developing proprietary interface tied to Sangoma WAN
124 cards, we decided to separate all hardware-independent code into a separate
125 module and defined two levels of interfaces - one for user-level applications
126 and another for kernel-level WAN drivers. WANPIPE is now implemented as a
127 WAN driver compliant with the WAN Link Driver interface. Also a general
128 purpose WAN configuration utility and a set of shell scripts was developed to
129 support WAN router at the user level.
131 Many useful ideas concerning hardware-independent interface implementation
132 were given by Mike McLagan <mike.mclagan@linux.org> and his implementation
133 of the Frame Relay router and drivers for Sangoma cards (dlci/sdla).
135 With the new implementation of the APIs being incorporated into the WANPIPE,
136 a special thank goes to Alan Cox in providing insight into BSD sockets.
138 Special thanks to all the WANPIPE users who performed field-testing, reported
139 bugs and made valuable comments and suggestions that help us to improve this
140 product.
144 NEW IN THIS RELEASE
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 daemon 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.
165 PRODUCT COMPONENTS AND RELATED FILES
167 /etc: (or user defined)
168 wanpipe1.conf default router configuration file
170 /lib/modules/X.Y.Z/misc:
171 wanrouter.o router kernel loadable module
172 af_wanpipe.o wanpipe api socket module
174 /lib/modules/X.Y.Z/net:
175 sdladrv.o Sangoma SDLA support module
176 wanpipe.o Sangoma WANPIPE(tm) driver module
178 /proc/net/wanrouter
179 Config reads current router configuration
180 Status reads current router status
181 {name} reads WAN driver statistics
183 /usr/sbin:
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
193 /usr/local/wanrouter:
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)
201 /usr/local/wanrouter/doc:
202 wanpipeForLinux.pdf WAN Router User's Manual
204 /usr/local/wanrouter/patches:
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.
214 /usr/local/wanrouter/patches/kdrivers:
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 patched with
218 WANPIPE drivers.
220 /usr/local/wanrouter/samples:
221 interface sample interface configuration file
222 wanpipe1.cpri CHDLC primary port
223 wanpipe2.csec CHDLC secondary port
224 wanpipe1.fr 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
232 /usr/local/wanrouter/util:
233 * wan-tools utilities source code
235 /usr/local/wanrouter/api/x25:
236 * x25 api sample programs.
237 /usr/local/wanrouter/api/chdlc:
238 * chdlc api sample programs.
239 /usr/local/wanrouter/api/fr:
240 * fr api sample programs.
241 /usr/local/wanrouter/config/wancfg:
242 wancfg WANPIPE GUI configuration program.
243 Creates wanpipe#.conf files.
244 /usr/local/wanrouter/config/cfgft1:
245 cfgft1 GUI CSU/DSU configuration program.
247 /usr/include/linux:
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 sdlapci.h WANPIPE PCI definitions
256 /usr/src/linux/net/wanrouter:
257 * wanrouter source code
259 /var/log:
260 wanrouter wanrouter start-up log (created by the Setup script)
262 /var/lock: (or /var/lock/subsys for RedHat)
263 wanrouter wanrouter lock file (created by the Setup script)
265 /usr/local/wanrouter/firmware:
266 fr514.sfm Frame relay firmware for Sangoma S508/S514 card
267 cdual514.sfm Dual Port Cisco HDLC firmware for Sangoma S508/S514 card
268 ppp514.sfm PPP Firmware for Sangoma S508 and S514 cards
269 x25_508.sfm X25 Firmware for Sangoma S508 card.
272 REVISION HISTORY
274 1.0.0 December 31, 1996 Initial version
276 1.0.1 January 30, 1997 Status and statistics can be read via /proc
277 filesystem entries.
279 1.0.2 April 30, 1997 Added UDP management via monitors.
281 1.0.3 June 3, 1997 UDP management for multiple boards using Frame
282 Relay and PPP
283 Enabled continuous transmission of Configure
284 Request Packet for PPP (for 508 only)
285 Connection Timeout for PPP changed from 900 to 0
286 Flow Control Problem fixed for Frame Relay
288 1.0.4 July 10, 1997 S508/FT1 monitoring capability in fpipemon and
289 ppipemon utilities.
290 Configurable TTL for UDP packets.
291 Multicast and Broadcast IP source addresses are
292 silently discarded.
294 1.0.5 July 28, 1997 Configurable T391,T392,N391,N392,N393 for Frame
295 Relay in router.conf.
296 Configurable Memory Address through router.conf
297 for Frame Relay, PPP and X.25. (commenting this
298 out enables auto-detection).
299 Fixed freeing up received buffers using kfree()
300 for Frame Relay and X.25.
301 Protect sdla_peek() by calling save_flags(),
302 cli() and restore_flags().
303 Changed number of Trace elements from 32 to 20
304 Added DLCI specific data monitoring in FPIPEMON.
305 2.0.0 Nov 07, 1997 Implemented protection of RACE conditions by
306 critical flags for FRAME RELAY and PPP.
307 DLCI List interrupt mode implemented.
308 IPX support in FRAME RELAY and PPP.
309 IPX Server Support (MARS)
310 More driver specific stats included in FPIPEMON
311 and PIPEMON.
313 2.0.1 Nov 28, 1997 Bug Fixes for version 2.0.0.
314 Protection of "enable_irq()" while
315 "disable_irq()" has been enabled from any other
316 routine (for Frame Relay, PPP and X25).
317 Added additional Stats for Fpipemon and Ppipemon
318 Improved Load Sharing for multiple boards
320 2.0.2 Dec 09, 1997 Support for PAP and CHAP for ppp has been
321 implemented.
323 2.0.3 Aug 15, 1998 New release supporting Cisco HDLC, CIR for Frame
324 relay, Dynamic IP assignment for PPP and Inverse
325 Arp support for Frame-relay. Man Pages are
326 included for better support and a new utility
327 for configuring FT1 cards.
329 2.0.4 Dec 09, 1998 Dual Port support for Cisco HDLC.
330 Support for HDLC (LAPB) API.
331 Supports BiSync Streaming code for S502E
332 and S503 cards.
333 Support for Streaming HDLC API.
334 Provides a BSD socket interface for
335 creating applications using BiSync
336 streaming.
338 2.0.5 Aug 04, 1999 CHDLC initialization bug fix.
339 PPP interrupt driven driver:
340 Fix to the PPP line hangup problem.
341 New PPP firmware
342 Added comments to the startup SYSTEM ERROR messages
343 Xpipemon debugging application for the X25 protocol
344 New USER_MANUAL.txt
345 Fixed the odd boundary 4byte writes to the board.
346 BiSync Streaming code has been taken out.
347 Available as a patch.
348 Streaming HDLC API has been taken out.
349 Available as a patch.
351 2.0.6 Aug 17, 1999 Increased debugging in statup scripts
352 Fixed installation bugs from 2.0.5
353 Kernel patch works for both 2.2.10 and 2.2.11 kernels.
354 There is no functional difference between the two packages
356 2.0.7 Aug 26, 1999 o Merged X25API code into WANPIPE.
357 o Fixed a memory leak for X25API
358 o Updated the X25API code for 2.2.X kernels.
359 o Improved NEM handling.
361 2.1.0 Oct 25, 1999 o New code for S514 PCI Card
362 o New CHDLC and Frame Relay drivers
363 o PPP and X25 are not supported in this release
365 2.1.1 Nov 30, 1999 o PPP support for S514 PCI Cards
367 2.1.3 Apr 06, 2000 o Socket based x25api
368 o Socket based chdlc api
369 o Socket based fr api
370 o Dual Port Receive only CHDLC support.
371 o Asynchronous CHDLC support (Secondary Port)
372 o cfgft1 GUI csu/dsu configurator
373 o wancfg GUI configuration file
374 configurator.
375 o Architectural directory changes.
377 beta-2.1.4 Jul 2000 o Dynamic interface configuration:
378 Network interfaces reflect the state
379 of protocol layer. If the protocol becomes
380 disconnected, driver will bring down
381 the interface. Once the protocol reconnects
382 the interface will be brought up.
384 Note: This option is turned off by default.
386 o Dynamic wanrouter setup using 'wanconfig':
387 wanconfig utility can be used to
388 shutdown,restart,start or reconfigure
389 a virtual circuit dynamically.
391 Frame Relay: Each DLCI can be:
392 created,stopped,restarted and reconfigured
393 dynamically using wanconfig.
395 ex: wanconfig card wanpipe1 dev wp1_fr16 up
397 o Wanrouter startup via command line arguments:
398 wanconfig also supports wanrouter startup via command line
399 arguments. Thus, there is no need to create a wanpipe#.conf
400 configuration file.
402 o Socket based x25api update/bug fixes.
403 Added support for LCN numbers greater than 255.
404 Option to pass up modem messages.
405 Provided a PCI IRQ check, so a single S514
406 card is guaranteed to have a non-sharing interrupt.
408 o Fixes to the wancfg utility.
409 o New FT1 debugging support via *pipemon utilities.
410 o Frame Relay ARP support Enabled.
412 beta3-2.1.4 Jul 2000 o X25 M_BIT Problem fix.
413 o Added the Multi-Port PPP
414 Updated utilities for the Multi-Port PPP.
416 2.1.4 Aut 2000
417 o In X25API:
418 Maximum packet an application can send
419 to the driver has been extended to 4096 bytes.
421 Fixed the x25 startup bug. Enable
422 communications only after all interfaces
423 come up. HIGH SVC/PVC is used to calculate
424 the number of channels.
425 Enable protocol only after all interfaces
426 are enabled.
428 o Added an extra state to the FT1 config, kernel module.
429 o Updated the pipemon debuggers.
431 o Blocked the Multi-Port PPP from running on kernels
432 2.2.16 or greater, due to syncppp kernel module
433 change.
435 beta1-2.1.5 Nov 15 2000
436 o Fixed the MultiPort PPP Support for kernels 2.2.16 and above.
437 2.2.X kernels only
439 o Secured the driver UDP debugging calls
440 - All illegal network debugging calls are reported to
441 the log.
442 - Defined a set of allowed commands, all other denied.
444 o Cpipemon
445 - Added set FT1 commands to the cpipemon. Thus CSU/DSU
446 configuration can be performed using cpipemon.
447 All systems that cannot run cfgft1 GUI utility should
448 use cpipemon to configure the on board CSU/DSU.
451 o Keyboard Led Monitor/Debugger
452 - A new utility /usr/sbin/wpkbdmon uses keyboard leds
453 to convey operational statistic information of the
454 Sangoma WANPIPE cards.
455 NUM_LOCK = Line State (On=connected, Off=disconnected)
456 CAPS_LOCK = Tx data (On=transmitting, Off=no tx data)
457 SCROLL_LOCK = Rx data (On=receiving, Off=no rx data
459 o Hardware probe on module load and dynamic device allocation
460 - During WANPIPE module load, all Sangoma cards are probed
461 and found information is printed in the /var/log/messages.
462 - If no cards are found, the module load fails.
463 - Appropriate number of devices are dynamically loaded
464 based on the number of Sangoma cards found.
466 Note: The kernel configuration option
467 CONFIG_WANPIPE_CARDS has been taken out.
469 o Fixed the Frame Relay and Chdlc network interfaces so they are
470 compatible with libpcap libraries. Meaning, tcpdump, snort,
471 ethereal, and all other packet sniffers and debuggers work on
472 all WANPIPE network interfaces.
473 - Set the network interface encoding type to ARPHRD_PPP.
474 This tell the sniffers that data obtained from the
475 network interface is in pure IP format.
476 Fix for 2.2.X kernels only.
478 o True interface encoding option for Frame Relay and CHDLC
479 - The above fix sets the network interface encoding
480 type to ARPHRD_PPP, however some customers use
481 the encoding interface type to determine the
482 protocol running. Therefore, the TURE ENCODING
483 option will set the interface type back to the
484 original value.
486 NOTE: If this option is used with Frame Relay and CHDLC
487 libpcap library support will be broken.
488 i.e. tcpdump will not work.
489 Fix for 2.2.x Kernels only.
491 o Ethernet Bridgind over Frame Relay
492 - The Frame Relay bridging has been developed by
493 Kristian Hoffmann and Mark Wells.
494 - The Linux kernel bridge is used to send ethernet
495 data over the frame relay links.
496 For 2.2.X Kernels only.
498 o Added extensive 2.0.X support. Most new features of
499 2.1.5 for protocols Frame Relay, PPP and CHDLC are
500 supported under 2.0.X kernels.
502 beta1-2.2.0 Dec 30 2000
503 o Updated drivers for 2.4.X kernels.
504 o Updated drivers for SMP support.
505 o X25API is now able to share PCI interrupts.
506 o Took out a general polling routine that was used
507 only by X25API.
508 o Added appropriate locks to the dynamic reconfiguration
509 code.
510 o Fixed a bug in the keyboard debug monitor.
512 beta2-2.2.0 Jan 8 2001
513 o Patches for 2.4.0 kernel
514 o Patches for 2.2.18 kernel
515 o Minor updates to PPP and CHLDC drivers.
516 Note: No functional difference.
518 beta3-2.2.9 Jan 10 2001
519 o I missed the 2.2.18 kernel patches in beta2-2.2.0
520 release. They are included in this release.
522 Stable Release
523 2.2.0 Feb 01 2001
524 o Bug fix in wancfg GUI configurator.
525 The edit function didn't work properly.
528 bata1-2.2.1 Feb 09 2001
529 o WANPIPE TTY Driver emulation.
530 Two modes of operation Sync and Async.
531 Sync: Using the PPPD daemon, kernel SyncPPP layer
532 and the Wanpipe sync TTY driver: a PPP protocol
533 connection can be established via Sangoma adapter, over
534 a T1 leased line.
536 The 2.4.0 kernel PPP layer supports MULTILINK
537 protocol, that can be used to bundle any number of Sangoma
538 adapters (T1 lines) into one, under a single IP address.
539 Thus, efficiently obtaining multiple T1 throughput.
541 NOTE: The remote side must also implement MULTILINK PPP
542 protocol.
544 Async:Using the PPPD daemon, kernel AsyncPPP layer
545 and the WANPIPE async TTY driver: a PPP protocol
546 connection can be established via Sangoma adapter and
547 a modem, over a telephone line.
549 Thus, the WANPIPE async TTY driver simulates a serial
550 TTY driver that would normally be used to interface the
551 MODEM to the linux kernel.
553 o WANPIPE PPP Backup Utility
554 This utility will monitor the state of the PPP T1 line.
555 In case of failure, a dial up connection will be established
556 via pppd daemon, ether via a serial tty driver (serial port),
557 or a WANPIPE async TTY driver (in case serial port is unavailable).
559 Furthermore, while in dial up mode, the primary PPP T1 link
560 will be monitored for signs of life.
562 If the PPP T1 link comes back to life, the dial up connection
563 will be shutdown and T1 line re-established.
566 o New Setup installation script.
567 Option to UPGRADE device drivers if the kernel source has
568 already been patched with WANPIPE.
570 Option to COMPILE WANPIPE modules against the currently
571 running kernel, thus no need for manual kernel and module
572 re-compilation.
574 o Updates and Bug Fixes to wancfg utility.
576 bata2-2.2.1 Feb 20 2001
578 o Bug fixes to the CHDLC device drivers.
579 The driver had compilation problems under kernels
580 2.2.14 or lower.
582 o Bug fixes to the Setup installation script.
583 The device drivers compilation options didn't work
584 properly.
586 o Update to the wpbackupd daemon.
587 Optimized the cross-over times, between the primary
588 link and the backup dialup.
590 beta3-2.2.1 Mar 02 2001
591 o Patches for 2.4.2 kernel.
593 o Bug fixes to util/ make files.
594 o Bug fixes to the Setup installation script.
596 o Took out the backupd support and made it into
597 as separate package.
599 beta4-2.2.1 Mar 12 2001
601 o Fix to the Frame Relay Device driver.
602 IPSAC sends a packet of zero length
603 header to the frame relay driver. The
604 driver tries to push its own 2 byte header
605 into the packet, which causes the driver to
606 crash.
608 o Fix the WANPIPE re-configuration code.
609 Bug was found by trying to run the cfgft1 while the
610 interface was already running.
612 o Updates to cfgft1.
613 Writes a wanpipe#.cfgft1 configuration file
614 once the CSU/DSU is configured. This file can
615 holds the current CSU/DSU configuration.
619 >>>>>> END OF README <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<