1------------------------------------------------------------------------------ 2Linux WAN Router Utilities Package 3------------------------------------------------------------------------------ 4Version 2.2.1 5Mar 28, 2001 6Author: Nenad Corbic <ncorbic@sangoma.com> 7Copyright (c) 1995-2001 Sangoma Technologies Inc. 8------------------------------------------------------------------------------ 9 10INTRODUCTION 11 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 15connections. 16 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. 23 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. 31 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. 37 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. 44 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. 52 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. 61 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: 65 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 71 72To ba able to use the Linux WAN Router you will also need a WAN Tools package 73available from 74 75 ftp.sangoma.com/pub/linux/current_wanpipe/wanpipe-X.Y.Z.tgz 76 77where vX.Y.Z represent the wanpipe version number. 78 79For technical questions and/or comments please e-mail to ncorbic@sangoma.com. 80For general inquiries please contact Sangoma Technologies Inc. by 81 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 87 88 89INSTALLATION 90 91Please read the WanpipeForLinux.pdf manual on how to 92install the WANPIPE tools and drivers properly. 93 94 95After installing wanpipe package: /usr/local/wanrouter/doc. 96On the ftp.sangoma.com : /linux/current_wanpipe/doc 97 98 99COPYRIGHT AND LICENSING INFORMATION 100 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. 104 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. 108 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. 112 113 114 115ACKNOWLEDGEMENTS 116 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 121features. 122 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. 130 131Many useful ideas concerning hardware-independent interface implementation 132were given by Mike McLagan <mike.mclagan@linux.org> and his implementation 133of the Frame Relay router and drivers for Sangoma cards (dlci/sdla). 134 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. 137 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 140product. 141 142 143 144NEW IN THIS RELEASE 145 146 o Updated the WANCFG utility 147 Calls the pppconfig to configure the PPPD 148 for async connections. 149 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. 155 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. 160 161 o This release has been tested with the new backupd 162 daemon release. 163 164 165PRODUCT COMPONENTS AND RELATED FILES 166 167/etc: (or user defined) 168 wanpipe1.conf default router configuration file 169 170/lib/modules/X.Y.Z/misc: 171 wanrouter.o router kernel loadable module 172 af_wanpipe.o wanpipe api socket module 173 174/lib/modules/X.Y.Z/net: 175 sdladrv.o Sangoma SDLA support module 176 wanpipe.o Sangoma WANPIPE(tm) driver module 177 178/proc/net/wanrouter 179 Config reads current router configuration 180 Status reads current router status 181 {name} reads WAN driver statistics 182 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 192 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) 200 201/usr/local/wanrouter/doc: 202 wanpipeForLinux.pdf WAN Router User's Manual 203 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. 213 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. 219 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 231 232/usr/local/wanrouter/util: 233 * wan-tools utilities source code 234 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. 246 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 254 255 256/usr/src/linux/net/wanrouter: 257 * wanrouter source code 258 259/var/log: 260 wanrouter wanrouter start-up log (created by the Setup script) 261 262/var/lock: (or /var/lock/subsys for RedHat) 263 wanrouter wanrouter lock file (created by the Setup script) 264 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. 270 271 272REVISION HISTORY 273 2741.0.0 December 31, 1996 Initial version 275 2761.0.1 January 30, 1997 Status and statistics can be read via /proc 277 filesystem entries. 278 2791.0.2 April 30, 1997 Added UDP management via monitors. 280 2811.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 287 2881.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. 293 2941.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. 3052.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. 312 3132.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 319 3202.0.2 Dec 09, 1997 Support for PAP and CHAP for ppp has been 321 implemented. 322 3232.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. 328 3292.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. 337 3382.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. 350 3512.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 355 3562.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. 360 3612.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 364 3652.1.1 Nov 30, 1999 o PPP support for S514 PCI Cards 366 3672.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. 376 377beta-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. 383 384 Note: This option is turned off by default. 385 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. 390 391 Frame Relay: Each DLCI can be: 392 created,stopped,restarted and reconfigured 393 dynamically using wanconfig. 394 395 ex: wanconfig card wanpipe1 dev wp1_fr16 up 396 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. 401 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. 407 408 o Fixes to the wancfg utility. 409 o New FT1 debugging support via *pipemon utilities. 410 o Frame Relay ARP support Enabled. 411 412beta3-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. 415 4162.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. 420 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. 427 428 o Added an extra state to the FT1 config, kernel module. 429 o Updated the pipemon debuggers. 430 431 o Blocked the Multi-Port PPP from running on kernels 432 2.2.16 or greater, due to syncppp kernel module 433 change. 434 435beta1-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 438 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. 443 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. 449 450 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 458 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. 465 466 Note: The kernel configuration option 467 CONFIG_WANPIPE_CARDS has been taken out. 468 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. 477 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. 485 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. 490 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. 497 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. 501 502beta1-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. 511 512beta2-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. 517 518beta3-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. 521 522Stable Release 5232.2.0 Feb 01 2001 524 o Bug fix in wancfg GUI configurator. 525 The edit function didn't work properly. 526 527 528bata1-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. 535 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. 540 541 NOTE: The remote side must also implement MULTILINK PPP 542 protocol. 543 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. 548 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. 552 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). 558 559 Furthermore, while in dial up mode, the primary PPP T1 link 560 will be monitored for signs of life. 561 562 If the PPP T1 link comes back to life, the dial up connection 563 will be shutdown and T1 line re-established. 564 565 566 o New Setup installation script. 567 Option to UPGRADE device drivers if the kernel source has 568 already been patched with WANPIPE. 569 570 Option to COMPILE WANPIPE modules against the currently 571 running kernel, thus no need for manual kernel and module 572 re-compilation. 573 574 o Updates and Bug Fixes to wancfg utility. 575 576bata2-2.2.1 Feb 20 2001 577 578 o Bug fixes to the CHDLC device drivers. 579 The driver had compilation problems under kernels 580 2.2.14 or lower. 581 582 o Bug fixes to the Setup installation script. 583 The device drivers compilation options didn't work 584 properly. 585 586 o Update to the wpbackupd daemon. 587 Optimized the cross-over times, between the primary 588 link and the backup dialup. 589 590beta3-2.2.1 Mar 02 2001 591 o Patches for 2.4.2 kernel. 592 593 o Bug fixes to util/ make files. 594 o Bug fixes to the Setup installation script. 595 596 o Took out the backupd support and made it into 597 as separate package. 598 599beta4-2.2.1 Mar 12 2001 600 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. 607 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. 611 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. 616 617 618 619>>>>>> END OF README <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< 620