This is a Ruby extension for reading/writing warts files. Warts files are output by scamper, a tool for performing large-scale traceroute- and ping-based network measurements. You can also use this extension to read (but not write) arts++ files produced by skitter.
This extension only provides a thin wrapper around the C-language routines in scamper 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, life is too short to be writing in C. Write your analysis scripts with rb-wartslib, and with a Zen-like peace, spend your newly discovered free time with your friends, family, and your neglected small furry pet animals.
Yes, it is. But it is also fast enough. For example, some of the sample Ruby analysis scripts only take 1½ 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 correct code with Ruby than C, and correctness is far more important than speed with data analysis.
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 principal 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).
You don't have to download anything manually to
install rb-wartslib, because the gem file is already available
on the online RubyGems repository. Installation is, therefore, a
simple matter of executing RubyGem's gem command on your
system.
If rb-wartslib were a typical Ruby Gem, you would install it with
$ sudo gem install rb-wartslib
However, rb-wartslib must be compiled against the scamper source code so there are a few additional steps.
First, download and build scamper; for example:
$ 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)
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 absolute directory where you built scamper)
$ sudo gem install rb-wartslib -- --with-scamper-include=$SCAMPER
--with-scamper-lib=$SCAMPER
That's it.
Start by reading the tutorial, which discusses fundamental concepts and covers most of the common uses. Then look over the sample analysis scripts. For a more in-depth documentation of the Ruby classes, see the reference documentation.
The sample scripts are also included in the bin subdirectory
of the rb-wartslib distribution file. To find them on your system,
execute the following after installing rb-wartslib:
$ 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 ...
rb-wartslib is written and maintained by
Young Hyun as a part of
CAIDA's work on
the Archipelago Measurement
Infrastructure. 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:
mjl (squigglyatthingie) wand (period) net (period) nz
The rb-wartslib binding code is licensed under GPLv2 or later, but this binding must link with scamper, which is licensed under GPLv2 only (no later). Therefore, when your own Ruby program makes calls into rb-wartslib (that is, "links" to rb-wartslib), then rb-wartslib is effectively under GPLv2 only, so your client program must be GPLv2 compatible. However, if you merely re-use any of the rb-wartslib source code in your own programs (but none of the scamper source code), then the license is GPLv2 or later. For example, if you wish to use the rb-wartslib 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.
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 not have to be released under the GPL to use rb-wartslib; it can have whatever license you choose. This freedom is intentionally allowed by the GPL.
The design of these web pages draws on one of the styles used by the TWiki wiki tool.