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. :)
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 statsIf 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. :)
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.
install/create_statsIf 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.
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.
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 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:
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 "/".
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:
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".)
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.
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.
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):
"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.. :)
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
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/*
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.
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.
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.)
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
(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***
mysql stats < update-to-1.2.sqlIt 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.
***IF UPGRADING FROM v1.2, START HERE***
mysql stats < update-to-1.3.sqlOnce 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.
***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***
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.
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:
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".)
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.
 | |
| 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.