TRgb TRACEROUTE Graphical Browser --------------------------------- This describes the system used for creating Tree-GRAPHS in traceanalysis The all needed software is held in TRgb.tar.gz file. How to Install this tracegraphs package ======================================= Step 1/ untar file: TRgb.tar.gz You will get following structure: bin cgi-bin samples lib "bin" contains all programs needed for running this application" lynx lynx.cfg pnets trana.pl "trana.pl" is most important program for this project. It makes analysis of traceroutes data and convert them into tree structure, The output is held in the structural file which is used in next step of processing for drawing tree-graphs. Real drawing is done by program "pnets". The lynx is used just for transportation data between WEB. Several version of "pnets" (graphical browser) in tis directory under different names. PNETS is C program written as part of the INCITE project (supported by DOE in frame of SCIDAC program in 2002-2004) to make visualization of tomographical measurements of uknown networks. PNETS versions are identical and they only differ by operating system and the graphical libraries. The oldest version "pnets and Spnets" using gd-1.3 library, It generates GIF pictures. (We don't recommend to use it.) Spnets is C program for Sun machines Ppnets is C program for LINUX machines using gd-2.0.1 version gd library (generates *.png pictures) SPpnets is C program for Sun machines using gd-1.8.4 version gd library (generates *.png pictures) cgi-bin directory containes 3 application examples: pnets.pl xnets.pl ampx.pl Each of them is cgi-bin type of program which drive the whole application. This program is a basic tool for man-machine interaction. It mmust be copied into real cgi-bin directory in WEB server tree. Remarks: Potential problems with Perl program can be caused by different versions of the interpreter and its location (usr/bin/perl) or (/usr/local/bin/perl). You also need library (libgd.so) for gd type application (gd is known graphic package). The version for using *.png and *.jpg pictures is quite complicated and it is not part of standard distribution of Linux. You must use your own library or create it from downloaded sources or you can used our version, which is libgd.so.2.0.0. It is located in dir lib. You must copy it into /usr/lib and make few symbolic links to it. ln -s /usr/lib/libgd.so.2.0.0 /usr/lib/libgd.so ln -s /usr/lib/libgd.so.2.0.0 /usr/lib/libgd.so.1.8 "samples" dir containes several important traceroute samples and the directory Data with the pictures, the color definitions and the network definitions. There are also the icons and pictures used in the application. Step 2/ Make configuration file for new site Look into sample configuration file in samples/sample.conf and make your own configuration file. It containes several variables: WEB_SERVER - webserver where application is running WEB_ROOT - where starts WEB Tree (directories as cgi-bin,htdocs,...) CGI_DIR - from which dir cgi program as started (usually cgi-bin) CGI_SCRIPT - cgi application script (ampx.pl pnets.pl etc.) PGM_NAME - name of graphical browser (Ppnets,PSpnets..) DATA_PATH - root data directory (usually /tmp) APPL_HOME Is directory where you installed this software For example: WEB_SERVER giga.oz.ch:8080 WEB_ROOT /home/trell/apache APPL_HOME /home/trell/package/util/jntg CGI_DIR cgi-bin CGI_SCRIPT xnets.pl PGM_NAME Ppnets DATA_PATH /tmp In this example we are using Linux machine as WEB server so Ppnets version of "pnets" is used. WEB is running on port 8080. Finally, save your configuration file somewhere. Step 3/ Copy pnets.pl into real cgi-bin directory and also copy there your configuration file Each application script has own configuration file. The pnets.pl must have name ".pnets.conf" located in same directory as application script. The configuration ifile is later copied to /tmp directory and used by other programs belong to this application. (Ppnets and trana.pl). If you have your own application, you can have your configuration anywhere. The fullname of the configuration file is last paramieter for Ppnet and trana.pl Usually it is cgi-bin so for this case the config file and applica5tion scripts are sitting in cgi-bin as it is shown in following lines: /home/trell/apache/cgi-bin/pnets.pl /home/trell/apache/cgi-bin/.pnets.conf Step 4/ In many cases you can run your application directly in the space which is directly accessible via WEB. In that case you just use the configuration variable "DATA_DIR" to setup this. In some other cases you must run your application in /tmp directory which is accessible by "nobody" for write". We are using this techniqueand so you must do more steps. You must relink relink directory /tmp to visible WEB SPACE. In examples there are used to application groups TOMO and XOMO. Subdirectory XOMO is always used for colors,networks and prepared examples. The data which are send to this server externally using usually subdirectory TOMO (as default). If somebody is using "pnets" (C program) directly from another application he/she can set up own subdirectory via "group" param (see calling pnets in next). If we are using apache server so relink whole /tmp or individual /tmp/XOMO and /tmp/TOMO into .../apache/htdocs ln -s /tmp /home/cottrell/apache/htdocs You should also clarify this relation between real data directory and WEB results idirectory in configuration file: In Linux case with apache it is simple: WEB_ROOT /home/ja/apache WEB_RESULT_DIR tmp DATA_PATH /tmp For cgi-wrap style used in SLAC www.slac.stanford.edu it is a little bit more complicated WEB_ROOT comp/net/bandwidth-tests/hercules WEB_RESULT_DIR comp/net/bandwidth-tests/hercules/tmp DATA_PATH /tmp (where comp/net/bandwidth-tests/hercules/ is alias WEB_ROOT) The examples of several configuration files are in directory: ../TRgb/samples Run applications ================ From your webrowser call folowing reference: A/ DEMO mode ------------- http://yourwebserver/cgi-bin/xnets.pl or http://yourwebserver/cgi-bin/ampx.pl You will get WEB page from which you can test if everything works well. Go to the field "Select example" and take some of these which are offered (ES,abilene,CAN,EEEE,.). Those examples are based on traceroute from SLAC to many destinations on ES- Esnet, on Abilene on EEEE-EastEurope.) Finally press "Give me MAP" button. You will get preprocessed map from your examples originally located in directory samples. You can manipulated with map if you click on target nodes. B/ Making your own traceroute map remotely ------------------------------------------ We expect that you are external user of "this-web" and via your browser you are on the page with the form: "Traceroute graphs". Assume, you have your traceroute data ready. If not, you must run traceroutes from one site (yours or what ever) to several other sites and to merge all this traceroute results into one file. Save this file into the place from we can remotely accessed it from you. (On "yourweb" to /tmp dir or into your ~/public_html dir.) Than go to the Input panel in this form and type there location where we can find this file (http://anyweb/yourdir/yourfile). We will read it processed it and create map that you will see in few seconds. You can manipulate with the map (zoom it, see different view, details of the path etc.) How to manipulate tree-graphs ----------------------------- You can click on the node and get new sub-tree. You can recurently repeat this proces and finally you can get quite readable tree-graphs. There is also option to see reverse path from target host to the source or to see so called RTT profile (graph with RTT times). Just click on target when you have reverse path on the screen. You can also use the "zooming gadget + -" for resizing pictures. See "manipulate.jpg" located at samples/Data/pictures dir for some hints. 3/ Using "PNETS" from other cgi-bin applications running on this web -------------------------------------------------------------------- In that case we expect that you will use your own group in /tmp directory and you will copy your traceroute filesi directly into /tmp/$group/Data under name which you select. The traceroute files must have appendix *.trace (Be carefull about access rights. You must know under which uid WEB is running.) Better way than call the pnets.pl directly and make file independently, is to call an application programs trana.pl and pnets from your own cgi-application and display only page that pnets generates as an entry point to this application. After accessing this page the pnets is called recurently with all internal params. Entry page is called ASENS_$filename-$ip.html. One typical application is using Group TOMO and filename tomo, so the page will be visible as hhtp://webserver/TOMO/ASENS_tomo-124.22.24.55.html The $ip address iof the user is used to avoid conflicts of manipulation of grapfs from two or more terminals How to use application programs: -------------------------------- ./trana.pl input_file output_file cfg_file ./trana.pl tomo.trace tomo /tmp/.pnets.conf` (All files needs absolute full pathes.) ./pnets grp filename gifW gifH ori target rsw2 rsw2c cfg_file example: ./pnets TOMO can 300 300 s 1 0 0 /tmp/.pnets.conf grp - application group (not unix group) as TOMO,XOMO,SLAC etc. filename - name of the structural file (output from trana23f.pl program) gifW - graph width gifH - graph height ori - orientation (s) target - target number (0-999), it is allocated during traceroute analysis rsw2 - magnifying mode (0,1..6) rsw2c - coloring mode (0,1..) cfgfile - configuration file How to upgrade Networks table: ------------------------------ The network file is simple: es 1 abilene 2 calren2 3 geant 4 .. New networks can be add to the end (You must know what "keyword to use" to match appearence in traceroute.) BUT !! If you extend network file, you must also extend rgb40.txt file. The rgb40.txt file has following structure: .... 255 250 205 LemonChiffon1 210 105 30 chocolate 233 150 122 DarkSalmon 255 235 205 BlanchedAlmond 230 230 250 lavender ... So add more color to the end Known problems: --------------- Symptoms: The pages are not updated according to your wish Somebody (system cleaning procedure) deleted /tmp/.pnets.conf file. 1/ You must recreate it (or copy it from somewhere). (Because ../cgi-bin/pnets.pl don't find the application programs). 2/ be sure that all your programs are located on WEB server Have a fun. *jn* SLAC August 25th, 2004