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 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" 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-" 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 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 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 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. -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: : || ..... ||: \ $ ! where was assigned to an input line and repeats as necessary to interpret 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 then to find route via y.y.y.y y.y.y.y+x.x.x.x 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 do it again but verbosely -v x.x.x.x do it again but with "standard" output -q x.x.x.x Zap through a file of target addresses - default multi-threaded and "standard" output. $ jroute Ditto but slowly and verbosely $ jroute -v Zap through a file of target addresses - save results in foo.routes. $ jroute -ofoo.routes Fire up server in interactive mode $ telnet.py then enter targets and flags just as in multi-shot mode Fire up server in batch mode - targets in foo.targets $ telnet.py 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