============================================================================

                                LANdb v0.91.2
                      Network Management Through SQL

                  Distributed under the terms of the GPL
                        See COPYING for more info
============================================================================

LANdb provides network managers a means of cataloging all network
connections, switches/hubs, closets, and buildings in an SQL database.  

The installation process is quite straightforward, but does require a bit of
prior knowledge.  This document assumes that you already have a working
installation of MySQL (or compatible SQL RDBMS), and that Perl 5 and CGI/DBI/DBD
are already properly installed on the subject machine.

With that said, let's get onto the installation.  There are now two ways of
doing things: the quick and easy, and the slow and dirty.  As of v0.74,
LANdb includes an install script, which should work for most installations. 
And as of v0.91.2, that single install script has been broken up into one
for fresh installs and one for each version upgrade.  For a fresh install,
run installer/new-install.pl, and for upgrades, run
'installer/<oldversion>_to_<oneversionhigher>' (just read from the
directory, it'll make more sense).  Once you're running the version
intended, you should be able to just point your browser to the location you
specified during the install, and start dropping in data.

NOTE: Be sure to read the section below on user accounts for an important
security note.

The installer isn't infallible though, so if you have troubles with it, just
follow the instructions in "installing the hard way."


=============================
  CSV file conversion utils
=============================

After installing LANdb, you have to start putting in your data.  Most
installations already have some means of recording network information. 
The project was inspired out of a need to replace the Comma-separated-values
files used to store such information about the author's network.  Working
through a spreadsheet is slow and inefficient, and risky most of the time,
but for things like that initial data entry, they can be helpful. 
Spreadsheets allow the nice and fast copy and paste, and formulas to
automate auto-incementing fields.  Obviously, entering thousands of rows of
data into LANdb's database isn't going to be easy if you have to do it all
by hand.

... Enter the CSV conversion scripts.  These guys will take your
comma-separated files and chuck them into the database.  In order to do
this, a standard order of columns, and standard content have to be
established before the scritps can do you any good.  Thus, let's lay out the
column content and order now.  Break your CSV files into one file for each
building.  In each file, arrange your columns in the following order:

	-Jack number
	-Switch slot/card that this jack is connected to, if any
	-Switch port that this jack is connected to, if any
	-Cable label connected to this jack
	-Media (Make sure this is written exactly how it is entered in the
	 database: cable type, speed, duplex, and connector (remove the commas, of
	 course, and separate the elements by spaces) "Cat5 10meg Half RJ-45" is a good example.
	-Closet name that the switch this jack is on is in
	-Switch/hub IP address that the jack's slot & port are on

Use common sense here: make sure that the numbers in your spreadsheet are
consistent with both what you want in the database, and what you've already
put in- switch IP's, slots/ports, closets, etc. should all line up nicely. 
The script, unfortunately, doesn't/can't do a lot of error checking for you.
If, for any of the above columns, your installation doesn't make use of the
listed variable, DON'T IGNORE THE COLUMN, just leave a blank column in the
spreadsheet.  MAKE SURE that none of the columns in the spreadsheet have any
commas (,) in them, as this will obviously change the number of columns in a
row, and throw off the conversion script.  It shouldn't be difficult at all 
to move columns around in your existing spreadsheets so that they match the 
above order.  IF YOU DON'T GET THIS RIGHT, YOUR DATABASE WILL BE TRASHED.  
The scripts that automate this don't care what the data looks like, so 
they'll take the mistake on your part of putting the switch IP in the first 
column as a jack number, and things will get messed up pretty badly.  Once
you've got your CSV file(s) created, give them a look over, and make sure
things look right.  Each line in the file should have the same number of
columns -- 8 (only applies to csv-building.pl).  

Before you can use the scripts to move things into the database, you must
first define your switches, vlans, buildings, closets, and media types.  As
with the spreadsheets, I suggest you do this one building at a time.  Here's
a suggested order of operation:

	1) Define a building
	2) Define all closets for this building
	3) Add VLANs/Subnets present in this building
	4) Define all switches in this building
	5) Add media types
	6) Put spreadsheets into the required format, and run the CSV script
	7) Repeat 1-6 for each building

That should get 99% of your data into the database.  Be sure to execute this
from a location that contains LANdb.pm, as it depends on it.


=============================
  Installing The "Hard" Way
=============================

1.  Untar the distribution:

tar zxvf landb-version.tar.gz

2.  Copy the cgi-bin directory to your /cgi-bin.  If your cgi-bin isn't at
your web server's serverroot, like "/cgi-bin," you'll have to modify all the
scripts accordingly.  Copy all .html files to a common directory.  In
testing, these have all been placed at the serverroot, but you should be
able to place them at a point like /landb without any trouble.  Please let
me know if you have any difficulty with this.

3.  Create the MySQL database 'nis.'  

mysqladmin -u root -p create nis

If the database is on a different machine than the one you're running
mysqladmin on, issue

mysqladmin -u root -p -h <machine name> create nis1

instead.  This creates the nis database, within which we'll be storing all
of LANdb's tables.

4.  Read through the file nis.txt, part of the distribution.  This is a dump
(created with mysqldump) of the tables in nis.  To create the tables, follow
the syntax contained in nis.txt (i.e., "CREATE TABLE switches ....") from a
mysql client, or type

cat nis1.txt | mysql -u root -p nis1

to cat nis1.txt into mysql as root (omit the -p if you don't have a password
on your root mysql account-- which is, of course, bad.  shame on you... :) )

5.  Add accounts to your MySQL server for access to the nis database.  See
the section titled "Users."  

6.  Follow the section 

=========
  Users
=========

By default, LANdb uses account 'admin' as the account that's able to make
modifications to the database.  This user should be granted CREATE, DROP
(optional), INSERT, ALTER, USAGE, SELECT, and UPDATE.  If you'd rather 
have a differently named account, simply change 'admin' to the account name 
in the script menu.cgi.  ('admin' is given an extra set of functions that 
aren't available to regular users.) 

As of v0.90, the only users you need to add to the database are 'admin' and
'superuser,' who should have the same permissions-- all of them.  LANdb's
user management system will handle the rest.  This document will be updated
later on to remove the rest of v0.80's user stuff.

Another user can be added for read-only functions.  The name of
this user doesn't matter, as long as it isn't 'admin.'  This user isn't
provided with any of the modification-enabled functions of the application.
In the future, LANdb will support more advanced function / user management,
and the scheme will be a lot more flexible than the current setup.

A Note on Binary distributions of MySQL: I've run into the issue on multiple
installations that a funky line is put in the mysql.user table, which causes
havoc when trying to add a new user.  The line contains 'localhost' as the
host, and a blank (' ') value for the username!  "DELETE FROM mysql.user
WHERE host='localhost' AND user=' '" should fix up the problem.  Please let
me know if anyone else has had experience with this...

SECURITY NOTE: All authentication necessary to completely trash your
installation is stored in plain text, in your /etc/landb.conf.  You have
been warned.  Make sure the file is only readable by the user your webserver
runs as.  Consider using suexec.  Make sure that no other CGI scripts open
files on the system (or at least, audit them to make sure they don't do it
unsafely).  


=====================
  IF ALL ELSE FAILS
=====================

If the installer fails, and you have no idea what's going on, here's a quick
reference card to getting LANdb installed.

First thing's first: Read the above Users section, and create the NIS
database on your mysql host, as specified in nis.txt, and the 'hard way'
part of this file.  Then, continue...

1) Copy "landb.conf-sample" included in this tarball to "/etc/landb.conf".

2) Put the location of your webserver's root document directory in
/etc/landb.conf in the variable $web_home.  

3) Make sure you've got a directory for LANdb.  It can be anywhere
underneath what you entered for $web_home.  Put this directory in 
/etc/landb.conf in URL-style, relative to what you entered for $web_home,
something like '/landb.'  Copy *.html to this directory.

4) Give the location of your cgi-bin in /etc/landb.conf, relative to the URL
that points to your webserver's document root.  Something like '/cgi-bin'. 
Copy, from the tarball, cgi-bin/* to this location.

5) Enter the host that the physical database is located on for the
funky-looking variable "$ENV{"mysql_host"}" in /etc/landb.conf.  It's
'localhost' for most folks.

6) Save that landb.conf file, and startup your web browser, pointing it to
your LANdb installation.  You should get the login page.  If you've
specified everything right, you're up and running.

7) Before you tear out your last hair, send me a descriptive email about
your problem.  Include what you've done, and a bit about your installation,
and I'll be glad to help you out.  Things will get more failsafe once the
installation script has been kicked around, but it can only improve if you
complain! :)

=================================================================

That should be all.  Questions/comments go to fes@users.sourceforge.net (do me a
favor and put 'landb' somewhere in the subject. :))

There are also mailings list for news, support and development.  To subscribe,
go to 

http://sourceforge.net/projects/landb/

and follow the mailing list links.