1234567890123456789012345678901234567890123456789012345678901234567890123456789

As of 30/11/2002 (v2.3.0):

Idea:
	In a switch based campus it is not easy to restrict users from using
	whatever IP address they want on their computers. It is common to
	know of an IP address that causes problems but not to know the actual
	place of this IP in the campus.

	Netinfo tries to locate each and every known IP address inside a
	campus.

	As of v2.1.1 netinfo has an one week history of NICs/IPs and their
	network location. It can report NICs that seem to change IP address
	and vice versa. It can also recognize NICs that seem to change their
	network location.

	As of v2.1.2 NIC Manufacturers are recognized using the MAC addresses.

	As of v2.1.3 history entries can be filtered to prevent 'flooding'
	when using DHCP.

	As of v2.2.0 it is possible to add comments for a specific history
	entry and/or ignore it. It is also possible to remove entries from
	the history. A simple search for the history was added. More CSSs
	for the web pages where used.

	As of v2.3.0 a registry of IPs, MACs and Persons exist. IPs can
	be associated with MACs and vice versa. After that netinfo will
	identify nodes that are using invalid IPs or IPs used by invalid
	MACs

How:
	After the user defines the switches and the routers to be scanned;
	netinfo uses SNMP to get:

	From routers:
		* The interface list, names and aliases
		* The ARP cache and the IP to interface association
		* The interface MAC addresses

	From switchs:
		* The interface list, names and aliases
		* The MAC-to-port mapings
		* The internal MAC addresses
		* The interface MAC addresses (for L3 switches)

	After that it combines the information by:

		* Identifying ports that are reported to 'contain' MAC
		  addresses of other switches/routers. Those ports are
		  not reported.

		* Creating a table of (IP, MAC, router, router_interface)
		  pairs.

		* Creating a table of (MAC, switch, switch_interface) pairs.

	Finaly, it combines the tables created to report for each MAC address
	the IP that coresponds to (if any), the router, the router interface
	the switch and the switch port that this MAC is found. It also reports
	IP addresses that are not mapped to MAC addresses.

	It also collects interface names and aliases to provide better
	reports.

	There is a standalone program that collects the information and stores
	the data in a postgreSQL database.

	The user interface is provided thru some php scripts. It doesn't
	require mod_php. The scripts are run thru php using #!/usr/bin/php
	(Or wherever the php exetuble is placed). This way it can be run
	even under the suexec wrapper. 

	It does *NOT* require any privileges.

	As of v2.1.1 a detailed history is kept and updated for each IP-MAC
	pair.

Requirements:
	To use Netinfo you'll need:

		* PostgreSQL >= 7.2
		  http://www.postgresql.org/

		* PHP 4 (I don't know if 3 will work)
		  http://www.php.net/

		* libnetsnmp (This is the new version of ucd-snmp)
		  http://www.net-snmp.org/

		* v-lib >= 1.5.0.0
		  http://aetos.it.teithe.gr/~v13/vlib

		* Openssl if PostgreSQL or libnetsnmp use it. In case of
		  PostgreSQL, you'll need a full installation
		  since the headers are also used from PostgreSQL headers.
		  http://www.openssl.org/

Installation:
	To install Netinfo:

	* Unpack it and run configure:

		+ In case v-lib is not installed in a common place you should
		  consider using --enable-static-vlib.
		+ The location of vlib can be specified with --with-vlib
		+ Specify the location of postgreSQL with --with-postgre
		+ Specify the location of libnetsnmp with --with-snmp
		+ Specify the location of openssl with --with-openssl
		+ Specify the location of php with --with-php
		+ Specify the installation prefix with --prefix
		+ Specify where to install cgi scripts with --with-htmldir

	* After that run `make' and `make install'. This will place:

		- The web related scripts and the web pages in htmldir.
		  Also a configuration file will be placed in this dir too.

		- The netinfo binary in ${prefix}/bin

		- The netinfo configuration file in ${prefix}/etc
		  (named netinfo.conf)

		- A `create.sql' and a `drop.sql' in ${prefix}/db

Configuration:
	To prepare Netinfo to run you should:

		* Create the database. Use PostgreSQL's createdb utility
		  like:

			$ /usr/local/postgre/bin/createdb koko
			CREATE DATABASE

		  also create the language 'plpgsql' for the database:

			$ /usr/local/postgre/bin/createlang plpgsql koko

		  where koko is tha name of the database. After that use
		  create.sql to create the tables of the database:

			$ /usr/local/postgre/bin/psql -f create.sql koko

		  It will produce some notices but this is OK. If you see
		  any lines containing the word 'ERROR' you have a problem.

		  You should also populate the vendors table:

			$ /usr/local/postgre/bin/psql -f vendors.sql koko

		* Go to the etc/ directory and rename netinfo.conf.sample
		  to netinfo.conf. Edit it and set dbname to the database
		  name and dbuser/dbpass to a username and a password for
		  a user that is able to write in the tables we created.

		* Go to the directory where the cgi scripts are installed
		  and rename the .sample configuration file just like
		  you did with netinfo.conf. Now change the values in
		  here too. It is possible to use another user that only has
		  write permitions on table `netdevs' and read on the
		  other tables.

		* Configure your web server to be able to use the cgi scripts
		  dir. Don't forget to password protect them (see the FAQ
		  about security issues)

Usage:
	Using the interface (Devices), define your switches and routers
	to be scanned. You'll need to enter the ip of the device (any ip
	in case of router), a simple description and a RO or RW community
	name.
	
	Now run the executable.. It will produce a lot of output (for now).
	Just redirect it to /dev/null..

	After that use the interface to look at the information. 

Notes:
	Currently it will only work for CISCO devices since it uses
	CISCO specific MIBs to collect the required information.

	Also note that it is *REQUIRED* for the device to be able to provide
	SNMPv2 information and use SNMPv2 (2c). This means that you'll need
	to have IOS 12.0 or greater. IOS 11.2 will not do the job.

	Using `netdevs.cgi' you can see what devices returned data.

	It is suggested that you run a script from crontab every X
	minutes to collect the information. It should also run VACUUM
	on the database to prevent infinite growth. I recomend a
	script like:

	--------------------------------------------------------------
	#!/bin/sh
	# cd to the installation location
	cd /somewhere/out/there

	# Collect the information
	./bin/netinfo > /dev/null 2>&1

	# Run vacuum to discard old data and analyze to optimize
	# database access
	psql -c 'VACUUM ANALYZE' koko

	# Store data in history table
	psql -c 'select set_history()' koko

	# Expire old history data
	psql -c 'SELECT expire_history();' koko
	--------------------------------------------------------------

	(Assuming koko is the name of the database)

History:
	As of version 2.1.0 history was added. Every entry is recorded
	for 7 days in the database. If you're upgrading add to your
	cron script:

	--------------------------------------------------------------
	# Store data in history table
	psql -c 'select set_history()' koko

	# Expire old history data
	psql -c 'select expire_history()' koko
	--------------------------------------------------------------

	You will need to recreate the database if you're using version 2.0.0

	A new cgi named history.cgi will be installed. It will try to list
	
		* IPs / MACs that have changed location in the network

		* IPs that were mapped to more than one MAC addresses

		* MAC addresses that are mapped to more than one IP addresses

	As of version 2.1.2 history entries can be filtered. Just click the
	button 'Set filters' and enter criteria for hosts to be filtered out.
	IP and MAC addresses will match any IP starting with the valule entered
	(192.168 will match 192.168.0.0/16 and 00:00:0C will match all MACs 
	with that prefix.

	As of version 2.2.0 it is possible to add comments to specific
	history entries and/or ignore them. It is also possible to remove them
	from the history. This way entries that are solved can be removed
	or just commented and ignored. They can be ignored once or forever.

Registry:
	As of version 2.3.0 a registry of IPs MACs and Persons was added. You
	can add IP or MAC addresses. For each entry a short description, some
	notes and a person can be entered. IP and MAC addresses can be
	associated. One IP address can be set to be used by one or more MAC
	addresses and one MAC address can be set to use one or more IP
	addresses. After that IP and MAC addresses can be set to be able to
	use only the associated addresses. Whenever an IP-MAC pair is found
	that violates the Registry, it is considered an error and can be
	located using the UI. Persons are for informational puproses only.
	For each person you have to enter his name and a personid. The ID
	can be any string and will be used to associate IP/MAC addresses.

Upgrade:
	* v2.2.0 -> v2.3.0:	- plpgsql language must be created in database.
				  (See configuration section above)
				- Database should be recreated. (See the README
				  inside the db/ dir)

	* v2.2.0 -> v2.2.1:	- No changes are required.

	* v2.1.3 -> v2.2.0:	- Database should be recreated.
				- The .dbconf file should be recreated from the
				  .dbconf.sample. Removing the empty line at
				  the end of file will also work.

	* v2.1.2 -> v2.1.3:	- Database should be recreated.

	* v2.1.1 -> v2.1.2:	- Database should be recreated.

	* v2.1.0 -> v2.1.1:	- An HTML4 capable browser should be used.

	* v2.0.0 -> v2.1.0:	- Database should be recreated.

License:
	* This program is distributed under the terms of the GNU GPL v2.
	  A copy of the license is included in the distribution.
	* Icons included hold their license and copyright as stated in
	  the interface/img/README file.
	* This license may change without further notice but will only affect
	  future versions.
	* You're using the program at your own risk and you're the only
	  responsible for any damage that it may cause. It may be illegal to
	  collect this kind of information from your (or another one's)
	  network.
	* If you believe that this license doesn't fit your needs then
	  contact me.

Home:
	The homepage of netinfo is at http://www.it.teithe.gr/~v13

Send notes bug reports and requests to v13@priest.com

