rb-wartslib 0.9.12 → 0.9.13

data/CHANGES

@@ -1,3 +1,40 @@
+version 0.9.13, 2008-02-01
+  * fixed Warts::File#open to handle paths with spaces and other special
+    characters
+  * implemented methods to retrieve hop TLV values; namely,
+       hop_reply_ipid
+       hop_reply_iptos
+       hop_next_hop_mtu
+       hop_inner_iplen
+       hop_inner_ipttl
+       hop_inner_iptos
+  * implemented Warts::Trace#hop_has_reply_ttl?; you should call this when
+    Warts::Trace#hop_reply_ttl returns 0, to distinguish between a true
+    0 reply TTL and a missing reply TTL
+  * implemented Warts::Trace#hop_has_tcp_reply? and #hop_has_icmp_reply?;
+    use these methods to determine which type of reply data is available,
+    either ICMP or TCP (these are mutually exclusive); the methods
+    Trace#hop_icmp_type, Trace#hop_icmp_code, and Trace#hop_tcp_flags
+    now return nil if a reply of the given type isn't available    
+  * implemented Warts::Trace#hop_tcp_flags_breakdown
+  * implemented Warts::Trace.decompose_tcp_flags and decompose_hop_flags
+    convenience methods
+  * added Warts::Trace::STOP_REASON_TEXT which is a hash from stop reason
+    code to human-oriented text
+  * added Warts::Trace#dest and #dest_cmp methods; the previous #dst and
+    #dst_cmp methods are still available but deprecated
+  * moved Warts::File::TRACE, Warts::File::LIST, Warts::File::CYCLE_START,
+    etc. constants to Warts::TRACE, Warts::LIST, etc.; the previous definitions
+    are still available, though deprecated
+  * added Warts::Trace::HOP_FLAG_TCP
+  * changed to export the internal scamper constant SCAMPER_TRACE_STOP_DEAD
+    as Warts::Trace::STOP_GAPLIMIT rather than Warts::Trace::STOP_DEAD; this
+    is in keeping with recent changes in scamper; the old STOP_DEAD constant
+    is still available for backwards compatibility, though deprecated
+  * made internal changes needed to build with scamper-cvs-20070523j
+  * updated sample scripts to use newest non-deprecated methods; also
+    improved stat-traces script to print out TCP flags stats
+
 version 0.9.12, 2008-01-16
   * renamed Warts::Trace#each_attempt to each_response
   * renamed Warts::Trace#each_hop_and_attempt to each_hop_and_response

data/README

@@ -12,8 +12,9 @@ This extension will be useful to network researchers, operators, and users
 who need to analyze or process warts files.
 
 Please see the project home page at http://rb-wartslib.rubyforge.org/
-for further documentation and sample code.  Sample code is also available
-in the 'bin' subdirectory.
+for further documentation and sample code.  A possibly older copy of the
+project page and documentation is available in the 'docs' subdirectory.
+Sample code is also available in the 'bin' subdirectory.
 
 
 INSTALLING
@@ -40,7 +41,7 @@ That will build libscamperfile.a, which is what rb-wartslib links against.
 Now build and install rb-wartslib:
 
   $ SCAMPER=/Users/youngh/scamper-cvs-20070523h
-     (set the above to the directory where you built scamper)
+     (set the above to the *absolute* directory where you built scamper)
   $ sudo gem install rb-wartslib -- --with-scamper-include=$SCAMPER --with-scamper-lib=$SCAMPER
 
 That's it.
@@ -49,9 +50,11 @@ That's it.
 CONTACT
 -------
 
-rb-wartslib is written by Young Hyun.  You may contact him at
-youngh AT rubyforge.org, or use the tracker/forums at
-http://rubyforge.org/projects/rb-wartslib/ for getting help.
+rb-wartslib is written and maintained by Young Hyun as a part of
+CAIDA's work on the Archipelago Measurement Infrastructure
+[http://www.caida.org/projects/ark/].  You may contact him at youngh
+AT rubyforge.org, or use the tracker/forums at the RubyForge project
+page for getting help.
 
 Please direct scamper questions, including problems building it,
 to Matthew Luckie:

data/bin/count-traces

@@ -21,7 +21,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: count-traces,v 1.1 2007/11/30 01:14:47 youngh Exp $
+## $Id: count-traces,v 1.3 2008/02/02 00:01:23 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -30,13 +30,13 @@ require 'wartslib'
 total = 0
 ARGV.each do |path|
   file = Warts::File::open path
-  file.add_filters Warts::File::TRACE
+  file.add_filters Warts::TRACE
 
   count = 0
   file.read { count += 1 }
 
-  puts "%8d %s" % [count, path]
+  printf "%8d %s\n", count, path
   total += count
 end
 
-puts "%8d total" % [total]
+printf "%8d total\n", total

data/bin/create-aspath

@@ -20,7 +20,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: create-aspath,v 1.1 2007/11/30 01:14:47 youngh Exp $
+## $Id: create-aspath,v 1.3 2008/02/02 00:01:23 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -84,7 +84,7 @@ def extract_ippath(trace)
     end
   end
 
-  retval << trace.dst if dest_response
+  retval << trace.dest if dest_response
   retval
 end
 
@@ -129,7 +129,7 @@ ARGV.each do |path|
     next
   end
 
-  file.add_filters Warts::File::TRACE
+  file.add_filters Warts::TRACE
   file.read do |trace|
     if $options.verbose
       puts "-" * 78

data/bin/extract-trace-addrs

@@ -24,7 +24,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: extract-trace-addrs,v 1.2 2007/12/08 00:56:04 youngh Exp $
+## $Id: extract-trace-addrs,v 1.4 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -69,7 +69,7 @@ def extract_addresses(trace, addresses)
     addresses[trace.hop_addr(hop, response)] += 1
   end
 
-  addresses[trace.dst] += 1 if dest_response
+  addresses[trace.dest] += 1 if dest_response
 end
 
 
@@ -82,7 +82,7 @@ addresses = Hash.new { |h,k| h[k] = 0 }
 ARGV.each do |path|
   $stderr.puts "examining #{path} ..."
   Warts::File.open(path) do |file|
-    file.add_filters Warts::File::TRACE
+    file.add_filters Warts::TRACE
     file.read do |trace|
       extract_addresses trace, addresses
     end

data/bin/modify-traces

@@ -20,7 +20,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: modify-traces,v 1.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: modify-traces,v 1.2 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -98,9 +98,9 @@ ARGV.each do |path|
   puts "processing #{path} ..."
 
   file = Warts::File::open path
-  filters = [ Warts::File::TRACE ]
-  filters << Warts::File::CYCLE_START unless options.delete_cycle_start
-  filters << Warts::File::CYCLE_STOP unless options.delete_cycle_stop
+  filters = [ Warts::TRACE ]
+  filters << Warts::CYCLE_START unless options.delete_cycle_start
+  filters << Warts::CYCLE_STOP unless options.delete_cycle_stop
   file.add_filters *filters
 
   list = nil
@@ -111,13 +111,13 @@ ARGV.each do |path|
       list = element.list.derive list_options unless list
 
       case element.element_type
-      when Warts::File::CYCLE_START, Warts::File::CYCLE_STOP
+      when Warts::CYCLE_START, Warts::CYCLE_STOP
 	unless cycle
 	  options = {:list => list}.merge(cycle_options)
 	  options.delete(:stop_time)  # leave stop_time to 0 for START records
 	  cycle = element.derive options
 
-	  if element.element_type == Warts::File::CYCLE_STOP &&
+	  if element.element_type == Warts::CYCLE_STOP &&
 	      cycle_options.has_key?(:stop_time)
 	    element = cycle.derive :stop_time => cycle_options[:stop_time]
 	  else
@@ -127,7 +127,7 @@ ARGV.each do |path|
 	  out.write element  # write out a START record only once per file
 	end
 
-      when Warts::File::TRACE
+      when Warts::TRACE
 	cycle = element.cycle.derive list, cycle_options unless cycle
 	element.cycle = cycle
 	out.write element

data/bin/scdump

@@ -20,7 +20,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: scdump,v 1.13 2007/12/08 00:43:19 youngh Exp $
+## $Id: scdump,v 1.15 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -44,7 +44,7 @@ $halt_reason[Warts::Trace::STOP_DEAD] = "G"
 def show_trace(trace)
   fields = ["T"]
 
-  fields.push trace.src, trace.dst, trace.list_id, trace.cycle_id, trace.start
+  fields.push trace.src, trace.dest, trace.list_id, trace.cycle_id, trace.start
 
   dest_response = trace.find_dest_response
   if dest_response
@@ -111,7 +111,7 @@ end
 
 ARGV.each do |path|
   file = Warts::File::open path
-  file.add_filters Warts::File::TRACE
+  file.add_filters Warts::TRACE
   while (trace = file.read)
     show_trace trace
   end

data/bin/select-traces

@@ -22,7 +22,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: select-traces,v 1.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: select-traces,v 1.3 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -170,18 +170,18 @@ class Stats
   end
 
   def print
-    puts "%8d traces" % [@traces]
-    puts "%8d responding (%.1f%%)" % [@responding, pct(@responding, @traces)]
-    puts "%8d complete (%.1f%%)" % [@complete, pct(@complete, @traces)]
-    puts "%8d dead traces with zero hop count (%.1f%%)" %
-      [ @zero_dead, pct(@zero_dead, @traces) ]
+    printf "%8d traces\n", @traces
+    printf "%8d responding (%.1f%%)\n", @responding, pct(@responding, @traces)
+    printf "%8d complete (%.1f%%)\n", @complete, pct(@complete, @traces)
+    printf "%8d dead traces with zero hop count (%.1f%%)\n",
+      @zero_dead, pct(@zero_dead, @traces)
     puts
     stop_reason.to_a.sort.each do |k, v|
-      puts "%8d stop reason %d, %s" % [v, k, @stop_text[k]]
+      printf "%8d stop reason %d, %s\n", v, k, @stop_text[k]
     end
     puts
     @hop_histogram.to_a.sort.each do |k, v|
-      puts "%8d %d hops" % [v, k]
+      printf "%8d %d hops\n", v, k
     end
   end
 
@@ -226,7 +226,7 @@ ARGV.each do |path|
     exit 1
   end
 
-  file.add_filters Warts::File::TRACE
+  file.add_filters Warts::TRACE
   file.read do |trace|
     trace_index += 1
     next if trace_index <= $options.skip_traces

data/bin/show-cycles

@@ -21,7 +21,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: show-cycles,v 1.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: show-cycles,v 1.2 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require "rubygems"
@@ -29,9 +29,9 @@ require 'wartslib'
 
 def cycle_type(element)
   case element.element_type
-  when Warts::File::CYCLE_START: "START"
-  when Warts::File::CYCLE_DEF: "DEF"
-  when Warts::File::CYCLE_STOP: "STOP"
+  when Warts::CYCLE_START: "START"
+  when Warts::CYCLE_DEF: "DEF"
+  when Warts::CYCLE_STOP: "STOP"
   end
 end
 
@@ -42,8 +42,7 @@ end
 ARGV.each do |path|
   puts ">> #{path}"
   Warts::File::open(path) do |file|
-    file.add_filters Warts::File::CYCLE_START, Warts::File::CYCLE_DEF,
-      Warts::File::CYCLE_STOP
+    file.add_filters Warts::CYCLE_START, Warts::CYCLE_DEF, Warts::CYCLE_STOP
     file.read do |c|
       start_date = ts_date c.start_time
       stop_date = ts_date c.stop_time

data/bin/split-traces-by-type

@@ -21,7 +21,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ##
-## $Id: split-traces-by-type,v 1.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: split-traces-by-type,v 1.2 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -83,7 +83,7 @@ if ARGV.length > 0
     split = SplitFiles.new filename
 
     Warts::File::open(filename) do |file|
-      file.add_filters Warts::File::TRACE
+      file.add_filters Warts::TRACE
       file.read do |element|
         split.sort_trace element
       end

data/bin/stat-traces

@@ -20,7 +20,7 @@
 ## along with this program; if not, write to the Free Software
 ## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 ## 
-## $Id: stat-traces,v 1.3 2007/12/08 00:56:04 youngh Exp $
+## $Id: stat-traces,v 1.10 2008/02/02 00:01:24 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -29,7 +29,7 @@ require 'wartslib'
 
 class Stats
   attr_accessor :traces, :responding, :complete, :stop_reason, :icmp_reason
-  attr_accessor :hop_histogram, :zero_dead
+  attr_accessor :hop_histogram
 
   # Based on http://www.iana.org/assignments/icmp-parameters
   ICMP_TYPE_NAMES = {
@@ -84,33 +84,18 @@ class Stats
     @complete = 0
     @stop_reason = Hash.new 0
     @icmp_reason = Hash.new 0  # "#{icmp_type} #{icmp_code}"
-
-    # from scamper_trace.h:SCAMPER_TRACE_STOP_*
-    @stop_text = {
-      0 => "none (null reason)",
-      1 => "completed (got an ICMP port unreach)",
-      2 => "unreach (got an other ICMP unreach code)",
-      3 => "icmp (got an ICMP msg, not unreach)",
-      4 => "loop (loop detected)",
-      5 => "dead (unresponsive target)",
-      6 => "error (sendto error)"
-    }
-    @stop_text.default = "<<UNKNOWN STOP CODE>>"
-
+    @tcp_flags = Hash.new 0
     @hop_histogram = Hash.new 0
-    @zero_dead = 0
   end
 
   def print
-    puts "%8d traces" % [@traces]
-    puts "%8d responding (%.1f%%)" % [@responding, pct(@responding, @traces)]
-    puts "%8d complete (%.1f%%)" % [@complete, pct(@complete, @traces)]
-    puts "%8d dead traces with zero hop count (%.1f%%)" %
-      [ @zero_dead, pct(@zero_dead, @traces) ]
+    printf "%8d traces\n", @traces
+    printf "%8d responding (%.1f%%)\n", @responding, pct(@responding, @traces)
+    printf "%8d complete (%.1f%%)\n", @complete, pct(@complete, @traces)
 
     puts
     @stop_reason.to_a.sort.each do |k, v|
-      puts "%8d stop reason %d, %s" % [v, k, @stop_text[k]]
+      printf "%8d stop reason %d, %s\n", v, k, Warts::Trace::STOP_REASON_TEXT[k]
     end
 
     puts
@@ -127,12 +112,20 @@ class Stats
         end
         names += ")"
       end
-      puts "%8d icmp type %d, code %d%s" % [v, t, c, names]
+      printf "%8d icmp type %d, code %d%s\n", v, t, c, names
+    end
+
+    unless @tcp_flags.empty?
+      puts
+      @tcp_flags.to_a.sort.each do |k, v|
+        printf "%8d tcp flags %d ", v, k
+        p Warts::Trace.decompose_tcp_flags(k)
+      end
     end
 
     puts
     @hop_histogram.to_a.sort.each do |k, v|
-      puts "%8d %d hops" % [v, k]
+      printf "%8d %d hops\n", v, k
     end
   end
 
@@ -140,6 +133,10 @@ class Stats
     @icmp_reason[icmp_type << 8 | icmp_code] += 1
   end
 
+  def add_tcp_flags(flags)
+    @tcp_flags[flags] += 1
+  end
+
   def add(other)
     @traces += other.traces
     @responding += other.responding
@@ -147,7 +144,6 @@ class Stats
     other.stop_reason.each { |k,v| @stop_reason[k] += v }
     other.icmp_reason.each { |k,v| @icmp_reason[k] += v }
     other.hop_histogram.each { |k,v| @hop_histogram[k] += v }
-    @zero_dead += other.zero_dead
   end
 
   def pct(x, y)
@@ -163,7 +159,7 @@ total = Stats.new
 ARGV.each do |path|
   stats = Stats.new
   Warts::File.open(path) do |file|
-    file.add_filters Warts::File::TRACE
+    file.add_filters Warts::TRACE
     file.read do |trace|
       stats.traces += 1
       stats.responding += 1 if trace.dest_responded?
@@ -175,13 +171,16 @@ ARGV.each do |path|
       #     values for the response from the destination.
       trace.each_hop_and_response do |hop, response, exists|
         next unless exists
-        icmp_type = trace.hop_icmp_type hop, response
-        icmp_code = trace.hop_icmp_code hop, response
-        stats.add_icmp_reason icmp_type, icmp_code
+        if trace.hop_has_icmp_reply? hop, response
+          icmp_type = trace.hop_icmp_type hop, response
+          icmp_code = trace.hop_icmp_code hop, response
+          stats.add_icmp_reason icmp_type, icmp_code
+        else
+          stats.add_tcp_flags trace.hop_tcp_flags(hop, response)
+        end
       end
 
       stats.hop_histogram[trace.path_length] += 1
-      stats.zero_dead += 1 if trace.stop_reason == 5 && trace.hop_count == 0
     end
   end