WANPIPE (LITE) INSTALLATION AND OPERATIONS MANUAL ================================================= Copyright Sangoma Technologies Corporation 2004 INTRODUCTION ============ WANPIPE (LITE) is a software and hardware package that allows a user to transport TCP/IP traffic over a Wide Area Network. The hardware required for WANPIPE (LITE) is available from Sangoma Technologies Corporation and a wide range of physical interfaces are supported including T1, E1, serial, DDS, T3 and E3. The software components include a driver set, a loader and maintenance utilities. The WAN protocol stacks supported by WANPIPE (LITE) are not provided by Sangoma Technologies Corporation. Instead, these are independant software modules and are available in the specific distribution of the selected operating system. INSTALLING AND UNINSTALLING WANPIPE (LITE) FOR LINUX ==================================================== Downloading the WANPIPE (LITE) package for Linux ------------------------------------------------ WANPIPE(LITE) source packages are located at: ftp.sangoma.com/wanpipe-lite/linux Download the latest WANPIPE(LITE) release in any directory, and run: tar xvfz wanpipe-lite-.tgz The tar will create a temporary 'wanpipe_lite/' directory. Installing WANPIPE (LITE) for Linux ----------------------------------- WANPIPE (LITE) is installed using the 'Setup' script located in temporary 'wanpipe_lite/' directory. Running ./Setup install will do the following: 1. Check that all WANPIPE (LITE) files are accounted for. 2. Check/modify permissions on all WANPIPE (LITE) files. 3. Prompt the user to Install/Upgrade WANPIPE (LITE) drivers into the Linux kernel source. 4. Prompt the user to re-compile all WANPIPE (LITE)kernel drivers and install them as modules in the the current /lib/modules/ directory. 5. Prompt the user to install bootstrap scripts that will be used to start WANPIPE during boot up. 6. Setup the ENVIRONMENT configuration file that will contain directory locations of the WANPIPE configuration and lock files. 7. Compile all WANPIPE (LITE) utilities 8. Setup the WANPIPE (LITE) working environment and install all binary files into the Linux file tree. Directories used are as follows: /etc/wanpipe/samples sample configuration files. /usr/sbin user space, binary and utilites /lib/modules/ wanpipe kernel modules Un-Installing WANPIPE (LITE) for Linux -------------------------------------- WANPIPE (LITE) is un-installed using the 'Setup' script located in temporary 'wanpipe_lite/' directory. Running ./Setup remove will do the following: 1. Remove all boot strap WANPIPE (LITE) scripts. 2. Remove all utilities from '/usr/sbin' and '/etc/wanpipe' directories. After the 'Setup remove' command, it is safe to remove the whole temporary 'wanpipe_lite/' directory ('rm -rf wanpipe_lite/'). INSTALLING AND UNINSTALLING WANPIPE (LITE) FOR FreeBSD and OpenBSD ================================================================== General ------- 1. It is recommended that a Sangoma Device Driver package be installed on a FreeBSD/OPenBSD kernel that has no prior installation of Sangoma Device Drivers, unless upgrading from an earlier version. 2. All WANPIPE scripts must be run under bash (at least version 2.03) shell. 3. Ensure that you have a complete kernel source in your /usr/src/sys directory. A kernel source can be downloaded from ftp.freebsd.org or ftp.openbsd.org. 4. Ensure that your kernel has the SPPP option enabled in a kernel configuration file, as this option is required by the WANPIPE (LITE) device driver. Downloading the WANPIPE (LITE) package for FreeBSD/OpenBSD ---------------------------------------------------------- WANPIPE (LITE) source packages for FreeBSD (3.x/4.x/5.x releases) are located at: ftp.sangoma.com/wanpipe-lite/FreeBSD WANPIPE (LITE) source packages for OpenBSD are located at: ftp.sangoma.com/wanpipe-lite/OpenBSD Installing WANPIPE (LITE) for FreeBSD/OpenBSD --------------------------------------------- You can download the WANPIPE (LITE) package from the Sangoma ftp site and then install this package on your PC or you can install WANPIPE (LITE) directly from the Sangoma ftp site. To install a WANPIPE (LITE) package previously downloaded from the Sangoma ftp site, run the following command from the directory where the WANPIPE package is located: pkg_add wanpipe-lite-fbsd-X.Y.Z.tgz (for FreeBSD) pkg_add wanpipe-lite-obsd-X.Y.Z.tgz (for OpenBSD) To install the WANPIPE (LITE) package directly from the Sangoma ftp site, run the following command: pkg_add -f ftp://ftp.sangoma.com/wanpipe-lite/FreeBSD/wanpipe-lite- fbsd-X.Y.Z.tgz (for FreeBSD) pkg_add -f ftp://ftp.sangoma.com/wanpipe-lite/OpenBSD/wanpipe-lite- obsd-X.Y.Z.tgz (for FreeBSD) The 'pkg_add' utility will execute the following steps: 1. Download the WANPIPE (LITE) package (if you installing from Sangoma ftp site). 2. Unpack the WANPIPE (LITE) package in the /usr/local/wanpipe-lite directory. 3. Copy files to FreeBSD/OpenBSD kernel directories. 4. Set WANPIPE (LITE) global variables such as enable/disable Berkley Packet Filtering, enable/disable Alternative Queuing, enable/disable Sync PPP. 5. Compile and install driver/utilities. 6. Update, compile and install the FreeBSD/OpenBSD kernel. Note - To display the Sangoma WANPIPE (LITE) package information, run the following command: pkg_info wanpipe-lite Un-Installing WANPIPE (LITE) for FreeBSD/OpenBSD ------------------------------------------------ To remove the Sangoma WANPIPE (LITE) package from the system, run the following command: pkg_delete wanpipe-lite CONFIGURING WANPIPE (LITE) ========================== There are two methods of operating the WANPIPE (LITE)product: a) Using the 'wanlite' script provided to load and configure the driver (recommended). b) Manually loading and configuring the kernel driver module. It is important to note that if you elect to use the 'wanlite' script, a configuration file (ifcfg-hdlcN, where N=0, 1, 2, 3, etc.) must be created in the /etc/wanpipe directory for each WAN physical connection required. Each connection is allocated a device name (hdlcN, where N=0, 1, 2, 3, etc.) by the operating system, and this device name is used to identify the configuration file associated with the physical connection. In order to obtain a list of the device names allocated to the installed Sangoma hardware, run wanlite hwprobe You will see a display such as: hdlc0: AFT-A101-PCI : SLOT=13 : BUS=1 : IRQ=9 : CPU=A : PORT=PRI This indicates that Sangoma hardware has been found (adapter type AFT-A101-PCI) on the PCI bus and has been allocated the device name 'hdlc0'. The configuration file associated with this physical connection will be identified by the line DEVICE=hdlc0 in that configuration file. It is important to note that the parameters to be included in the configuration files are dependant on the selected physical interface and the WAN protocol to be used. Sample configuration files are located in the /etc/wanpipe/samples directory. You may use these samples as templates and edit them as appropriate to match your connectivity requirements. Configuration parameters common to all connections -------------------------------------------------- DEVICE the network device in use as discovered by running 'wanlite hwprobe' (for example, 'DEVICE=hdlc0'). BOARD the board type for this device - always set to 'BOARD=wanpipe'. MTU the local interface Maximum Transfer Unit (for example, 'MTU=1500'). ONBOOT defines whether the interface should be loaded on boot (for example, 'ONBOOT=yes'). UDPPORT UDP port value. This parameter is used by the `wanutil` debugging utility for accessing the WANPIPE driver(for example, 'UDPPORT=9000'). TTL the Time-to-Live value. This parameter is used by the `wanutil` debugging utility to define the number of hops permitted when accessing a remote system (for example, 'TTL=255'). PROTO the WAN protocol to be used on this physical connection. Valid options are 'ppp' (for PPP), 'cisco' (for Cisco HDLC) or 'fr' (for Frame Relay). MEDIA the physical connectivity medium used on this interface. Valid options are 't1' (for T1), 'e1' (for E1), 'rs232' (for RS-232), 'v35' (for V.35/V.11/X.21). Configuration parameters required to qualify the selected physical connectivity medium ('MEDIA' parameter) ------------------------------------------------------------------ For 'MEDIA=t1' LCODE the line encoding mode for this T1 link. Valid options are 'ami' or 'b8zs' (for example, 'LCODE=b8zs'). FRAME the framing mode for this T1 link. Valid options are 'esf' or 'd4'(for example, 'FRAME=esf') LBO the Line Build Out for this T1 link. Valid options are '0db', '7.5db', '15db', '22.5db', '110ft', '220ft', '330ft', '440ft', '550ft' or '660ft' (for example, 'LBO=7.5db'). RXSENS the receiver sensitivity for this interface. Valid options are 'sh' (for short haul) or 'lh' (for long haul). TECLOCK the T1 clock source for this interface. Valid options are 'normal' or 'master' (for example, 'TECLOCK=normal'). ACTIVE_CH the active 64Kb channels (DS0s) on this interface. For a full T1 link, set 'ACTIVE_CH=all'. For fractional links, set ACTIVE_CH to the active channels (timeslots) and/or channel ranges on the link, separating each channel or channel range by a period. Channel ranges are specified by the first and the last channel in the range, separated by a dash '-'. For example, 'ACTIVE_CH=1.2.4-6.10' means that the following timeslots are active: 1, 2, 4, 5, 6 and 10. It is important to note that WANPIPE (LITE) only supports a single link per physical connection, that is, full or fractional T1 support only. For 'MEDIA=e1' LCODE the line encoding mode for this E1 link. Valid options are 'ami' or 'hdb3' (for example, 'LCODE=hdb3'). FRAME the framing mode for this E1 link. Valid options are 'crc4', 'non-crc4' or 'unframed' (for example, 'FRAME=crc4'). TECLOCK the E1 clock source for this interface. Valid options are 'normal' or 'master' (for example, 'TECLOCK=normal'). ACTIVE_CH the active 64Kb channels (DS0s) on this interface. For a full E1 link, set 'ACTIVE_CH=all'. For fractional links, set ACTIVE_CH to the active channels (timeslots) and/or channel ranges on the link, separating each channel or channel range by a period. Channel ranges are specified by the first and the last channel in the range, separated by a dash '-'. For example, 'ACTIVE_CH=1.2.4-6.10' means that the following timeslots are active: 1, 2, 4, 5, 6 and 10. It is important to note that WANPIPE (LITE) only supports a single link per physical connection, that is, full or fractional E1 support only. For 'MEDIA=rs232' or 'MEDIA=v35' CLOCK defines the clock source for this interface. Valid options are 'int' (internal clock) or 'ext' (external clock). BAUDRATE Clock rate in bps. This parameter is only valid if internal clocking is used ('CLOCK=int'). Valid values are from 600 to 128000 bps for RS-232 and from 600 to 2048000 bps for V.35 (for example, 'BAUDRATE=2048000'). Configuration parameters required to qualify the selected WAN protocol ('PROTO' parameter) ---------------------------------------------------------------------- For 'PROTO=cisco' IPADDR the local interface IP address (for example, 'IPADDR=201.1.1.1'). NETMASK the local interface subnet mask (for example, 'NETMASK=255.255.255.0'). NETWORK the local interface network address (for example, 'NETWORK=201.1.1.0'). This value may be left blank if required. BROADCAST the local interface broadcast address (for example, 'BROADCAST=201.1.1.255'). This value may be left blank if required. POINTOPOINT the remote node IP address (for example, 'POINTOPOINT=201.1.1.2'). INTERVAL the time interval between transmitted keepalive frames (in seconds). Valid values are from 1 to 100 seconds (for example, 'INTERVAL=10'). Note that this parameter is applicable to the Linux OS (kernel 2.4.X) only. TIMEOUT the maximum time period between incoming keepalive frames required in order to maintain an active link (in seconds). Valid values are from 1 to 100 seconds (for example, 'TIMEOUT=25'). Note that this parameter is applicable to the Linux OS (kernel 2.4.X) only. An example of an ifcfg-hdlcN file for Cisco HDLC (E1 interface)would be as follows: DEVICE=hdlc0 BOARD=wanpipe IPADDR=202.1.1.2 NETMASK=255.255.255.0 NETWORK= BROADCAST= POINTOPOINT=202.1.1.1 MTU=1500 ONBOOT=yes UDPPORT=9000 TTL=255 MEDIA=e1 LCODE=hdb3 FRAME=ncrc4 TECLOCK=normal ACTIVE_CH=all PROTO=cisco INTERVAL=10 TIMEOUT=11 For 'PROTO=ppp' IPADDR the local interface IP address (for example, 'IPADDR=201.1.1.1'). NETMASK the local interface subnet mask (for example, 'NETMASK=255.255.255.0'). NETWORK the local interface network address (for example, 'NETWORK=201.1.1.0'). This value may be left blank if required. BROADCAST the local interface broadcast address (for example, 'BROADCAST=201.1.1.255'). This value may be left blank if required. POINTOPOINT the remote node IP address (for example, 'POINTOPOINT=201.1.1.2'). An example of an ifcfg-hdlcN file for PPP (T1 interface)would be as follows: DEVICE=hdlc0 BOARD=wanpipe IPADDR=202.1.1.2 NETMASK=255.255.255.0 NETWORK= BROADCAST= POINTOPOINT=202.1.1.1 MTU=1500 ONBOOT=yes UDPPORT=9000 TTL=255 MEDIA=t1 LCODE=b8zs FRAME=esf LBO=0db RXSENS=sh TECLOCK=normal ACTIVE_CH=all PROTO=ppp For 'PROTO=fr' DCE determines the operating mode of the Frame Relay device. Valid options are 'no' (for a Customer Premises Equipment location) or 'yes' (for a Frame Relay switch emulation). Note that the following parameters are applicable to the Linux OS (kernel 2.4.X) only. LMI the format of the Frame Relay signalling frames. Valid options are 'ansi' (ANSI T1.617 Annex D), 'ccitt' (Q.933) or 'none' (for example, 'LMI=ansi'). T391 the interval between the transmitted Link Integrity Verification Enquiry messages (used if 'DCE=no'). Valid values are from 5 to 30 seconds (for example, 'T391=10'). T392 the maximum interval between received Link Integrity Verification Enquiry messages (used if 'DCE=yes'). Valid values are from 5 to 30 seconds (for example, 'T392=15'). N391 the Full Status Polling Counter. Full Status Enquiry messages are sent every N391-th Status Enquiry message (used if 'DCE=no'). Valid values are from 1 to 255 (for example, 'N391=6'). N392 the number of errors during N393 monitored events which cause the network to be declared inactive. Valid values are from 1 and 10 (for example, 'N392=3'). N393 the monitored events counter for measuring N392. Valid values are from 1 and 10 (for example, 'N393=4'). IMPORTANT: When using Frame Relay, a file called ifcfg-pvcN must be created for each PVC (Permanent Virtual Circuit) to be included in the Frame Relay link. These PVC interface definition files are created in addition to the global configuration file ifcfg-hdlcN defined for the 'master' Frame Relay link and must be located in the /etc/wanpipe directory. Parameters used in the ifcfg-pvcN files are as follows: DEVICE the PVC device in use. The DEVICE name is also used as the interface name when using system utilities such as ifconfig. Each ifcfg-pvcN file must be given a different DEVICE name of format 'pvcN', where N=0, 1, 2, 3, etc (for example, 'DEVICE=pvc0'). MASTERDEV the 'master' Frame Relay network device with which this PVC is associated. The MASTERDEV corresponds to the DEVICE name in a previously created ifcfg-hdlcN file (for example, 'MASTERDEV=hdlc0'). DLCI the Frame Relay DLCI number for this PVC (for example, 'DLCI=16'). IPADDR the local interface IP address (for example, 'IPADDR=201.1.1.1'). NETMASK the local interface subnet mask (for example, 'NETMASK=255.255.255.0'). NETWORK the local interface network address (for example, 'NETWORK=201.1.1.0'). This value may be left blank if required. POINTOPOINT the remote DLCI IP address (for example, 'POINTOPOINT=201.1.1.2'). If this address should be dynamically allocated using inverse ARP, then set this value to 'inverse-arp'. CIR_RATE the bandwidth limit (Committed Information Rate) for this link in bits/second (for example, 'CIR_RATE=16000'). If no CIR is applicable to this PVC, then omit the CIR_RATE, CIR_INTERVAL and CIR_MARK parameters. CIR_INTERVAL the period of time to calculate the CIR, in seconds (for example, 'CIR_INTERVAL=1'). CIR_MARK a message identifier. Messages with this mark will not be discarded. You can use this option with NETFILTER. For example, if you use 'CIR_MARK=5' and you call the command: "#iptables -t mangle -A PREROUTING -p tcp -j MARK --set- mark 5", all messages that exceed CIR_RATE will be marked to be discarded excepting TCP messages. ONBOOT defines whether the interface should be loaded on boot (for example, 'ONBOOT=yes'). An example of an ifcfg-hdlcN file for Frame Relay (T1 interface)would be as follows: DEVICE=hdlc0 BOARD=wanpipe MTU=1500 ONBOOT=yes UDPPORT=9000 TTL=255 MEDIA=t1 LCODE=b8zs FRAME=esf LBO=0db RXSENS=sh TECLOCK=normal ACTIVE_CH=all PROTO=fr DCE=no LMI=ansi T391=10 T392=11 N391=6 N392=3 N393=4 An example of an ifcfg-pvcN file would be as follows: DEVICE=pvc0 MASTERDEV=hdlc0 DLCI=16 IPADDR=201.1.1.2 NETMASK=255.255.255.0 POINTOPOINT=201.1.1.1 NETWORK=201.1.1.0 CIR_RATE=32000 CIR_INTERVAL=1 CIR_MARK=20000 ONBOOT=yes Note that sample configuration files may be found in the /etc/wanpipe/samples directory. The files are as follows: ifcfg-hdlc0.cisco.e1 Cisco HDLC over E1 ifcfg-hdlc0.cisco.v35 Cisco HDLC over serial V.35 ifcfg-hdlc0.ppp.t1 PPP over T1 ifcfg-hdlc0.fr.t1 Frame Relay over T1 (master file) ifcfg-pvc0.hdlc0.dlci16 PVC for Frame Relay (hdlc0) master USING WANPIPE (LITE) ==================== There are two methods of loading and unloading the WANPIPE (LITE) drivers: 1) By using a simple script that has been provided. 2) By manually loading and configuring the kernel driver module. Using the WANPIPE (LITE) operation script ----------------------------------------- The 'wanlite` script serves to load and configure the kernel driver module, using the 'ifcfg-hdlcN' configuration file created by the user. Usage of this script is as follows: wanlite [up|down] Where: - WANPIPE (LITE) device name (hdlcN, where N=0, 1, 2, 3, etc.) as used in the 'ifcfg-hdlcN' configuration file. up - Load the WANPIPE (LITE) module and configure the interface. down - Shut the interface down and unload the WANPIPE (LITE) module Manually loading and configuring the kernel driver module --------------------------------------------------------- The steps for manually loading and configuring the kernel driver module are as follows: * Load the WANPIPE (LITE) kernel driver module. modprobe wanpipe-lite * Run ifconfig -a and check that at least one hdclN network interfaces has been created. * If more that one hdlcN interface has been created, run wanhdlc hdlcN so as to establish the association between the physical port and the network interface. * Use the 'wanhdlc' utility to set the physical and protocol parameters for the hdlcN interface (run 'wanhdlc' to print a usage message). For example, to set the T1 parameters and then configure the link for Cisco HDLC usage for the network interface 'hdlc0', run: wanhdlc hdlc0 t1 b8zs esf wanhdlc hdlc0 cisco interval 10 timeout 15 * Use the 'ifconfig' utility to set the IP information for the network interface. This command will automatically bring the network interface up. * If you want to save the current network interface configuration in a configuration file, do the following: * Run 'wandhlc hdlcN'. * Copy the output from this command to the file /etc/wanpipe/ifcfg-hdlcN (where N=0, 1, 2, 3, etc). Now, you can simply run 'wanlite hdlcN up' or 'wanlite hdlcN down' to bring the network interface hdlcN UP or DOWN. Troubleshooting the driver loading process ------------------------------------------ All WANPIPE (LITE)driver events are recorded in the file '/var/log/messages'. Thus, if errors occur, check this file for any obvious error messages relating to WANPIPE and the interface 'hdlcN'. DEBUGGING WANPIPE (LITE) ======================== General ------- All WANPIPE (LITE)driver events are recorded in the file '/var/log/messages'. Once the 'hdlcN' device has been sucessfully loaded and the physical connection established (for example, T1 connected with all alarms off), then the following message will be displayed: hdlcN: HDLC Framer Active! This message indicates that the physical communication parameters required by the Sangoma WANPIPE (LITE) product have been met and that HDLC frames may be passed to and from the selected protocol stack. Any WAN connectivity problems occurring after the HDLC framer has become active should be referred to the author/maintainer of the protocol stack. The 'wanutil' WANPIPE (LITE) Debugger ------------------------------------- The utility /usr/sbin/wanutil should be used to debug any connectivity problems that occur. This software is used to display line traces, protocol statistics, hardware statistics and configuration parameters. Complete usage of 'wanutil' may be found by running: wanutil -h and wanutil -traceinfo In summary, the general usage of 'wanutil' is as follows: For local debugging wanutil -i -c For remote debugging wanutil -i -u -c Note that 'local debugging' implies that the 'wanutil' utility is located on the same machine as the WANPIPE (LITE) card. Thus, 'wanutil' needs only the interface name to reach the driver. For example, /usr/sbin/wanutil -i hdlc0 -c xm When using 'remote debugging', 'wanutil' is located on a network (LAN or WAN) and must use the UDP protocol to reach the applicable WANPIPE (LITE) card. In this case, both the IP and UDP addresses must be specified, so that the debugging packet will pass through the network to access the WANPIPE (LITE) driver. For example: /usr/sbin/wanutil -i 201.1.1.2 -u 9000 -c xm Commonly used 'wanutil' debugging options ----------------------------------------- To read the T1/E1 alarm status and performance monitoring status: wanutil -i hdlc0 -c Ta For a successful physical connection to occur, all the listed T1/E1 alarms should be in the 'OFF' state. To read the modem status (serial line): wanutil -i hdlc0 -c xm Both DCD and CTS should be shown as being 'HIGH'in a successful physical connection. To read the communication error statistics: wanutil -i hdlc0 -c sc Check for CRC and Abort errors. If any error counters are incrementing, then there is a physical link issue which may include: A CSU/DSU misconfiguration on a T1 or E1 line. A noisy/bad line. To display real-time line trace data (raw hexadecimal mode): wanutil -i hdlc0 -c tr This allows the user to accurately determine: If there are frames being transferred in both directions ('OUTGOING' and 'INCOMING') on the link. The format of the actual data being transferred across the link.