Welcome to NISCA. Here's how to install it.
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 (see the PHP_HINTS file for information about that subject). I've never used a precompiled binary release of... well, anything but X... so I have very little idea how to tell you how to do it. :)
Here's what all you need; some is required, some optional.
| Package | Version | Footnote |
|---|---|---|
| Apache | v 1.3.x | 1 |
| MySQL | v 3.23.x | |
| PHP | v 4.x.x | |
| zlib | v 1.1.4 | |
| UCD SNMP | v 4.2.3 | 2 |
| libGD | v 1.8.x | 3 |
| libJPEG | v 6b | 4 |
| libPNG | v 2.1 | 5 |
| The FreeType Library | v 1.x or 2.x | 6 |
| The Zend Optimizer | ? | 7 |
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. It also requires that you have the "register_globals" setting in php.ini set to "On". Sorry. :)
Make sure "phtml" files can be executed in this directory (Apache configuration).
Also make sure Apache knows to treat "index.phtml" as an index file
(add "index.phtml" 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 JPGs in it.
Do whatever you want with the "docs" directory. :)
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.
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.
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 it 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:
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 them or your machine
will never actually finish booting. :)
There is another way, 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/local/sbin or something.
The crontab entry might look something like this for every 5 minutes:
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.
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 counts 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):
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 469 of "report.phtml".
Nisca will detect whether you have it or not all by itself.
EXCESSIVELY-brief instructions for experts upgrading from 2.3.x or 2.4 only
Brief instructions for people upgrading from 2.3.x or 2.4 only
Detailed upgrade instructions for the enlightenment of all
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.
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.)
(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***
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:
***IF UPGRADING FROM v1.2, START HERE***
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.
***IF UPGRADING FROM v1.3, START HERE***
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 "*.conf") are
in the database; you have to use the "admin/index.phtml" 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.
***IF UPGRADING FROM v2.0, START 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***
***IF UPGRADING FROM v2.2 OR v2.3.x, START HERE***
There is another way, 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/local/sbin or something.
The crontab entry might look something like this for every 5 minutes:
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.phtml" to
configure your system). All config options are now re-read every fetch cycle.
Fresh Installation Procedure
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. :)
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.
Select, Insert, Update, Delete, Create,
Drop, References, Index, and Alter.
There are many ways to do this; I recommend
the MySQL documentation
for help. :)
install/create_stats
If you want to change the default admin password, edit create_stats
before you run the above 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/local/bin/php") points to
your standalone PHP binary.
Be sure you've set up the local and SNMP interfaces to be monitored
in the configuration section before running the collector scripts!!
nohup /usr/local/sbin/collect & (for collection from localhost)
nohup /usr/local/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 "/".
0,5,10,15,20,25,30,35,40,45,50,55 * * * * root /usr/local/bin/nisca_check 2>&1 > /dev/null
(You only need the "root" in there if you're putting it in "/etc/crontab".)
utils/mrtg_import <MRTG file to import> <hostname> <community> '<interface 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.
"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.. :)
Upgrade Procedure
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/*
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" to change the location each of Nisca's scripts
gets nisca.conf from.
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. :)
mysqldump -a stats > backup.sql
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.
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.
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.
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/local/bin/nisca_check 2>&1 > /dev/null
(You only need the "root" in there if you're putting it in "/etc/crontab".)
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.
 | |
| Symptom: | snmp_collect does absolutely nothing and just exits as soon as you start it. |
|---|---|
| Cause: | Most likely, you don't have the required SNMP utilities installed or set up right. |
| Solution: | Install ucd-snmp or net-snmp. See PHP_HINTS for details. Then make sure your nisca.conf is set up right; the $location["snmpdir"] tells Nisca where to look for them. |
| |
| Symptom: | Even though you KNOW you're logging in with a valid user/password, you can't get past the login page. |
| Cause: | php.ini (mis)setting. |
| Solution: |
Edit your "php.ini" file. The Apache module and the standalone
binary can use different ini files. Run "php -i|grep php.ini" from a command
prompt on the server to see which ini file it thinks it should be using.
To see which one the Apache module is using, open the "test.phtml"
page that comes with Nisca in a browser and you'll find it about halfway down the
table on that page. Once you've found it or them, edit it or them and change
its or their "register_globals" and "register_argc_argv" entries to "On".
Then restart Apache and any running collector daemons, and the new settings
will be active... and your problem will probably go away.
If not, it's possible the session variables aren't working right on your machine. This is probably also in the php.ini file, "session.use_cookies". I have mine set to 1; the alternative is 0, which makes sessions be server- stored instead of stored in your browser as cookies. If you change this setting, beware; it could break other applications on that server that need it set the other way. |
| |
For ease-of-configuration comparison purposes, you might want to look at this link. 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.
Here 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.
Note that the fancy Javascript interface selection boxes aren't used on the reports administration page. It's just too unstable to trust in an administrative capacity thanks to the shoddy Javascript support in damn near every browser in existence.
I do also have a Bugzilla repository set up for this project. Please make all bug reports there.
