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.
