24-12-92		Beholder, The Next Generation Install 'Manual'

By:	Jan van Oorschot
For:	btng version 2
To:	users and developers

==========================================================================
This file contains the installation procedure of 
Beholder, The Next Generation, version 2. 
It does not describe how to compile the source-code distribution or
how to compile the UNIX utilities.

It consists of the following steps:

	1 - get correct distributions
	2 - unpack the distribution
	3 - adjust NDIS network configuration (config.sys and protocol.ini)
	4 - edit btng configuration files
	5 - set environment variables
	6 - compile btng configuration files
	7 - reboot machine
	8 - test configuration and start applications
	9 - register your installation
	10- install Perl support (optional) 
	
To have any chance to run the beholder your will need

	- PC running OS/2 1.x or 2.0
	- ethernet network interface
	- NDIS network software, included in networking packages
	  like IBM TCP/IP 2 and Microsoft's LANMAN
	  At least you will need the files:
	  
	  	- protman.sys
		- NDIS compatible ethernet card driver for OS/2
		- netbind.exe (if no NETWKSTA.SYS is loaded)
		
==========================================================================
Step 1:  get correct distributions

You can get the btng distribution using anonymous ftp from:

	dnpap.et.tudelft.nl
	
Log in as 'anonymous', password 'your-id@your-host'.  (do not type the ''s)

Get the file

	btngexe2.zip
	
Make sure you use binary transfer, and you can write in your local directory.

==========================================================================
Step 2:  unpack the distribution
 
The distribution is zipped using Zip version 1.9. You can
unzip it using zip version v5.0, or any other unzip that
handles that format.

Make a directory where you want the btng files. From now,
we will assume this is done as follows:

	d:
	cd \
	mkdir bntg
	cd \btng
	
So, the btng distribution will be in d:\btng.

Unzip the distribution with the following commands:

	d:
	cd \btng
	unzip -d d:\tmp\btng2.zip
	
==========================================================================
Step 3:  adjust NDIS network configuration

This is the hard part. Bntg uses the NDIS protocol stack to access
an ethernet network interface card. This can can not be used by
any other protocol stack such as IBM's TCP/IP and Microsoft lanmgr.
If you have only one ethernet card in your OS/2 machine, you will
need to make two versions of the files:

	config.sys
	protocol.ini
	
One to be used when you run btng, and one when you want to do 
normal network work. It's best to install an extra ethernet card,
and let btng use that one.

We assume all these terms are familiair to you, if not, read the
documentation that comes with your normal network software.

Ok, you will need to add the neus.os2 driver in config.sys, and add a
NEUS0_XIF section in protocol.ini. 

In config.sys add a line:

                DEVICE = d:\btng\neus\obj\neus.os2
		
The place of this line in config.sys is important, to give you
an example, part of our config.sys is  (two cards, LANMAN+btng)

REM ====== LANMAN 2.1 === DO NOT MODIFY BETWEEN THESE LINES === LANMAN 2.1 ===
DEVICE=D:\LANMAN\DRIVERS\PROTMAN\PROTMAN.OS2 /i:D:\LANMAN
DEVICE=D:\LANMAN\DRIVERS\ETHERNET\MACWD\MACWD.OS2
DEVICE=D:\LANMAN\DRIVERS\ETHERNET\MACWD\MACWD2.OS2
DEVICE=D:\LANMAN\DRIVERS\PROTOCOL\NETBEUI\NETBEUI.OS2
DEVICE=D:\BTNG1\NEUS\OBJ\NEUS.OS2
DEVICE=D:\LANMAN\NETPROG\RDRHELP.SYS
IFS=D:\LANMAN\NETPROG\NETWKSTA.SYS /i:D:\LANMAN
DEVICE=D:\LANMAN\NETPROG\NETVDD.SYS
REM ====== LANMAN 2.1 === DO NOT MODIFY BETWEEN THESE LINES === LANMAN 2.1 ===

In protocol.ini add a section for neus, the btng NDIS interface. It should
look something like:

                ...
                [NEUS0_XIF]
                        DriverName = NEUS0$
                        Bindings = "MACWD_NIF"
                [MACWD_NIF]
                        DriverName = MACWD$
                        ...
                ...

In this case, NEUS is connected to a Western Digital card with section
name MACWD_NIF.

==========================================================================
Step 4:  edit btng configuration files

The beholder uses its own configuration files. This files usually have
the extension .cfg. Before the btng executables can use these files,
they have to be compiled to a .ini file. Compilation will be discussed 
in step 6.

For now, we will only discuss what changes to make in what .cfg files.
You will find the .cfg files in d:\btng\init. You should have the
following .cfg files in that directory:

	global.cfg
	beholder.cfg
	pix.cfg
	info.cfg
	stat.cfg
	
In the following we will show what configuration variables to adjust
in what file:

You should adjust everything which is listed here. There
are much more lines in the .cfg files, and you can have a 
look at them, but for the moment you can leave them unchanged.


global.cfg
==========

mgmt.agent     = (STRING) beholder		# your btng ip-host name
mgmt.community = (BYTES) "dnpap"		# community of beholder
mibdf.mibhome  = (STRING) "d:\btng\mibhome"	# path to mibhome

beholder.cfg
============
beholder.sys.contact    = (STRING) Jan		# your name
beholder.sys.description= (STRING) btng		# system decription
beholder.sys.location   = (STRING) here		# place of system
beholder.sys.name       = (STRING) beholder	# your btng ip-host name

ip.iface.name.1        = (STRING) NEUS0
ip.iface.addr.1        = (IPADDR) 130.161.145.1 # ip address of beholder
ip.iface.mask.1        = (IPADDR) 255.255.0.0   # netmask of your ip network
ip.iface.up.1          = (BOOLEAN) TRUE

ip.route.dest.2        = (IPADDR) 0.0.0.0
ip.route.mask.2        = (IPADDR) 0.0.0.0
ip.route.nextHop.2     = (IPADDR) 130.161.180.25# address of the default
						# ip gateway on your
						# ip network
ip.route.iface.2       = (STRING) NEUS0
ip.route.metric.2      = (SHORT)  255

pipe.hostname   = (STRING) beholder		# your btng ip-host name

pix.cfg
=======
	no changes
	
info.cfg
========
	no changes
	
stat.cfg
========
	no changes

==========================================================================
Step  5 - set environment variables

bntg uses the following environment variables:

	PATH= ......;d:\btng\bin;.....
	CONFIGPATH=.;d:\btng\init
	
Make sure these variables are set whenever you run one of the
btng executables.

==========================================================================
Step  6 - compile btng configuration files

The configuration files edited in step 4 should now be compiled.
Make sure the environment variables are set correctly !

Execute the following commands:

	d:
	cd \btng\init
	cfg2ini global.cfg
	cfg2ini beholder.cfg
	cfg2ini pix.cfg
	cfg2ini info.cfg
	cfg2ini stat.cfg
==========================================================================
Step  7 - reboot machine

You should now reboot your machine to activate the modified
config.sys and protocol.ini. 

==========================================================================
Step  8 - test configuration and run applications

The boot of the machine should be completed without error messages
when loading NEUS.OS2.


If no other networking software is loaded (you have only one card in
your machine), you will need to run netbind.exe. This program
should be included in your normal network software.

	netbind
	
This should not report any errors in protocol.ini

Test if your environment is setup correctly, do this by

	ini2cfg beholder
	
This should report the correct  configution parameters that will
be used by beholder.exe.

Test if everything works, do this by starting beholder.exe

	
You should get only the message:

	Beholder TNG active !

It is now time to use the beholder. You can start the following executables:

	stat.exe	--> PM application with etherStat statistics
	info.exe	--> PM application with Beholder statistics
	
	echo sysDescr | snmp-get	--> get SNMP variables
	echo internet[] | snmp-tbl	--> dump SNMP MIB tree
	
You can now try to collect data from your favorite TCP/IP box.

First do a 

	ping beholder
	
Use whatever name belongs to the ip-address you have configured 
btng with.

If this works, the beholder is up and running. Now you can collect all
the RMON SNMP variables you want.

Other applications included in the btng distribution are

	- pix.exe	--> should be run without a beholder 
			    being active. It uses NEUS to
			    display all connections active on
			    the network.
	
	- npspook.exe	--> name pipe Tricklet interface
	- snmp-???.exe	--> Tricklet library for OS/2, can
			    use IBM TCP/IP 1.2 or name pipes
			    to collect SNMP variables
	- gobbler.exe	--> demo of packet dissassembler. Is not
			    connected the beholder.exe yet.

==========================================================================
Step  9 - register your installation

Now everything is working, it is time to let us know your
copy is up and running. This is very simple, just run
the script REGISTER.CMD, found in the doc directory.
This script will set two SNMP variables, which will result in
a SNMP trap to one of our machines in The Netherlands.
In this trap, only global info about your installation
is included, no sensitive data.

Note that procedure only works if the Beholder is connected to
the Internet. If not, send us a mail, not as fancy, but it works.

==========================================================================
Step  10 - install Perl support (optional)

We include a perl library and the spook tools which enable you to 
collect SNMP/Beholder variables using relatively simple perl
scripts. 
To use these scripts, first get and install perl for OS/2. This includes
getting the perl distribution, unzip it, and set the environment variable

	set perllib=d:\perl\lib

change the path as needed.
Now you will have to copy the file perl\spook.os2 to $(PERLLIB)\spook.pl, so

	copy perl\spook.os2 d:\perl\lib\spook.pl

and the file perl\rmon\collector.pl to $(PERLLIB)\collector.pl, so:

	copy perl\rmon\collector.pl d:\perl\lib\collector.pl

Next, you will have to start the daemon program npspook. This program 
will make the actual SNMP requests. 
The perl scripts will find this daemon automaticly.
so:

	start npspook

You can iconize npspook so it won't clutter up your screen.

Now make sure that perl.exe is somewhere in $(PATH), 
and go to the directory perl.
Here you should find tw demo perl scripts, execute them as:

	perl demoget.pl  beholder dnpap pipe
	perl demotbl.pl  beholder dnpap pipe

You should see statistical information about the running beholder. If you have
the TCP/IP stack for OS/2 from IBM running, you should also be able to collect
SNMP varaibles from other sources by specifying the UDP medium.

RMON/Beholder specific perl scripts can be found in perl/rmon. Here you will
find the etherstats.pl script. 
This script creates an ethernet collector and displays 
results much like info.exe, but then less graphical.
Run this like:

	perl etherstats.pl beholder dnpap pipe 1

We noticed that the 16-bit versions of PERL for OS/2 will wrap very quickly, so 
you will see negative integers !!!!!!!!!!!!!!!

	


