============================================================================ 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/_to_' (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 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.