Documentation - FINS v0.9.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. 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

  • FINS v0.9.0 requires a modified kernel, which suggests deployment should be on a virtual machine.
  • Linux Ubuntu 10.04 or higher (FINS Framework has been tested on both 10.04 and 11).
  • FINS Framework is supposed to work on any Linux distribution as long as it has a modified 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
  • fins_metadata_wrapper
  • 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 a modified 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 a Virtual Machine

  • Users developing using the FINS Framework are recommended to use a Virtual Machine.
  • A full ready installed development environment can be downloaded 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 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. The folder into which the FINS code Tree was checked out will thus be referred to as the 'FINS_root' directory.
  7. Five main project folders will be created in FINS_root:
    • capturer - the Ethernet Stub,
    • common - contains data structures and types common to all projects,
    • socketdaemon - the user-space part of the socket stub and the FINSCore,
    • wedge - the kernel-space part of the socket stub,
    • examples - examples for simple UDP applications.

Modified Kernel

  • In order for the socket stub to work a custom version of the Linux 2.6.x Kernel must be created where the AF_INET socket family is displaced.
  • This can be done by editing the <linux_root>/include/linux/socket.h file to patch the following:
-#define AF_INET		2	/* Internet IP Protocol 	*/
+#define AF_FINS		2	/* FINS:  Override for INET	*/
-#define AF_MAX		39	/* For now.. */
+#define AF_INET	39	/* FINS:  added this to hold old Internet IP Protocol entry	*/
+#define AF_MAX		40	/* For now.. */
 #define PF_INET		AF_INET
+#define PF_FINS		AF_FINS
  • In addition, to ensure that LKMs can be force removed CONFIG_MODULE_FORCE_UNLOAD must be enabled in the kernel config file.
  • When compiling the kernel the concurrency level should be set to 'CONCURRENCY_LEVEL=3'.

Compilation & Building on Linux

  • Provided in FINS_root is a build system preconfigured for several platforms. The default platform is set to build on a x86 Linux system with the modified v2.6.x kernel, which can be changed by editing the settings.finsmk file.
  • To compile the entire FINS framework, from FINS_root run:
$ make


$ make clean all
  • Alternatively specific projects can be compiled by listing them, e.g.
$ make capturer socketdaemon

Running FINS

Running Sequence

  • the executable binaries are assumed to exist in each project folder.
  1. Insert the wedge LKM (./
  2. Run the EtherStub executable(./capturer).
  3. Run the Socket Daemon executable (./socketdaemon).
  4. Run the application(s).

Shutting down Sequence

  1. Quit the application(s) or kill the application main process.
  2. kill the socketdaemon (FINSCore) process.
  3. Kill the Capturer process.
  4. Remove the wedge LKM (Note: removes the wedge prior to inserting it).

Running Applications

  • In v0.9.0 socket calls are automatically routed to FINS through the kernel, so applications can be run like normal.
  • If an application quits or is killed, the kernel wedge, capturer, and socket daemon do not need to be restarted. Error handling for normal and preemptive exits has been tested successfully for most instances.
  • In rare cases where significant errors occur (kernel segmentation faults) performing the entire shutdown and startup sequences may be required.

Running the Provided UDP Client/Server Example

  • The provided example has two files client.c and server.c located in the examples folder. Client is a simple UDP application that reads text input from the command line and sends it to the server, who receives it and prints it out.
  • The example files are automatically included in the FINS_root makefile but can also be compiled independently.
  • Running:
    1. Browse into the folder where the binary files of the compiled example exist
    2. Setup the server (default port is set to 5000):
      $ ./server <port>
    3. Run the client (default port is set to 5000):
      $ ./client <port>


  • Debug output can be seen through the terminal for: capturer and socket daemon.
  • Kernel debug messages from the kernel wedge are retrievable using 'dmesg'.
  • Error cases for most socket calls are implemented; however, the socket wedge does not current set the correct errno value when a error is caught.

Special Notes

  • SINCE FINS v0.9.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. A module to handle TCP calls is slated to be released in FINS v1.0.0 and developement for ICMP traffic is already underway.

Known Bugs

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