The GIMS High-Speed Traffic Capture System

The GIMS High-Speed Traffic Capture System

Charles Thomas

Last Update: July 29, 2011

This document will attempt to document the current state of the GIMS project.

Table of Contents:

Section 1: ProtoGENI Integration via the Reference Component Manager

Section 2: The GIMS Backend

Section 3: The GIMS Control GUI

Section 4: The GIMS Admin GUI

Section 5: The GIMS Results Page

Section 6: Modifications to the Rspec to support ProtoGENI Integration

Section 7: The GIMS Database

Section 8: Logging

Section 9: The Capture Daemon

Section 9a: Starting the capture daemon

Section 10: Sample Experiment Workflow

Section 11: Experiment Commands in the ProtoGENI console

Appendix A: Console traces from the “CreateSliver” function.

Appendix A1: ProtoGENI command line.

Appendix A2: GIMSControl log trace.

Appendix A3: GIMS backend log trace.

Appendix A4: Console output from the capture daemon.

Appendix B: Console traces from the “DeleteSlice” function.

Appendix B1: ProtoGENI command line.

Appendix B2: GIMSControl log trace.

Appendix B3: GIMS backend log trace.

Appendix B4: Console output from the capture daemon.

Appendix C: GIMS database diagram

Appendix D: GIMS system diagram

Appendix E: GIMS Work Flow diagram

Appendix F: Capture Daemon diagram

Appendix G: GIMS Admin Page (screenshot)

Appendix H: GIMS Results Page (screenshot)

Appendix I: GIMS-Related File Locations

Section 1: ProtoGENI Integration via the Reference Component Manager

The GIMS system works with the ProtoGENI Reference Component Manager (RCM). The RCM is installed on a machine called gims.wail.wisc.edu. The main GIMS functions are contained in the file GeniCM.pm, a perl module that provides skeleton calls for a variety of the “limited” ProtoGENI functions. The ones we use in the GIMS project are as follows:

CreateSliver:

Normally this call is passed a slice name and an Rspec and it goes through the process of creating and registering a slice with the SliceAuthority, checking all the certificates for authentication and authorization, calling a Component Manager to create one or more slivers, and starting all the slivers in the slice. If all of these functions go well, at that point we call out to our capture device and perform the following functions:

Assign a unique Experiment ID based on the given slice name.
Create a new experiment in the database, including storage of the slice URN and the Rspec.
Check the Rspec passed to the function to determine the name of the configuration to load into the capture device.
Retrieve the config from the database.
Load the config into the capture device.
Begin capturing traffic.

DeleteSlice:

Normally this call is passed a slice name and goes through the chain the ProtoGENI hierarchy to clean up after an experiment is finished. The slivers in the slice are shut down, and the database states are set to show that these entities are no longer in use. Again, certs are checked to perform all appropriate authN/authZ functions. Assuming all these functions succeed, we then call out to our capture system and perform the following functions:

Stop capture.

Set the capture state to ‘done’ in the database.
Write end-of-experiment data to the various log files.

SliverAction:

As deployed in the RCM, this function can only “reboot” slices/slivers, but I expanded its functionality to allow the functions “StartSliver” and “StopSliver” to be invoked.

StopSliver:

Not a part of the “simplified” command set, this function was used to allow us to pause packet capture once an experiment had been started. This will be useful, for example, in cases where the experiment is run for a while with one setting, then capture is paused while the experiment is reconfigured and capture can then be restarted.

StartSliver:

Not a part of the “simplified” command set, this function was used to allow us to restart packet capture after it had been paused using “StopSliver”.

The basic methodology for integrating our device functionality was to create a perl module (GIMSControl.pm) that would reside in the same directory as the RCM. At the end of the selected RCM subroutines (in a location that is only reached if all the previous code has completed successfully) calls to the GIMSControl module were inserted to invoke the required capture functionality and also to log the results of these calls. This methodology was selected in order to keep perturbation of the RCM code to a minimum in the hope that RCM upgrades would be minimally disruptive to the GIMS code.

Section 2: The GIMS Backend

Formerly known as the “GIMS Aggregate Manager” this functional unit is now called the “GIMS backend”. Its role is to act as a coordinating “nerve center” for the capture system. It is not an “Aggregate Manager” in the GENI sense of that word (implying an implementation of the AM API).

The GIMS Backend implements functions that are used to support ProtoGENI integration. A list of current functions is given here:

Functions that do not directly involve the capture device (so-called “Non-Device Functions”):

GetDeviceCapabilities – Retrieves the stored device capabilities from the database. This allows the device config GUI to present the user with options that make sense for the device they are planning to configure.

GetExperimentSettings – Returns the device configuration for a given experiment.

GetExperimentStats – Not implemented yet, but we are going to use this to return live status results during running experiments, then return final result information and URLs after an experiment has finished.

GetNewExpId – Generate a unique experiment ID.

CreateNewExperiment – An involved call. Generates a new ExperimentID based on the slice name, create an experiment in the database (storing all appropriate ProtoGENI info like slice URN and Rspec), and associate this experiment with a certain capture device.

GetExpInfoFromURN – Given a ProtoGENI URN, return all database info on this experiment.

GetDeviceConfig – Returns a given device config from the database.

StoreDeviceConfig – Allows the GIMS Control GUI to save device configs directly to the GIMS database.

The Backend also handles functions that involve communication with the capture device (so-called “Device Functions”):

StartExperiment – Sets the experiment status, the experiment device status, and the experiment start time, then calls StartExperiment on the capture Daemon.

PauseExperiment – Sets the experiment status and the experiment device status. Pauses the capture Daemon.

StopExperiment – Sets the experiment status and the experiment device status. Sets the experiment Stop Time. Stops the capture Daemon.

ConfigureExperiment – Updates the device experiment settings, sets the experiment status, and sets the experiment device status. Configures the capture Daemon with the configuration specified in the RSpec.

Section 3: The GIMS Control GUI

The GIMS Control Tool was originally used in the prototyping phase to control all aspects of experiment setup and control. Since then the tool has been modified to allow users to create device configurations, assign names to specific configurations, and store them in the GIMS database for retrieval. This turned out to be necessary since ProtoGENI does slice creation and slice “start” in the same operation, therefore we could not move from the ‘Created’ state to the ‘Configured’ state to the ‘Start’ state as we had in the prototype GIMS system.

When a user creates a new slice, the capture experiment is created, a pre-loaded config is retrieved from the database and loaded into the device, and capture is started. The GUI supports storage of these configs in the database, rather than pushing them directly to the device.

Section 4: The GIMS Admin GUI

This tool allows authorized admins of the GIMS system to add, delete and edit devices in the GIMS database. A device must be added to the database before it will be available to be selected for an experiment.

The user will be prompted for information about the device such as location, device name, device type, hostname, port and description. The capabilities of the device will also need to be entered so that the correct options can be displayed to the user during the creation of device configurations.

See Appendix for a screen shot of the GIMS Admin Page.

Section 5: The GIMS Results Page

Currently located at the GIMS Results page is where users can go to check on a running experiment (via the “Real Time” link) or to view the results of an experiment after it has ended. Clicking on an Experiment ID will filter the page to only show results from that Experiment.

The “Real Time” link begins tailing the Backend log and also queries the capture device regularly for updates on the experiment progress. This real-time querying can be toggled on and off. We hope to expand this feature to include more real-time feedback for the experimenter.

See Appendix for a screen shot of the GIMS Results Page.

Section 6: Modifications to the Rspec to support ProtoGENI Integration

Since the Rspec 2.0 version, which is going to include user extensions, was not yet fully developed, ad hoc modifications were made to enable certain configuration options to be passed to the ProtoGENI calls (and from there to the GIMSControl subroutines) via the Rspec. An unmodified Rspec for a simple GENI slice might look like this:

<rspec xmlns="

</node>

</rspec>

This was extended as follows (changes in italics):

<rspec xmlns="

</node>

<config_name value="GENIWithSSH">

</config_name>

<location_name value="msn">

</location_name>

<device_name value="gims-sensor-01">

</device_name>

</rspec>

In this example, the device location, device name, and the config name are given in the Rspec. We use this tuple of information as a key to retrieve the given configuration from the database and load it into the device during Slice/Sliver creation.

Once the user-extensions are firmed up in version 2.0 of the Rspec, we are hoping to store this information using those extensions. The modifications were shared with Jon Duerig at the University of Utah in the hopes that our input will help drive the v2.0 conversation and allow us to encode our device-specific information in a more officially-supported manner.

Section 7: The GIMS Database

The GIMS database contains tables to keep track of experiment state, location and type of devices, which devices are being used in a given experiment, the configuration of experiment devices, and statistics for each experiment. Fields have been added to the “experiment” table to support ProtoGENI integration including “slice_urn” and “rspec”.

The GIMS Backend coordinates all data input and data retrieval from the GIMS database. Other tools call the Backend to insert rows, delete rows, or select rows from the database as required.

See Appendix C for a diagram outlining the database configuration.

Section 8: Logging

The capture device itself has logs that it writes to allow post-mortem analysis of a capture experiment. In addition to these, there is also a log called “gims_backend.log” which stores the output of the GIMS backend and lives with the GIMS backend, and another called “GIMSControl.log” that records the output of the GIMSControl module that lives with the RCM. Both of the entities being monitored have been designed to throw enough information to the logs to make debugging problems with the system as easy as possible.

There is also a log called “gims_admin.log” that records output from the GIMS Admin tool that can help with troubleshooting problems during device creation/deletion/editing.

Section 9: The Capture Daemon

Here are the simple instructions for getting the daemon started on a machine where the capture software has been installed.

Log into the capture node as root, and cd into the directory capd.

To clean everything up (i.e., old storage files, etc.) before a fresh

start, run ./cleanup.sh

- Note that doing a clean up does *not* remove any log files, so

you can still inspect the log files to find out what the system

was doing, even after you clean up any temporary storage files.

To start the capture daemon proxy, just do ./runproxy.sh

- You'll need to keep the terminal open where you start it.

- To stop it, just type ^C.

- It's never a bad idea to type ./cleanup.sh between starts of the

capture daemon proxy.

- Once it's started, it should be accessible on TCP port 8001 for

XML/RPC.

Section 10: Sample Experiment Workflow

This section will briefly outline the steps taken to start and stop a very basic GIMS experiment.

Section 10a: Starting the Capture Daemon

For example, a capture daemon lives on the host ‘gims-sensor-01.wail.wisc.edu. One of the GIMS admins should start this daemon running by logging in as root (with password) and issuing the command:

./runproxy.sh

There are more detailed instructions on how to start the GIMS capture daemon on the GIMS website.

Section 10b: Creating a config

Using the GIMSControl.cgi:

Select “Preload a Config Into Database”.
Select the capture device you want to configure.
You can ignore the “Experiment ID” fields.
Give the configuration a unique name and select the parameters that apply to the type of experiment you want to perform. You can enter libpcap instructions in the box for libpcap strings.
Submit the config and check for errors.

Section 10c: Create an RSpec for your experiment.

See the section on RSpec modifications. You will need to add fields for “config_name”, “location_name” (of the capture device) and “device_name” (of the capture device). Use the config name for the config you created in the previous step.

Section 10d: Create a slice and start the experiment.

Use a ProtoGENI command to start the slice and start traffic capture. Here is an example of a command that passes the GIMS Component Manager URL, a slice name, and the RSpec created in the previous step:

./createsliver.py -m -d -n CTSlice1 GimsMSNLocalhost.rspec

Section 10e: (Optional) Pause experiment capture.

Use ProtoGENI command to pause capture:

./sliveraction.py -m -d -n CTSlice1 stop

System will respond with ‘Sliver has been stop'ed’.

Section 10f: (Optional) Restart experiment capture.

Use ProtoGENI command to restart capture:

./sliveraction.py -m -d -n CTSlice1 start

System will respond with ‘Sliver has been start'ed’.

Section 10g: Stop experiment.

Use ProtoGENI command to stop the slice and tear down experiment:

./deleteslice.py -m -d -n CTSlice1

System will respond with a variety of response data about the experiment that was running.

Section 11: Experiment Commands in the ProtoGENI console

These are example commands using the GIMS component manager and an example RSpec. We run these commands out of the directory where the ProtoGENI test scripts reside:

Create a slice:

./createsliver.py -m -d -n CTSlice1 GimsMSNLocalhost.rspec

Start or restart a sliver/slice:

./sliveraction.py -m -d -n CTSlice1 start

Pausea sliver/slice:

./sliveraction.py -m -d -n CTSlice1 stop

Delete a slice:

./deleteslice.py -m -d -n CTSlice1

Appendix A: Console traces from the “CreateSliver” function.

Appendix A1: ProtoGENI command line.

[cthomas@ops ~/protogeni/test]$ ./createsliver.py -m -d -n GENI5 GimsMSNProduction.rspec

GetCredential

Got my SA credential

GetKeys

Resolve

No such slice registered here:Creating new slice called GENI5

New slice created

Creating the Sliver ...

CreateSliver

Created the sliver

<config_name>

<value>default</value>

</config_name>

<device_name>

<value>gims-sensor-01</value>

</device_name>

<location_name>

</location_name>

<node> <component_manager_uuid>urn:publicid:IDN+gims.wail.wisc.edu+authority+cm</component_manager_uuid> <component_urn>urn:publicid:IDN+gims.wail.wisc.edu+node+pc1</component_urn>

<component_uuid>urn:publicid:IDN+gims.wail.wisc.edu+node+pc1</component_uuid>

<sliver_urn>urn:publicid:IDN+gims.wail.wisc.edu+sliver+140</sliver_urn>

<sliver_uuid</sliver_uuid>

<virtual_id>node1</virtual_id>

<virtualization_type>raw</virtualization_type>

</node>

<xmlns>

</manifest>

Appendix A2: GIMSControl log trace.

2010-11-05 13:52:37: Started session with GIMS Backend...

2010-11-05 13:52:37: Handling command StartExperiment...

2010-11-05 13:52:37: handleDeviceCommand(StartExperiment)...

2010-11-05 13:52:37: Got DB handle...

2010-11-05 13:52:37: Validating experiment state...

2010-11-05 13:52:37: Opening socket for gims-sensor-01.wail.wisc.edu, 8001...

2010-11-05 13:52:37: Calling socket()...

2010-11-05 13:52:37: Setting filehandle to unbuffered mode...

2010-11-05 13:52:37: Connecting...

2010-11-05 13:52:37: Socket opened to gims-sensor-01.wail.wisc.edu:8001.

2010-11-05 13:52:37: Sending to socket...

2010-11-05 13:52:37: Listening for response...

2010-11-05 13:52:37: Closing socket...

2010-11-05 13:52:37: Socket closed.

2010-11-05 13:52:37: Updated status to 'running' on ExpID: GENI5_48694C9A.

2010-11-05 13:52:37: Formulating reply...

2010-11-05 13:52:37: Packaged reply:

2010-11-05 13:52:37: <?xml version="1.0" encoding="UTF-8" ?>

<params<param<value<struct>

<member<name>backend_data</name>

<value<string<![CDATA[GIMS Backend received command StartExperiment.

]]</string</value</member>