JROUTE README

Jroute is a fast and efficient Internet route-tracing tool based upon
traceroute but which uses TCP probe packets and parallel probing of
multiple target hosts. It may be used interactively for single traces, to
process batched targets, or as a server processing route-tracing 
requests from remote (telnet-connected) clients.

For stuff on jroute design see jroute.ps

*******************************************************************************
*******************************************************************************

DISCLAIMER

This tool was written in support of Internet topology work in progress, 
development stopped at an arbitrary point when the needs of that work were met.

Consequently there may be some bugs, no fitness for any particular purpose is 
claimed, and the code is emphatically not maintained.

In particular work on query contexts is incomplete, and they are therefore not 
included in the current build.

Most of this is written from memory (after 3 years) so if you find any patent 
nonsense please let me know.

*******************************************************************************
*******************************************************************************

BUILDING

Currently builds on RH 7.x Linux, build status on OSF/1 is unknown

*******************************************************************************
*******************************************************************************

USING IT

Try $jroute -h

Can be used in single-shot, multiple shot, batch, or server modes. Some 
examples are given below.

Meaning of various flags is explained below.

*******************************************************************************

SINGLE SHOT:

Needs root.
Allowable c.l.flags: -v -q -Q -m -f -r -o -g -I -S -b -B -h

	$ /somepath/jroute [flags] hostname[:port]

where:	hostname may be domain name or dotted decimal
	port defaults to 80

*******************************************************************************


MULTIPLE SHOT:

Needs root.
Allowable c.l.flags: -v -q -Q -m -f -o -g -I -S -b -B -h
"-" as final argument means use stdin as input

	$ /somepath/jroute [flags] -

then enter request lines of form LINE <CR> where:

LINE = [addr1+addr2+...+]host[:port][/f/m$label]
        where:  addrs form a list of loose source routed requirements
                f/m = min/max probe ttl to employ
                and optional label will be quoted with result
                lsr list, either/both of /f /m and label are optional
        if any option is not supplied the current default is used

flags "-vqQmfrbBh<CR>" may be entered at any point and will 
        act/set current defaults from that point
       	(if preceeded by a double "--" will take effect immediately)
Current defaults can be cleared by entering flag followed by "-"
        i.e. to set source routing from current point in input:
                "-raddr1+addr2+..."
        and to clear it:
                "-r-"

<CTL-D> exits when done

*******************************************************************************

BATCH MODE:

Needs root.
Allowable c.l.args: -v -q -Q -s -t -m -f -o -g -I -b -B -h

	$ /somepath/jroute [flags] /somepath/HOSTFILE

where HOSTFILE is a file of hosts to trace consisting of LINE(s) (possibly
interspersed with flags) as in multiple-shot mode.

NB. By default operates in quiet mode - output would otherwise be so 
interlaced as to be incomprehensible. If you want to see verbose output invoke 
it single-threaded (-t1).

See explanation of output format below. If you want to save output to a file use normal shell redirection.

*******************************************************************************

SERVER MODE - SERVER END:

If invoked with -X flag will expect input via stdin but filter it through a 
telnet input machine. Is not coded as a daemon so should be invoked via inetd.

Add the following to /etc/inetd.conf (or hack /etc/xinetd.conf and 
/etc/xinetd.d appropriately):

jroute  stream  tcp     nowait  root    /usr/sbin/tcpd  /usr/sbin/jroute -Q -
jroute-b stream tcp     nowait  root    /usr/sbin/tcpd  /usr/sbin/jroute -X -

and to /etc/services:

jroute          n/tcp        # jroute interactive route tracer server
jroute-b        p/tcp        # jroute batch server

where n/p are ports of your choice.

Don't forget $killall -HUP inetd to restart inetd correctly configured.

The first entry will establish an interactive server and the second a batch 
server.

*******************************************************************************

SERVER MODE - CLIENT END:

To use the server telnet server-host port, where port is for interactive or 
batch mode.

IT IS STRONGLY RECOMMENDED THAT YOU USE THE TELNET CLIENT "telnet.py" 
PROVIDED RATHER THAN THE SYSTEM TELNET.

	$telnet.py server port 

In interactive mode just use as if multiple-shot mode on local machine.

	$telnet.py server-name interactive-port

	<CTR-D> to exit
	

In batch mode send it a file of target hosts just as in local batch mode but 
using shell indirection.

	$telnet.py server-name batch-port <HOSTFILE [>RESULTFILE]

*******************************************************************************

CL or INPUT FLAGS

COMMAND LINE

-v(erboser) 
-q(uieter) 
-Q(uite like traceroute)	- but without the RTTs
-t(hreads)			- No of concurrent route-tracers
-m(ax-ttl) 
-f(irst-ttl) 
-r(oute)			- loose source route for single-shot mode 
-o(utput file) 
-s(ort) 			- sort output in batch mode
				  NB input stream must commence with a line 
				  "n addresses" giving the number of targets
-S(et src address)		- for multipley-homed hosts 
-I set interface 		- where ther's a choice
-g(ive up after n timeouts)	- don't try reachability tests etc. 
-b generate probes and replies at most nKb/s
-B generate src routed packets at most n/s 
-h(elp)

-v -q -Q have no effect in multi-threaded (default) batch mode - output would 
be uselessly garbled, or self-defeatingly slowed down. If you want these 
output forms in batch mode invoke with -t1 i.e. single-threaded.

INPUT FLAGS 

Any of -vqQmfrbBh<CR> may be inserted anywhere in the input stream when using 
multiple-shot, batch or interactive server modes and will act/set 
current defaults from that point (if preceeded by a double "--" will take 
effect immediately).
Current defaults can be cleared by entering flag followed by "-" 
	i.e. to set source routing from current point in input:
                "-raddr1+addr2+..."
        and to clear it:
                "-r-"

Limitations on -v -q -Q are as above i.e. will not take effect unless running 
single-threaded.

Any input line commencing with "#" is regarded as a comment and not processed.

*******************************************************************************

OUTPUT

All output is on std out/std error unless invoked with -o<FILENAME>.

-Q gives output nearest in appearance to traceroute - but without RTTs

-v gives a more comprehensive picture of activity (and is cumulative)

-q reverses effect of -v

"Standard" output (default in batch and multi-shot modes) consists of machine 
readable output lines - one per target host - with the following format:

	<target addr>: <hop addr1>|<hop addr2>| ..... |<hop addrN>|:<No.hops> \
		<Status code> $<optional label> !<outcome text1>

where <optional label> was assigned to an input line and <outcome text1> 
repeats as necessary to interpret <Status code> in human friendly form.

Output comment lines commence with "#", any input comment lines are output 
as comments un-modified.

*******************************************************************************

INTELLIGENT DRIVERS

While jroute works fine (I hope) for single or batched queries it was really designed as the route-tracing engine for an intelligent topology-investigating front end.

To this end it is envisaged that it would be invoked in batch or multi-shot 
modes with input/output redirected to an intelligent agent (either locally or 
as a remote client) generating queries, interpreting output, and synthesising 
further queries from it (eg investigating sub-trees of spanning trees by use 
of minimum/maximum probe TTLs and sorce routing). Using such an agent 
topological information could be built up by generation of spanning trees 
from various points in the network - using source routing - and superposition 
of such trees over their common nodes. 

Driving agents could be written with functionalities determined by the 
information required and limited only by the imagination of the writer. 
Python might be use by the sensible, and PERL or somesuch by the masochist.

*******************************************************************************

EXAMPLES:

Trace route to host x.x.x.x - traceroute-like output (single-shot mode)

	$ jroute -Q x.x.x.x

Ditto with "standard" output and probes directed towards port 1000

	$ jroute -qq x.x.x.x:1000

Ditto verbosely

	$ jroute -vv x.x.x.x

Start in multi-shot mode

	$ jroute -
then to find hops 4-8 to x.x.x.x
	  x.x.x.x/4/8 <CR>
then to find route via y.y.y.y
	  y.y.y.y+x.x.x.x <CR>

Start in multi-shot mode but with traceroute-like output 
(will be single-threaded)

	$ jroute -Q -
find route to x.x.x.x
	  x.x.x.x <CR>
do it again but verbosely
	  -v <CR>
	  x.x.x.x <CR>
do it again but with "standard" output
	  -q <CR>
	  x.x.x.x <CR>

Zap through a file of target addresses - default multi-threaded and "standard" 
output.

	$ jroute <target-file>

Ditto but slowly and verbosely 

	$ jroute -v <target-file>

Zap through a file of target addresses - save results in foo.routes.

	$ jroute -ofoo.routes <target-file>

Fire up server in interactive mode 

	$ telnet.py <SERVER ADDR> <INTERACTIVE PORT>
then enter targets and flags just as in multi-shot mode

Fire up server in batch mode - targets in foo.targets

	$ telnet.py <SERVER ADDR> <BATCH PORT> <foo.targets

Ditto but saving results in bar.routes

	$ telnet.py <SERVER ADDR> <BATCH PORT> <foo.targets >bar.routes


*******************************************************************************

I've tried to get this right (and comprehensible). Any errors or puzzles - 
please let me know.

James Hall

james.hall@cl.cam.ac.uk

November 2001
