rb-wartslib 0.9.11 → 0.9.12

data/CHANGES

@@ -1,3 +1,9 @@
+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
+  * the previous each_attempt and each_hop_and_attempt methods are still
+    available as aliases, though deprecated
+
 version 0.9.11, 2007-11-29:
   * added more sample code to the 'bin' subdirectory
   * added GPLv2+ license header to sample code

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.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: extract-trace-addrs,v 1.2 2007/12/08 00:56:04 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -63,10 +63,10 @@ end
 def extract_addresses(trace, addresses)
   dest_response = trace.find_dest_response
 
-  trace.each_hop_and_attempt do |hop, attempt, exists|
+  trace.each_hop_and_response do |hop, response, exists|
     next unless exists
     break if dest_response && hop == dest_response[0]
-    addresses[trace.hop_addr(hop, attempt)] += 1
+    addresses[trace.hop_addr(hop, response)] += 1
   end
 
   addresses[trace.dst] += 1 if dest_response

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.12 2007/11/29 23:57:41 youngh Exp $
+## $Id: scdump,v 1.13 2007/12/08 00:43:19 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -64,7 +64,7 @@ def show_trace(trace)
   path_complete = "I"
   if dest_response
     hop = 0
-    trace.each do |hop, attempt, exists|
+    trace.each do |hop, response, exists|
       break if !exists || hop >= dest_response[0]
     end
     path_complete = "C" if hop == dest_response[0]
@@ -79,15 +79,15 @@ def show_trace(trace)
   trace.each_hop do |hop, exists|
     if exists
       hop_str = ""
-      trace.each_attempt(hop) do |attempt|
+      trace.each_response(hop) do |response|
 	# sc_analysis_dump compatibility
 	next if dest_response &&
-	  hop == dest_response[0] && attempt == dest_response[1]
+	  hop == dest_response[0] && response == dest_response[1]
 
 	hop_str << ";" unless hop_str.empty?
-	hop_str << trace.hop_addr(hop, attempt)
-	hop_str << "," << trace.hop_rtt_str(hop, attempt)
-	hop_str << "," << trace.hop_probe_id(hop, attempt).to_s
+	hop_str << trace.hop_addr(hop, response)
+	hop_str << "," << trace.hop_rtt_str(hop, response)
+	hop_str << "," << trace.hop_probe_id(hop, response).to_s
       end
 
       unless hop_str.empty?

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.1 2007/11/30 01:14:48 youngh Exp $
+## $Id: stat-traces,v 1.3 2007/12/08 00:56:04 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -28,14 +28,62 @@ require 'ostruct'
 require 'wartslib'
 
 class Stats
-  attr_accessor :traces, :responding, :complete, :stop_reason
+  attr_accessor :traces, :responding, :complete, :stop_reason, :icmp_reason
   attr_accessor :hop_histogram, :zero_dead
 
+  # Based on http://www.iana.org/assignments/icmp-parameters
+  ICMP_TYPE_NAMES = {
+    0 => "Echo Reply",
+    3 => "Dest Unreachable",
+    4 => "Source Quench",
+    5 => "Redirect",
+   11 => "Time Exceeded",
+   12 => "Parameter Problem"
+  }
+
+  ICMP_CODE_NAMES = Hash.new { |h,k| h[k] = {} }
+  ICMP_CODE_NAMES.merge!({
+    0 => {
+      0 => ""  # No Code
+    },
+    3 => {
+      0 => "Net Unreachable",
+      1 => "Host Unreachable",
+      2 => "Protocol Unreachable",
+      3 => "Port Unreachable",
+      4 => "Fragmentation Needed and DF Set",
+      5 => "Source Route Failed",
+      6 => "Destination Network Unknown",
+      7 => "Destination Host Unknown",
+      8 => "Source Host Isolated",
+      9 => "Admin Prohibited: Dest Network",
+     10 => "Admin Prohibited: Dest Host",
+     11 => "Dest Network Unreachable for TOS",
+     12 => "Dest Host Unreachable for TOS",
+     13 => "Administratively Prohibited",
+     14 => "Host Precedence Violation",
+     15 => "Precedence Cutoff in Effect"
+    },
+    4 => {
+      0 => ""  # No Code
+    },
+    11 => {
+      0 => "TTL Exceeded in Transit",
+      1 => "Fragment Reassembly Time Exceeded"
+    },
+    12 => {
+      0 => "Pointer Indicates the Error",
+      1 => "Missing a Required Option",
+      2 => "Bad Length"
+    }
+  })
+
   def initialize
     @traces = 0
     @responding = 0
     @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 = {
@@ -59,21 +107,45 @@ class Stats
     puts "%8d complete (%.1f%%)" % [@complete, pct(@complete, @traces)]
     puts "%8d dead traces with zero hop count (%.1f%%)" %
       [ @zero_dead, pct(@zero_dead, @traces) ]
+
     puts
-    stop_reason.to_a.sort.each do |k, v|
+    @stop_reason.to_a.sort.each do |k, v|
       puts "%8d stop reason %d, %s" % [v, k, @stop_text[k]]
     end
+
+    puts
+    @icmp_reason.to_a.map{ |k, v| [k >> 8, k & 0xFF, v] }.sort.each do |t, c, v|
+      type_name = ICMP_TYPE_NAMES[t]
+      code_name = ICMP_CODE_NAMES[t][c]
+      names = ""
+      if type_name
+        names = " (#{type_name}"
+        if code_name
+          names += ": #{code_name}" unless code_name == ""
+        else
+          names += ": ?"
+        end
+        names += ")"
+      end
+      puts "%8d icmp type %d, code %d%s" % [v, t, c, names]
+    end
+
     puts
     @hop_histogram.to_a.sort.each do |k, v|
       puts "%8d %d hops" % [v, k]
     end
   end
 
+  def add_icmp_reason(icmp_type, icmp_code)
+    @icmp_reason[icmp_type << 8 | icmp_code] += 1
+  end
+
   def add(other)
     @traces += other.traces
     @responding += other.responding
     @complete += other.complete
     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
@@ -97,6 +169,17 @@ ARGV.each do |path|
       stats.responding += 1 if trace.dest_responded?
       stats.complete += 1 if trace.complete?
       stats.stop_reason[trace.stop_reason] += 1
+
+      # XXX This doesn't work properly for TCP traces, because TCP traces with
+      #     stop reason == 1 (completed) have TCP flags but no ICMP type/code
+      #     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
+      end
+
       stats.hop_histogram[trace.path_length] += 1
       stats.zero_dead += 1 if trace.stop_reason == 5 && trace.hop_count == 0
     end

data/bin/wdump

@@ -25,7 +25,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: wdump,v 1.10 2007/11/29 23:57:24 youngh Exp $
+## $Id: wdump,v 1.11 2007/12/08 00:43:48 youngh Exp $
 #############################################################################
 
 require 'rubygems'
@@ -58,13 +58,13 @@ def show_trace(trace)
     show_attr trace, name
   end
 
-  trace.each do |hop, attempt, exists|
+  trace.each do |hop, response, exists|
     unless exists
-      puts "hop #{hop}, attempt 0: *"
+      puts "hop #{hop}, response 0: *"
       next
     end
 
-    puts "hop #{hop}, attempt #{attempt}"
+    puts "hop #{hop}, response #{response}"
     [
       :hop_addr,
       :hop_flags,
@@ -80,7 +80,7 @@ def show_trace(trace)
       :hop_rtt_usec
     ].each do |name|
       print "  "
-      show_attr trace, name, hop, attempt
+      show_attr trace, name, hop, response
     end
   end
 end

data/docs/gen-code-html

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+
+##############################################################################
+## Generate a web page showing Ruby scripts with syntax highlighting.
+##
+## $Id: gen-code-html,v 1.2 2007/12/04 22:57:31 youngh Exp $
+##############################################################################
+
+require 'rubygems'
+require 'ostruct'
+require 'optparse'
+
+require 'syntax/convertors/html'
+
+$options = OpenStruct.new
+
+opts = OptionParser.new
+opts.banner = "Usage: gen-code-html [options] <script> ..."
+
+opts.on("-s", "--snippet", TrueClass,
+        "generate HTML fragment for code snippet") do |v|
+  $options.snippet = v
+end
+
+begin
+  ARGV.replace opts.parse(*ARGV)
+rescue OptionParser::ParseError
+  $stderr.puts "ERROR: " + $!
+  $stderr.puts opts
+  exit 1
+end
+
+#===========================================================================
+
+ARGV.each do |path|
+  convertor = Syntax::Convertors::HTML.for_syntax "ruby"
+  html = convertor.convert(File.read(path))
+
+  if $options.snippet
+    html.sub!(/^<pre/, "<pre class=\"ruby snippet\"")
+  else
+    html.sub!(/^<pre/, "<pre class=\"ruby\"")
+  end
+
+  basename = File.basename path
+  out = File.open basename + ".html", "w"
+
+  unless $options.snippet
+    out.puts <<HEADER
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <title>rb-wartslib: Sample Script: #{basename}</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+  <link rel="stylesheet" type="text/css" href="layout.css">
+  <link rel="stylesheet" type="text/css" href="style.css">
+  <link rel="stylesheet" type="text/css" href="ruby.css">
+</head>
+
+<body class="twikiViewPage">
+
+<div class="twikiTopBar">
+<div class="twikiTopBarContents">
+<h1 class="pagetitle">rb-wartslib: Ruby Warts Library</h1>
+</div>
+</div>
+
+<a name="PageTop"></a>
+<div class="twikiMiddleContainer">
+<div class="twikiLeftBar">
+<div class="twikiLeftBarContents">
+<ul>
+<li> <a class="twikiLink" href="http://rb-wartslib.rubyforge.org/">Project Home Page</a></li>
+<li> <a class="twikiLink" href="http://rubyforge.org/projects/rb-wartslib/">RubyForge Page</a></li>
+</ul>
+<hr>
+<ul>
+<li> <a class="twikiLink" href="index.html#installation">Installation</a></li>
+<li> <a class="twikiLink" href="tutorial.html">Tutorial</a></li>
+<li> <a class="twikiLink" href="reference.html">Class Reference</a></li>
+<li> <a class="twikiLink" href="samples.html"><b>Sample Scripts</b></a></li>
+</ul>
+<hr>
+<ul>
+<li> <a class="twikiLink" href="index.html#contact">Contact</a></li>
+<li> <a class="twikiLink" href="index.html#license">License Note</a></li>
+</ul>
+</div></div></div>
+
+<div class="twikiMain">
+<div class="twikiTopic">
+<h1>Sample Script: #{basename}</h1>
+HEADER
+  end
+
+  out.puts html
+
+  unless $options.snippet
+    out.puts <<FOOTER
+<!---->
+</div></div>
+</body></html>
+FOOTER
+  end
+
+  out.close
+end

data/docs/gen-output-html

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+puts "<pre class=\"snippet\">"
+puts "<span class=\"shell_command\"></span>"
+$stdin.each do |line|
+  print "<span class=\"command_output\">", line.chomp!, "</span>", "\n"
+end
+puts "</pre>"
+

data/docs/gen-tut-html

@@ -0,0 +1,4 @@
+#!/bin/sh
+
+rm tut-*.rb.html
+./gen-code-html -s tut-*.rb

data/docs/index.html

@@ -0,0 +1,221 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html>
+<head>
+  <title>rb-wartslib: Ruby Warts Library</title>
+  <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+  <link rel="stylesheet" type="text/css" href="layout.css">
+  <link rel="stylesheet" type="text/css" href="style.css">
+</head>
+
+<body>
+
+<div class="twikiTopBar">
+<div class="twikiTopBarContents">
+<h1 class="pagetitle">rb-wartslib: Ruby Warts Library</h1>
+</div>
+</div>
+
+<a name="PageTop"></a>
+<div class="twikiLeftBar">
+<div class="twikiLeftBarContents">
+<ul>
+<li> <a href="index.html"><b>Project Home Page</b></a></li>
+<li> <a href="http://rubyforge.org/projects/rb-wartslib/">RubyForge Page</a></li>
+</ul>
+<hr>
+<ul>
+<li> <a href="#installation">Installation</a></li>
+<li> <a href="tutorial.html">Tutorial</a></li>
+<li> <a href="reference.html">Class Reference</a></li>
+<li> <a href="samples.html">Sample Scripts</a></li>
+</ul>
+<hr>
+<ul>
+<li> <a href="#contact">Contact</a></li>
+<li> <a href="#license">License</a></li>
+</ul>
+</div></div>
+
+<div class="twikiMain">
+<div class="twikiTopic">
+<h2>What is it?</h2>
+<p>
+<b>This is a Ruby extension for reading/writing warts files.</b>  Warts
+files are output by <a href="http://www.wand.net.nz/scamper/">scamper</a>,
+a tool for performing large-scale traceroute- and ping-based network
+measurements.  You can also use this extension to read (but not write)
+<a href="http://www.caida.org/tools/utilities/arts/">arts++</a> files
+produced by <a href="http://www.caida.org/tools/measurement/skitter/index.xml">skitter</a>.
+</p>
+
+<p>
+This extension only provides a thin wrapper around the C-language routines
+in <i>scamper</i> for reading/writing warts files.  But this is all you
+need to write pleasant little Ruby scripts that compute various statistics
+about collected traces, convert IP paths to AS paths, and perform myriad
+other processing for which, let's be honest, <b>life is too short to be
+writing in C</b>.  Write your analysis scripts with <i>rb-wartslib</i>, and
+with a Zen-like peace, spend your newly discovered free time with your
+friends, family, and your neglected small furry pet animals.
+</p>
+
+<h2>But Ruby is slow!</h2>
+
+<p>
+Yes, it is.  But it is also <b>fast enough.</b>  For example, some of the
+sample Ruby analysis scripts only take 1&frac12; to 2 times longer than an
+equivalent written in C/C++ because all the warts I/O is done in C code.
+If you're computing the hyperbolic Lagrangian bleibenvalues, then it might
+be a bit slow with Ruby, but what are computers for after all?  More
+importantly, it's much easier to write <b>correct</b> code with Ruby than
+C, and correctness is far more important than speed with data analysis.
+</p>
+
+<h2>Limitations</h2>
+
+<p>
+Although you can use this extension to write out trace data to warts files,
+you can't use this extension itself to create completely new traces in
+memory--that is, you can only write out traces you've read in from a file.
+Furthermore, any read-in data is immutable, with a few careful exceptions,
+because the principle purpose of this extension is to support the analysis
+of existing data rather than the creation of new data.  The ability to
+write out (unmodified) traces is still useful for filtering out traces and
+for re-organizing traces into a different set of files (for example, into
+daily files, or into separate files by the type of probing method used).
+</p>
+
+<h2><a name="installation"></a>Installation</h2>
+
+<p>
+If <i>rb-wartslib</i> were a typical Ruby Gem, you would install it with
+</p>
+
+<pre>
+  $ sudo gem install rb-wartslib
+</pre>
+
+<p>
+However, <i>rb-wartslib</i> must be compiled against the <i>scamper</i>
+source code so there are a few additional steps.
+</p>
+
+<p>
+First, download and build <i>scamper;</i> for example:
+</p>
+
+<pre>
+  $ wget http://www.wand.net.nz/scamper/scamper-cvs-20070523i.tar.gz
+  $ tar xvzf scamper-cvs-20070523i.tar.gz
+  $ cd scamper-cvs-20070523i
+  $ make -f Makefile.gnu     (if you're on Linux or MacOS X)
+  $ make                     (if you're on FreeBSD)
+</pre>
+
+<p>
+That will build <code>libscamperfile.a</code>, which is what <i>rb-wartslib</i>
+links against.
+</p>
+
+<p>
+Now build and install <i>rb-wartslib:</i>
+</p>
+
+<pre>
+  $ SCAMPER=/Users/youngh/scamper-cvs-20070523h
+     (set the above to the directory where you built scamper)
+  $ sudo gem install rb-wartslib -- --with-scamper-include=$SCAMPER
+       --with-scamper-lib=$SCAMPER
+</pre>
+
+<p>
+That's it.
+</p>
+
+<h2>Documentation</h2>
+
+<p>
+Start by reading the <a href="tutorial.html">tutorial</a>, which discusses
+fundamental concepts and covers most of the common uses.  Then look over
+the <a href="samples.html">sample analysis scripts</a>.  For a more
+in-depth documentation of the Ruby classes, see
+the <a href="reference.html">reference documentation</a>.
+</p>
+
+<p>
+The sample scripts are also included in the <code>bin</code> subdirectory
+of the <i>rb-wartslib</i> distribution file.  To find them on your system,
+execute the following after installing <i>rb-wartslib:</i>
+</p>
+
+<pre>
+  $ gem contents rb-wartslib
+  /opt/local/lib/ruby/gems/1.8/gems/rb-wartslib-0.9.11/bin/count-traces
+  /opt/local/lib/ruby/gems/1.8/gems/rb-wartslib-0.9.11/bin/create-aspath
+  /opt/local/lib/ruby/gems/1.8/gems/rb-wartslib-0.9.11/bin/extract-trace-addrs
+  ...
+</pre>
+
+
+<h2><a name="contact"></a>Contact</h2>
+
+<p>
+<i>rb-wartslib</i> is written and maintained by
+<a href="http://www.caida.org/~youngh/">Young Hyun</a> as a part of
+<a href="http://www.caida.org">CAIDA</a>'s work on
+the <a href="http://www.caida.org/projects/ark/"> Archipelago Measurement
+Infrastructure</a>.  You may contact him at <code>youngh AT
+rubyforge.org</code>, or use the tracker/forums at
+the <a href="http://rubyforge.org/projects/rb-wartslib/">RubyForge project
+page</a> for getting help.
+</p>
+
+<p>
+Please direct <i>scamper</i> questions, including problems building it,
+to <a href="http://www.wand.net.nz/personDetail.php?id=13">Matthew
+Luckie</a>:
+</p>
+
+<pre>
+   mjl (squigglyatthingie) wand (period) net (period) nz
+</pre>
+
+
+<h2><a name="license"></a>License</h2>
+
+<p>
+The <i>rb-wartslib</i> binding code is licensed under
+<a href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GPLv2</a>
+<b>or later</b>, but this binding must link with <i>scamper</i>, which is
+licensed under GPLv2 <b>only</b> (no later).  Therefore, when your own Ruby
+program makes calls into <i>rb-wartslib</i> (that is, "links"
+to <i>rb-wartslib</i>), then <i>rb-wartslib</i> is effectively under GPLv2
+<b>only</b>, so your client program must be GPLv2 compatible.  However, if
+you merely re-use any of the <i>rb-wartslib</i> source code in your own
+programs (but none of the <i>scamper</i> source code), then the license is
+GPLv2 <b>or later</b>.  For example, if you wish to use
+the <i>rb-wartslib</i> source code as a template for writing an extension
+of your own (that provides a binding to something else), then the code is
+licensed under GPLv2 or later.
+</p>
+
+<p>
+If you don't distribute your client program, then the requirements of the
+GPL do not apply to your client program.  In particular, if you write an
+internal tool used only in your organization, then it does <b>not</b> have
+to be released under the GPL to use <i>rb-wartslib</i>; it can have
+whatever license you choose.  This freedom is intentionally allowed by the
+GPL.
+</p>
+
+<h2>Acknowledgments</h2>
+
+<p>
+The design of these web pages draws on one of the styles used by the
+<a href="http://twiki.org/">TWiki</a> wiki tool.
+</p>
+
+
+<!---->
+</div></div>
+</body></html>