FarSync Drivers

WAN Installation Instructions

This section details how to install the FarSync drivers if you want to use the Kernel Network stack to set up Point-to-Point connections between nodes in a network to carry IP Traffic over protocols like PPP, Cisco HDLC or Frame Relay.  To successfully install this product, please follow the instructions in the following sequence.

Pre-Installation Requirements

Required Build Tools

The following are a prerequisite for the installation of the device driver and supporting software:

Kernel development system including:
C compiler
Make system
Patch utility

2.6 & 3.0 Kernels

The FarSync and FarSync Flex drivers are built as an external Kernel module.  In order to be compatible with your Kernel, you will requre a copy of the Kernel Development Headers to be in place and the following symbolic link pointing to them:

/usr/src/linux

The most usual place for the Kernel headers to reside is in or below the /usr/src directory, so after making the symbolic link your /usr/src directory may look like this:

[root@Rental fsx25-3.4.2]# ls -l /usr/src/
total 273396
drwxr-xr-x. 2 root root 4096 Sep 23 2011 debug
drwxr-xr-x. 3 root root 4096 Aug 1 2012 kernels
lrwxrwxrwx. 1 root root 34 Aug 1 2012 linux -> kernels/2.6.32-279.2.1.el6.x86_64/

In general, the Kernels supported supported by the farsync and flex drivers are:

Running the Install Script

The installation CD contains a file called farsync-2.2.x.tar.gz, where x is a release number, e.g. 2.  Make a working directory and copy this file into it. Use the following command to unpack the software:

# tar -zxvf farsync-2.2.x.tar.gz

Change directory to the newly created source tree:

# cd farsync-2.2.x

The source tree will contain the following files and sub-directories:

install The installation script
uninstall A script to uninstall the driver
Readme The Readme file
COPYING A copy of the GNU Public License
common/ Common files for the installation
doc/ Online documentation
farnetd/ Port monitoring utility
includes/ Include files for the drivers
kernel/ Support files and scripts for sync driver
kernel-hdlc/ Support files and scripts for hdlc driver
kernel-oem/ Support files and scripts for oem driver

As root, run the install script with the following command:

# ./install wan

Use ./install rather than simply install so as not to confuse the command with any standard install command that may be present on the system.

The installation script will detect the Kernel version under /usr/src/linux and perform some other checks before installing the software.

For FarSync T-Series cards the WAN driver source files farsync.c and farsync.h will be installed in /usr/src/linux/drivers/net/wan with any previous versions being backed up as farsync.c~ and farsync.h~.  The farsync and fsflex drivers are built as external modules.

The support utilities will be added to /sbin and support files placed in /etc/farsite/farsync.

If no configuration files are present then examples files will be placed in /etc/farsite/farsync (/etc/sysconfig/network-scripts on Red Hat like systems).

Post Install Actions

2.6 Kernels & 3.0 Kernels

In order to load the farsync and fsflex modules may require other WAN modules to be available.  If your distribution does not have the required WAN drivers already built, then these modules (hdlc modules, and possibly the syncppp modules) must also be built as external kernel modules.  But, this is not a difficult step.

The install script will inform you if you need to build the syncppp & hdlc modules.

If you do need to build the syncppp & hdlc modules follow the procedure below, otherwise proceed to Start the Drivers.

Building the syncppp & hdlc modules

The first thing that is required is the source file for the syncppp & hdlc modules.  This means that you will need to obtain the source code for the running Kernel.  For most distro's you can usually issue a command to get it, e.g.

# yum install kernel-devel 
# apt-get install kernel-source

If you are unable to find the kernel source in your distro or from its update manager, then download the nearest to it from www.kernel.org.  Locate the Kernel source to /usr/src and make the symbolic link to it (/usr/src/linux).

The following steps assume that you have a shell window open and the current working directory is /fswan/farsync-2.2.x, i.e. the directory from where the install command was executed.

If the Kernel version is below 2.6.19 do the following:

Note that if the Kernel version number is 2.6.19 or above then use the Makefile-with-hdlc-2.6.19, e.g.

cp Makefile-with-hdlc-2.6.19 Makefile

And if the Kernel version number is 2.6.29 or above then the syncppp.c file is no longer required, so the steps become:

And if the Kernel version number is 3.17.0 or above, the steps become:

It is also convenient to load and unload the hdlc and syncppp modules with the farsync and fsflex drivers.  Edit the /etc/init.d/farsync script and uncomment the following lines as indicated:

# If you are using the WAN driver and have built the syncppp
# and hdlc modules with the farsync module then
# uncomment the next 2 lines to load syncppp & hdlc with farsync
/sbin/insmod $MODULE_DIR/syncppp.ko
/sbin/insmod $MODULE_DIR/hdlc.ko

and

# If you are using the WAN driver and have built the syncppp
# and hdlc modules with the farsync module then
# uncomment the next 2 lines to unload syncppp & hdlc with farsync
/sbin/rmmod $MODULE_DIR/hdlc.ko
/sbin/rmmod $MODULE_DIR/syncppp.ko

If you are running a Kernel version that is 2.6.19 or later, then each hdlc protocol is a separate loadable module, and so you may wish to add additional insmod/rmmod lines to the init script to load and remove them.  For example, if you are configuring the PPP protocol then you may wish to add the following lines:

/sbin/insmod $MODULE_DIR/hdlc_ppp.ko

and

/sbin/rmmod $MODULE_DIR/hdlc_ppp.ko

There was a problem in the Generic HDLC module when using the PPP protocol in Kernel versions 2.6.23 to 2.6.25. The oops would occur when the interface was enabled (e.g. ifup hdlc0). There was also a problem with the Frame Relay protocol in 2.6.23. The Frame Relay line would become ready, but as soon as any PPP protocol was exchanged over the line the Kernel would panic. This was fixed in Kernel version 2.6.25

Start the Drivers

The next step is to start the drivers.  If you had to build the synppp module then load that module first if you did not update the /etc/init.d/farsync script to always load and unload it.  You can manually load the module with the command:

insmod syncppp.ko

and then start the drivers with the following command:

/etc/init.d/farsync start

If you have FarSync PCI cards installed, then you should see a message showing that the card is being loaded.  For example:

[root@odeon ~]# 
Loading T4U
[root@odeon ~]#

And you can cat the /proc/farsync and /proc/fsflex files to check that the interfaces are running.

[root@odeon ~]# 
[root@odeon ~]# more /proc/farsync 
FarSync WAN Driver version 2.2.2 - Patch Level 00 - Build -b233
1 Cards found
hdlc0-hdlc3:(W7418039) FarSync T4U IRQ5, 4 ports, State: Running 
Total number of ports = 4
Total number of async connects = 0
[root@odeon ~]# 
[root@odeon ~]# more /proc/fsflex 
FarSync Flex WAN Driver version 2.2.2 - Patch Level 00 - Build -b233
2 Cards found
hdlc4-hdlc4: FarSync Flex-1 (U0010063), 1 ports, State: Running 
hdlc5-hdlc5: FarSync Flex-1 (U0010096), 1 ports, State: Running 
Total number of ports = 2
Total number of async connects = 0
[root@odeon ~]# 

Port Configuration

Having successfully installed the drivers, the next stage is configuring the ports for use.  If you are connecting to a leased line, then the operational parameters for the line will have been provided by your service provider.

There are several ways to configure a line, but the method we recommend is of configuration through the use of config files.  During the install process some example config files will have been installed for you, and you can edit these files and modify them for your needs.

In order to configure the ports you will need to know:

Once you have set up the port configuration in the configuration files, you can apply the configuration and activate the port with a single command.  This will either be ifup (for RedHat based systems) or farifup (for Debian based systems).  If the configuration is successful then the line should be activated.  You can test this by pinging the remote point-to-point IP address.

Reboot (Optional)

Once the new kernel has been installed and you are happy with the initial configuration, reboot the system in the normal way. If not already done, this is a good time to power off and install the hardware.

As the system boots look for and check the FarSync card startup messages which should look something like this:

FarSync WAN driver 2.2.2-00-64bit-b233 (c) 2014 FarSite Communications Ltd.
hdlc0-hdlc3: (W7870001) FarSync T4U IRQ5, 4 ports
fst: fst_min_dma_len set to 0
fst: fst_dmathr set to dd00dd00
fst: fst_iocinfo_version set to 1
fst: Initialising flex tty driver
Flex USB WAN driver 2.2.2-00-64bit-b233 (c) 2014 FarSite Communications Ltd.
hdlc4-hdlc4: (U0010063) FarSync Flex-1, 1 ports
USB flex device now attached to Minor 0
hdlc5-hdlc5: (U0010096) FarSync Flex-1, 1 ports
USB flex device now attached to Minor 1

You can confirm that the drivers have found all the FarSync devices and check the card serial numbers by looking in the /proc/farsync and /proc/fsflex files as detailed above.

Copyright © 2001-2014 FarSite Communications Ltd.