The files in this directory comprise the MIT LCS Network Map program. This is presently considered Beta release software. Since I expect there to be lots of frequent corrections etc., I would appreciate not having it indirectly redistributed. If additional people want it, please have them contact me for a full up-to-date release. Further, please send all information on your efforts to bring it up to the address "Magratheans@LCS.MIT.Edu" (as described at the end of this file) so that others may know of it and so that these corrections may make it into the master copy. This file describes briefly what the program is, what the various files are, and how to install and use it. It concludes with a description of the mailing lists related to this program. ---------------- What does it do? This program draws a map of network connectivity and allows interactive examination of information about various components including whether hosts can be reached over the network. Queries can be initiated by either point-and-click or by typed commands. The program can also be run on a non-graphics terminal for typed commands only. I use this program as the base for most of my personal (as opposed to automated) network monitoring and observation, both on my office workstation and from my home terminal via dialup. The program does not automatically determine a layout for a given network, these must be set up in Geometry files beforehand. Several sample Geometry files are provided to give a base for designing your own. Additionally, since the program supports moving from one Geometry to another, any files written for other networks should be contributed to the common pool. Eventually this could result in the ability to wander very widely in analyzing network problems. The program initializes itself from static data stored in the file system and therefore does not need to access the network in order to get running (unless the static files are network mounted, this is NOT recommended). For detailed information on what is and isn't supported yet, consult the Status file. MIT LCS Network Map program ReadMe file Page 2 ---------------- What are all these files? The files are roughly grouped by which term of the "make release" they fall under. See the Makefile for these. The files shown as SUPPORT (generally having names that start with a capital letter) are divided into three classes, documentation, control files (for building) and data files (for operation). There is an intent to make them unique in the first letter (where convenient) for ease in completion. The documentation files describe the program and also track progress in the development. This file (ReadMe) is one, it has what you see. Intro is a short (one-page) excerpt from this for general mailings. The Status file describes what the current status is, what is supported and major restrictions, this is fairly general. Update is a reverse chronological list of changes for ease in comparing to older versions. The ToDo file contains a list of things that I think should be done to/for the program (the format is designed for parsing with another program I wrote), this is much more detailed than the Status file. The Copyright file is self-explanatory. Among the control files are those that control building the program (Makefile and Makefile.in) and those that control its operation (map.*, *.Geometry and Hosts). The various Geometry files are those contributed by various users (presently only me, please make your own contributions) and can be used as examples for trying out the program and for writing your own Geometry. The Hosts file is the data about all hosts to be known to the program. This is a HUGE file, containing any info available on any hosts that I thought might be of interest. The file is in extended RFC952 format (same as the NIC HOSTS.TXT file, in fact you may notice that as a part of this file), extended to allow non-IP addresses. The file map.cf is read by the program when it starts up, it might be customized for particular sites, but see below about user customization. Finally, map.PS.header is the preamble used on PostScript files. The HDRS files are common definitional files and include the CONFIGS which describe the option selection for building (vide infra). The files shown in the Makefile as NETSRC are a set of common support files used by several of the network utilities I have written. There are copies in the distribution, on the master copy they are really just links off to a library directory. The files shown as SRC are the main sources for the program. map.c is the top level of the program and all the common routines. X10.c and X11.c are the X interface. cmd.c is the command line parser, I have a fancier one in preparation. ps.c and tek.c are the drivers for hardcopy. snmp.c is the interface to the MIT SNMP Development Kit. MIT LCS Network Map program ReadMe file Page 3 ---------------- Building the program. To build the program without SNMP you should just need to put this all in a directory and type "make". This will run a short configuration dialog to set up the config file and then build the program. The configuration procedure and options are described in more detail below, but the script should be self-explanatory. If you want SNMP support you will additionally need a copy of the MIT SNMP Development Kit. I keep the Map program and the SNMP Kit in two side by side directories (called map and snmpdk). The config script reflects this layout, and defaults SNMP support on if "../snmpdk" is a directory and off otherwise. If you do it this same way, you can just default the option from the script. If you don't already have the SNMP DK, there is a copy of the distribution in the same directory with the rest of the files for your convenience. After you retrieve the SNMPDK you should build it by typing "make depend" and then "make" in its top level directory. After you've done this, you can then build Map by typing "make" here. The program needs privileges to access the ICMP socket (if it is going to do pinging of hosts, without privileges it will print a brief warning at start up, all other operations will work fine). This can either be done by running it as root (not recommended), or making it suid to root. The later can be done by su and "make priv". The program opens the ICMP socket immediately on startup and then turns off the temporary privileges to avoid any security holes. ---------------- Configuring the program. The program is configured with the shell script "config". It walks you through a short series of questions and generates a config file for use in building. The first thing the script does is to determine a name to use for this configuration. The build procedures support multiple configurations and switching between them. This name is used to identify the set of answers you give, it is actually used as part of a file name and is case sensitive. If you later wish to change an option, you can rerun the shell script which will recognize the name and read the original config file to set the defaults for all questions. The next options have to do with the display. At the present time the only window system supported is X and that is required. There is an interface for both X10 and X11 although the X10 hasn't been tested for several releases and probably needs a few additions to work. If anybody actually has an X10 machine still around, I'd be glad to help them get this up. X10 support is scheduled to be classified "archaic" starting with V6.0 and will no longer be included in the standard release or available in the config script. Next it asks about what types of hardcopy you wish to support. The program can write files in either of two formats for printing. Standard PostScript is supported, but I haven't had access to a color printer until recently so only black and white is supported. Color output can be generated for Tektronix 4317 printers. The default is to include support for writing PostScript, but not Tektronix files. The next question is about SNMP support. For SNMP the MIT SNMP Development Kit (from someone else at MIT) is needed. See the paragraph above for more details. The next question is the toughy. Between versions 4.2 and 4.3 of Berkeley UNIX the details of raw IP sockets changed, the difference being whether packets were returned with the IP header or just the data. The build procedure is set up with several ways to try and default this right, but you may have to force it to get pinging to work. I'm not sure how you really determine which way it is on your system, the things I know about are coded in the standard procedures so I suggest trying the offered default to start with. If pinging doesn't work try re-running "config" and changing your answer on this question. Someday I'll get around to making the program figure it out. I believe this is possible, but somewhat tricky. It then asks about Chaos protocol support. If you don't know you have it, then you almost certainly DON'T have it. "Just say No." It will ask for a short comment to be included in the config file (in case you have trouble remembering why you built several :-). This is just used in a comment and is any text you want (except empty :-). The new config file is then written. If you already have a default config set up, you are asked if you want to replace it with this one. If you don't it goes ahead and does it. ---------------- Installing the program. The program references a bunch of data files which are normally searched for with the fixed search sequence ".", "./nets", and "/usr/lib/nets". If you are setting up for all users of a machine to use the program, I suggest that you either make a directory "/usr/lib/nets", or install there a link to where the "released" versions are kept. Then the "make install" command can be used copy the needed files out of the build directory to there. If you are only building it for yourself, you can just put everything in a "nets" directory (or use a soft-link) in your home directory. If you use the program much, you'll probably be running it from your login (or xsession) or put it on a window manager menu, these will find it relative to your homedir. You will probably also want to make a soft link from Geometry to whatever Geometry file you want to be the default. You may also want to put a soft link to the executable (or a copy of it) in /usr/local or some suitable place on your search path. One advantage to this scheme is that the directory all these files live in can be owned by the person maintaining the program and data files and you don't have to worry about "su" (except for making the executable suid root). You may want to read through the sections below on running and customizing to get some idea about what's going on before you do the actual installation. MIT LCS Network Map program ReadMe file Page 5 ---------------- Running the program. When the program starts up, it reads commands from a file "map.cf". A different name for the initial command file can be specified on the command line. The one in the release reads in the default host and geometry files. Normally these default to Hosts and Geometry, but the names can be changed with the -H and -G options respectively. The program prints out reports to the standard output, thus it is usually best to run it from an xterm used to display this info. I usually use a command like: xterm -geometry 111x20+2+555 -fn 6x10 -e map =+2+23 & to run it (but see below in customization). Path ---- All files are searched for using the same path. For now this is compiled in. It looks first in the current directory. Then it looks in the subdirectory nets. [I wanted to include ~ and ~/nets, but haven't gotten around to adding the "~" code to the appropriate routine. Since I usually run it out of my window manager menu or from some startup script it's in my home dir anyway.] Then finally it looks in the directory /usr/lib/nets. I wrote and maintain several utilities that share the /usr/lib/nets directory and on my system this directory contains the "released" versions, while the work versions are in a seperate location. If you want to maintain a general use version this directory should contain the program and data files or be a link to where they actually are. Geometry -------- Several (i.e. 4) example Geometry files have been provided. You will most likely want to make one of your network, you should send this in (to Map-Makers@Gaak.LCS.MIT.Edu) so that it can be integrated. There is a way to wander from map to map and having many maps, each supported by the appropriate organization, would be really useful. You should make a link (I prefer soft) from Geometry to the one you want to be the initial display (remember, users can override this with a command line argument). Hosts ----- The Hosts file should be in NIC host table format (RFC952) and include any hosts that you may wish to watch with this tool. A copy with all the NIC hosts, plus essentially all of MIT, NEARnet, and JvNCnet as of the release date is included. A more up-to-date copy can be FTP'd from the same directory as the distribution. The data changes daily but the copy in the release corresponds to the given Geometry files. Help ---- There is no written documentation on the command line arguments, the best source of such info might be to type "map -h" and read the usage string (or find it in the source). Once the program is running the "Help" command can be used for on-line help with commands. MIT LCS Network Map program ReadMe file Page 6 ---------------- User customization Like any good X program (although not as much as some), in fact any good program, there are lots of user customizations. The first is in the map.cf file itself. If you have put the standard distribution in /usr/lib/nets (or made a link) then individual users may set up their own map.cf to override this. In fact I have a map.cf file in my standard home directory which says: ; This is my own map.cf file -MAP ; I do this to set some debug flags by default Debug File Debug Connect Take /usr/lib/nets/map.cf Which you'll notice sets two flags I normally want on and then runs the standard setup. Since I haven't gotten around to making the search path code deal with ~ or environment variables, this file has to be in the directory the program is run from or a subdirectory named nets. Since I usually run it from a menu in my window manager, it always runs with the default directory being my home directory. There are also a large number of customizations available for X, most notably in colors to be used. Basically when a media or protocol is to be displayed, the string naming it is first checked for being a color already (as an aid in testing mostly) and then looked up in the X resources data base (see xrdb). If this translation returns a working color, that is used. Otherwise the next color from the built in list of fall-back colors is tried, and ultimately the foreground color of the window. To try and help out with all the customization available, here are some of the ways I set up. First is the relevant section from my X resource setup: #ifdef COLOR map*Background: Turquoise map*Foreground: Black map*Highlight: White map*Pronet: Blue map*uWave: Blue map*Phone: LightGray map*Ethernet: Yellow map*Chaosnet: Orange map*DTE: Orange map*T1: Orange map*Apollo: Red map*CAN: Red map*WAN: DimGray map*CATV: Black map*56Kb: Navy map*CHAOS: Khaki map*IP: Goldenrod #endif Then there is the line I use to run it from a menu in my .uwmrc file: "Network Map": (Blue:White) :!"xterm -geometry 111x20+2+555 -fn 6x10 -n 'nets I/O' -bg turquoise -fg Black -bd Black -e map =+2+23&" the command on the end could be used to start it direct from a shell (with or without it's own xterm). MIT LCS Network Map program ReadMe file Page 7 ---------------- Mailing lists There are several mailing lists associated with the map program and contributions are encouraged. Especially of value is people who want to support it in various different environments to shake out any portability problems. At this time the mailing lists are strict subsets of one another. [In fact, right now, only one is really active, the multiple lists were set up to support more people]. Here is a description of them starting from the most inclusive and going to the more exclusive. All have a primary name that starts Map- and at least one one word alias. All names have associated -Request addresses for addition/change/deletion requests, there is also a general Map-Request for administrivia spanning more than one list. Map-Users (aliases Travelers, Explorers) People who use the program to observe/monitor/explore networks using maps already prepared, just using the features of the program through its user interface. Map-Makers (alias Cartographers) People who design and write map Geometry files. Map-Builders (alias Magratheans) People who hack the code. Map-Bugs (alias Bug-Map) The original author :-), anybody else who wants to respond to problem reports.