======================================================================
                    I N S T A L L 
                    doc: Fri Mar  6 15:32:06 1992
                    dlm: Fri Jul  3 13:52:57 1992
                    (c) 1992 ant@sitter
                    uE-Info: 310 53 T 0 0 72 3 2 8 ofnI
======================================================================

I. Compilation
==============
In order to compile inetray on your machines you first need to edit a
couple of files.

prognum.h: Usually you should not need to edit this file!
	   In this file, the program numbers for the RPC-servers are
	   stored. Note that you should only edit this file if some of
	   the program numbers are already in use on your machine. Note
	   also, that if you edit this file, you have to run rpcgen
	   again to generate a number of source files (to do this, just
	   ``make rpcgen''). 
	   Note that if you want to have n servers running on one
	   machine, they take the program numbers IRNUM to IRNUM+n-1.

config.h: Very probably you would change here only the RESULTPORT
	  definition. Find a free port on the machines you want to run
	  the dispatcher (inetray) from and enter its number.
	  You might also want to change the timeout values (all in
	  seconds) and/or the nice value for the workers. On slow
	  machines you'll probably have to change the following timeouts:
	  	RTIMEOUT:   time to wait for the next machine to register
	  	CHKCLNT:    time between checks for inetray
	  	STARTDELAY: time to give inetray.start to start servers
	  The default settings in config.h will, however, probably work
	  on many machines.

Makefile: Now you need to edit the Makefile. Note that you'll only have
	  to change stuff in the Tweakables section of the Makefile.
	  Most of the things you must define here you can extract from
	  the Makefiles of rayshade.

	  CCFLAGS  : c compiler flags such as optimization, ...
	  LIBSHADE : complete path of the libshade.a library
	  INCSHADE : directory where the libshade includes reside
	  	     Note: -I must be specified
	  LIBRAY   : complete path of the libray.a library
	  INCRAY   : directories where the libshade includes reside
	  	     Note: this usually includes the rayshade main dir
	  LIBURT   : complete path of the librle.a library
	  INCURT   : directory where the liburt includes reside
	  LIBRPC   : library where the SUN-RPC and XDR routines are to be
	  	     found. If you don't know where you should probably
		     grep for xdr_int in /usr/lib or wherever your
		     libraries may be.
	  INCRPC   : If you compile Inetray with a non-default LIBRPC
		     (i.e. one you compiled yourself), you'll 
		     need a non-default set of h-files to include
		     (matching version).
		     !!! NOTE: YOU NEED TO SET incrpc TO THE PARENT
		         DIRECTORY OF THE DIRECTORY WHERE THE H-FILES
	 		 ACTUALLY ARE LOCATED !!!
 		     Note that with the current version you also need to 
		     define a var here which defines the wordlength of
		     your machine. See SUPPORT for values for specific
		     machines.
	  LIBDRAND : If you have to compile rayshade with a drand
		     library, you should also define it here.
	  SPAIR    : On most machines this should be empty. On A/UX,
	  	     however, the built in socketpair() does not seem to
		     work. If you compiled it and get socketpair()
 		     errors, try to add socketpair.o here.
	  INSTDIR  : directory to install the executables to
	  INSTUSER : user to install the executables under
	  INSTGROUP: group to install ...
	  INSTMODE : mode to install ...
	  QUIRKS   : I tried to avoid that, but there seem to be
		     operating systems quirks around which have to be
		     taken care of. The only quirk available -s
 		     D_AUX_QUIRK which makes inetray.start not
		     disaccociate from its tty so that the stderr to
		     syslog redirection works.

	  Now you should be able to compile inetray. A short description
	  of the available target follows:

	  all:	    compiles everything (default target)
	  server:   compiles only rpc.inetrayd, inetray.start, inetray.relay
	  client:   compiles only inetray, inetray.kill, inetray.ping,
	            rpc.dereg
	  rpcgen:   runs rpcgen to remake some source files. Note that
		    you must run this if you changed prognum.h or any .x
		    file. Note also that not every rpcgen has all the
		    options to work correctly; older ones usually lack
		    the -I option.
	  install:  installs the executables. Usually you should be root
	  	    to do that.
	  bak:	    makes a bak directory and opies everything important
	  	    there
	  old:	    makes a copy of the old version (for patch)
	  tar:	    makes the distribution tar
	  ftp:	    installs it to public ftp
	  patch:    makes and checks a patch (patchX)
	  Patch:    same, but includes Makefile in patchX
	  clean:    cleans temp compilation files & executables
	  spotless: cleans all executables and rpcgen generated files.

	  Additionally there is a target for every executable.
	  Furthermore, there is a rule for making .rle from .ray files.

First Test
----------
To run the first test it is assumed that you successfully compiled the
following executables: inetray.start inetray.ping rpc.inetrayd. They
should reside in the current directory.

% inetray.start rpc.inetrayd

After that you should have an entry for the inetray.start in the map
handled by your local portmapper. You can check that with the rpcinfo
command.

% inetray.ping

This should give you a list of answering machines after a few seconds. 
If your machine answered, everything's fine and you can continue your
installation.
NOTE: If you get something like ``Pinging... [startSegmentation fault''
      then you've very probably got an old version of RPC (where you
      cannot give a NULL pointer as the function to call on
      clnt_broadcast()). Compile at least version 4.0 and retry!

II. Installation
================

Basic Installation
------------------
The basic installation is extremely simple: you just start up one
inetray.start on every machine you want to have servers running. It
takes one parameter, the full path of rpc.inetrayd. If you can, you
should start it as root, since then the workers will run under the same
user id as the dispatcher. Note that inetray and inetray.ping give back
the username as who the servers are running.
Note that there are a number of cases where the basic installation does
not work and/or is not sufficient. These cases are described below.

~/.inetrayrc
------------
Most advanced installations requires the user to have a .inetrayrc in
the current directory or in his home. This file is kept user-local since
not every user might have access to the same machines.
An exact description of the syntax of this file is given in Appendix B.

Using a single Machine not on the local network
-----------------------------------------------
To do this you add the following line to your .inetrayrc file:
	``use: <machinename>''
If you want to find out what machines are on your local network you
should issue a ping command with the broadcast address of your local
network (usually, if your machine has the number a.b.c.d, the broadcast
address is a.b.c.0). You may have to specify an option for ping to be
able to do so (i.e. on SUNOS you have to write ``ping -s a.b.c.0'').
Note: usually, you supply another user id under which you want the
      workers to run on the remote machine. To do this you add the
      Option UID=<number> (see below).

Using many machines on one remote local network
-----------------------------------------------
A remote local network is a lokal network to which the machine you are
starting inetray from is not directly connected. To add such a network
you add the following line to your .inetrayrc file:
	``use: <directed broadcast address>''
To find out the directed broadcast address(es) of a machine, run
netinfo (supplied with inetray). Any broadcast address returned by
netinfo should work if everything is installed correctly. Note that if
a machine listens to 2 different broadcast and/or local addresses (i.e.
has 2 interfaces), it is a gateway. 
Note: usually, you supply another user id under which you want the
      workers to run on the remote machines. To do this you add the
      Option UID=<number> (see below).

Running Multiple Workers on a Machine (Network)
-----------------------------------------------
To do this, you just add the option N=<Number> to your Use List-Entry.
Example:
	``use: multiHost N=16, myHost''
This line makes inetray start 16 workers on host ``multiHost'' but only
one worker on ``myHost''. You can also supply the option to a network
entry (if you are lucky enough to have a network full of machines with
more than one processor).
Note: The above line even works if multiHost is on the local network
      since parameters for single machines precede the ones for whole
      networks.

Running workers under a different uid on a Machine (Network)
------------------------------------------------------------
To do this, you just add the option UID=<number> to your Use List-Entry.
Note that this only has any effect if inetray.start was started as root
(or you used the inetd-installation described below).

Excluding the Local Network
---------------------------
Sometimes it may be advisable not to use any machines on the local
network. To do this, you just add
	``use: local N=0''
to your .inetrayrc. Note that local is a reserved word, no machine must
be called ``local''. You can also have something like
	``use: local UID=56''
if you want all inetray workers run under a special user id on the local
network. 

Installing Servers with Inetd
-----------------------------
This is very simple but you must be root to do it. If you do it you
won't have to have an inetray.start running on the machine. You also
won't be able to have multiple workers running on that machine. On the
machines, you want to install inetray like that you add the following
line to inetd.conf:
  ``555555555/1 dgram rpc/udp wait root <path>/rpc.inetrayd rpc.inetrayd''

  
III. Example Installation
=========================
This is (more or less) the actual installation on which inetray was
developped. First follows the description of the basic installation
(accessible by all users with accounts on the machines mentioned below).

Local Network:
	SUN4s:	sitter, julia, orinoco, tiber, yukon
	SUN3s:	various
	SGIs:	plessur (2 processors), saane, glatt
Notes:
	- The SUN3s should not be used for traceing due to the huge
	  difference in speed
	- yukon usually heavily loaded and should not be used
	- All machines know the same users and have (mostly) the same
	  filesystems mounted

Server Installation:
	- On all machines except plessur inetd.conf has been changed to
	  start	rpc.inetrayd by inetd.
	- plessur needs to have an inetray.start running to allow 2
	  server to be running there. (inetray.start is started at
	  boottime as root).

~/.inetrayrc:
	ignore: yukon
	use: plessur N=2

There is a user, let's call him ant (uid 819), who has a number of
accounts on different machines. He has no root access on any of these
machines. His specific installation follows:

Accounts:
	bernina (4 processor DECstation)	uid = 1211
	kyu1	(MAC II running A/UX)		uid = 1011
	c11-c99	(SUN3s on another local net)	uid = 1980

Server Installation:
	- On all machines he executes ``inetray.start rpc.inetrayd''

~/.inetrayrc (on the local network):
	ignore: yukon
	use: plessur N=2
	use: bernina N=4 UID=1211
	use: 129.132.13.0 UID=1980, kyu1 UID=1011

~/.inetrayrc (on bernina):
	ignore: yukon
	use: local N=4                                               
	use: 129.132.13.0 UID=1980, kyu1 UID=1001
	use: 129.132.17.0 UID=819, plessur N=2 UID=819

Notes:
	- The machine c13 has inet# 129.132.17.33, therefore the directed
	  broadcast address for the c?? machines is 129.132.13.0
	- Although kyu1 is really on the same local network as the c??
	  machines, its parameters take precedence 
	- Actually, the userids in ~/.inetrayrc are not really necessary
	  since the programs will run under that user anyway. Note,
	  however that it is a good idea always to supply the user id
	  for clarity
	- Since the filesystems are different on those machines, the
	  .ray files have to be transferred before traceing. User ant
	  usually have a directory ~/trabajo/inetray on all machines

Appendix A: Compiling librpclib.a (4.0)
=======================================
On some machines, there are only old/partial implementations of the SUN
RPC library (librpclib.a) e.g. Apple (AUX), DECstations (Ultrix 4.0). On
these machines, librpclib.a has to be compiled. On all machines I've
been doing that I had very few problems.
The only tricky part is the XDR implementation for machines with a
different representation of floats/doubles (different from IEEE and/or
different byte order from SPARC/68000). Fortunately, on many of those
machies (e.g. DECstations) there is already an xdr implementation (on
the DECstations it is in libc.a). Therefore, xdr doesn't have to be
recompiled - it is sufficient to comment out all *xdr* files from the
Makefile.
Usual changes include:
	Makefile: Add a CFLAG, something like -Dmc68000 or -Dsparc, ...
		  Reason: in auth.h there is a typedef for a 32bit
   		          unsigned integer which is dependent on the
			  machine.
		  Comment out all *xdr* files
		  Reason: See above
	netdb.h: Comment out the definition of struct rpcent
		 Reason: This usually is already defined int
		 	 /usr/include/netdb.h.
	types.h: Comment out the definition of MAXHOSTNAMELEN (or at
		 least check if it is consistent with the system defined
		 value (normally in <sys/params.h>)).
	various files: Add #include where needed.
		       Reason: not on all systems everything includes
		       	       the same sub-includes.
Note that if you use a non-default librpclib.a you HAVE to set INCRPC in
the Makefile since you have to supply a new default path for all the
rpc-specific includes!
IMPORTANT: If you get warnings when compiling librpclib.a and/or
	   Inetray concerning the redefinition of some symbols (like
	   MAXHOSTNAMELEN in <sys/params.h>, you MUST exclude these
	   symbols from the rpc h-files (in the example mentioned, it is
	   in types.h)!

Appendix B: The .inetrayrc Syntax
=================================
A .inetrayrc in the current directory takes precedence over the one in
the home directory to allow a different setup for a special raytracing
session (especially changes to the timeout and/or machines accessed).
Empty lines and comments starting with # are allowed in this file (check
the default file for details). It contains a nuber of option lists.
Every option list starts with a keyword followed by a colon. After that
a comma separated list of items follows. Note that a list must not
encompass more than one line. Keywords can be repeated.
The following keywords are available:

    resultport: port#
    			Port number on which results are sent back.
                    	This overrides RESULTPORT in config.h.
                    	
    timeout: time
    			Timeout in seconds when registering workers.
                    	This overrides RTIMEOUT in config.h.
                    	
    minworkers: number
    			When registering workers, the timeout is ignored
                    	until at least this number of workers have
                    	registered.
                    	
    maxworkers: number
    			Only so many workers are considered. All
			further answers are ignored automatically.

    blocksperserver: number
    			See POO/Work Scheduling for details.

    minblocksize: number
    			Minimun number of lines per block used by
			scheduler. See POO/Work Scheduling for details.
			Note that the last block may be smaller.

    maxblocksize: number
    			Maximum number of lines per block used by
			scheduler. See POO/Work Scheduling for details.
			
    ignore: hostname {, hostname}
    			List of machines to ignore. If you don't want to
			trace on a specific machine, just add it to this
			list. The names of the hosts given here must
			match exactly the names returned by
			inetray.ping. This list allows specific hosts
			from a network to be ignored which would
			otherwise react to a broadcast. Note that simply
			having ``use: name n=0'' would not work since
			this only means that this machine will not be
			called directly, it does not effect broadcasts.

    use: Use-List
			List of machines and networks to use in trace.
			See below.

The Use List
------------
The Use List is probably the most important part of the installation. It
is used both after the use: keyword in .inetrayrc and as a list of
parameters for inetray.ping. 

Formally, the Use List looks like this (EBNF):
	"UseList" ::= "ListElt" {, "ListElt"}
	"ListElt" ::= "Address" "Option" {"Option"}
	"Address" ::= local |
		      "Letter"{"Char"} |
		      "Number"."Number"."Number"."Number"
	"Option"  ::= N= "Number" | UID= "Number"

The Use List defines internally 3 data structures:
	- a list of hosts (with parameters) given as their names
	- a list of nets (with parameters) given as their inet numbers
	- local parameters given after the reserved hostname local

Whenever inetray or inetray.ping is run they call the hosts according to
the use list in the above sequence. This means that the parameters for a
host on a net precede the parameters for the net (if both are present).

Both options have defaults, N= defaults to 1 and UID= defaults to the
return value of geteuid(). The local parameters usually default as
expected, except when you call inetray.ping with at least one parameter;
then, local defaults to N=0 (so that you really ping only the machines
specified and not also the ones reachable by broadcast from the current
machine.

Note that you can give the machine number instead of its name; this is
discouraged, however, since it is then internally treated like a
network. 
    

