trema 0.2.5 → 0.2.6

data/.gitignore

@@ -27,7 +27,7 @@ callgrind.out.*
 html
 objects
 
-# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore: 
+# Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
 #
 # * Create a file at ~/.gitignore
 # * Include files you want ignored

data/Doxyfile

@@ -616,7 +616,7 @@ INPUT_ENCODING         = UTF-8
 # *.hxx *.hpp *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm *.dox *.py
 # *.f90 *.f *.for *.vhd *.vhdl
 
-FILE_PATTERNS          = 
+FILE_PATTERNS          =
 
 # The RECURSIVE tag can be used to turn specify whether or not subdirectories
 # should be searched for input files as well. Possible values are YES and NO.

data/Gemfile

@@ -1,23 +1,35 @@
-source "http://rubygems.org"
+source :rubygems
 
+
+# Include dependencies from trema.gemspec. DRY!
 gemspec
 
+
 # Add dependencies required to use your gem here.
 # Example:
 #   gem "activesupport", ">= 2.3.5"
 
+
 # Add dependencies to develop your gem here.
 # Include everything needed to run rake, tests, features, etc.
 group :development do
+  gem "aruba", "~> 0.5.1"
   gem "cucumber", "~> 1.2.1"
   gem "flay", "~> 1.4.3"
   gem "flog", "~> 2.5.3"
-  gem "rake", "~> 0.9.2.2"
+  gem "rake", "~> 10.0.2"
   gem "rcov", "~> 1.0.0"
   gem "rdoc", "~> 3.12"
-  gem "redcarpet", "~> 2.1.0"
-  gem "reek", "~> 1.2.8"
+  gem "redcarpet", "~> 2.2.2"
+  gem "reek", "~> 1.2.13"
   gem "roodi", "~> 2.1.0"
-  gem "rspec", "~> 2.11.0"
-  gem "yard", "~> 0.7"
+  gem "rspec", "~> 2.12.0"
+  gem "yard", "~> 0.8.3"
 end
+
+
+### Local variables:
+### mode: Ruby
+### coding: utf-8-unix
+### indent-tabs-mode: nil
+### End:

data/README.md

@@ -22,19 +22,30 @@ Supported Platforms
 
 Trema supports GNU/Linux only. And it has been tested on the following environments:
 
-* Ubuntu 12.04, 11.10, 11.04, 10.10, and 10.04 (i386/amd64, Desktop Edition)
+* Ruby 1.8.7 (1.9.x is NOT supported yet)
+* Ubuntu 12.10, 12.04, 11.10, and 10.04 (i386/amd64, Desktop Edition)
 * Debian GNU/Linux 6.0 (i386/amd64)
 
 It may also run on other GNU/Linux distributions but is not tested and
 NOT SUPPORTED at this moment.
 
 
+Supported OpenFlow Protocol Versions
+------------------------------------
+
+Trema currently supports OpenFlow version 1.0 only.
+
+
 Getting Started
 ---------------
 
 1.Install the prerequisites at the command prompt:
 
-    $ sudo apt-get install gcc make ruby rubygems ruby-dev irb libpcap-dev libsqlite3-dev
+    (In Debian GNU/Linux or Ubuntu 12.04 and below)
+    $ sudo apt-get install gcc make ruby rubygems ruby-dev libpcap-dev libsqlite3-dev
+
+    (In Ubuntu 12.10)
+    $ sudo apt-get install gcc make ruby1.8 rubygems1.8 ruby1.8-dev libpcap-dev libsqlite3-dev
 
 2.Install Trema at the command prompt:
 
@@ -51,7 +62,7 @@ Getting Started
 Ruby API
 --------
 
-The following is an exerpt from the Trema Ruby API.
+The following is an excerpt from the Trema Ruby API.
 The full documents are found here http://rubydoc.info/github/trema/trema/master/frames
 
 ### Event and Message Handlers
@@ -61,6 +72,22 @@ Subclass
 and override some of the following methods to implement your own
 controller.
 
+```ruby
+class MyController < Controller
+  # handle Packet-In messages here.
+  def packet_in datapath_id, message
+    # ...
+  end
+  
+  # handle Flow-Removed messages here.
+  def flow_removed datapath_id, message
+    # ...
+  end
+  
+  # ...
+end
+```
+
 * [switch_ready(datapath_id)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:switch_ready)
 * [switch_disconnected(datapath_id)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:switch_disconnected)
 * [packet_in(datapath_id, message)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:packet_in)
@@ -80,6 +107,18 @@ For sending Flow-Mod and Packet-Out, there are some methods defined in
 [Trema::Controller](http://rubydoc.info/github/trema/trema/master/Trema/Controller)
 class.
 
+```ruby
+class MyController < Controller
+  def packet_in datapath_id, message
+    # ...
+    send_flow_mod_add( datapath_id, ... )
+    send_packet_out( datapath_id, ... )
+  end
+  
+  # ...
+end
+```
+
 * [send_flow_mod_add(datapath_id, options)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:send_flow_mod_add)
 * [send_flow_mod_delete(datapath_id, options)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:send_flow_mod_delete)
 * [send_flow_mod_modify(datapath_id, options)](http://rubydoc.info/github/trema/trema/master/Trema/Controller:send_flow_mod_modify)
@@ -90,6 +129,24 @@ class.
 The following OpenFlow messages can be sent with
 [Trema::Controller#send_message](http://rubydoc.info/github/trema/trema/master/Trema/Controller:send_message)
 
+```ruby
+class MyController < Controller
+  def switch_ready datapath_id
+    # send a FeaturesRequest message
+    send_message datapath_id, FeaturesRequest.new
+  end
+  
+  def features_reply datapath_id, message
+    # ...
+  end
+  
+  # ...
+end
+```
+
+* [Trema::Hello](http://rubydoc.info/github/trema/trema/master/Trema/Hello)
+* [Trema::EchoRequest](http://rubydoc.info/github/trema/trema/master/Trema/EchoRequest)
+* [Trema::EchoReply](http://rubydoc.info/github/trema/trema/master/Trema/EchoReply)
 * [Trema::FeaturesRequest](http://rubydoc.info/github/trema/trema/master/Trema/FeaturesRequest)
 * [Trema::SetConfig](http://rubydoc.info/github/trema/trema/master/Trema/SetConfig)
 * [Trema::GetConfigRequest](http://rubydoc.info/github/trema/trema/master/Trema/GetConfigRequest)
@@ -105,9 +162,57 @@ The following OpenFlow messages can be sent with
 * [Trema::PortMod](http://rubydoc.info/github/trema/trema/master/Trema/PortMod)
 * [Trema::Vendor](http://rubydoc.info/github/trema/trema/master/Trema/Vendor)
 
+### Matching Rules
+
+The matching rule of each flow table entry can be created with
+[Match.new(options)](http://rubydoc.info/github/trema/trema/master/Trema/Match)
+and passed as ":match =>" option when sending Flow-Mod or Packet-Out.
+
+```ruby
+def packet_in datapath_id, message
+  # ...
+
+  send_flow_mod_add(
+    datapath_id,
+    :match => Match.new( :in_port => message.in_port, ...)
+    # ...
+  )
+  
+  # ...
+end
+```
+
+Also there is a utility method called
+[ExactMatch.from(packetin)](http://rubydoc.info/github/trema/trema/master/Trema/ExactMatch)
+for getting an exact match corresponding to a packet.
+
+```ruby
+def packet_in datapath_id, message
+  # ...
+
+  send_flow_mod_add(
+    datapath_id,
+    :match => ExactMatch.from( message )
+    # ...
+  )
+  
+  # ...
+end
+```
+
 ### Actions
 
-Each flow table entry contains a list of actions that will be executed when a packet matches the entry.
+The actions list of each flow table entry can be set with ":actions
+=>" when sending Flow-Mod or Packet-Out.
+
+```ruby
+# Strip the VLAN tag of a packet then send it out to switch port #1
+send_flow_mod_add(
+  datapath_id,
+  # ...
+  :actions => [ StripVlanHeader.new, SendOutPort.new( 1 ) ]
+)
+```
 
 * [Trema::SendOutPort](http://rubydoc.info/github/trema/trema/master/Trema/SendOutPort)
 * [Trema::SetEthSrcAddr](http://rubydoc.info/github/trema/trema/master/Trema/SetEthSrcAddr)
@@ -135,7 +240,8 @@ Meta
 Contributors
 ------------
 
-Special thanks to all contributors for submitting patches. A full list of contributors including their patches can be found at:
+Special thanks to all contributors for submitting patches. A full list
+of contributors including their patches can be found at:
 
 https://github.com/trema/trema/contributors
 
@@ -145,6 +251,7 @@ Project Status
 
 * Build Status [![Build Status](https://secure.travis-ci.org/trema/trema.png?branch=develop)](http://travis-ci.org/trema/trema)
 * Dependency Status [![Dependency Status](https://gemnasium.com/trema/trema.png)](https://gemnasium.com/trema/trema)
+* Code Quality [![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/trema/trema)
 
 
 License

data/Rakefile

@@ -61,7 +61,9 @@ end
 
 begin
   require "cucumber/rake/task"
-  Cucumber::Rake::Task.new( :features )
+  Cucumber::Rake::Task.new( :features ) do | t |
+    t.cucumber_opts = "features --tags ~@wip"
+  end
 rescue LoadError
   $stderr.puts $!.to_s
 end

data/Rantfile

@@ -37,6 +37,7 @@ import "directedrule"
 desc "Build trema."
 task :default => [
   :libtrema,
+  :management_commands,
   :rubylib,
   :switch_manager,
   :switch,
@@ -57,6 +58,7 @@ task :examples => [
   "examples:learning_switch",
   "examples:list_switches",
   "examples:multi_learning_switch",
+  "examples:openflow_switch",
   "examples:openflow_message",
   "examples:packet_in",
   "examples:repeater_hub",
@@ -67,6 +69,14 @@ task :examples => [
 ]
 
 
+task :management_commands => [
+  "management_commands:application",
+  "management_commands:echo",
+  "management_commands:set_logging_level",
+  "management_commands:show_stats",
+]
+
+
 import "clean"
 
 desc "Cleanup generated files."
@@ -173,7 +183,7 @@ end
 
 
 desc "Run the c cbench switch controller to benchmark"
-task "cbench" => "cbench:c"
+task "cbench" => "cbench:ruby"
 
 
 desc "Run the c cbench switch controller to benchmark"
@@ -588,6 +598,45 @@ file Trema::Executables.stdin_relay => stdin_relay_objects + [ libtrema ] do | t
 end
 
 
+################################################################################
+# Build management commands
+################################################################################
+
+management_commands = [
+  "application",
+  "echo",
+  "set_logging_level",
+  "show_stats",
+]
+
+management_source_dir = "src/management"
+management_objects_dir = objects( "management" )
+
+gen C::Dependencies, dependency( "management" ),
+  :search => [ Trema.include ], :sources => sys[ "#{ management_source_dir }/*.c" ]
+
+gen Action do
+  source dependency( "management" )
+end
+
+gen Directory, management_objects_dir
+
+
+gen DirectedRule, management_objects_dir => [ management_source_dir ], :o => :c do | t |
+  sys "gcc -I#{ Trema.include } -I#{ Trema.openflow } #{ var :CFLAGS } -c -o #{ t.name } #{ t.source }"
+end
+
+
+management_commands.each do | each |
+  target = File.join( management_objects_dir, each )
+  desc "Build #{ each } management command."
+  task "management_commands:#{ each }" => target
+  file target => [ File.join( management_objects_dir, "#{ each }.o" ), libtrema ] do | t |
+    sys "gcc -L#{ Trema.lib } -o #{ t.name } #{ t.source } -ltrema -lsqlite3 -ldl -lrt -lpthread"
+  end
+end
+
+
 ################################################################################
 # Build standalone examples
 ################################################################################
@@ -633,6 +682,41 @@ standalone_examples.each do | each |
 end
 
 
+########################################################################################
+# Build openflow switches
+################################################################################
+
+openflow_switches = [
+  "hello_switch",
+]
+
+openflow_switch_source_dir = "src/examples/openflow_switch"
+openflow_switch_objects_dir = objects( "examples/openflow_switch" )
+
+gen C::Dependencies, dependency( "openflow_switch" ),
+  :search => [ Trema.include ], :sources => sys[ "#{ openflow_switch_source_dir }/*.c" ]
+
+gen Action do
+  source dependency( "openflow_switch" )
+end
+
+gen Directory, openflow_switch_objects_dir
+
+
+gen DirectedRule, openflow_switch_objects_dir => [ openflow_switch_source_dir ], :o => :c do | t |
+  sys "gcc -I#{ Trema.include } -I#{ Trema.openflow } #{ var :CFLAGS } -c -o #{ t.name } #{ t.source }"
+end
+
+
+openflow_switches.each do | each |
+  target = File.join( openflow_switch_objects_dir, each )
+  task "examples:openflow_switch" => target
+  file target => [ File.join( openflow_switch_objects_dir, "#{ each }.o" ), libtrema ] do | t |
+    sys "gcc -L#{ Trema.lib } -o #{ t.name } #{ t.source } -ltrema -lsqlite3 -ldl -lrt -lpthread"
+  end
+end
+
+
 ################################################################################
 # Build openflow messages
 ################################################################################
@@ -643,6 +727,7 @@ openflow_messages = [
   "features_request",
   "hello",
   "set_config",
+  "vendor_action",
 ]
 
 openflow_message_source_dir = "src/examples/openflow_message"
@@ -794,6 +879,8 @@ tests = [
   "objects/unittests/wrapper_test",
   "objects/unittests/match_table_test",
   "objects/unittests/message_queue_test",
+  "objects/unittests/management_interface_test",
+  "objects/unittests/management_service_interface_test",
 ]
 
 

data/bin/trema

@@ -0,0 +1,248 @@
+#! /usr/bin/env ruby
+#
+# Trema command-line tool.
+#
+# Copyright (C) 2008-2012 NEC Corporation
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License, version 2, as
+# published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
+#
+
+
+$LOAD_PATH.unshift File.expand_path( File.join File.dirname( __FILE__ ), "..", "ruby" )
+
+
+require "rubygems"
+
+require "gli"
+require "trema/command"
+require "trema/util"
+require "trema/version"
+
+
+include GLI::App
+include Trema::Util
+include Trema::Command
+
+
+program_desc "Trema command-line tool"
+
+
+desc "Displays the current runtime version"
+version Trema::VERSION
+
+
+desc "Be verbose"
+switch [ :v, :verbose ], :negatable => false
+
+
+desc "Runs a trema application"
+arg_name "controller"
+command :run do | c |
+  c.desc "Runs as a daemon"
+  c.switch [ :d, :daemonize ], :negatable => false
+
+  c.desc "Enables Trema wireshark plugin"
+  c.switch [ :s, :tremashark ], :negatable => false
+
+  c.desc "Specifies emulated network configuration"
+  c.flag [ :c, :conf ]
+
+  c.action do | global_options, options, args |
+    trema_run options
+  end
+end
+
+
+desc "Terminates a trema process"
+arg_name "name"
+command :kill do | c |
+  c.action do | global_options, options, args |
+    help_now!( "name is required" ) if args.empty?
+    args.each do | each |
+      trema_kill each
+    end
+  end
+end
+
+
+desc "Starts a killed trema process again"
+arg_name "name"
+command :up do | c |
+  c.action do | global_options, options, args |
+    trema_up args[ 0 ]
+  end
+end
+
+
+desc "Terminates all trema processes"
+command :killall do | c |
+  c.action do
+    trema_killall
+  end
+end
+
+
+desc "Sends UDP packets to destination host"
+command :send_packets do | c |
+  c.desc "host that sends packets"
+  c.flag [ :s, :source ]
+
+  c.desc "host that receives packets"
+  c.flag [ :d, :dest ]
+
+  c.desc "number of times to increment the IP source address"
+  c.default_value nil
+  c.flag [ :inc_ip_src ]
+
+  c.desc "number of times to increment the IP destination address"
+  c.default_value nil
+  c.flag [ :inc_ip_dst ]
+
+  c.desc "set the initial UDP source port"
+  c.flag [ :tp_src ]
+
+  c.desc "number of times to increment the UDP source port"
+  c.default_value nil
+  c.flag [ :inc_tp_src ]
+
+  c.desc "set the initial UDP destination port"
+  c.flag [ :tp_dst ]
+
+  c.desc "number of times to increment the UDP destination port"
+  c.default_value nil
+  c.flag [ :inc_tp_dst ]
+
+  c.desc "send packet rate - packets per second"
+  c.flag [ :pps ]
+
+  c.desc "number of packets to send"
+  c.flag [ :n_pkts ]
+
+  c.desc "time duration to send packets"
+  c.flag [ :duration ]
+
+  c.desc "length of UDP payload"
+  c.flag [ :length ]
+
+  c.desc "increment UDP payload"
+  c.default_value nil
+  c.flag [ :inc_payload ]
+
+  c.action do | global_options, options, args |
+    raise "--source option is mandatory" if options[ :source ].nil?
+    raise "--dest option is mandatory" if options[ :dest ].nil?
+
+    trema_send_packets options[ :source ], options[ :dest ], options
+  end
+end
+
+
+desc "Shows stats of packets"
+arg_name "host"
+command :show_stats do | c |
+  c.desc "Show stats of packets sent"
+  c.switch [ :t, :tx ], :negatable => false
+  c.desc "Show stats of packets received"
+  c.switch [ :r, :rx ], :negatable => false
+
+  c.action do | global_options, options, args |
+    help_now!( "host is required" ) if args.empty?
+    trema_show_stats args[ 0 ], options[ :tx ], options[ :rx ]
+  end
+end
+
+
+desc "Resets stats of packets"
+arg_name "hosts..."
+command :reset_stats do | c |
+  c.action do | global_options, options, args |
+    hosts = args
+    if hosts.empty?
+      hosts = Trema::DSL::Context.load_current.hosts.keys
+    end
+    hosts.each do | each |
+      trema_reset_stats each
+    end
+  end
+end
+
+
+desc "Print all flow entries"
+arg_name "switches..."
+command :dump_flows do | c |
+  c.action do | global_options, options, args |
+    help_now!( "switches is required" ) if args.empty?
+    trema_dump_flows args
+  end
+end
+
+
+desc "Opens a new shell in the specified network namespace"
+arg_name "name"
+command :netns do | c |
+  c.action do | global_options, options, args |
+    trema_netns args[ 0 ]
+  end
+end
+
+
+desc "Opens in your browser Trema's Ruby API documentation"
+command :ruby do | c |
+  c.action do
+    trema_ruby
+  end
+end
+
+
+desc "Displays the current runtime version"
+command :version do | c |
+  c.action do
+    trema_version
+  end
+end
+
+
+pre do | global, command, options, args |
+  $verbose = global[ :verbose ]
+
+  assert_trema_is_built
+
+  if FileTest.exist?( Trema.tmp ) and not FileTest.writable?( Trema.tmp )
+    # Trema is system widely installed with gem command
+    sh "sudo chmod o+w -R #{ Trema.tmp }"
+  end
+
+  FileUtils.mkdir_p Trema.log
+  FileUtils.mkdir_p Trema.pid
+  FileUtils.mkdir_p Trema.sock
+
+  true
+end
+
+
+on_error do | exception |
+  # Error logic here
+  # return false to skip default error handling
+  true
+end
+
+
+exit run( ARGV )
+
+
+### Local variables:
+### mode: Ruby
+### coding: utf-8
+### indent-tabs-mode: nil
+### End: