Quick Start

Event dumper is an sample controller that outputs any OpenFlow related events to your terminal. With this sample, you can learn how to capture and handle OpenFlow related events with the manner of Trema.

You can run the event dumper with the following command:

$ ./trema run ./objects/examples/dumper/dumper -c ./src/examples/dumper/dumper.conf

This command starts a single OpenFlow switch (datapath ID = "0xabc") and two virtual hosts (named "host1" and "host2") connected to the switch as described in Trema configuration file.

vswitch {
  datapath_id "0xabc"
}

vhost( "host1" ) {
  ip "192.168.0.1"
  netmask "255.255.0.0"
  mac "00:00:00:01:00:01"
}

vhost( "host2" ) {
  ip "192.168.0.2"
  netmask "255.255.0.0"
  mac "00:00:00:01:00:02"
}

link "0xabc", "host1"
link "0xabc", "host2"

Do not surprise that Trema has an integrated OpenFlow network emulator and you do not need to prepare OpenFlow switches and end-hosts for testing controller applications!

After the environment is set up, the dumper application starts to capture OpenFlow related events from the switch.

Now you can send packets between these two virtual hosts using trema send_packets command and see several OpenFlow events are captured by the dumper. Open another terminal and try to run the following command:

$ ./trema send_packets --source host1 --dest host2 --n_pkts 10

Now you can see some Packet-In events being captured:

[packet_in]
datapath_id: 0xe0
transaction_id: 0
buffer_id: 0x121
total_len: 64
in_port: 1
reason: 0
data:
000000010002000000010001080045000032000000004011ff67ffff0001f ...

Learning switch

Learning switch ([trema]/src/examples/learning_switch) is an application that emulates a layer 2 switch consists of a single OpenFlow switch.

From this application, you will learn how you can send OpenFlow messages to OpenFlow switches respond to Packet-In events and how you can set a periodic timer event with the manner of Trema.

You can run the learning switch with the following command:

$ ./trema run -c ./src/examples/learning_switch/learning_switch.conf

This command starts a single OpenFlow switch and two virtual hosts (named "host1" and "host2") connected to the switch. Again please do not surprise that Trema has an integrated network emulator and you do not need to prepare OpenFlow switches and end-hosts for testing a controller.

Try trema send_packets to send packets from host1 to host2. This eventually generates Packet-In events that are handled by the learning switch:

$ ./trema send_packets --source host1 --dest host2 --n_pkts 10

Let's see packets are properly forwarded by the learning switch. You can show sender and receiver's statistics with trema show_stats command.

$ ./trema show_stats host1 --tx
ip_dst,tp_dst,ip_src,tp_src,n_pkts,n_octets
192.168.0.2,1,192.168.0.1,1,10,500

$ ./trema show_stats host2 --rx
ip_dst,tp_dst,ip_src,tp_src,n_pkts,n_octets
192.168.0.2,1,192.168.0.1,1,10,500

If the learning switch works correctly, the tx and rx should be identical.

Routing switch

Routing switch ([trema]/src/examples/routing_switch) is an application that emulates a virtual layer 2 switch formed by multiple OpenFlow switches. For routing traffic among these switches, network topology is retrieved from separated application named "topology" ([trema]/src/examples/topology) and a shortest path algorithm (Dijkstra's algorithm) is implemented.

From this application, you will learn how you can interact with other applications via an IPC mechanism provided by Trema.

You can run the routing switch with the following command:

$ ./trema run -c ./src/examples/routing_switch/routing_switch_fullmesh.conf

This command starts four OpenFlow switches and four virtual hosts (named "host1", "host2", "host3", and "host4"). Each switch has a single host and switches are connected in full-mesh topology.

Try trema send_packets to send packets from host1 to host4. This eventually generates Packet-In events that are handled by the routing switch:

$ ./trema send_packets --source host1 --dest host4 --n_pkts 10

Let's see packets are properly forwarded by the routing switch.

$ ./trema show_stats host1 --tx
ip_dst,tp_dst,ip_src,tp_src,n_pkts,n_octets
192.168.0.4,1,192.168.0.1,1,10,500

$ ./trema show_stats host4 --rx
ip_dst,tp_dst,ip_src,tp_src,n_pkts,n_octets
192.168.0.4,1,192.168.0.1,1,10,500

If the routing switch works correctly, the tx and rx counts should be identical.

How to develop your own OpenFlow controller

Where to start?

The best way to learn how to develop your own OpenFlow controller on top of Trema at this moment is to explore sample applications in [trema]/src/examples.

Trema tutorial also provide good guidance how to write a controller with C or Ruby programming language but unfortunately they are still work in progress.

If you are interested in details of features provided by Trema, [trema]/src/lib/trema.h should be the starting point of your journey.

Understanding IPC among functional modules

If you are interested in developing an application consists of multiple processes and they require IPCs, the sample routing switch application ([trema]/src/examples/routing_switch) might be the starting point of your development. In addition, a tool named "tremashark" ([trema]/src/tremashark) that visualizes all IPC events should help to understand IPC messages/framework of Trema. See [trema]/src/tremashark/README for details.

Understanding core modules

Trema includes the following three core functional modules that are always required for interacting with OpenFlow switches. If you just want to develop an OpenFlow controller, you do not need to care about these modules. However, if you are really need to modify them (e.g., for extending OpenFlow protocol), please refer to the following explanations.

Switch manager ([trema]/src/switch_manager)

Switch manager listens a TCP port and waits for incoming connections from OpenFlow switches. If a connection is established with a switch, a new switch manager process (see below) is created for the switch.

Switch ([trema]/src/switch_manager)

Switch forwards OpenFlow messages received from OpenFlow switches to appropriate functional modules. In addition, it aggregates OpenFlow messages generated by other functional modules and takes care of message transactions and flow cookies. All transaction identifiers and cookie values are translated to guarantee uniqueness of them.

Packet-In filter ([trema]/src/packetin_filter)

Packet-In filter inspects the contents of Packet-In messages and distributes the messages to appropriate functional modules based on pre-defined filter criteria.