netbanner

netifera tutorial - Sniffing Module Part 1

About this tutorial

This tutorial will demonstrate how to create and install a simple extension module to the netifera sniffing service. In later tutorials in this series we will show you how to add more functionality to this module and also introduce some other netifera development concepts.

We will be using the free Eclipse development environment in our series of tutorials about developing modules, tools, and extensions for the netifera network security platform. There are a lot of advantages to working with Eclipse but if you are unfamiliar with it there is a fairly heavy learning curve to overcome before you can use it effectively. In this tutorial we assume no background with Eclipse or with Java and we try to explain every important detail for performing each step. What will not be well explained in this tutorial is why each of the steps is required and what really happens when you perform them.

If you really would prefer to avoid using Eclipse we have included a set of command line instructions at the end of this document which will produce exactly the same results without using any tools at all. We don't recommend that you write netifera extensions this way, but this information could be useful to understand what is going on behind the scenes while you follow the steps in Eclipse.

1) Install netifera and Eclipse

First download and install the latest available version of netifera. You should also read at least the quickstart user guide to familiarize yourself with the installation and basic operation of netifera.

http://netifera.com/downloads

You will also need the free Eclipse Java IDE which can be downloaded from the following site. Choose Eclipse for RCP/Plug-in Developers from the list of available packages.

http://www.eclipse.org/downloads

2) Start Eclipse and configure it for netifera plug-in development

The first time you start Eclipse you will be presented with a 'welcome' screen. To exit this screen either click on the arrow icon or close the welcome window.

Eclipse should now be opened to an empty workspace. The first thing which needs to be done is configuring the workspace so that the Eclipse development environment knows where to find the netifera plugins. The settings that need to be changed are located in the preferences dialog which can be accessed from the following menu path:

On Linux:

Window --> Preferences...

On OS X:

Eclipse --> Preferences...

Once the preferences dialog is opened the page which needs to be changed can be found at Plug-In Development --> Target Platform

The Location field at the top of this page needs to be changed to point to the base directory of your netifera installation.

Press the Browse... button and navigate to the filesystem location where you have installed netifera.

After choosing the correct directory, the target platform page should look like this:

If everything looks okay, press the OK button in the bottom right to exit the preferences dialog.

3) Create a new plugin project

Open the New dialog by pressing the top left button on the Eclipse toolbar.

Choose Plugin-in Project from the list of available items.

A wizard will open for configuring the new project.

  1. Enter the Project Name as com.netifera.tutorial1
  2. Change This plug-in is targeted to run with: from Eclipse Version to An OSGi Framework
  3. Press the Next > button.

On the second page set the Execution Environment to J2SE-1.5 if it is not already set to this value.

Nothing else needs to be changed on this page. Just press the Finish button after making this change.

A dialog will now appear offering to switch to the Plug-In Development perspective. This is a good idea, so select Yes here.

4) Add dependencies to project

After creating the new plug-in project a window will open in the editor area with many options for configuring your new plug-in. If you close this editor you can open it again by locating the file META-INF/MANIFEST.MF in the Package Explorer and double-clicking it.

Notice that at the bottom of this editor there are several tabs that take you to different pages of configuration information. In this tutorial we will be using each of the following pages: Overview, Dependencies, Build, MANIFEST.MF.

Select tab Dependencies to switch to a page where we can declare some packages that this plug-in will import.

On the right side of this page you will find an area called Imported Packages. This is where we will add our dependencies.

Press the Add... button and add the following packages to the list:

  • com.netifera.platform.net.daemon.sniffing
  • com.netifera.platform.net.sniffing
  • com.netifera.platform.net.sniffing.stream
  • com.netifera.platform.util

When you are finished the list should look like this.

Now you must Save your changes by pressing CTRL-S (Command-S in OS X) or through the File -> Save menu item.

Did you remember to save your changes? If you forget to save after adding the dependencies you will have problems in Steps 6 and 7.

5) Import a netifera source code plugin (optional)

This step is optional but recommended as it will allow you to browse the source code of a plug-in that implements several of the sniffing modules in netifera. The structure of this plug-in and the code it contains are useful references for how to create a more advanced plug-in than the one which is described in this tutorial.

Switch from the Package Explorer to the Plugins view.

Locate the plug-in with the name com.netifera.platform.net.daemon.sniffing.modules

For each netifera plug-in there is a corresponding plug-in with the same name, but ending with the suffix .source. The plug-in with the .source suffix contains the source code for the plug-in without the suffix. Right click on any plugin WITHOUT the source suffix and select Import As --> Source Project from the context menu.

This procedure is counter-intuitive enough that it's probably worth repeating: The plug-in you should select in order to import the source code into your workspace is NOT the one with the .source suffix, it's the plug-in without the suffix. Eclipse will find the source code in the .source plug-in automatically.

One more time!

  • YES com.netifera.platform.net.daemon.sniffing.modules
  • NO com.netifera.platform.net.daemon.sniffing.modules.source

After you have imported this plug-in into your workspace you can switch back to the Package Explorer and begin to explore the source code for the sniffing modules.

Once you understand the basic concepts of how to create an extension module for the sniffing service this will be a very valuable source of information about how to do more advanced things. The source code for every netifera component can be imported and browsed this way.

6) Create a sniffing module class

You are now going to create a class to implement the sniffing module functionality. First select the package com.netifera.tutorial1 in the Package Explorer

Press the New Java Class button on the main Eclipse toolbar. It's the green disc with the 'C' on it.

A dialog will appear for you to enter information about the new class. When you are finished, everything should look like this:

Two things need to be added to the dialog.

  1. Set the Name of the class to SnifferTutorial1
  2. Press the button Add... in the interfaces section of the dialog and enter the interface name ITCPStreamSniffer

If the ITCPStreamSniffer name cannot be found go back to Step 4 and verify that the dependencies have been added correctly and that you have saved the information in the plug-in editor.

The Package field should already be set to com.netifera.tutorial1. If you did not select the package before pressing the New Java Class button this field will be blank and you will need to enter this value manually.

Press the Finish button and the class will be created and the source code for this class will open for editing.

7) Implement some functionality

Change the getName() and handleNewSession() methods so that they look like this. For now you don't need to change any of the other methods.

	public String getName() {
		return "Tutorial Sniffer 1";
	}
	public boolean handleNewSession(IStreamModuleContext ctx) {
		ISessionKey key = ctx.getKey();
		ctx.printOutput("New TCP session: " + key);
		return false;
	}

Save your changes with CTRL-S (Command-S in OS X) or the File -> Save menu item.

Eclipse will display an error because the type ISessionKey must be imported.

This is easy to fix by selecting ISessionKey in the editor and pressing ctrl-1 (Command-1 on OS X, and that's a one not an L). Eclipse will present a list of possible solutions for this problem. Choose Import ISessionKey from the top list of options and Eclipse will automatically add the required import declaration to the top of the source file. Save the file again after correcting this problem.

8) Add required meta-data

8.1) Create OSGI-INF folder

First you must add a folder called OSGI-INF to the root of the project. Press the New button at the top left of the Eclipse toolbar.

Choose Folder from the list of options.

Set the parent folder to com.netifera.tutorial1 and the Folder Name to OSGI-INF

8.2) Create tutorial1.xml

The next step is to create an XML file in the newly created directory. To do this, press the New button again and this time choose XML from the list of options.

Set the parent folder to the OSGI-INF directory and the File Name to tutorial1.xml. Press Finish.

An editor will open for the new XML file with two tabs at the bottom called Design and Source. Switch to the Source view and copy the following content into the editor and save it.

<?xml version="1.0" encoding="UTF-8"?>
<component name="netifera.sniffer.tutorial1">
	<implementation class="com.netifera.tutorial1.SnifferTutorial1" />
	<service>
		<provide interface="com.netifera.platform.net.daemon.sniffing.ISniffingModule" />

	</service>
</component>

8.3) Add Service-Component to MANIFEST.MF

Open the plug-in editor (see step 4) by selecting the corresponding editor tab. If you have closed the plug-in editor you can open it again by finding the file META-INF/MANIFEST.MF in the Package Explorer and double clicking on it. Once the plug-in editor is open, switch to the Build page using the tabs at the bottom of the editor.

On this page locate the section on the left side called Binary Build and select the checkbox beside the OSGI-INF directory to indicate that this directory should be included in the plug-in we are going to export in the next step.

Now switch to the MANIFEST.MF page because we need to add one line here.

Add the Service-Component header to this file with a value which points to the XML file you just created.

If you add it as the last line you must also remember to add a newline because a field in a Java manifest file will not be processed unless it ends with a newline.

Save your changes with CTRL-S (Command-S on OS X).

9) Export the plugin

You are now ready to export your new plug-in into netifera and test it. Switch to the Overview page of the plug-in editor by clicking on the corresponding tab. On this page at the top right corner there are four buttons. If the editor window is not large enough, you may have to scroll them into view. Press the one with the tooltip which reads Export deployable plug-ins and fragments.

A wizard will open for entering information about how to export the plug-in. The only thing which needs to be changed is the Destination which should point to the base directory where netifera is installed.

Notice that the correct format is Directory and not Archive File.

After choosing the correct directory press the Finish button and your new plug-in will be exported directly into your netifera installation.

10) Test new plug-in in netifera

In netifera switch to the Sniffing Perspective if necessary.

On the main toolbar press the Configure Sniffing Service button.

The following dialog should appear and Tutorial Sniffer 1 should appear in the list of available sniffing modules. Disable all of the other modules by unselecting the checkboxes so only the tutorial module is enabled.

Now start the sniffing service with the green start arrow on the main toolbar and output from the tutorial module will appear in the netifera console:

Alternative to the Eclipse Tutorial

We recommend that you learn to use Eclipse because it provides a very nice environment for navigating the netifera code and automates many otherwise tedious things. However, if you are having some problem with the tutorial and want to understand what is happening 'under the hood' of all the Eclipse hand-waving or if you just hate IDEs and have sworn you will never use one, we've provided the following alternative version of the tutorial.

You will need to have the Java Development Kit (JDK) installed to follow these instructions since you need the Java compiler (javac) and the JAR bundling tool (jar). It is not sufficient to only have the Java Runtime Environment (JRE) installed.


#
# You must set this to the base directory of your netifera installation
#

NETIFERA=~/netifera

#
# Make some directories
# 

mkdir com.netifera.tutorial1 && cd com.netifera.tutorial1
mkdir -p bin META-INF OSGI-INF src/com/netifera/tutorial1

#
# Create Activator.java
#

cat > src/com/netifera/tutorial1/Activator.java << 'EOF'
package com.netifera.tutorial1;

import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator {
        public void start(BundleContext context) throws Exception {
        }
        public void stop(BundleContext context) throws Exception {
        }
}
EOF

#
# Create SniffingTutorial1.java
#

cat > src/com/netifera/tutorial1/SniffingTutorial1.java << 'EOF'
package com.netifera.tutorial1;

import java.nio.ByteBuffer;

import com.netifera.platform.net.daemon.sniffing.IStreamModuleContext;
import com.netifera.platform.net.daemon.sniffing.IStreamSnifferConfig;
import com.netifera.platform.net.daemon.sniffing.ITCPStreamSniffer;
import com.netifera.platform.net.sniffing.IPacketFilter;
import com.netifera.platform.net.sniffing.stream.ISessionKey;

public class SniffingTutorial1 implements ITCPStreamSniffer {

        public String getName() {
                return "Tutorial Sniffer 1";
        }

        public boolean handleNewSession(IStreamModuleContext ctx) {
                ISessionKey key = ctx.getKey();
                ctx.printOutput("New TCP session: " + key);
                return false;
        }

        public boolean handleClientData(IStreamModuleContext ctx, ByteBuffer data) {
                return false;
        }

        public boolean handleServerData(IStreamModuleContext ctx, ByteBuffer data) {
                return false;
        }
        public void handleSessionClose(IStreamModuleContext ctx) {
        }

        public void initialize(IStreamSnifferConfig config) {
        }

        public IPacketFilter getFilter() {
                return null;
        }
}
EOF

#
# Create MANIFEST.MF
#

cat > META-INF/MANIFEST.MF << 'EOF'
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Tutorial1 Plug-in
Bundle-SymbolicName: com.netifera.tutorial1
Bundle-Version: 1.0.0
Bundle-Activator: com.netifera.tutorial1.Activator
Bundle-Vendor: NETIFERA
Bundle-RequiredExecutionEnvironment: J2SE-1.5
Import-Package: com.netifera.platform.net.daemon.sniffing,
 com.netifera.platform.net.sniffing,
 com.netifera.platform.net.sniffing.stream,
 com.netifera.platform.util,
 org.osgi.framework;version="1.3.0"
Service-Component: OSGI-INF/tutorial1.xml
Bundle-ActivationPolicy: lazy
EOF

#
# Create tutorial1.xml
#

cat > OSGI-INF/tutorial-sniffer.xml << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<component name="netifera.sniffer.tutorial1">
    <implementation class="com.netifera.tutorial1.SniffingTutorial1" />
    <service>
        <provide interface="com.netifera.platform.net.daemon.sniffing.ISniffingModule" />
    </service>
</component>
EOF


#
# Compile the classes
#
PLUGINS=$NETIFERA/plugins
CLP=$PLUGINS/com.netifera.platform.net.daemon.sniffing_1.0.0.jar
CLP=$CLP:$PLUGINS/plugins/com.netifera.platform.net.sniffing_1.0.0.jar
CLP=$CLP:$PLUGINS/org.eclipse.osgi_3.4.2.R34x_v20080826-1230.jar
javac -classpath $CLP -d bin src/com/netifera/tutorial1/*.java

#
# Create .jar and copy it into netifera plugin directory
#

jar cMf com.netifera.tutorial1_1.0.0.jar META-INF/ OSGI-INF/ -C bin com
cp com.netifera.tutorial1_1.0.0.jar $NETIFERA/plugins