## $Id: INSTALL,v 4.0 1994/11/29 21:10:19 vikas Exp vikas $

INSTALLATION INSTRUCTIONS FOR 'NOCOL' v4.0
==========================================

NOTE:  Please look at the file PORTING for special instructions that
       might pertain to your operating system.

NOTE:	You will have to edit & customize some of the PERL monitors manually
	(in perlnocol). See the perlnocol/README for more information.

Most/all of the configuration is done in the top level 'Makefile' (under
nocol/src). All customizable parameters are well documented. Edit this file
before typing 'make'.

To build only a subset of the monitoring programs, use the following syntax:

   make TOP=/usr/nocol SRCDIR=`pwd` SRCS="netconsole pingmon trapmon"

Sample config files are also provided for each monitor. These are copied
over in the nocol/etc/samples directory during installation. Copy these
to nocol/etc/ and edit for each monitor.


Makefile
--------
1. Decide on a toplevel directory under which the software will be installed.
   Define TOP to this toplevel directory.

   The Makefile creates the following directories under this toplevel ($TOP)
   directory:

	data		output from all the monitors
	bin		for installation of all the binaries
	etc		location of all the config files

   It is advised that the location of these subdirectories be left as they
   are. However, if you must make changes, then edit the various subdirectory
   names in the Makefile.

2. Set the value of SRCDIR to the location of the 'src' (current) directory.
   By default the Makefile sets the value to TOP/src. This is needed so
   that the various 'Makefiles' can find the include and lib directory, etc.
   during compile time.

3. Set NEEDOBJS to the missing functions on your system (see the file PORTING
   for more information). Some modules are provided under lib/ and listed in
   the Makefile (putenv.o bstring.o etc.).

4. Set SYSLIBS to the libraries needed to link with on your system.
   This is mainly for curses/resolver/bsd sockets. These are well 
   documented in the Makefile.

5. Check and set the VALUE of IPPING, OSIPING & RPCPING to the locations
   of these programs on your system. Typically IPPING should be set to
   the nocol BINDIR/multiping, and RPCPING should be set to BINDIR/rpcping
   (these are provided and installed with the nocol distribution).
   If you are using 'multiping' for IPPING, then define MULTIPING in
   SYSDEFS also. Make sure that multiping is installed suid root.
   If you are not using any of these monitors, define these variables to
   point to any dummy location.

   If you want to use your own version of IPPING or OSIPING, make sure
   that the output from the ping commands is as described below. Else you 
   will need to make minor modifications in the 'src/pingmon/poll_sites.c' 
   module (the area to modify is well commented so it should be easy).

	navya>  /usr/etc/ping -s abc.foo.com 1000  5 | tail -2
	  5 packets transmitted, 5 packets received, 0% packet loss
	  round-trip (ms)  min/avg/max = 4/4/5

   No changes are needed if you are using the provided multiping (or rpcping)
   programs for IP (or RPC).

6. Set the value of NLOG_HOST to be the host that receives all the
   NOCOL log messages. Ideally, you should create a CNAME entry for
   'nocol.your.domain' in your nameserver.
   Also set OPSMAIL to an email address for recieving logstat reports,
   and PERL to the location of 'perl' on your system.

7. The default NOCOL logging port is defined in 'noclog.h' to 5354.
   Also, if using hostmon, the default data port is defined in the hostmon
   modules as port 5355.

   You can change these ports in these files if you want to use some other
   port number (preferably >1023 so that the programs do not have to run 
   as 'root'). Then add the following lines in your '/etc/services' file
   (mainly for inetd- the programs use the default ports if there is no
   entry in the /etc/services file).

	noclog		5354/udp	# noclogd uses UDP
	hostmon		5355/tcp	# hostmon uses TCP

8. Check the values of CC (for the compiler type) and CFLAGS. 

9. If you have a new version of 'install' on your system which has a 
   non-'standard' syntax (whatever 'standard' means now-a-days), then
   set INSTALL to '$(SRCDIR)/utility/myinstall'.

   Use:
	install -c -m 751 thisfile destination

   ..to see if your 'install' is 'standard'.

10. Build the distribution using 'make'. It is advised to save the output 
    of the make command to a temporary output file so that it can be perused
    later for any errors.

       csh% make >& make.out
       csh% make install

11. Install the following programs as 'suid' root since they need to access
    priveleged ports:  trapmon, multiping, etherload

	chown root.nocolgroup  trapmon multiping etherload
	chmod 4710  trapmon multiping

12. Look at the config files in the $TOP/etc/samples directory, and edit/save
    them to the $TOP/etc directory. List the hosts (running the monitors if
    distributed on various systems) which can log to 'noclogd' in the config
    file for noclogd. If saving to log files, make sure that the proper LOG
    directory exists for the log files to be created.
    Edit all other config files for your site.

    PRIOR TO v4.0, IPPINGMON used the config file name of 'ipnodes'. Rename
    'ipnodes' to 'ippingmon-confg'. Furthermore, the variable name for
    ippingmon was 'Reachability' in the previous versions, it is now
    "ICMP-ping" - please change any local customized scripts that used
    to assume the old variable name.

13. Edit the following scripts (these are run from your CRONTAB).
    Then edit utility/crontab.file  and install in your (or nocol user's)
    crontab.

   - '$TOP/bin/keepalive_monitors' checks to see if the various monitors
     are running. Edit and set the values of PROGRAMS1, HOST1, etc.
     You can also distribute the monitors on multiple systems and share 
     the /nocol disk via NFS. List all the monitors that you want to run
     per system in this file.
     It is run from the crontab every 15-20 minutes.

   - Edit the '$TOP/bin/notifier' program and set TO3, TO4 etc. mail
     aliases. This program is useful to send email when a site is in 
     critical mode for extended period of times.
     It is run from the crontab every hour or so.

   - Edit the '$TOP/bin/log-maint' program and set the location of
     LOGDIR (make sure this directory exists for noclogd to run) as well
     as KEEPOLD (the number of old logs that you want to keep). This does 
     log file maintenance (moves the NOCOL log files to 'log/old/'), runs
     logstats for report generation and sends a HUP signal to the 'noclogd'
     daemon.

14. Test 'noclogd' by starting it up in debug mode (-d). See if it
    complains about anything.
    Start up the various monitors using 'keepalive_monitors'.
    Use 'netconsole -l 4' to see if any data is being collected under the 
    DATA directory. Look in the TOP/etc/*.error files for any errors.

    REMEMBER that the monitors log events to noclogd only when the state
    of the event CHANGES. So nothing might be logged to noclogd if all
    the sites remain at the same state (up/down) and threshold level.

15. You can add user 'nocol'  to your password file to allow anyone to
    log in as user 'nocol' and see the state of the network. A typical
    entry is:

	nocol::65534:65534:Network Monitoring:/tmp:/nocol/bin/netconsole

    All signals are trapped by the 'netconsole' display program and cause
    it to terminate.


PERLNOCOL
---------

There is a PERL interface for developing additional NOCOL monitors. To use 
this, you need to have PERL installed on your system (perl is available
from ftp.uu.net or from ftp.netlabs.com).

1.  The values of $nocolroot, $NLOG_HOST & perl are automatically
    set on doing a 'make install'. However, after installing, check
    $bindir/nocollib.pl for the values of:

	$nocolroot, $ping, $NLOG_HOST

    Check the location of the perl program on your system (the first line
    in the perl scripts).

2.  Watch out for the padding in the '$event_t'  template. Compilers tend
    to align the fields of structures on even boundaries, so you might
    have to add some additional 'null' padding using 'x' depending on
    your system architecture. Set $libdebug = 1 to see the size of the 
    $event structure. The size of the data files produced by the C monitors
    should be a multiple of the perl $event structure. The C program
    'show_nocol_struct_sizes' can be used to see the event struct sizes
    in the C modules.

3.  If using 'hostmon', edit the hostmon server and the clients to set
    the port & permitted hosts. The client routines do not use nocollib.pl
    and can be run entirely standalone on remote hosts (just install
    hostmon-client.xxx and hostmon-client.daemon on the remote hosts in
    any directory and start them up at boot time).
    Check the syntax of the ping() function in the 'hostmon' program 
    to make sure that the command line arguments are okay for your system.

4.  To use 'snmpmon',  edit and set the thresholds in the snmpmon-confg
    file. List the devices that need to be monitored in the 
    'snmpmon-client-confg'  file and run 'snmpmon-client'. SNMP data is
    generated in the '/tmp/snmpmon_data' directory- you can probably have
    a number of these processes running on different systems and rcp
    the datafile over to the host running the server 'snmpmon' program
    periodically from cron.

    Compile the 'snmpwalk' program under src/cmu-snmp/ and then install
    it in the nocol/bin/ directory. Copy over the MIB file 'mibII.txt'
    into the nocol/etc directory. Then edit the snmpmon-client program
    and set the location of the '$prog' and the '$mibfile' variables.

5.  If the monitor that you want to run uses 'rcisco', then enter your 
    router's password in it and install it in nocol/bin  with mode 710.
    Alternatively, you can use the 'tcpf.c' program to run a remote
    telnet command.
    If the monitor uses 'snmpwalk', compile the applications under 
    src/cmu-snmp/ and install it in nocol/bin. Edit the SNMP community
    string in the perl script if so indicated in the perlnocol/README
    or at the top of the script.

6.  Create the config files under $TOP/etc/. Samples are in the etc/samples
    subdirectory.

7.  For troubleshooting, set the $debug and $libdebug values to '1' or
    higher. You can also send a SIGUSR1 signal to running modules to
    change the debug level (increases to max and then resets on each
    SIGUSR1).


TROUBLESHOOTING
---------------

1. Some warnings are to be expected, but there should be no major errors.

2. If the errors are about include files or variable types, look for the file
   that is being included under the  /usr/include sub-directories. The
   various systems love to move include files back and forth between the
   include and the include/sys directories (especially 'time.h').

3. For the nameserver monitor, old versions of the resolver library might
   complain. Some include files defined the '_res' variable differently, so
   try changing all occurences of '_res.nsaddr' to '_res.nsaddr_list[0]'
   in the src/nsmon/nsmon.c module (look in your /usr/include/resolv.h).
   Make sure that the 'libresolv' library exists while linking.

4. For trapmon, the CMU SNMP library is used. Make sure that it was properly
   built under 'src/cmu-snmp/lib'

5. Most monitors have a '-d' option for debugging, or create error
   files in the TOP/etc.

6. If you get a 'h_addr_list[0]' not defined error, simply edit 
   nocol.h and add the following line in it:

	#define h_addr 1

  This is because of the difference in the hostent() structure of netdb.h
  in very old systems.

7. Check if the regular expressions in the &dotest() routine in the PERL
   modules need any changes for your site.


Best of luck. Comments to 'nocol-info@jvnc.net' and bugs to 'vikas@navya.com'

The README file has more information. For an overview, look at the file
doc/nocol-overview.8.


	Vikas Aggarwal
	(vikas@navya.com)
	Dec 1994
	-----------------

