FarSync Drivers

WAN Installation Instructions

This section details how to install the software 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

Reminder: For loadable module support on 2.4.x kernels you should have modutils 2.4.2 or better installed. As root you can use "insmod -V" to check.

2.6 Kernels

For 2.6 Kernels there is no need to rebuild the entire Kernel source, although this can be done if required.  By default, the FarSync and FarSync Flex driver will be built as an external Kernel module.  However, you will need the Kernel Development Headers in place and you will need a symbolic link pointing to them in place at /usr/src/linux

The FarSync Flex drivers are not currently in the Kernel source tree and are only available for 2.6 Kernels, so this module must always be built as an external Kernel module.

In general, the 2.6 Kernels supported are:

Proceed to running the install script.

2.4 Kernels

For 2.4 Kernels the FarSync driver source is updated in the Kernel source tree. Therefore you will need a valid Kernel source tree for the Kernel that you are running.  This would normally be in place under /usr/src and it is required that a the symbolic link /usr/src/linux should point to it.  Please note that the FarSync Flex driver is not currently available for 2.4 Kernels.

Each distribution seems to have it's own methods of building Kernel Source, but the following method is the one that we use here at FarSite.

Installing the Kernel Source Tree

If you've never reconfigured the Kernel before it is recommended that you do so prior to installing the FarSite software and make sure you are happy with the procedure. Ensure that the Kernel you build can boot and contains all the functionality you require. If you are new to building Kernels, follow these steps:

See your system documentation for more information.

Once you have successfully built and booted into the new Kernel version then you are ready to continue with the next step.

Running the Install Script

The installation CD will contains a file called farsync-1.09.xx.tar.gz, where xx is a release number, e.g. 01.  Make a working directory and copy this file in to it. In this example, we have created a directory called fswan under the root directory and have copied the tar.gz file (farsync-1.09.xx.tar.gz) into it. Use the following command to unpack the software:

# tar -zxvf farsync-1.09.xx.tar.gz

Change directory to the newly created source tree

# cd farsync-1.09.xx

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
Kernel2.2/ Support files and scripts for 2.2.x driver
Kernel2.4/ Support files and scripts for 2.4.x sync driver
Kernel2.4-hdlc/ Support files and scripts for 2.4.x hdlc driver
Kernel2.4-oem/ Support files and scripts for 2.4.x oem driver
Kernel2.6/ Support files and scripts for 2.6.x sync driver
Kernel2.6-hdlc/ Support files and scripts for 2.6.x hdlc driver
Kernel2.6-oem/ Support files and scripts for 2.6.x oem driver
patch/ various patch files

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.

The kernel configuration system will be patched to include support for the FarSync cards (if required) unless it already contains this support from a previous patch or as standard.

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 or /usr/src/linux/drivers/net as appropriate with any previous versions being backed up as farsync.c~ and farsync.h~

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

For 2.6 Kernels, the install script will build the farsync and fsflex modules as external Kernel modules.  However, if your distribution does not have WAN drivers already built, then the hdlc modules, and possibly the syncppp modules must also be built as external kernel modules.  But, this is not a difficult step.

You will know if syncppp & hdlc module are required to be built because the install script will tell you.

If you 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 module.  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 it's 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/farsync1.09.xx, i.e. the directory from where the install command was executed.  

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 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

It is also convenient to load and unload the hdlc and syncppp modules with the farsync and fsflex drivers.  Edit the /etc/init.d file 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 protocl 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

The next step is to Start the Drivers.

2.4 Kernels

We now need to rebuild the Kernel with the FarSync driver enabled in the Kernel configuration.

Make sure that you are root, and change directory to /usr/src/linux. Configure the kernel using one of the following

make xconfig      if your System supports X
make menuconfig   if you have the curses library installed or
make config       if you prefer.

You should have already tested the kernel configuration and build process before installing the FarSite software (see above). Red Hat 7.1 users are reminded that they should perform a make mrproper the first time they build the kernel.

The Kernel configuration layout varies depending on the Kernel series that you are using, but the description below assumes that you are using a 2.6 Kernel series.  The Kernel config layout may differ for the older 2.4 Kernels.

Make sure that PCI Support (CONFIG_PCI) is enabled in the Bus Options menu. This is the default on most systems.

Under the Device Driver->Network device support menu select the Wan interfaces menu and enable Wan interface support.

Then enable the Generic HDLC Layer.  Under this section enable all the WAN protocols that you require, typically this might be Cisco HDLC Support and Syncronous Point-to-point Protocol Support. You should also enable FarSync T-Series support in the same menu. You can select these as modules or to be compiled into the Kernel.

Save and exit the configuration system as normal.

Rebuild and Install Kernel

Now you should rebuild and install the new kernel as normal. On many systems this can be performed with the following sequence of commands:

make dep
make bzImage
make modules
make modules_install
make install

Update modules.conf

If you elected to build the FarSync driver as a loadable module then you will need to setup identifying aliases in the modules configuration file. This is in /etc/modules.conf for 2.4 systems. 

For the first port on each card add a line like
alias hdlcX farsync 

where X is the interface number 0, 1, 2... to the file.  Note that if this is not done, then the card may not be loaded with firmware when the system boots.

When the Kernel build process is complete reboot into the Kernel you have just built.

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 ~]# [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 1.09.05 - Patch Level 00 - Build -b23
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 1.09.05 - Patch Level 00 - Build -b23
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 0 configuration file required to trigger download
In order to avoid probing non-existent hardware the firmware download script uses the presence of the configuration file for port zero as a marker to trigger the attempted download of the card firmware. If this file is not present then the card firmware will not be downloaded even if other ports on the card are configured. In order to download card firmware where port zero is not used simply create a dummy configuration file with the ONBOOT parameter set to "no".

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 1.09.05-00-32bit-b21 (c) 2001-2009 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 1.09.05-00-32bit-b21 (c) 2009 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-2010 FarSite Communications Ltd.