Web Traceroute Package README file

This software is copyright (C) 1998 Owen DeLong.  It is licensed to
anyone for any non-commercial use.  You may modify it.  If you wish
to publish the modifications subject to the same license restrictions,
you are welcome to do so.  All modified versions must contain a README
which must include this note in it's entirety.  You may further distribute
it without modification.  If you wish to use it for commercial purposes
or derive a commercial product from it, please contact owen@delong.com
to negotiate an appropriate license.

In summary:  Enjoy this package, I hope you find it useful.  If you want
to make a profit using work that went into this package, I'd probably at
least like to know about it or get some of it.

The package consists of several files as follows:

traceroute.cgi		Script which simply redirects to nph-traceroute.cgi
nph-traceroute.cgi	The script which calls traceroute and traceroute-parse
			and puts the form up for the user to see.  It also
			handles all the HTML/HTTP protocol overhead that is
			not handled by the server.
			I think the HTTP/HTML stuff is correct.  If you don't,
			I'd like to hear from you, you probably know more
			about this than I do.  owen@delong.com
traceroute-parse	PERL script (tested 5.0) which parses the traceroute
			ouptut and produces some of the HTML presented to the
			user.  Namely, it draws the pretty pictures and
			makes nice with the formatting, etc.  There may be
			better ways to do this.  However, the choice not
			to use HTML tables was deliberate.  See below.

bar.gif			Small image files which are solid blobs of
cbar.gif		red, cyan, and white, respectively.  These blobs
wbar.gif		are stretched/squished by the output of the parser
			to form appropriate bar-graphs.  wbar is used to
			take up the space not occupied by the other two.

It does _NOT_ contain the traceroute binary or source.  I recommend
the traceroute verions 1.4a5 (ftp://ftp.ee.lbl.gov/traceroute.tar.Z),
which is newer than what's currently in use on the page, but will
work with this page.

Any traceroute should work as long as it supports the following:
	-g, -n, -w
	n.ddd ms times on the probe returns (as opposed to nn ms).
	Yes, the decimal point and three places to the right _ARE_
		important.  Not for accuracy, but so the parser knows
		what it's looking at.  (If you don't get this, read
		the code in traceroute-parse.  You'll understand.
		No, it's not pretty.)

Why did I do it this way or "THEORY OF OPERATION"

OK, so, here's this thing that produces HTML.  Some things about the
HTML it produces and why:

It's readable.  I find it alot easier to debug a code generating script
if the script produces readable code.  Sure, it costs a few extra octets
of runtime bandwidth, but in the grand scheme of things, I've got alot
more network bandwidth than patience for reading and deciphering illegible
gobbledygook to debug stuff.  Since I'm constantly tinkering with things,
and adding/fixing/changing stuff, I keep it readable, and don't optomize
down to the last extra white space being removed.

Most of the form stuff and the raw text comes directly from the
shell script nph-traceroute.cgi.  Why nph-?  Well, nph- at the
beginning of the name stands for "No Parse Headers."  While I'm
not going to pretend to completely understand what that really
means, the bottom line is that it made the difference between
whether Netscape rendered the traceroute data as it came out of
the script or waited for the entire document to be transmitted,
then rendered it all at once.

The Traceroute output (and the graphics) is all pretty-formated
using two very basic techniques which both probably make web
purists cringe like I took fingernails to a chalkboard.  Those
techniques are:

	<PRE>
	<IMG ... WIDTH=x HEIGHT=y>

<PRE>
I use PRE because it specifies not only that the browser will render the
text exactly as it's formatted, but also will use a fixed width font.
Sure, I could have accomplished what I was after using a proportional
font and tables, but there's a good reason not to do this.  See below.

<IMG... WIDTH=x HEIGHT=y>
If you know a better way to do this, I'm open to it, but the way I see
it, the GIF's I send to the client (once each) are 39 octets each, there
are exactly 3 of them, and if the browser has half a brain, it loads 'em
out of cache after the first line of the first trace.  ALL of them!  That
means I send a total of 117 octets+overhead to the client for all the
graphics on the entire page.  Since that's better than most home pages,
I haven't focused a lot of attention on finding a better way.

The output doesn't use tables.  That's right.  I know in today's world,
Frames and Tables seem to be how everyone does everything, but I really
don't think they have anything to offer here.  More importantly, tables
come with one very bad side effect.  Until the table is complete, nothing
in the table gets rendered.  As such, using <PRE> works better for this
application.  If you've got a better idea, bring it on.

There are a few embedded full- and partial- path names that you may
want to change or clean out.  That's one of the things on the round
tu-it list.

They're easy to find... Look for '/'.  Not much with / in it that isn't
a pathname (or an HTML end).  Here's what I found on a quick cursory
look:
nph-traceroute.cgi:2:TRACEROUTE=/home/www/delong.com/cgi/traceroute
nph-traceroute.cgi:3:PARSER=/home/www/delong.com/cgi/traceroute-parse
nph-traceroute.cgi:82:<FORM ACTION="/cgi-bin/nph-traceroute.cgi" METHOD=SUBMIT>
traceroute-parse:123:	    printf("<IMG SRC=\042/bar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute-parse:127:	    printf("<IMG SRC=\042/wbar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute-parse:142:	    printf("<IMG SRC=\042/bar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute-parse:144:	    printf("<IMG SRC=\042/wbar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute-parse:147:	    printf("<IMG SRC=\042/wbar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute-parse:149:	    printf("<IMG SRC=\042/cbar.gif\042 WIDTH=%d HEIGHT=%d>",
traceroute.cgi:11:<META  HTTP-EQUIV="REFRESH" CONTENT="0; URL=/cgi-bin/nph-traceroute.cgi">


There are, of course, the #! lines at the beginning of each script, as well.

Good luck, let me know how it goes.

Owen
owen@delong.com
