====================================================================== I N S T A L L doc: Fri Mar 6 15:32:06 1992 dlm: Tue Aug 17 16:58:34 1993 (c) 1992 ant@sitter uE-Info: 94 56 T 0 0 72 3 2 8 ofnI ====================================================================== Notes About Unix Flavours ========================= As of version 2.0.0 inetray is System V Rel. 4 clean. No BSD system calls are used any more (or so I hope). A few SysV syscalls have been implemented in terms of real BSD syscalls. These should be added in the Makefile under the SYSOBJS variable. 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. If you have an automounter running you should probably strip the first path name component (usually /tmp_mnt) from all pathnames. To do this you should just define STRIPHEAD to the string you want to remove from the head of all path names. If you compile inetray with the NOSYSLOG_QUIRK, it writes all messages to a file in a temp directory. The filename can be redefined by changing NOSYSLOG. The directory the messages file is written to cannot be changed for security reasons. It is always the one defined as _P_tmpdir in /usr/include/stdio.h. 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 !!! INSTDIR : directory to install the executables to INSTUSER : user to install the executables under INSTGROUP: group to install ... INSTMODE : mode to install ... QUIRKS : here a list of all quirks (see SUPPORT) you want inetray to be compiled with should be added. If you want to add the NOSYSLOG_QUIRK you should add -DNOSYSLOG_QUIRK. SYSOBJS : if your Unix does not offer all required System V syscalls the remaining ones can be defined here. See the NeXT section in SUPPORT for an extreme example. SYSLIBS : Some Unix systems have certain syscalls, but not included in the c-library. Additional system libraries (e.g. for networking, random number generation, ...) can be added here. DEPCPP : As of version 2.0.0 a depend target has been added. If ``/usr/lib/cpp -M'' does not do the trick on your machine you should change this. Now you should be able to compile inetray. A short description of the available target follows: all: compiles everything (default target) new: re-compiles everything from scratch brandnew: re-compiles also rpcgen stuff (use only on SUNs!!!) server: compiles only rpc.inetrayd, inetray.start client: compiles only inetray, inetray.kill, inetray.ping utils: compiles all utilities (rpc.dereg, netinfo, generr) 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 patch: makes and checks a patch (patchX) clean: cleans temp compilation files & executables spotless: cleans all executables and rpcgen generated files. Don't make this target if you don't have a very new rpcgen (I've only seen it work on a SUN). depend: You should make this target if you changed the Makefile (added or removed quirks) or any part of the source. 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! $ echo "sphere 2 0 0 0" | inetray > sphere.rle This is the first test shown in the rayshade user manual. As of version 1.1.0 it also works with inetray. 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. ~/.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: '' 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= (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: '' 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= (see below). Running Multiple Workers on a Machine (Network) ----------------------------------------------- To do this, you just add the option N= 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= 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. 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 /rpc.inetrayd rpc.inetrayd'' On some machines (e.g. SGIs), this doesn't work. There, you'll have to add ``inetray 555555555'' to /etc/rpc (or to the ypmap rpc) and add the following line to inetd.conf: ``inetray/1 dgram rpc/udp wait root /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 tracing 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 since the sysop does not want to add a line to inetd.conf. ~/.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 )). 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 , 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. irstart lines ------------- As of version 2.0.0 the irstart utility can be used to start inetray.start servers on remote machines. Irstart just looks for lines starting with #@ (i.e. special comments) and executes them with /bin/sh. Any sh command-line may stand after a #@; see .inetrayrc for examples.