Sophie: nisca-2.3.2-1mdk noarch

nisca-2.3.2-1mdk.noarch.rpm

Please don't let the length of the installation procedure scare you;
it's really not that hard. This is just a very thorough installation
manual. :) Installing PHP and its correct libraries is the most
difficult part, especially if you compile it yourself. I've never
used a precompiled binary release of... well, anything but X...
so I have no idea how to tell you how to do it. :)

Here's what all you need; some is required, some optional.

NISCA 2.3.2 Requirements
------------------------

(All versions shown are minimums.)

- Apache v 1.3.x (1) REQUIRED
http://httpd.apache.org/dist/httpd/
- MySQL v 3.23.x REQUIRED
http://www.mysql.com/downloads/index.html
- PHP v 4.x.x REQUIRED
http://www.php.net/downloads.php
- zlib v 1.1.4 REQUIRED
http://www.gzip.org/zlib.tar.gz
- UCDSnmp v 4.2.3 (2)
http://sourceforge.net/projects/net-snmp/
- libGD v 1.8.x (3)
http://www.boutell.com/gd/
- libJPEG v 6b (3)
http://www.ijg.org/
- libPNG v x.x (4)
http://www.libpng.org/pub/png/
- libfreetype v 1.x or 2.x (5)
http://sourceforge.net/projects/freetype/
- The Zend Optimizer (6)
http://www.zend.com/store/products/zend-optimizer.php

(1) Theoretically, any web server can be used, but NISCA
has been tested and developed using Apache's httpd.
And PHP doesn't recommend using the Apache 2.x versions yet.
(2) Also known as "net-snmp". Only required if you want
to collect stats using SNMP.
(3) Only required for JPG support in graphs.
(4) Only required for PNG support in graphs.
(5) Only required to use TrueType Fonts on graphs.
(6) Optional. Get the version to match your PHP version.
Zend will dramatically improve PHP performance.

NISCA also requires that Session Variables and Perl-Compatible
Regular Expressions support be enabled in both the module and
CGI binary versions of PHP. They're both enabled by default;
please don't disable them.

Fresh Installation Procedure
----------------------------

- Before proceeding verify that all the packages required
are correctly installed. Please see the PHP_HINTS file for a
highly detailed description of how to install all the pieces
that NISCA requires.

- Unpack the NISCA package (which you've probably done if you're reading
this).

- Move this entire directory to a directory somewhere in your web server's
DocumentRoot. It doesn't have to be called "nisca-2.3.2/"; all URLs and
links in the scripts are relative. For example, if you want its URL to
be "http://localhost/admin/stats/", you can just do

"mv -i nisca-2.3.2 <document_root_directory>/admin/stats"

and it's done.

Make sure .php" files can be executed in this directory (see Apache
configuration). Also make sure Apache knows to treat "index.php" as
an index file (add "index.php" to the "DirectoryIndex" line of your
"srm.conf" or "httpd.conf" file). Then, make sure the directory is
writable by the web server user, or just make your web server user
the *owner* of the directory. This is so it can create graph images in it.

- Do whatever you want with the "docs" directory. :)

- Scripts that don't run from a web server require that their first line be set
to the binary used to execute them. Nisca's scripts all assume your "php"
binary is in /usr/bin/. If it isn't, either make a symlink to php in
/usr/bin/php, or go through these scripts and change their first line
to match wherever it really is (leave the " -q" in it!):

utils/collect
utils/mrtg_import
utils/nisca_check
utils/nisca_kill
utils/snmp_collect
install/create_stats
install/move_niscaconf_to
install/update-to-2.3.2

- Make the directory "/etc/nisca" ("mkdir /etc/nisca" as root). Copy
"nisca.conf" and "db.conf" from the "install" directory into it. If you don't
like "/etc/nisca", it is actually possible to change the location and/or
filename of "nisca.conf" from the default. If you want to do so, run the
script "move_niscaconf_to" from your NISCA installation directory
(run it without any parameters to see the command-line options). This script
will move nisca.conf and db.conf into the directory of your choice (making
it if it doesn't exist already), change the "require_once" line in all the
various scripts, and then spit out the list of commands necessary to restore
all file ownerships and modes to their proper state, which you can just cut
and paste without any modification into your shell command line.

- Edit "/etc/nisca/nisca.conf". Set the file locations and URLs to wherever
you want to put things. Some are full pathnames on your filesystem,
some are URLs. Beginners new to NISCA may want to refer to the file
"nisca.conf.explained"; it explains all the options in detail.
It can also be installed as your working "nisca.conf".

- Edit "/etc/nisca/db.conf". Set the variables appropriately for your MySQL
installation; see the comments for each value.

- If you're using Debian, you can refer to this message for hints on
where to put the package's various files:

http://lists.debian.org/debian-mentors-0102/msg00228.html

- Correct file modes/permissions can now be achieved with these commands
as root; make sure you're in your NISCA installation directory first!!!
(Replace "nobody" with the username your web server runs as, and
"/etc/nisca" with wherever you put nisca.conf and db.conf.)

chown nobody:root .
chown -R root:root *
chown -R nobody:root /etc/nisca archive
chmod -R 644 *
chmod 744 install/* utils/*
chmod 644 install/*.conf
chmod 755 . */
chmod 700 /etc/nisca archive
chmod 600 /etc/nisca/*

And if your server's on Windows, of course, you can just ignore all
that. :)

- Create the database to hold the statistics in by executing this command
(and do make sure MySQL is running beforehand, of course):

mysqladmin create stats

If you already have a database named "stats", you can give it another
name; just change the $database="stats"; line in "db.conf" to whatever
you want to call it, and put that name in the "mysqladmin create ____"
line above. db.conf is the only place you'll have to change the
database's name. You're welcome. The "create_stats" script will NOT run
if this database does not exist or does exist but is not empty.

- In MySQL, give the user your web server connects as (the $db_user
variable in "db.conf") the following permissions for the database you
just created:

Select, Insert, Update, Delete, Create,
Drop, References, Index, and Alter.

There are many ways to do this; I recommend the MySQL documentation
for help. :)

http://www.mysql.com/documentation/mysql/bychapter/manual_Privilege_system.html#Privilege_system

I wouldn't worry too much about giving your web server such high
privileges; it's only on the one database, and only the one user
who's allowed to connect to it. Unless you have untrustworthy
jackals roaming your server with root access, it's safe.... but
if you do, Nisca's probably the least of your security concerns. :)

phpMyAdmin is also a big help for those unfamiliar with MySQL
administration:

http://phpwizard.net/projects/phpMyAdmin/index.html

- Initialize the database structure by running this command from the
directory where you untarred this file:

install/create_stats.php

If you want to change the default admin password, edit create_stats.php
before you run this command. Look for the "$admin_pw=" line and change
its value to whatever you want for a password. It defaults to "change".
Also make sure its first line (#!/usr/bin/php -q) points to your
standalone PHP binary.

- Open the NISCA administration page in your browser ("admin/index.php").
The default administrator login is username "admin", password "change".
See below for details on how to configure NISCA using this interface.

- Move the "collect" script to the bin directory of your choice
(/usr/sbin, for example). This script collects data only from
localhost using the /proc/net/dev procfs file.

You CAN monitor "localhost" with both the collect and
snmp_collect scripts, but I don't know why you would unless you're
me. The collect script will store stats with the community blank
(that is, put into the database as ""), and snmp_collect will store
them under whatever community name you use to connect to localhost.
It won't screw anything up, but it's duplicated effort.

- Move the "snmp_collect" script to a bin directory, as with "collect."
This script uses SNMP to get data from some remote host(s) (which are set up
in the administration section). The script won't refuse to get data from
"localhost" through SNMP, but it will be *far, much* faster to do it by
reading /proc/net/dev directly with the "collect" script instead.

Don't leave a copy of either collector in the main Nisca directory;
they could be a security hole (if either collector script is run from
a browser, it'll lock up your web server).

***********************************************************************
* Be sure you've set up the local and SNMP interfaces to be monitored *
* in the configuration section before running the collector scripts!! *
***********************************************************************

Now, you have two choices. You can either run these two collectors as
daemons, or you can run them from crontab. If you want to use crontab,
edit the collectors and look for the "$runasdaemon" variable declaration
at the very top. Change it from "y" to anything else, then save and exit
the file. Add a job for them to crontab as you would for anything else,
and you're done. No crontab entries are needed if they run as daemons.

If you want to run them daemonically, start the collector(s) of your choice
at this point by running these commands either as root or your web server
user:

nohup /usr/sbin/collect & (for collection from localhost)
nohup /usr/sbin/snmp_collect & (for collection via SNMP)

This will create the file "nohup.out" in either the current directory
or your home directory if the current one can't be written to.
If this is run from a system startup script, it will go into "/".

If you like, you can run collect and snmp_collect from one of
your system startup scripts, like rc.local. Just be SURE to put a "&"
after it or your machine will never actually finish booting. :)

There is another option, though. The script "nisca_check" will run
a "ps" command and look for running collectors. If it doesn't find
either one, it starts them (unless you tell it not to start one or
the other of them). If you create a "crontab" entry for this script,
it can run every five minutes (or one minute, or seven hours) and
keep the scripts running, and then you don't need to change your system
init scripts. If you want to use it, set it up in the Global Configuration
administration section and move it to /usr/sbin/ or something.
The crontab entry might look something like this for every 5 minutes:

0,5,10,15,20,25,30,35,40,45,50,55 * * * * root /usr/sbin/nisca_check 2>&1 > /dev/null

(You only need the "root" in there if you're putting it in "/etc/crontab".)

There's also a companion script for nisca_check: "nisca_kill". This
also runs from crontab, and will kill off the collector(s) of your choice
at specific times so nisca_check can restart them. This was done to get
around the hideous non-UDP-socket-closing bug in either PHP or ucd-snmp.
The collection scripts create process ID files (in /var/run by default),
which are read by nisca_kill so it knows what process to kill off. And
yes, it checks first to make sure the PID is actually a Nisca collector
before it kills it; it is running as root, after all. :) Just add another
crontab entry like the one for nisca_check, but only like once a day.

And please. Don't make the mistake of running one of the collectors
with a browser... it *will* just lock up and you'll have to HUP your
web server.

- Wait a while (at least three "Delay" cycles) after starting the
collector(s).

- If you have MRTG logfiles you want to import, do them now using the
following command:

utils/mrtg_import <MRTG logfile> <hostname> <community> '<IF name>'

Put the interface name in single quotes if it contains slashes or backticks
or something. Whatever you put in for <hostname>, <community>, and
<interface name> must already be defined in the configuration. There
MUST also already be entries in the database for this host, community, and
interface. What the script does is import everything from the MRTG log
that's earlier than the earliest stamp in the database (so no data
overlaps, which would be a Bad Thing). You have to run it separately
for each interface you want to import data for. I know, very
annoying... but it can't automatically determine which hostname/IF name
to use based just on the log filename. Sorry.

If you have an MRTG log that was collected on a localhost interface
(via SNMP of course) and you want to put them into the *NON*-SNMP counter(s)
in NISCA (thus meaning you'd have to use a blank community), you should
specify the community as "localhost". Yes, this is a Hack. :)

Note that this script may put entries into the database which are less
than zero; this is all right because the report generator accounts for
that automagically (only the *interval* between each entry is important,
not the actual values). The only important thing is that the importer knows
exactly where the running total byte count starts so it can decrement it
from there; hence the need to have at least one entry inserted by the
collector(s) before importing. Be very careful when using this script;
make very sure you have all the command line options perfect before
hitting enter. Pretend it's a "mke2fs" command and treat it just as
carefully. :) There's a lot of error checking in it, but you can still
put the wrong data in for the wrong interface pretty easily; there's no
way to automatically check for that.

Once you've run this it will refuse to run again for the same
host/interface. Rather, it will run but not enter anything into the
database whose timestamp is later than or equal to the earliest stamp in
the database. Be sure you get it right the first time. :)

Note that MRTG stores its data thusly (from "rateup.c" in the MRTG
package):

"The .log file stores real history every five minutes for 31 hours,
then 'compresses' the history into 30 minute samples for a week, then
2-hour samples for 31 days, then daily samples for two years."

This means that everything earlier than 31 hours ago will only be put in
the database for every 30 minutes, everything earlier than a week before
now will be put in in 2-hour increments, and everything earlier than
that will only have an entry once a day. (Everything more than two
years old is, I assume, simply lost forever.) This can make your graphs
look kinda funky, like there's not much data for earlier periods.
That's because there isn't. There's nothing anyone can do about it.
MRTG does this to save disk space used by its logfiles; NISCA does not
do this, which is why it takes up so much more space. But I thought the
data granularity deserved to be as small as possible back to the
beginning of time, so no data "compression" is done by NISCA whatsoever.
(MRTG is more like an MP3, and NISCA is more like a WAV file, to make an
easily-understood analogy.. :)

- If you wish, you can put an appropriate ".htaccess" file into the admin/
directory to make it even more secure (I did this for all you ultra-
paranoid admins out there... :) You can also move the entire directory,
or rename it. Just change the "$location["admin"]" entry appropriately.

- A note about the "archive" directory. It *must* be writable by your web
server user (the user it runs as), and can be located anywhere on your
system. Just point your "nisca.conf" file to its location. This directory is
where compressed backup data will be stored when you trim the stats in
your database.

- Try "index.php" in your browser. It should work at this point if there
are at least two database entries.

- If you want to add a watermark image to your graphs, just make an
appropriate image -- corporate logo, copyright, clever quip, whatever --
and set the $location["wmimg"] variable in your nisca.conf file to its
location (full path/filename). It should be a greyscale JPG, PNG, or BMP,
but it'll get treated as 256-color greyscale anyway so it doesn't really
matter. Oh, and it should be pretty small; the bigger the watermark, the
longer it takes to emboss it onto the graph image. I've included a silly
little example image, "wm.png".

Although there is a function in PHP, ImageCopyMerge, which will do embossing,
it will only do it in PHP 4.0.6 or later. It also requires a newer version
of libgd. For those reasons, I wrote my own implementation of it from
scratch. So there are two functions in Nisca which will do this: icm(), and
add_watermark(). You'll find them on or about line 377 of "report.php".
The script should detect whether you have it or not all by itself.

Upgrade Procedure
-----------------

*** Brief instructions for people upgrading from 2.2 or 2.3 only ***

- Unpack the distribution.
- Kill your running collectors.
- Delete everything in your existing NISCA installation directory.
- Copy everything in the distribution to your newly-empty install directory.
- Edit the "nisca.conf" and "db.conf" files; change as necessary. See
"nisca.conf.explained" for a more detailed explanation of all the options.
After editing it, rename it to "nisca.conf".
- Run "move_niscaconf_to.php" if you don't want to install nisca.conf
into "/etc/nisca/".
- If you didn't run "move_niscaconf_to.php", move the nisca.conf and
db.conf files to /etc/nisca/.
- Run these commands as root to restore/create the necessary modes/permissions.
Run them *only* from the NISCA installation directory, and only if you
didn't run them after running "move_niscaconf_to.php" (which will give
you these same commands to run).
Replace "nobody" with whatever user your web server runs as.

chown nobody:root .
chown -R root:root *
chown -R nobody:root /etc/nisca archive
chmod -R 644 *
chmod 744 install/*.php utils/*
chmod 644 install/*.conf
chmod 755 . */
chmod 700 /etc/nisca archive
chmod 600 /etc/nisca/*

- Run the "update-to-2.3.2.php" script and wait for it to finish;
make sure it doesn't report any errors. It only changes your version number
in the database; shouldn't need to do any backup first, it's so simple.
- In the Global Variables admin section, you'll need to update the two "nohup"
commands (in the "nisca_check" section). The ".php" extension has been
removed from collect.php and snmp_collect.php; just remove ".php" from the
two "nohup" commands, and all will be well. You'll also need to update
any crontab jobs you have for this as well; nisca_kill and nisca_check
have also lost the .php extension.
- Restart the collector(s), or wait for your crontab job to do it.
- A note about the "archive" directory. It *must* be writable by your web
server user (the user it runs as), and can be located anywhere on your
system. Just point your "nisca.conf" file to it ($location["archive"]).
This directory is where compressed backup data will be stored when you
trim/delete the stats in your database.
- If you want a watermark image merged onto your graphs, see the end of the
Fresh Installation Procedure above.
- Just skip the rest of the upgrade procedure, and enjoy.

*** Detailed upgrade instructions for the enlightenment of all ***

- All the old (v1.2-v2.2) upgrade scripts have been removed from the
distribution. They're still available at the distribution site:
http://nisca.sourceforge.net/stable/old-updates/ contains them all.
v2.3's updater is an exception; it's not that important.
- Delete everything in your NISCA installation dir, no matter what version it is.
It's just easier if you remove everything and then copy the new files into
the empty directory. "nisca.conf" has changed, but it's fortunately very easy
to set up. You might want to save your .htaccess file too, if you made one
for the admin/ directory. Everything else is expendable; this includes the
collector scripts and all nisca subdirectories. Exceptions:

If upgrading from 1.3, rename your "functions.php" file to "functions.bak"
and remove everything else.

If upgrading from v1.2 or earlier, keep "functions.php" and "snmp_setup.php".

This assumes you haven't done any of your own tweaking of NISCA, but if you
have, it was probably to do something that works now, so it's best to
install all the new files then tweak them using your originals for a
model. The basic structure of just about every file has changed completely
(again), hint hint.

- Kill your running "collect" and "snmp_collect" scripts.
Don't worry too much about data gaps; the program makes up for them
by just averaging over a longer period of time. If you're using crontab
to run them, just make sure they don't attempt to run while you're doing
the upgrade.

- Uncompress the archive, then copy it over your existing installation.
If you're using Debian, you can refer to this message for hints on
where to put the package's various files:

http://lists.debian.org/debian-mentors-0102/msg00228.html

- Make sure the first line of each executable ".php" file points to your
standalone PHP binary (i.e., "#!/usr/bin/php -q"). This includes
"functions.bak" if you're upgrading from 1.3. If a .php file doesn't
have such a line, don't add one... :)

- Edit "nisca.conf". Change the pathname definitions to match where you
want to put the various scripts. Also edit "db.conf" and change it to
match your MySQL setup. These files should then go into "/etc/nisca/".
Thus, run these commands as root after editing "nisca.conf" and "db.conf":

mkdir /etc/nisca/
mv nisca.conf db.conf /etc/nisca/

If you put nisca.conf anywhere else, you'll have to run the script
"move_niscaconf_to.php" to change the location each of Nisca's scripts
gets nisca.conf from.

Correct file modes/permissions can be achieved with these commands as
root; make sure you're in your NISCA installation directory first!!!
(Replace "nobody" with the username your web server runs as.)

And if your server's on Windows, of course, you can just ignore all
that. :)

- Back up your existing database with:

mysqldump -a stats > backup.sql

(Note that the "-a" option only works with MySQL v3.23.xx and above.
If using an older MySQL, leave off the "-a".)

***IF UPGRADING FROM v1.1 OR EARLIER, START HERE***

- If you're upgrading from v1.1 or earlier, run the "update-to-1.2.sql"
script through mysql to update your database to the v1.2 format, thus:

mysql stats < update-to-1.2.sql

It may take quite a while to run, depending on how much data you have
already. and the new database will probably take up a bit more space
(more indices). If you're using v1.2 already, don't do this; just follow
the update-to-1.3 step below.

This WILL fail if you have duplicate data in the database already; that
is, if there's more than one row containing the same stamp, hostname, and
if_name values. If this happens, it's trouble. You'll have to go through
the data and remove duplicate entries before the update will work (a
"duplicate entry" is one which has the same values for "hostname",
"if_name", and "stamp" as another entry). There's no easy way to do this
but if you don't mind losing it, you can always delete all entries with
that hostname and interface name in them and then run just the part of
update-to-1.2.sql that starts with:

alter table stats add primary key host_if (stamp, hostname, if_name);

Paste everything from there (including that line) to the end of the file
into a command-line mysql session ("mysql stats" as root) after fixing
the duplicates and everything will be fine. Since you're now at v1.2...

***IF UPGRADING FROM v1.2, START HERE***

- If you're upgrading from v1.2 or earlier, run the "update-to-1.3.sql"
script to update your database to the v1.3 format, thus:

mysql stats < update-to-1.3.sql

Once you've run it once, don't do it again... :) If for some reason
something dreadfully horrible goes wrong, restore the database with:

echo y|mysqladmin drop stats
mysqladmin create stats
mysql stats < backup.sql

If everything went okay, you can delete backup.sql if you want. It's very
likely to be a very large file.

Also, you should re-run the "snmp_setup.php" script (but first be sure to
change its "require_once" line to "functions.bak" instead of
"functions.php", assuming that's what you moved your old functions.php
to).

The format for the $interfaces[] array in functions.php changed
completely in v1.3, so you need to reimport the list of interface names
in the new format. Don't worry, this won't affect any data you already
have in your database.

Once you've run snmp_setup, cut & paste the output into "functions.bak"
so the upgrade script will import them correctly. The $hostname[] array
shouldn't need changing. Since you're now at v1.3...

***IF UPGRADING FROM v1.3, START HERE***

- If you're upgrading from v1.3 or earlier, edit the "update-to-2.0.php"
script and remove the line that will keep it from running before you read
this. (This was just so people wouldn't screw anything up thinking
"Oh, all I have to do is run this handy script here.") You can also change
the default administrator password here (the $admin_pw variable) so your
system will never have an admin password known to the world.

Run the "update-to-2.0.php" script as root to upgrade your database to
v2.0. This will convert your existing stored reports to the new format,
store all the config variables from "functions.bak" into the "config"
table of the database, store all your SNMP variables into the
"interfaces" table, store all your localhost (non-SNMP) variables into
the "localhost" table, and add/populate the "community" column in the
"stats" table. (This can take awhile; be patient with it :)

FROM THIS POINT ON, all your config options (except those in "db.conf")
are in the database; you have to use the "admin/index.php" script to
configure your NISCA installation now.

After verifying that your new installation works, you can remove
"functions.bak"; it will never be used again. Since you're now at v2.0...

***IF UPGRADING FROM v2.0, START HERE***

- Edit the "update-to-2.1.php" script and remove the line that will keep it
from running before you read this. (This was just so people wouldn't
screw anything up thinking "Oh, all I have to do is run this handy script
here.")

Run the "update-to-2.1.php" script as root to upgrade your database to
v2.1. This will convert your existing statistics to the new format, and
it can take awhile; be patient with it. :)

***IF UPGRADING FROM v2.1, START HERE***

- Edit, then run the "update-to-2.2.php" script and wait for it to finish;
make sure it doesn't report any errors.

- You can get rid of "snmp_setup.php" if you still have it at this point;
it's useless from here on.

***IF UPGRADING FROM v2.2 OR v2.3, START HERE***

- Run the "update-to-2.3.2.php" script and wait for it to finish;
make sure it doesn't report any errors.

- In the Global Variables admin section, you'll need to update the two "nohup"
commands (in the "nisca_check" section). The ".php" extension has been
removed from collect.php and snmp_collect.php; just remove ".php" from the
two "nohup" commands, and all will be well. You'll also need to update
any crontab jobs you have for this as well; nisca_kill and nisca_check
have also lost the .php extension.

- Don't run the "create_stats.php" script if you have existing data; it will
refuse to run.

- Restart the new "collect" and/or "snmp_collect" scripts.
You probably want to run the collectors with

nohup collect &
nohup snmp_collect &

especially if you're running it from an X-windows terminal. This should
keep the collector from dying by making it ignore all hangup signals
and increasing its scheduling priority by 5. If you don't understand,
don't worry; just trust me :) You still need to put the "&" on the end.
This will create the file "nohup.out" in either the current directory
or your home directory.

0,5,10,15,20,25,30,35,40,45,50,55 * * * * root /usr/sbin/nisca_check 2>&1 > /dev/null

(You only need the "root" in there if you're putting it in "/etc/crontab".)

There's also a companion script for nisca_check: "nisca_kill". This
also runs from crontab, and will kill off the collector(s) of your choice
at specific times so nisca_check can restart them. This was done to get
around the hideous non-UDP-socket-closing bug in either PHP or net-snmp.
The collection scripts create process ID files (in /var/run by default),
which are read by nisca_kill so it knows what process to kill off. And
yes, it checks first to make sure the PID is actually a Nisca collector
before it kills it; it is running as root, after all. :) Just add another
crontab entry like the one for nisca_check, but only like once a day.

NOTICE: the new config format doesn't require you to kill and restart
the collectors when you change config options (see "admin/index.php" to
configure your system). All config options are now re-read every fetch
cycle.

- The "update.sql" script was just for version 1.2; you can delete it.
"update-to-1.2.sql" is an exact copy of it.

- If you want a watermark image merged onto your graphs, see the end of the
Fresh Installation Procedure above.

- See the end of this file for instructions on configuring NISCA with the
new web interface.

*What If Errors Occur?*
-----------------------

This is a difficult topic. So many things can go wrong. This is a list of
some of the most common ones I see, and ones I anticipate. Note there's
only one problem listed now; that's because the others that were here
have been worked around in the code now.

-------------------------------------------------------------------------------
- Symptom: snmp_collect does absolutely nothing and just exits as soon
as you start it.

- Cause: Most likely, you don't have the ucd-snmp utilities installed or
set up right.

- Solution: Install ucd-snmp. See PHP_HINTS.html for details. Then make sure
your nisca.conf is set up right; the $location["bindir"] tells Nisca where
to look for them.
-------------------------------------------------------------------------------

*Configuration Procedure*
-------------------------

For ease-of-configuration comparison purposes, you might want to look at
this link:

http://people.ee.ethz.ch/~oetiker/webtools/mrtg/reference.html

Then come back here and read on. :)

Note: most of this is documented in the online help pages; click on the
"Help Me!" button on any page to get help for that page.

- First a note about bits and bytes. Nisca does both, in various
combinations, for many functions. Whenever it displays something like
"b/sec", that means "bits" (lower-case "b"). When the B is upper-case,
it means "bytes". So "K bps" is kilobits per second, "MB/sec" is megabytes
per second, etc. This applies *everywhere* in Nisca. If it's "b" it's
bits; if it's "B" it's bytes.

- Open "admin/index.php" in your browser, or click on the "Click here for
NISCA administration" link on the main index page.

- Enter the username "admin" and the password "change" on the login form.
You have to have cookies enabled to use the admin functions, sorry...
but even Lynx does cookies. :) If you just can't stand cookies, you
could hack your "security.php" to disable sessions and authentication,
and just use a ".htaccess" file in the admin directory. Oh, also the
login* and logout* scripts would require hacking. And it just occurred
to me that you could *probably* just put "$location["functions"]" in
your "nisca.conf" file for the "$location["security"]" variable, but
I have NOT tested this so be careful. Oh; you'd have to hack it
to add a value for "$username", although that variable isn't used
anywhere important to non-authentication functions.

- Welcome to the admin menu. First, if you didn't already do so, change the
administrator password. Click on "User Accounts", select "admin" under
"Change a User's Password", enter the same password in both boxes, and
hit "Change Passsword". You cannot *delete* the "admin" account; this is
so you'll always have a way into it. But you can add as many other
accounts as you want (they'll all have full admin access); then, return
to the administration menu. See the "Help Me!" button on this page for
detailed instructions.

- If this is your first install of NISCA, you probably want to set up the
global options first, so click on "Global Options." Each variable is
thoroughly explained on this page; read each one and set it accordingly,
then click "Update Settings". If you want to use the "nisca_check"
script to keep your collectors running (which you only need to do if
they die on you unexpectedly now and then), fill in the fields at the
bottom of the form; otherwise you can just leave them as they are
because they'll never get used.

- If you're monitoring "localhost" without SNMP (that is, you want to run
"collect"), click on "Localhost Interfaces Monitored". Select the
interfaces you want to monitor and click "Go". The list is generated
dynamically; it will always be a list of every available network
interface on your machine, some of which you probably want to ignore
(like dummy0 and lo0). See the "Help Me!" button on this page for detailed
instructions.

- If you're monitoring hosts via SNMP (that is, you want to run the
"snmp_collect" script), click on "SNMP Hosts & Interfaces Monitored".
Initially, there will be no configured hosts shown. Add a new host
by entering its IP or hostname (with FQDN if required) in the text box and
hitting enter. If you're upgrading, all the hosts you were monitoring
before should appear in the "SNMP Hosts Already Configured" table;
click on the "IFs" button next to the host you want to change, or
the "Del" button next to a host you want to delete completely. See the
"Help Me!" buttons on the pages that follow for detailed instructions.

- If you want to remove unneeded or unwanted or too-much-space-consuming
statistics from your database, you have two options: deleting stats,
or "re-averaging" them. Either can be done for all entries or only those
which fall within a certain time range. These operations can create an
archived backup, gzip-compressed, so you can change your mind and
restore them at a later date if you find you need more-detailed statistics
from some period in the distant past. Creating an archive is optional,
and defaults to "yes".

http://www.isthisthingon.org/nisca/Averaging.html is a page
which demonstrates the benefits of re-averaging statistics.

To use the Re-Averaging method, Click on "Collected Stats Re-Averaging
Utility". See the "Help Me!" button on this page for detailed
instructions.

To use the Deletion method, Click on "Collected Stats Deletion
Utility". See the "Help Me!" button on this page for detailed
instructions.

- Stored reports. Reports can be saved (but not replaced) from the
index page, but you can only edit or delete them from the admin pages.
Click on "Stored Reports", then select the report you want to edit.
Change the report's configuration as desired, then click "Save Updated
Report". Click "Delete the report _____" to delete the report completely.
Click "Reset the form..." to restore all values on the form to their
initial (saved) configuration. It's that easy. See the "Help Me!"
button on this page for detailed instructions.

- Sometimes, you might get confused about which config files ("nisca.conf"
and "db.conf") your installation is using, or have some question about
how they're set up, or are just curious, or something. Click on the link
"Display Hardcoded Config Options" and you'll be given a list containing
every variable which is set in those two files and their current value,
thus providing some small hint as to which files it's actually using.
And actually, you can even add your own variables to the "$var_set"
array which is defined in the "adm_showconf.php" script to have them
displayed as well if, for example, you want to keep an eye on the
global "$interfaces" variable for some arcane reason.

- There's also a link here, in nice friendly green, to the Help topic
index. Click there to browse through all the help files.

- The only other admin options are "Log Out" and "Return to NISCA Without
Logging Out". Both will return you to the main index form, but one
logs you out of the administration section (by deleting your cookie and
session information), and one doesn't. :)

Contact Information
-------------------

If problems develop or you just want to send humble thanks, you can email
me at phee@isthisthingon.org and I'll see if I can help; no promises
though... :) (Alternate address if that one doesn't work: brett@fnord.org)

I do also have a Bugzilla repository set up for this project:

http://www.isthisthingon.org/bugzilla/

Please make all bug reports there.