1.1   Obtaining NIFIC package

NIFIC package is available via WWW download page:

http://www.liberouter.org/clients

You can also check latest news at our web pages:

http://www.liberouter.org/

http://www.liberouter.org/nific.php

1.2   Package structure

The NIFIC package contains firmware and software to run NIFIC on COMBO cards. The package also contains NIFIC installation system, README and RELNOTES.

/firmware   - card firmware (*.mcs files)
/base       - source codes for software tools and drivers
   /mk                       - build system
   /sys_sw/drivers/linux     - Linux kernel drivers
   /sys_sw/hwtools           - necessary hardware tools for COMBO6 card
   /sys_sw/lib*              - libraries necessary for other tools
   /sys_sw/nsim              - nanoprocessor simulator
   /sys_sw/projects/nific    - configuration files and scripts for
                               using NIFIC
   /sys_sw/swtools/csxtool             - tool for handle COMBO6 XML files
   /vhdl_design/projects/nific4_1Gb/sw - NIFIC setting and testing programs
   /vhdl_design/units/       - necessary source files for testing programs
README      - this file
RELNOTES    - differences against previous release

2.1   Host computer

The NIFIC hardware has been designed to work on any PC-AT compatible computer running GNU/Linux or other "Unix-like" operating system. It has been tested only on computers that use the x86 family of processors. The hardware requirements necessary to run NIFIC are:

• Intel Pentium or equivalent x86 based PC
• COMBO6 - 32-bit/33 MHz PCI bus
• COMBO6X - 64-bit/66 MHz PCI bus

The "sandwich" consisting of COMBO6(X) and an interface card (COMBO-4MTX or COMBO-4SFPRO) fits into one PCI slot.

2.2   Supported hardware

2.3   Installing COMBO6 cards

After plugging Combo card into your PCI slot, you should test connection between the card and your PC. We use lspci(8) utility for this purpose. lspci(8) is a utility for displaying information about all PCI buses in the system and all devices connected to them. For correct recognition of the Combo card you need update PCI ID Database used by lspci(8) or download pciutils-2.2.2 (program collection containing lspci(8)) or later. If the lspci(8) output contains at least one of the following lines (according to the type of installed Combo card), your Combo card is connected properly.

$ lspci -d 18ec:
03:01.0 Ethernet controller: Cesnet, z.s.p.o. COMBO6X (rev 01)
04:02.0 Ethernet controller: Cesnet, z.s.p.o. COMBO6 (rev 01)

2.4   Building package

Compilation and installation process is covered by the build system located in the /base/mk directory. For more details about required tools necessary to build package see base/mk/REQUIREMENTS file.

To build kernel drivers needed by NIFIC package you will need fully configured Linux kernel source tree. More installation and compilation details about kernel drivers are available in the README file inside base/sys_sw/drivers/linux directory.

pkgtool(1) helps to build, install and uninstall a distribution package.

$ tar -xzvf nific-XX.YY.ZZ.tgz
$ cd nific-XX.YY.ZZ/base
$ ./pkgtool --build

Optionally you can define installation directory with the --prefix=path option. The --prefix option takes effect only during building package. If no prefix is set then /usr/local path is used.

$ ./pkgtool --build --prefix=/usr/local/nific

2.5   Installing package

The tools and kernel drivers will be installed to the installation directory (by default /usr/local).

# ./pkgtool --install

After successful installation some post-installation steps are required:

1. Set PATH variable to point to the installed tools directory -> ${PREFIX}/bin

   $ export PATH=$PATH:/usr/local/bin
   

2. Set /etc/ld.so.conf to point to the library directory -> ${PREFIX}/lib

   create file liberouter.conf with content /usr/local/lib (by default or with {PREFIX}/lib if you have used option --prefix during building process) in /etc/ld.so.conf.d directory:

   # echo "/usr/local/lib" > /etc/ld.so.conf.d/liberouter.conf
   # ldconfig
   

3. The driver needs device files in the /dev/combosix/ directory. To create them, run the combo6devices script in the /base/sys_sw/drivers/linux directory:

   # ./combo6devices
   

   To run NIFIC as a non-privileged user set r/w permissions on /dev/combosix/0 device.

   You have to change the permissions of the device file so that the non-privileged user that will execute the NIFIC tools has read-write access. For example, you can create a new group, say combo-rw, add that user to this group and change the file group ownership and permissions as follows:

   # chgrp combo-rw /dev/combosix/0
   # chmod 664 /dev/combosix/0
   

   Using recent 2.6 kernels it might be wanted to use the sysfs/udev mechanisms to create device files. For more details about udev see http://www.kernel.org/pub/linux/utils/kernel/hotplug/udev.html

   Example udev rules are placed in combo6.udev.rules file. Copy this file to /etc/udev/rules.d directory and modify it (change group or permissions). Following line will create combo6 device files required by NIFIC package:

   KERNEL=="combosix[0-9]*",       NAME="combosix/%n",     GROUP="combo-rw"

   NOTE:	Depending on your version of udevd you must adjust syntax of your udev rule file. Older versions of udevd require '=' character to match KERNEL key e.g. KERNEL="combosix[0-9]*". The newer one require '==' characters to match KERNEL key e.g. KERNEL=="combosix[0-9]*".

4. If you want to load NIFIC's kernel modules when the PC starts up, add following lines to the /etc/modules file.

   For COMBO6 card:

   combo6core
   combo6
   combo6-c6lr1
   

   For COMBO6X card:

   combo6core
   combo6x
   combo6x-c6pcreth
   

   After this, you don't need to run nific_lkm script any more.

2.6   Upgrading package

If you have used some previous version of the NIFIC package, please follow all building and installing steps described above. Post-installation steps can be skipped if you performed these steps during previous installation (and an installation path was the same!). pkgtool(1) is able to detect your NIFIC configuration files and it will ask you to decide if you wish to keep your own (but may be obsolete) configuration files or overwrite them with our default (but up-to-date) configuration files.

2.7   Uninstalling package

It is not possible (for safety reasons) to automatically uninstall NIFIC package. pkgtool(1) will only show directories where the NIFIC tools are placed. By default the NIFIC package uses following files and directories:

/dev/combosix/
/etc/liberouter/
/usr/local/bin/
/usr/local/etc/
/usr/local/include/
/usr/local/lib/
/usr/local/mcs/

3.1   NIFIC configuration files

Configuration files for NIFIC are placed in the /etc/liberouter/ directory and these are:

All files can be freely modified to redefine default values and to set-up filtration. Default installation copy of each file is stored in ${PREFIX}/etc/liberouter (by default /usr/local/etc/liberouter) directory. By default NIFIC behaves like a NIC without filtering or forwarding.

During installation of the next NIFIC package version you will be inquired if you prefer to keep your own configuration files (with your modifications) or to rewrite it with our up-to-date version. So you don't have to be worry to lose your changes. Up-to-date file will be copied to the ${PREFIX}/etc/liberouter directory.

src.IP  src.port  dst.IP           dst.port  LUP record(32 bits)
                                             reserved(24),MCAST(4),SW(4)

10.*.*.*    *       *.*.*.*           *       => 0000000F
# all packets with source address starting with 10 are sent to SW

192.*.*.*   *       *.*.*.*           *       => 00000000
# all packets with source address starting with 192 are filtered

*.*.*.*     *       192.225.215.59    80      => 00000080
# all packets with destination IP 192.225.215.59 and destination port 80
# are forwarded to interface 3

*.*.*.*     *       *.*.*.*           *       => 0000000F
# all other packets are sent to SW

bit 0: packet is sent to SW (=1) or is filtered(=0);
bit 4: packet is sent to interface 0 (bit4 = 1);
bit 5: packet is sent to interface 1 (bit5 = 1);
bit 6: packet is sent to interface 2 (bit6 = 1);
bit 7: packet is sent to interface 3 (bit7 = 1).

4.1   Loading kernel modules

nific_lkm script is used for loading/removing NIFIC kernel modules. There are two main options for this script. Option -l is used for loading NIFIC kernel modules and option -r is used for removing these modules. Script supports combo6 card as well as combo6x card. Detection of the card is performed by the lspci(8) utility.

When all kernel modules are loaded, csid(1) is able to detect type of plugged cards and provide more detailed information.

You should get following output on PC with installed

• combo6 mother card and mtx add-on card:

  $ csid
  combo6 mtx2 xcv2000
  

• combo6x mother card and sfpro add-on card:

  $ csid
  combo6x sfpro xc2vp20
  

4.2   Setting up NIFIC

nific is main start up script for NIFIC. Script boots firmware files (according to FIRMWARE_PATH variable from the /etc/liberouter/nific.conf), generates HFE and LUP programs to set up filter (according to content of the etc/liberouter/nific.filter.ipv*) and configures combo card interfaces. More information about using nific script can be displayed by -h option:

$ nific -h

4.3   Scripts usage

# nific_lkm -l
$ nific

After the execution of those scripts NIFIC is started and ready to use. There are four new network interfaces c6eth00 - c6eth03 in the system. Numbers in the interface names are set according to number of card plugged in the PC (the first digit - 0 in our example) and according to number of interface (second digit).

You can check that NIFIC is set up correctly by setting desired IP address to NIFIC interfaces (via nific.conf or ifconfig) and then ping(8) it from PC connected to some NIFIC port. Default behavior of NIFIC is usual NIC without filtering and packet forwarding (see Configuration section how to change it) so it will answer to echo request by echo reply.

Firmware can be checked by csid(1):

$ csid -s
Board    : combo6x
Addon    : sfpro
Chip     : xc2vp20
LAN ports: 4
Firmware : ok
SW       : 0x4f1c0000
HW       : 0x00020001
Text     : NIFIC_1Gbps

Detailed firmware description can be found at http://www.liberouter.org/nific.php - firmware architecture. HW number detected by csid -s reflects firmware version, e.g. HW : 0x00020001 reflects version NIFIC_02_01.

4.4   NIFIC init.d script

Startup scripts are used to start some service (or some script) at the machine's boot time. Our sample startup script is used to automatically start up the NIFIC (loads kernel modules, boots firmware and set up network interfaces) anytime your PC is starting up. Sample script is stored in the package directory structure in the base/sys_sw/projects/nific/doc directory as a nific.rc file. It is prepared for use in the SysV init system (tested on the Red Hat Linux distribution). Script is commented so you can get a lot of information directly from the script.

Startup script uses nific.conf file to set up network interfaces.

5.1   Simple NIFIC testing

If you want to check NIFIC features you can use for example this PC connection:

                             -----------
-----------                  |         |                  -----------
|         | eth0      c6eth0 |   PC +  | c6eth1      eth0 |         |
|   PC1   | ---------------- |  COMBO  | ---------------- |   PC2   |
|         |                  |         |                  |         |
-----------                  -----------                  -----------

where:

PC1 - eth0: IP = 10.0.0.3/8
PC2 - eth0: IP = 10.0.0.4/8

NIFIC:
  nific.conf:
      IP = 4
      C6ETH0_IP="10.0.0.1"
      C6ETH0_MASK="255.0.0.0"
      C6ETH1_IP="10.0.0.2"
      C6ETH1_MASK="255.0.0.0"

  nific.filter.ipv4:
      10.0.0.4    *       10.0.0.2          *       => 0000001F
      10.0.0.4    *       10.0.0.3          *       => 00000000
      *.*.*.*     *       *.*.*.*           *       => 0000000F

run tcpdump on PC1 eth0 and PC2 eth0 and perform following tests:

from PC1: ping 10.0.0.1
    - should be typical echo request - reply communication
from PC1: ping 10.0.0.4
    - should be typical echo request - reply communication
from PC with COMBO: ping 10.0.0.3
    - should be typical echo request - reply communication
from PC2: ping 10.0.0.2
    - should be typical echo request - reply communication plus
    - request packet should be forwarded via c6eth0 interface
      (and visible in tcpdump on PC1 eth0)
    - it matches first rule of nific.filter.ipv4
from PC2: ping 10.0.0.3
    - there should be no reply
    - packet is filtered due to the second rule

5.2   HW firewall with packet forwarding

Example of usage as a HW firewall with forwarding of unwanted traffic to honey-pot:

-------------------
|                 |
|    Internet     |
|                 |
-------------------
        |
        |
        | c6eth0
   -----------
   |         |                  -------------
   |   PC +  | c6eth1           |           |
   |  COMBO  | ---------------- | honey-pot |
   |         |                  |           |
   -----------                  -------------
        | c6eth2
        |
        |
-------------------
|                 |
|    Intranet     |
|                 |
-------------------

where:

c6eth0: IP = 10.0.0.1/16
c6eth1: IP = 10.1.0.1/16
c6eth2: IP = 10.2.0.1/16

NIFIC:
  nific.conf:
      IP = 4
      C6ETH0_IP="10.0.0.1"
      C6ETH0_MASK="255.255.0.0"
      C6ETH1_IP="10.1.0.1"
      C6ETH1_MASK="255.255.0.0"
      C6ETH2_IP="10.2.0.1"
      C6ETH2_MASK="255.255.0.0"

  nific.filter.ipv4:

      ### firewall rules
      # honey-pot is not accessible from Internet
      10.0.*.*    *       10.1.*.*          *       => 00000000
      # web services allowed in both directions
      *.*.*.*     *       *.*.*.*          80       => 0000000F
      # SMTP allowed in both directions
      *.*.*.*     *       *.*.*.*          25       => 0000000F
      # all other packets will be filtered (default match bellow)

      ### forwarding to honey-pot
      # unused telnet service forwarded to honey-pot
      # and honey-pot replies forwarded back to network:
      *.*.*.*     *       *.*.*.*          23       => 00000020
      *.*.*.*    23       *.*.*.*           *       => 00000010

      ### default match - packet is filtered
      *.*.*.*     *       *.*.*.*           *       => 00000000

7.1   Mailing lists

For any questions or general technical support issues, please send mail to the liberouter-support@liberouter.org general mailing list.

7.2   Submitting problem reports

Suggestions, bug reports and contributions of code are always valued. Please do not hesitate to report any problems you may find. Bug reports with attached fixes are of course even more welcome. You can use our mailing list to report bugs or (preferably) our bug tracking system at http://www.liberouter.org/bugtrack/ - project NIFIC.

7.3   Other COMBO6 based projects

Check our web pages for information about other projects, e.g. HW accelerated flow exporter or intrusion detection system.

http://www.liberouter.org/