niksu / pax Goto Github PK

Framework for prototyping network elements

License: Apache License 2.0

C# 95.80% Shell 2.07% Python 2.13%

packet-processing network-monitoring networking packet-generator mono

pax's Introduction

Pax be upon packets

System and network programming can be a magical mystery tour de force across several APIs and tools. Pax aspires to be your peaceful gesture at complexity, and seeks to facilitate prototype development.

Pax provides a library and runtime support that wrap underlying wrappers so you can quickly test prototypes of packet-processors written in high-level languages. More information can be found in our API documentation.

Example code

Various example implementations are included in this repo. Additional examples involving Pax show how to replay a pcap file on the network (recap) and an implementation of TCP (TCPuny).

Building

Follow the instructions in BUILD.md. We've tested Pax on OSX and different versions of Ubuntu Linux, but it shouldn't be hard to get it running wherever .NET runs.

Writing for Pax

Packet processers using Pax can be written in any .NET language. They use Pax's API and define one or more functions that handle incoming packets. Semantic versioning is used for Pax, to facilitate checking whether a given version of a packet processor should run on a given version of Pax. The examples included with Pax could help get you going. The workflow is as follows:

Write your packet processors and use a .NET compiler to produce a DLL. Your DLL may contain multiple packet processors -- it is the configuration file that specifies which processor you wish you bind with which network interface.
Write a configuration file (or scheme) for your packet processor. This specifies all parameters to your packet processor, including which specific network interfaces that are bound to logical ports. Configuration in Pax is JSON-encoded.
Run Pax, indicating your configuration and DLL.

The configuration file "wires up" the network interfaces with packet processors in your assembly. Not all packet processors in your assembly need be connected, and different network interfaces may be connected to the same handler. The drawing example shows an assembly with four packet processors, only two of which is used. The blue processor handles packets coming on network port 0. The configuration file determines which processors handle traffic coming on which network interface.

Running

Simply run Pax.exe --config=CONFIGURATION_FILENAME --code=ASSEMBLY_FILENAME. For more on command-line switches, run Pax.exe --help. Probably you'd have to run this command with root/administrator-level access because of the privileged access to hardware that's used while Pax is running. For the example code I run:

sudo ./Bin/Pax.exe --config=examples/wiring.json --code=examples/Bin/Examples.dll

This runs the Printer element, which simply prints an integer whenever a particular kind of packet arrives on an interface. For another element we use for debugging, try:

sudo ./Bin/Pax.exe --config=examples/tallyer_wiring.json --code=examples/Bin/Examples.dll

Pax then starts up and checks the configuration file and assembly, listing some of their contents. It connects the network interfaces with the handlers in the assembly, as specified in the configuration. Then Pax activates the handlers, and your code takes it from there.

License

Pax is licensed under Apache 2.0. Mono.Options is licensed as described in its header.

Acknowledgements ✌️

Project NaaS and its funder (EPSRC).
Colleagues at NetOS.
Contributors to PacketDotNet, SharpPcap, Newtonsoft.JSON, libpcap and winpcap, Mono.Options.

Project ideas

Try using Pax to implement prototypes of the following:

Protocol conversion (e.g., IPv4 <-> IPv6)
DPI
Load balancer (see these descriptions from the HAProxy and NGINX sites for ideas)
Datagram-based servers, e.g., DNS.
Firewall
Router

Fellow travellers

If you're interested in what Pax does, you might be interested in these other systems:

pax's People

Contributors

Stargazers

Watchers

Forkers

tmvector

pax's Issues

Problem with large packets

When testing TCP throughput with iperf, I came across a SharpPcap error resulting from large packets.

SharpPcap.PcapException: Can't send packet: send: Message too long

The size of packets sent by iperf can be controlled with the -M option. E.g. iperf -c <ip> -M 700
The actual size of the packets seems to be related to the value specified with -M, M, by 2_M_+42. So using a value of 736 should yield a packet size of 1514B, which works. Using a value of 737 breaks it.

Sometimes a large packet is still received, but I couldn't create steps to reproduce it.

Steps to reproduce:

Run the Pax NAT implementation on the middle node
On the 'server': iperf -s
On the 'client': iperf -c <IP_OF_SERVER>

Some notes about PAX setup steps

"DEPENDENCIES" section under "BUILDING" section

Please specify that:

It's fine to use either Mono or Microsoft's C# compiler/runtime.
We do use features specific to C# 6.0 however, and that's why a compiler for previous versions of C# can't be used.
Therefore C# (>=6.0) compiler and runtime is required.
The following setup steps have been tested on: Ubuntu 14.04.5, they should work fine on Ubuntu 16.10 too.
After setting-up PAX, I have succesfully tested tallyer, dinger and wiring examples.

[1] RUN: sudo apt-get update AND sudo apt-get upgrade
[2] RUN: sudo apt-get install libpcap0.8
[3] Clone or download SharpPcap repository (https://github.com/chmorgan/sharppcap)
[4] Clone or download PacketDotNet repository (https://github.com/chmorgan/packetnet)
[5] Download one of Newtonsoft's JSON library releases (https://github.com/JamesNK/Newtonsoft.Json/releases)
[6] Clone or download PAX repository
[7] Install MONO by following the setup instructions (http://www.mono-project.com/docs/getting-started/install/linux/)
[OPTIONAL] RUN: sudo apt-get install mininet

!!!!
THIS STEP IS IMPORTANT AND SHOULD BE HIGHLIGHTED, SINCE MANY *.dll FILES HAVE THE SAME NAME AND THE USER IS ASKED FOR REPLACING THEM.
!!!!
[8] Copy all *.dll files from Newtonsoft, SharpPcap and PacketDotNet folders into Pax's lib/ directory.(Replace files if asked while copying)

!!!!
THIS STEP SHOWS THAT NO DLLMAP CHANGE IS REQUIRED INTO MONO CONFIGURATION.
HOWEVER, THE PROVIDED "pax/lib/SharpPcap.dll.config" FILE MUST BE CHANGED AS FOLLOWS
IN ORDER TO POINT TO THE CORRECT "libpcap.so" LOCATION
!!!!
[9] DLLMAP

pax/lib/SharpPcap.dll.config

<configuration>
  <dllmap dll="wpcap" target="libpcap.dylib" os="osx" />
  <dllmap dll="wpcap" target="/usr/lib/x86_64-linux-gnu/libpcap.so.0.8" os="linux" />
</configuration>

Mininet test hanging

This patch leads to the test hanging on exit:
229a891
undoing the change (i.e., not using the PaxNode class) fixes the problem, so perhaps one could look at whether there are any error messages that are being missed, or if Mininet requires anything specific to complete clean-up and termination.

measure timing

Find out how long it takes for a frame to be processed by Pax. That is, once the frame arrives, how long it takes before the frame's dropped or sent on to the next port. This might different depending on whether Mono's AOT compiler is used, and would require warming up if the (standard for .NET) JIT compiler is used. It would also be useful to find out how long it takes for the frame to reach Pax after the frame arrives at the NIC, and how long it takes for the Pax process frame to get to the NIC.

In conversation last week about rudimentary testing ideas, @luigirizzo suggested access a pcap file from disk (rather than receiving/sending packets to a network interface) and measuring Pax's processing time.

caching or preprocessing layer for forwarding decisions

Since forwarding decisions are immutable, instead of allocating objects for forwarding decisions we could cache similar earlier decisions. This could take the form of a general caching layer, which users of Pax could tune or extend for their packet processors. Or it could take the form of a preprocessing step.

That is, instead of creating a new SinglePortForward each time we make a forwarding decision, if we have a single-port forwarding processor with 5 ports we could simply instantiate SinglePortForward 6 times (one for each port, and once for drop -- port -1) when the packet processor starts, then reference these instances during runtime.

Things might get a bit harder with MultiPortForward, where it might make more sense to have a caching layer rather than parameter-sweep at start-time as a preprocessing step.

For more context see #7 (comment)

replace build.sh with an .sln file

xbuild appears to work reliably enough, therefore using a .sln file would improve portability since the current build.sh cannot directly be used on Windows. The replacement .sln file would build both projects included in Pax: Pax itself, and the Examples project.

Add unit/white-box testing

It might be useful to have the ability to check the forwarding tables in tests. Unit testing would also likely be useful.

See this comment for context.

regression testing

The core bits of Pax (e.g., PaxConfig and Paxifax) are changing much less frequently now. Since it's laborious to test the increasing number of examples every time a core change happens, it would be useful to have automated regression testing, perhaps building on the Python scripts written by @TMVector to use Mininet.

update `examples/wiring.json`

The default example invocation:
sudo ./Bin/Pax.exe examples/wiring.json examples/Bin/Examples.dll
currently doesn't work. I believe this is because the constructor arguments to the wiring (configuration) info for Nested_Chained_Test2 (referenced in examples/wiring.json) has not been updated to work with the latest version of the code. Every packet processor (e.g., hub, switch, ..., Nested_Chained_Test2) has a constructor with parameters. This summer we implemented a better way to pass these parameters in the .json file, but wiring.json has not beed updated to pass the right parameters to Nested_Chained_Test2.
Until it's fixed, for an example that should work, try running:
sudo ./Bin/Pax.exe examples/tallyer_wiring.json examples/Bin/Examples.dll

json-encoded configuration file for batch processes

The current json configuration format doesn't feel right for batch processes, as in Recap. For example see https://github.com/niksu/recap/blob/8f11121df68c29ca3dad6a5504651c18498e5a15/recap.json, where it seems unnecessary to have Recap be the lead_handler for any interfaces. Perhaps such batch processes should be started in their own thread, unrelated to any interface?

measure load

In addition to measuring the time taken for packets to cross the packet processor (and return to the NIC), it would also be useful to get one or more measures of load, such as table size.