From OpenFlow Wiki

Capsulator is a user-space program which can be used to transparently connect networks. In particular, it can make an arbitrary number of links act as if they were connected to a hub.

Contents 1 Terminology 2 Overview 3 How it Works 3.1 Descriptions of Capsulator Port Types 3.2 Tunneling Protocol 3.3 How Incoming Data is Handled 4 OpenFlow Network Example 5 How to Run

Terminology

• Capsulator - the software and machine which sits on the edge of a network and connects its "border ports" to other Capsulators' "border ports"
• Border Port - A port on a Capsulator which is virtually connected to other identically tagged border port(s) on other Capsulator(s). Each border port's tag is specified by the user when starting the Capsulator.
• Tunnel Port - The port on each Capsulator which is used for communicating with other Capsulators.

Overview

Capsulator virtually connects ports which are assigned the same tag value. It does this with a MAC-in-IP tunnel. This means Ethernet frames are read from each border port, and forwarded to all Capsulators' border ports with the same tag. The Ethernet frames are communicated from one Capsulator to another as the payload of an IP packet.

How it Works

The diagram below shows how Capsulator can be used to connect an arbitrary number of networks. In each network shown, eth0 is used as the tunnel port to connect to the network which is used to communicate with the other Capsulators. Typically, this central network will probably be the Internet.

(PDF Version)

Descriptions of Capsulator Port Types

Each Capsulator has some number of additional ports, the border ports, which connect into the local network. Each Capsulator may have a different number of border ports. Each border port may be tagged with any tag value (an integer).

Tunneling Protocol

Tunneling is done over IP. The Capsulator uses its own protocol and specifies that its protocol ID is 0xF5. The payload of an IP packet containing a tunneling payload is:

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |                              Tag                              |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | Ethernet frame being tunneled: header+payload; no preamble/CRC|
 | ...                                                           |
 | ...                                                           |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

How Incoming Data is Handled

When an Ethernet frame is received by a border port, it is put into an IP packet in the above format and sent to all other Capsulators.

When a tunneling port (eth0 in this diagram) receives an IP packet, it removes the IP header, examines the tag value, and forwards the Ethernet frame out all of the border ports whose tag match. The OS takes care of fragmenting and reassembling the IP packet on each end, so essentially arbitrary-sized (e.g. bigger than intermediate MTU-sized) Ethernet frames can be tunneled.

OpenFlow Network Example

In this example, each Capsulator has one tunnel port (eth2) and two border ports (eth0 and eth1). Each eth0 is connected to the a hub which is hooked into the OpenFlow switches' and NOX's control ports. Each eth1 is connected to an OpenFlow switch's data port. Typically, this might be a data port on the switch at the root of the local network.

With this setup, control can be maintained by a single NOX controller over all OpenFlow switches in the network. Furthermore, the two networks operate as if they were directly connected by a link between the two OpenFlow switches which are connected to the eth1 port.

(PDF Version)

How to Run

These instructions show how to obtain a copy of the source and run the Capsulator.

 $ git clone yuba:/usr/local/git/capsulator (1)
 $ cd capsulator (2)
 $ make (3)
 $ ./capsulator -t eth2 -f 2.2.2.2 -b eth0:0 -b eth1:1 (4)

1. Get a copy of the source from the Capsulator git repository.
2. Change to the Capsulator's root folder.
3. Build the Capsulator.
4. Run the capsulator.
   • -t: specifies which interface to use for tunneling
   • -f: a comma-separated list of the IPs of other Capsulator tunnel endpoints
   • -b: specifies an interface to use as a border port and its tag (may be specified multiple times)
   • Therefore, these command-line arguments will result in the following: eth2 will be used for tunneling to another Capsulator at 2.2.2.2. Traffic arriving on eth0 will be tunneled with tag 0, and any traffic received from the tunnel with a tag of 0 will be forwarded to eth0. Likewise for eth1 with tag 1.