ScaleBox Manual

Disclaimer: Note that the manual is for the software that lies in a pre-alpha state. Use the code at your own risk!

Table of Contents

• Getting Started
  • Building ScaleBox
  • Running ScaleBox
• Operating ScaleBox
  • Console Commands
• ScaleBox Modules
  • List of Modules - Input
  • List of Modules - Output
  • Input Log
  • Input Passthrough
  • Example - Simple Passthrough

Getting Started

Building ScaleBox

• Retrieve the ScaleBox tar/gzip from the NetScale website

Download ScaleBox

Download Direct

You can retrieve the most current version of ScaleBox via Subversion:

 svn co http://ndss-gpu2.cse.nd.edu/svn/ScaleBox

Current Build

The next build is slated for the third week of July and will include:

• Improved NGW support / testing
• Cygwin validation
• Preliminary version of virtual host / virtual network support

Fixed Builds

Platform Requirements

• Operating System
  • Mac OX 10.5 (Leopard) or better
  • Linux (any recent variant)
  • Solaris 10 (x86 or SPARC)
• Modules / software
  • libpcap, pthread

• Place the files in an appropriate directory
• Ungzip / untar the files

   % gunzip ScaleBox.tar.gz
   % tar -xvf ScaleBox.tar

• Make the entirety of the distribution
  • At this time, we will not be adapting the code for automatic configuration. OS specific instructions are bundled with the code as applicable.
  • Our intention at this time is to only test the system under Linux (primary system), Mac OS X, and Solaris with the order representing priority for testing / bug stomping.

   % make clean
   % make all

• Create a symbolic link or execute the code directly from the bin directory

Running ScaleBox

At this time, ScaleBox is currently configured to operate entirely in a console mode as a single executable. Support will be added for execution as a daemon in November or December as time allows. As ScaleBox relies on libpcap by default for packet sniffing, execution as the super-user (root) is required. The man page? for ScaleBox will be reflected here.

By default, the test.xml configuration file will be loaded in the ex/xml directory of ScaleBox.

   % ./ScaleBox

Command line options for ScaleBox include:

Operating ScaleBox

Console Commands

list - List information regarding ScaleBox components

The list console command (list, l) allows for listing the status of various components within the ScaleBox framework. Options for the list components include:

stat - Show the current statistics of a given ScaleBox component

ScaleBox Adapters

Adapter - AdapterFile

Base Class: Adapter

The AdapterFile object emulates an adapter in the ScaleBox framework to provide replay of tcpdump files (libpcap format) similar to tcpreplay. Similar to the normal pcap-based adapter, the file adapter can have its own chain of modules with respect to both the input and output aspects. Future planned modules include remapping modules to allow for layer 2, layer 3, and layer 4 translation of previous packets into a new virtual network.

Example Declaration (see readDumpFile.xml

        <Adapter type="file">
      <name>fileAdapter</name>
      <file>../test/file/testFile.tcpdump</file>
      <!-- Start the input module chain -->
      <InputModule type="InputLog">
      </InputModule>
      <!-- We really don't want to send it, just to see the packets -->
      <InputModule type="InputPurge">
      </InputModule>
      <!-- Start the output module chain -->
      <OutputModule type="OutputPurge">
      </OutputModule>
   </Adapter>

In the above example, an AdapterFile file object is defined under the name of fileAdapter. The adapter will read in the file testFile.tcpdump (contained in the ScaleBox distribution for testing) and play it back at normal speed across its input chain which contains only a call to the simple logging function. The remainder of the packets are purged via the InputPurge module listed in the chain shortly after the logging module. The adapter can queue up a list of files that will then be played back in sequential order as per the relative timing specified in each of the files.

Note that the adapter class will do its best to play back packets at the specified rate. Depending upon the load of the system and other processes, it may not be possible to meet the exact playback criterion specified by the file.

processPacket (InputLog)
IL(fileAdapter):  0x80E400 66 bytes  IPv4 129.74.153.157 to 129.74.227.102
processPacket (InputLog)
IL(fileAdapter):  0x809400 66 bytes  IPv4 129.74.227.102 to 129.74.153.157
processPacket (InputLog)
IL(fileAdapter):  0x809E00 78 bytes  IPv4 129.74.153.157 to 129.74.227.102
processPacket (InputLog)
IL(fileAdapter):  0x80A800 74 bytes  IPv4 129.74.227.102 to 129.74.153.157
processPacket (InputLog)
IL(fileAdapter):  0x80B200 66 bytes  IPv4 129.74.153.157 to 129.74.227.102
processPacket (InputLog)
IL(fileAdapter):  0x808000 77 bytes  IPv4 129.74.153.157 to 129.74.250.100

Tags

The following tags (in addition to the base Adapter tags) are recognized by the adapter when processing the XML configuration file.

| Tag | Description | Values | Note

Tag - file

<file>../test/file/testFile.tcpdump</file>

The file tag contains a single file listing that will be added to the replay list. By default, the file will be replayed at the same rate as recorded by libpcap.

Tag - filePath

<filePath>/zfs/filedumps/</filePath>

Tag - playbackRate

<playbackRate >0.5</playbackRate >

Tag - loopCount

<loopCount >5</loopCount >

Special Notes

• When rolling between files, relative times are not preserved for the first packet in each new file, i.e. if the adapter finishes playing back file 1 and opens up file 2, the first packet of file 2 will not be replayed relative to the timeline of file 1.
• The adapter will not fill in missing data when the capture length is not the same as the actual length. Packets that do not have the entirety of their data will be ignored for the time being to avoid adverse impacts on downstream processing.

ScaleBox Modules

Input Module - InputLog

Input Module - Input Passthrough

Input Module - InputPurge

Base Class: IOModule

The InputPurge module is a generic I/O chain module capable of purging (releasing) packets that are being processed on a I/O module chain for an adapter. The module itself can be tuned in its current form to purge all packets (default) or to selectively purge packets based on the matches in the source or destination fields of the Ethernet or IPv4 headers.

Example Declaration (passthroughHidden.xml)

<InputModule type="InputPurge">
   <Ethernet>00:FA:34:56:12:34</Ethernet>
   <IPv4>10.0.0.1</IPv4>
</InputModule>

The above code show an InputPurge module taken from the [[http://ndss-gpu2.cse.nd.edu/svn/ScaleBox/trunk/cfg/passthroughHidden.xml][passthroughHidden.xml][example]]. The code defines an InputModule? on the chain of type InputPurge and creates filters such that it will purge any packets sent or destined to Ethernet address 00:FA:34:56:12:34 as well as any packets sent or destined to IPv4 address 10.0.0.1. The relationship in the listing is for a lazy OR evaluation meaning that if one of the addresses is a match in the source or destination aspect, the packet will be purged.

By default with no addresses listed, all packets entering this module would be purged.

Statistics

The number of packets purged is recorded for the module.

Tag - Ethernet

   <Ethernet>00:FA:34:56:12:34</Ethernet>

The Ethernet tag lists a valid 802.3 six byte MAC address, either as a list of sequential hex values or as a colon separated list of hex values. Characters in the hex address may be upper or lower case without any processing issues. A match on either the source MAC or destination MAC address will result in the packet being purged from the input or output chain. Note that the broadcast address must be explicitly stated in order for it to be purged in the source or destination case. There is no limit to the number of MAC addresses that can be listed beyond the performance degradation that occurs with listing additional addresses.

Tag - IPv4

   <IPv4>10.0.0.1</IPv4>

The IPv4 tag lists a valid IPv4 address in dot notation. Host names are not allowed as the address must be a specific v4 address. Subnet support via the /bits notation is not currently enabled but will likely be enabled via a separate identifier (i.e. 10.0.0.0/8). Note that multicast or broadcast addresses must be explicitly stated in order to be considered. In order to trigger the comparison, the packet must be an IPv4 packet, i.e. outbound ARPs from a particular IP would not be caught. There is no limit to the number of IP addresses that can be listed beyond the performance degradation that occurs with listing additional addresses.

Other Considerations

• Should this be renamed to reflect input or output status?

Future

• The internals of the class will eventually be reworked once the filter mechanism is complete. The ability to single out MAC or IPv4 addresses will remain in future versions regardless of the underlying mechanism for comparison.

Example - Simple Passthrough