Documentation - FINS v0.8.0

From FINSwiki
Jump to: navigation, search



Simulation is still the most widely adopted performance evaluation technique in mobile ad hoc network research, in spite of a growing number of questions about the fidelity of this technique. Implementation-based testing and evaluation of wireless networks tends to produce believable results, but the technique sometimes suffers from poor repeatability, high implementation cost, and complex experimental logistics. The Flexible Internetwork Stack (FINS) framework, is an open-source solution for network protocol implementation, integration, and testing. FINS is a software tool to enable implementation-based experimental research on wireless networks. FINS aims to provide researchers with monitoring, logging, and reconfiguring utilities similar to the ones provided by simulation environments or emulation testbeds.

Motivation and Use Cases

Objectives and Motivation

The FINS Framework is a modular software framework which aims to lower the barrier for implementation-based wireless network experiments across the network stack by providing access to functionality that is usually implemented as part of the operating system kernel. The goal of the FINS Framework is to provide researchers with generic modules and interfaces which can be used to:

  1. build conventional and innovative network stacks using existing or new layers, protocols, and algorithms;
  2. monitor and log the behavior of the stack components;
  3. dynamically control the behavior of the network stack during run-time by modifying certain control parameters bound to each module; and
  4. dynamically load, link and de-link stack components to support a wide range of experimental benchmarking scenarios.

The main motivation for the FINS Framework is to encourage the research community to adopt implementation-based experiments as a trusted technique to evaluate the performance of new network protocols or algorithms. The FINS project is inspired by the MANIAC Challenge experimental competition MANIAC, which gave us better insight into the real performance of the TCP/IP stack in wireless ad hoc networks. For example, we noted significant differences in how ad hoc routing protocols perform in real environments compared to simulation scenarios, pointing to the necessity of implementation-based experiments. Also, the technical challenges faced to implement the MANIAC Challenge API and the logistical challenges of the MANIAC experiments motivate us to present the FINS Framework to the research community.

Use Cases

  • Research and experiments on Cross-Layer proposals
    • Improve transport and routing protocols in wireless networks using cross layer solutions.
    • The FINS Framework allows the exchange of control information bi-directionally between two adjacent or non-adjacent layers.
    • Cross layer solutions schemes can be divided into four classes
      • Vertical Calibration Control Flow
      • Upward Control Flow
      • Downward Control Flow
      • Back and Forth Control Flow
      • Merging Data-Flow between Adjacent Layers
  • Research and experiments on Cognitive Network Code, and Cognitive Network Protocols Stack
  • Research ad experiments on disruption and Delay-tolerant-networking Protocols
    • Bundle Protocols
  • Research and experiments on Context Aware Protocols

Architecture Overview

Fins arch.jpg

Figure 1: FINS Framework Architecture next to the traditional stack

  • The central component of the FINS framework, as shown in Figure (1) above, is the FINS Switch. It is responsible for forwarding control and data traffic between the various modules above the data link layer. Instead of moving the data between adjacent layers as in the conventional stack, the data traffic coming in from (or out to) the data link layer will be directed to the switch module, which forwards the data to the appropriate protocol module as specified into the linking table, discussed later.
  • The FINS Framework uses its own frame format which differs based on whether the FINS frame contains conventional protocol data units, control instructions or notifications. In order to maintain backward compatibility with legacy applications, the FINS Framework retains the conventional applications socket interface.
  • A stub module, the socket stub, is used to redirect the traffic coming down from (or up to) the application to the switch and vice versa. A data link stub is responsible for capturing the incoming traffic and injecting the outgoing traffic from/to the data link layer. Both stubs make sure that the FINS Framework is transparent to the applications and the layers below the network layer.


FINS Frames

  • FINS Data Frame (FDF)

|| Data/Control | Destination_IDs_List | Direction_Flag | Length_Of_PDU | PDU | MetaData ||

  • FINS Control Frames (FCFs)
    • General Control Frame Structure

|| Data/Control | Destination_IDs_List | SenderID | Operation_Code | ........... ||

    • Read Parameter (Knob/meter) Request

|| Data/Control | Destination_IDs_List | SenderID | Read_Param_Request_Code | ParameterID | Serial_Number ||

    • Read Parameter (Knob/meter) Reply

|| Data/Control | Destination_IDs_List | SenderID | Read_Param_Reply_Code | Value | Serial_Number ||

    • Write Parameter (Knob) Request

|| Data/Control | Destination_IDs_List | SenderID | Write_parameter_Request_code | ParameterID | Value | Serial_Number ||

    • Write Parameter (Knob) Confirmation

|| Data/Control | Destination_IDs_List | SenderID | Write_parameter_Confirmation_Code | Serial_Number ||

    • Query Request

|| Data/Control | Destination_IDs_List | SenderID | Query_Request_Code | Serial_Number ||

    • Query Reply

|| Data/Control | DestinationID | SenderID | Query_Reply_Code| Serial_Number| Number_Of_Records=N | Record(1) | ... | Record (N) ||

data modules

  • Data modules are modules which implement the functional behavior of a network protocol or algorithm, such as IPv4, TCP, ICMP, and ARP. Protocol modules can be also programmed to send statistics periodically to another interested module through the switch. Socket Stub and Ethernet Stub are also considered Data Modules.
  • FINS v1 includes modules for IPv4, UDP, socket stub and Ethernet stub.

non-data modules

  • A non-data module is a module which contributes toward the control or managerial tasks of the FINS Framework.
  • FINS v1 includes only one non-data modules which is the SWITCH Module
  • Other Non-Data modules will be implemented in later versions, or might be even implemented by the users.
  • For example;
    • A Logging Module is a module which can be programmed to collect various metrics about the network stack. Such a module can be implemented using the control frames provided as part of FINS.
    • Supervisory module, another non-data module, behaves as a master module. It has the capability to control the FINS framework including the switch module itself. The supervisory module can send control instructions to any of the modules linked to the switch. It can also change the path the data travels among the modules by reconfiguring the linking table which the switch module maintains for forwarding FINS frames.
  • The switch module broadcasts a copy of the linking table to other modules whenever an update takes place. Other modules use their local cached copies to determine the appropriate ID(s) of the destination module(s)to fill into FINS frames, while the switch only forwards the frames to the destination(s).

communications channel

Implementation Overview


  1. Main Outgoing Communication Channel (Named Pipe)
  2. Incoming Communication Channels ( A Named Pipe per Each Socket )
  3. Jinni-To-Switch FINS Frames Queue
  4. Switch-To-Jinni FINS Frames Queues (A Queue per each Socket)
  5. Pair of IN-OUT FINS Frames Queues (UDP-To-Switch, and Switch-To-UDP)
  6. Pair of IN-OUT FINS Frames Queues (IPv4-To-Switch, and Switch-To-IPv4)
  7. Outgoing Traffic (Named Pipe) Carrying Ethernet Frames
  8. Incoming Traffic (Named Pipe) Carrying Ethernet Frames

Initial Setup and Installation

System Requirements

  • Linux Ubuntu 9.10 or higher (FINS Framework has been tested on both 9.10 and 10.04).
  • FINS Framework is supposed to work on any Linux distribution as long as it has Kernel 2.6.x, and the list of dependent libraries mentioned below.
  • Correctly functioning Network Adapter either wired Ethernet Card or WiFi Card.
  • Correctly Installed and functioning Driver for the Network Adapter mentioned above.
  • The driver must support and match the minimum capturing and injection features mentioned in the LibPCAP documentation

Libraries and Dependencies

The metadata library

  • Here is an internal link describes some facts on the metadata library we have chosen libconfig


  • Download and install The Libconfig library Libconfig
  • Notice that the libconfig is available under GNU Lesser General Public License !

Frames capturing and Injetion library LIBPCAP

  • Make sure that LibPCAP is installed. In case it is not found you can install it using apt-get install command or manually from the provided link TCPDUMP and LiPCAP . Notice that TCPDUMO AND LiPCAP are used usually to refer to the same library , although they are not the same.
  • LibPCAP is available under BSD license

MultiThreading support using pthread

  • pthread runs on kernel 2.6.x based on NPTL. No more use of The LinuxThreads.
  • NPTL Now is part of the linux kernel starting from kernel 2.6. and fully integrated into GLibc (GNU C library)
  • GNU C library in released under lesser GPL

Development Environment

Using Virtual Machine

  • For user who would like to try development using FINS Framework regardless of the poor performance of running using Virtual Machine.
  • Users can download a full ready installed development environment as a VMWARE virtual machine Image file from the following link Virtual Image DOWNLOAD LINK (Under Construction)

Genuine Development Environment Step by Step

  1. Install Linux Ubuntu 9.10 or 10.04
  2. Install Eclipse with its C/C++ Development packages
  3. Install the Git plugin for Eclipse
  4. Install the Doxygen plugin for Eclipse
  5. Fork and Fetch the FINS code Tree from the FINS Framework GitHub Repository page FINS GitHub Repository
  6. Three project folders will be created: interceptor, socketdaemon (aka FINSCore), and capturer

Compilation & Building on Linux

  1. In order to use eclipse for compiling and building, edit the projects to exclude .sh files from the files to build the project
  2. Build the interceptor as a dynamic linking library using the file named (
  3. compile and Build the project named socketdaemon as regular executable binary (Assumed build option is for Debug)
  4. compile and build the capturer project too as regular executable binary (Assumed build option is for Debug)

Running FINS

Running Sequence

  • the executable binaries are assumed to exit in the subdirectory named (Debug) in each project folder (for the FINSCore and the capturer project). If you build the project with different target folder , edit the scripts to match your target folder.
  1. Make directory named (fins) inside /tmp/
  2. Run the EtherStub script (
  3. Run the Jinni Script (fins_jinni)
  4. Run the application(s) either in single application mode or multiple applications mode as explained above

Shutting down Sequence

  1. Quit the application or kill the application main process
  2. kill the socketdaemon (FINSCore) process
  3. Kill the Capturer process

Single Application mode

  • use NetFilter/iptables commands form the command prompt to block any incoming or outgoing traffic (your desired application involved with it) from going in or out the traditional stack.
  • This is a must not only to prevent incoming traffic from going through the traditional stack. But also to make sure that our Libpcap based ethernet stub does not recapture the outgoing traffic that we sent ourselves through the injection direction.
  • For example if you want the ping utility to use FINS Framework instead of the traditional stack. Then you have to block the traffic related to ping by the following commands. (The type code is corresponding in order to the type field of ICMP message incase of Echo Request and Echo Reply )
# iptables -A INPUT -p icmp --icmp-type 8 -j DROP
# iptables -A OUTPUT -p icmp --icmp-type 8 -j DROP
# iptables -A INPUT -p icmp --icmp-type 0 -j DROP
# iptables -A OUTPUT -p icmp --icmp-type 0 -j DROP 
  • In Single Application mode, the user assigns FINS to serve the socket calls (of type AF_INET) invoked by a certain single application.
  • This is done by dynamically linking the desired application against the FINS interception library.User can do this using the following command
$ sudo LD_PRELOAD="./" application_name 

Running the Simple Single UDP Client Server Example provided with the Source Code

  • The provided example has two files server.c, and client.c
  • Compile your example files normally
  • Configure the dynamic linker/loader in Linux to be able to find the location of (
  • browse into the folder where the binary files of your compiled example exist
  • notice that you can only run one application at a time. So you can run either the client or the application to run over FINS while the other side runs through the normal stack
  • To run either the client or the server, run the corresponding line below, then run the other side normally.
$ sudo LD_PRELOAD="./" ./server
$ sudo LD_PRELOAD="./" ./client

Multiple Applications mode

  • Use NetFilter/iptables to bring all the network traffic through the traditional stack down. you can use the following commands
# iptable -F
# iptables -P INPUT DROP
# iptables -P OUTPUT DROP
# iptables -P FORWARD DROP
  • In this mode, the user assigns FINS to serve all the socket calls (of type AF_INET)invoked by any application running in the user space
  • This is done by modifying the environmental variable named "LD_LIBRARY_PATH" to include the path of the FINS interception library. So the dynamic linker will favor picking up the FINS socket handlers before the default standard socket calls handlers found in GNU C Library. To do this, use the following command
  • Then run your desired application normally either from the terminal or the GUI. In both cases, the FINS socket interception library will be able to receive all the socket related calls made by your desired application

Special Notes

  • SINCE FINS v0.8.0 has only UDP protocol Implemented so only UDP socket calls are handled by the FINS Framework. Other socket calls related to protocols like TCP or ICMP is currently redirected to the original GNU C Library.
  • In Single Application Mode: The UDP calls will be still able to go through the original stack because the iptables only blocks the UDP traffic as we specify in our iptables rules.
  • In Multiple Applications Mode: Currently supports only UDP Multiple Applications. Any NON UDP TRAFFIC WILL FAIL. Because the specified iptables rules prevents any kind of traffics from going through the original stack.
  • In case the application quit. YOU MUST RESTART THE Jinni using the same running sequence explained above

Already implemented modules and features

Data modules


UDP flowchart.png

The UDP module is fairly simple. On receiving an outgoing packet of data, it generates the checksum, and fills the header from the metadata.

With an incoming packet, the header is removed and then placed into the metadata. Then the PDU pointer is incremented by 8 to point to data inside the UDP datagram.


IP4 in block.png

The IPv4 Module is an implementation of the standard IPv4 protocol to be used with FINS framework. The current version is designed to run on host network nodes and thus only supports input and output processing. Forwarding functionality is not implemented. Also, this version is not capable of IP option processing. Packets with options in their headers are correctly processed, but the options are ignored.

The code is split into two main logical blocks. The input block, which handles all the traffic coming from the network to the host. The output block is then responsible for handling of data coming from the host itself.

The input block has four main tasks:

  • Byte ordering
  • Verification of incoming packets
  • Forwarding
  • Packet reassembly

Byte ordering

The Internet standards specify the byte ordering of a multi-byte variables in the protocol header as big-endian. As the ordering on the x86 and many other platforms is little-endian the bytes need to be reordered in such systems. Whether the bytes are going to be reordered or not is defined during the compile time depending on the platform on which the program is compiled on.

Verification of incoming packets

Content of all the incoming packets is checked for the following errors. Damaged or erroneous packets are silently discarded.

  • Correct IP version- The IP version is specified in the first 4 bits of the IP header and for this module must correspond to value 4.
  • Minimum header length- The header length is specified in the second 4 bits of the IP header. It is indicated as a number of 4 byte words in the header. The minimum header length in the IP version 4 is 20 bytes. If the header is shorter that this value, the packet is considered to be corrupted.
  • Integrity by checksum calculation- Integrity of the entire header is checked by a checksum calculation. If the packets fails the checksum check it is discarded.
  • Physical vs declared packet length- If the physical length of the packet is larger than the one declared in the header, the additional bits are trimmed. If the physical length of the packet is smaller than declared the packet is considered to be corrupted.
  • Fragmentation error- Checks if the flags More Fragments and Do not Fragment flags are not both set at the same time. If so the packet is considered to be erroneous.

Non-Data modules

Implementations of FINS Frames

  • The source code files that implement the FINS Frame types, FINS constants, as well as other FINS definitions are (finstypes.h) and (finsdebug.h)

Implementation of Meta-Data

Meta-Data Wrapper and its dependencies

  • Meta-Data Wrapper is a wrapper that had been implemented around the Configuration Library Libconfig [1]
  • The wrapper implementation source code files are
  • Meta-Data fields into the FINS frames structures are implemented using the meta_data Wrapper mentioned above.
  • Only integers with size of 32 bits and Strings are supported till now with the provided meta-data wrapper.
  • The code has to be dynamically linked with the library Libconfig at compilation in order to compile correctly.
  • Libconfig has to exist and its installed location on the system has to be visible for the Dynamic loader, in order for the library to load correctly in run time.
  • User had to take care only of calling the function
metadata_create (metadata *ptr)
  • The library has its own function which frees metadata objects.
metadata_destory (metadata *meta_ptr)
free (void *ptr)
to free the metadata pointers. Such explicit freeing of memory may cause a memory crash in run time

Implementation of Data Structures involved into source code

  • Basic Implementation of some data structure was necessary for FINS Framework to provide its features mentioned above.
  • The queues which links between the SWITCH and every other modules, have their own implementation as array with initial maximum size.
  • The source code files are

Modifying a Module

Creating New Modules

  • Every record in the switching table consists of ( VPN, Direction, List of Destinations IDs ). first step to create add new module to FINS is to handle its corresponding addressing issues. Below are the steps to accomplish that
  1. Pick VPN value. A standard way we adopt in FINS is to pick the standard protocol number as a VPN value. For example; we picked (17) for UDP, and (6) for TCP. These values are the same corresponding protocol numbers in their RFCs. This number will be used as the VPN field into the addressing records related to this module.
  2. Pick an integer number as an address for the new module. Take a look at the list of addresses on top of finstypes.h, to make sure this address is not in use for another module.
  3. create the corresponding records of the new protocol module into the FINS configuration file. This is the file which FINS switch uses to initialize the main copy of its switching table. Every record is unique if it has different combination of both VPN and direction. For example; a VPN value of (17) + direction value (1), creates different record than VPN value (17) with direction flag (0). In other words, the key parameter to search the table is not only the VPN but both (VPN + Direction Flag).

Implementation of Use Cases using FINS Framework

Fins crosslayer.jpg Cross-Layer Solutions using FINS Fins cognitive.jpg Cognitive Network Stack using FINS Fins bundleprotocol.jpg Bundle Protocol Implementation using FINS

Code Documentation

Future Directions - Version 2 ideas


Personal tools