Installing NMIS 4.3.x
on GNU/Linux (CentOS 5) and Debian 5.0 "Lenny"
by C. Terrell Prudé, Jr.
v1.1: April 1, 2010
This document will describe how to install NMIS 4.3.x on GNU/Linux distros. The example distribution was originally CentOS 5, because that's what I run. However, we also include instructions for how to install NMIS on Debian 5.0 "Lenny".
My assumptions about the audience:
The reader is assumed to have a working knowledge of UNIX or GNU/Linux systems, how to compile software, and what PERL is. While NMIS is written in PERL, you do not need to be a "PERL hacker" to install this program and make it work.
Where there are differences between CentOS 5 and Debian Lenny, this document will use the following convention.
Instructions specific to Red Hat/CentOS will be in RED.
Instructions specific to Debian will be in SKY BLUE.
Instructions applicable to any distro will remain in BLACK.
Also, this document will use the <nmisdir> tag to refer to NMIS's installation directory. The default place is /usr/local/nmis4.
Let's get to it!
First, install your GNU/Linux distribution. With both CentOS 5 and Debian, I do a basic installation with no extra stuff. That means no GNOME, KDE, "Server" packages, or anything else. Just a base installation is all that's necessary.
If you're running CentOS or any other Red Hat-derived distribution, be sure that SELinux is turned off. It's just a lot easier that way. Also, I like to turn off the default Red Hat firewall. It is assumed that the reader knows how to do both of these; if not, there are plenty of resources on the Web describing how.
Now that you have your system set up, there are some things that we need to install to make NMIS work. Some of these are also to make RRDtool, which NMIS also uses, compile. These will come from your distribution's repositories. For users of previous versions of NMIS, note that MySQL is now a required item! Fortunately, MySQL is easy to deal with for NMIS's purposes.
For Red Hat-based distros (e. g. CentOS), we do this.
$ su - root
# yum install autoconf automake gcc
# yum install cairo cairo-devel \
pango pango-devel \
glib glib-devel \
libxml2 libxml2-devel \
gd gd-devel \
mysql*
For Debian-based distros, we do this.
# su root # apt-get install autoconf automake gcc make # apt-get install libcairo2 libcairo2-dev libglib2.0-dev libpango1.0-dev libxml2 libxml2-dev # apt-get install ^mysql*
Note that caret in last line for installing MySQL on Debian-based distros. We must include the regexp character "^" (caret) otherwise APT will end up trying to install "*mysql*" instead of "mysql*". APT will ask you during this installation for a "root" password for MySQL. It's not mandatory, but it is recommended.
We also need the Apache HTTP Server.
# yum install httpd (for Red Hat-derived distributions) # apt-get install apache2 (for Debian-derived distributions)
The official NMIS documentation says that the Korn Shell (ksh) is required. I have found that the Bourne-Again Shell (bash) works just as well.
We now need to get a copy of RRDtool, by Tobi Oetiker. The NMIS development team recommend that you download the latest stable RRDtool and compile it, instead of using whatever version of RRDtool may come with your distribution. The latest version of RRD is available at http://oss.oetiker.ch/rrdtool/.
Unpack the RRDtool tarball. I'm using v1.4.2 for this example. And do your standard ./configure before you compile, like this.
# ./configure --enable-shared --prefix=/usr/local/rrdtool
When this step is finished, you should see something like this:
ordering CD from http://tobi.oetiker.ch/wish .... just kidding ;-)
----------------------------------------------------------------
Config is DONE!
With MMAP IO: yes
Build rrd_getopt: no
Static programs: no
Perl Modules: perl_piped perl_shared
Perl Binary: /usr/bin/perl
Perl Version: 5.8.8
Perl Options: PREFIX=/usr/local/rrdtool LIB=/usr/local/rrdtool/lib/perl/5.8.8
Ruby Modules:
Ruby Binary: no
Ruby Options: sitedir=/usr/local/rrdtool/lib/ruby
Build Lua Bindings: no
Build Tcl Bindings: no
Build Python Bindings: no
Build rrdcgi: yes
Build librrd MT: yes
Use gettext: yes
With libDBI: no
Libraries: -lxml2 -lcairo -lcairo -lcairo -lm -lcairo -lpng12 -lglib-2.0 -lpangocairo-1.0 -lpango-1.0 -lcairo -lgobject-2.0 -lgmodule-2.0 -ldl -lglib-2.0
Type 'make' to compile the software and use 'make install' to
install everything to: /usr/local/rrdtool.
... that wishlist is NO JOKE. If you find RRDtool useful
make me happy. Go to http://tobi.oetiker.ch/wish and
place an order.
-- Tobi Oetiker <tobi@oetiker.ch>
----------------------------------------------------------------
So far, so good. You have all the things RRDtool needs to compile. Let's keep going.
# make # make install
Now, rrdtool should be installed the way NMIS likes it.
And speaking of NMIS, if you haven't already downloaded it, the latest version (v4.3.6e at time of this writing) is available at http://nmis.co.nz.
Unpack the NMIS tarball and install the SNMP_Session PERL module. We have to install SNMP_Session manually, not from within CPAN. No, I don't know why, but I know that this works.
# tar -xvzf nmis-4.3.6e.tar.gz # cd nmis-4.3.6e/ # cd install # tar -xvzf SNMP_Session-1.12.tar.gz # cd SNMP_Session-1.12 # perl Makefile.PL # make # make test # make install
At this point, I like to copy this entire directory to the /usr/local directory tree and make some symlinks, like so.
# cp -Rpv nmis-4.3.6e/ /usr/local/ # cd /usr/local # ln -s nmis-4.3.6e nmis4 # ln -s nmis4 nmis
My <nmisdir> is, in this case, /usr/local/nmis-4.3.6e. NMIS by default expects a /usr/local/nmis4 directory, so that's why I make that symlink. Additionally, since I've been using NMIS for five years and am getting old 'n' crotchety, I also make a /usr/local/nmis, so it looks to me like it did in the NMIS 3.x days. Old habits die hard, you know. :-)
The <nmisdir> tree needs to be owned by the user "nmis", which doesn't exist yet. Furthermore, the userID under which Apache runs ("apache" on Red Hat and "wwc-data" on Debian) needs to have access to the <nmisdir> tree. So, we need to add to make these things happen. We are still in the /usr/local directory at this point.
# useradd nmis # chown -Rv nmis:nmis <nmisdir> # chmod -Rv 775 <nmisdir>
Now we add the Apache userID to the nmis group.
# usermod -G nmis apache (Red Hat/CentOS) # usermod -G nmis www-data (Debian)
NOTE: the stuff that used to be sitting in <nmisdir>/conf in previous NMIS tarballs is now located in <nmisdir>/install. Since we're doing a new installation here, we'll just copy everything in <nmisdir>/install to <nmisdir>/conf.
BUG NOTE! There is a bug in the included nodes.csv file. There should be 15 columns in this file, and indeed, in the "localhost.localdomain" entry, there are in fact 15 items in that line. PROBLEM: there are only 14 in the header! Whoops....
This obiously needs to be fixed. The missing header item is "runupdate". Go ahead and use your favourite text editor to add the word "runupdate" between "role" and "services. Remember to to use a single tab character, not spaces, in between column entries.
Now, let's get busy with the PERL modules. NMIS, being written in PERL, uses several PERL subroutines, known as "PERL modules". These are available from the Comprehensive PERL Archive Network, known affectionately as "CPAN". No, not "C-SPAN", I mean "CPAN". :-)
Here's how we get to CPAN.
# perl -MCPAN -e "shell"
You will be asked a bunch of questions. It is safe to select all the defaults. Indeed, if you don't know what the questions are asking you, selecting the defaults is strongly recommended! HOWEVER, with some distros (Debian is a notable exception) you must select some CPAN mirrors, because that's where you're going to download your PERL modules from. Choose those which are closest to you. For me, that's North America; for Peruvians and Brazilians, that's South America; and so on.
On some distros like Red Hat/CentOS, you should start with this command. Debian doesn't seem to require it, which is good, because the command doesn't work on Debian's CPAN client anyway. :-)
$cpan> o conf set LC_ALL=C (Red Hat/CentOS)
Additionally, I like to ensure my CPAN client program, which is what we're running ("CPAN.pm"), is the latest, up-to-date version. This will take a while and ask for several other "dependency" modules. Just tell it "yes" each time.
$cpan> install Bundle::CPAN $cpan> reload cpan
OK, we've got CPAN prepped, locked, and loaded. :-) Now, install all the PERL modules listed in the official NMIS docs, like so.
$cpan> install Time::HiRes $cpan> install Time::ParseDate $cpan> install Statistics::Lite $cpan> install Net::SNPP $cpan> install Net::SMTP $cpan> install Net::DNS # Only required if using DNS lookups for geoplots $cpan> install IPC::Shareable # Only required if multithreading on Unix/Linux. $cpan> install BSD::Resource # Only required if multithreading on Unix/Linux. $cpan> install GD::Graph # Only required for Capacity Planning tool. $cpan> install Net::EasyTCP # Only required for master slave operation. $cpan> install Data::Dumper # Required for cgi metrics stats caching $cpan> install Cache::Mmap # required for caching cgi metric stat
Here's where things can get a little tricky. There are in fact some additional PERL module dependencies that NMIS has. However, the official NMIS docs don't tell you about them! No problem; here they are.
$cpan> install Proc::Queue $cpan> install Date::Parse $cpan> install Date::Calc $cpan> install Math::Round $cpan> install DBI
Now, you're ready to exit CPAN.
$cpan> exit
For some reason, on some distros, NMIS will not be able to find the file RRDs.pm, which is a PERL module that comes with RRDtool, and that NMIS needs to be able to find and use. I ran into this problem. Fortunately, the NMIS development team included a small hack to take care of this. The line explicitly "uses" the RRDs.pm file in the /usr/local/rrdtool directory tree, but you have to uncomment that line in the NMIS program files themselves. Kinda tedious.
One way to quickly accomplish that is to run the following script within /usr/local/nmis/bin and /usr/local/nmis/cgi-bin. You can just cut 'n' paste it into your terminal. Since I'm running GNU/Linux, I happen to be using bash, as you no doubt guessed. :-)
#!/bin/bash for file in *.pl do sed -i 's|#use lib "/usr/local/rrdtool|use lib "/usr/local/rrdtool|g' $file done
NMIS now stores its events in a MySQL database. Therefore, we now need to prepare MySQL.
MySQL uses a config file called "my.cnf". Debian systems come with one that is NMIS-friendly out of the box. However, Red Hat systems like CentOS currently do not. Fortunately, the NMIS team thoughtfully included a my.cnf file that's perfect for NMIS on Red Hat/CentOS. Here's how we apply it.
First, back up the default /etc/my.cnf:
# cp -p /etc/my.cnf /etc/my.cnf.orig (Red Hat/CentOS)
Go to <nmisdir>/install and copy over the my.cnf file that was designed for NMIS.
# cp -p my.cnf /etc/ (Red Hat/CentOS)
Now we configure MySQL with a password. We do this because we do not want to get "pwned" by leaving our database wide open! Just substitute <password> with whatever strong password you like. Since I use special characters in my passwords, I enclose the password in single quotes.
Note: there are four commands. On Red Hat/CentOS, all four are needed. On Debian, only the fourth one is needed. This is because Debian not only prompts you for a MySQL "root" password when you install MySQL, it also automatically starts MySQL when the installation's done.
# service mysqld start (Red Hat/CentOS) # chkconfig mysqld on (Red Hat/CentOS) # mysqladmin -u root password '<password>' (Red Hat/CentOS) # mysqladmin -u root -h '<yourhost.domainname>' password '<password>' -p
For that second "mysqldmin" command, MySQL will prompt you for the password you entered in the first "mysqladmin" command above it. On Debian distros, this will be the MySQL "root" password you entered at MySQL installation time.
Also note: the my.cnf file for NMIS is configured to allow connections to the loopback address only (typically 127.0.0.1 on most systems). If you specify your actual hostname (i. e. other than localhost), you might get the following error:
error: 'Lost connection to MySQL server at 'reading initial communication packet', system error: 111'
There are two easy ways to deal with this. The first is to make an entry in your /etc/hosts file that points to your loopback address. The other is to just specify localhost in your "mysqladmin" command. This scenario can easily happen for those who are re-purposing an existing server to do NMIS duty, and yes, it happened to me once.
Now that we have a properly protected MySQL database, we need to make the actual DB tables that NMIS uses. Fortunately, the NMIS development team was kind enough to give us a script to run that does this. The script lives in <nmisdir>/install, and thus it should also be in nmisdir>/conf. Make sure you're in one of these two directories, and do the following.
# mysql -u root -p < nmis-event.sql
You will be asked for that MySQL password that you just entered, above. After entering it correctly, the tables will be made quickly.
You should now be set. As an initial check, I like to go into my <nmisdir>/cgi-bin directory and run
# ./nmiscgi.pl
and see what happens. If all is working, you should get a bunch of HTML code. If you don't, it'll probably be NMISCGI complaining that it cannot find a given PERL module. Review your steps above; you likely missed something. The important thing to do is not to panic.
Once this is working, you're ready to head into the <nmisdir>/bin directory and do the "acid" test.
# ./nmis.pl type=config debug=true
You should get what looks like a long checklist with "OK" at the end of every check. If you do this, then NMIS itself is configured correctly.
Now, we need to set up the Web server so that folks can actually *get to* NMIS and look at the data. :-) That means generating an Apache config file pointing to the NMIS directory tree. NMIS itself is smart enough to be able to generate this for us. Thanks, NMIS team!
All you have to do is this.
./nmis.pl type=apache > 00nmis.conf
You can use whatever filename you want instead of "00nmis.conf". In this file, comment out the following lines at the bottom by putting hash marks ("#") in front of them. If you don't, Apache will complain and refuse to start. I once forgot to do this and nearly drove myself nuts trying to troubleshoot the problem.
*** URL required in browser *** http://<yourhostname.yourdomain.com>/cgi-nmis4/nmiscgi.pl ***
After commenting those lines out, copy this file to your Apache configuration directory. This is very distro-dependent. On CentOS and other Red Hat derivatives, this directory is /etc/httpd/conf.d/. On Debian-style distributions, it's /etc/apache2/sites-available/, and you must also make a symlink to that file from /etc/apache2/sites-enabled.
Note that Debian has an existing "000-default" symlink in /etc/apache2/sites-enabled. Remembering how Apache processes config files, we must rename this symlink to something like "default" without the "000"! This is so "00nmis.conf" will be seen first. Otherwise you'll get the Apache default home page ("It Works!") instead of the NMIS home page. Not what we want. :-)
Debian systems have one other requirement for this file. Two lines need to be edited, specifically the "ErrorLog" and "CustomLog" lines. The lines as they are point to locations present in Red Hat-style distros (this is really Red Hat following Apache's upstream functionality). Debian doesn't do that. Therefore, Apache will complain and refuse to start unless we make these tweaks.
Since Debian puts its Apache logs under /var/log/apache2, I edited these lines to read as follows.
ErrorLog /var/log/apache2/nmis-dev-error_log CustomLog /var/log/apache2/nmis-dev-access_log common
Now that your NMIS config file for Apache is present--and if necessary, tweaked for your distro--start Apache itself. If it's already started, then restart it. How to do this is also very distro-dependent. Unlike me, BSD and Solaris users don't need no steenkin' startup scripts. :-)
Now, fire up your favourite Web browser (mine's Konqueror) and surf to your server. The URL will be "http://yourhostname.domain.tld/cgi-nmis4/nmiscgi.pl". Of course, if you have no DNS or hosts lookup for this box yet, just replace "yourhostname.domain.tld" with your new NMIS server's IP address.
You should get the NMIS Dashboard. If you don't, then check to make sure you included the "/cgi-nmis4/nmiscgi.pl" in the URL. Yep, I've made that mistake too many times to count. It's easy to forget, so make sure you include it.
Congratulations! It works, and you're almost done. We're in the home stretch.
Now we have to tell NMIS to run the data collection every so often. For that, we use a cron job. Edit root's crontab ("crontab -e" at the root shell), like so. Remember to change the first line, the "MAILTO" line, to contain your actual email address.
MAILTO=WhoeverYouAre@yourdomain.tld ###################################################### # Run the Reports Weekly Monthly Daily ###################################################### 54 23 * * * /usr/local/nmis/bin/run-reports.sh day health 55 23 * * 0 /usr/local/nmis/bin/run-reports.sh week health 5 0 1 * * /usr/local/nmis/bin/run-reports.sh month health 5 0 1 * * /usr/local/nmis/bin/run-reports.sh month avail 0 18 * * * /usr/local/nmis/bin/run-reports.sh day response 57 23 * * 0 /usr/local/nmis/bin/run-reports.sh week outage ###################################################### # Run Statistics Collection - every 5 minutes */5 * * * * /usr/local/nmis/bin/nmis.pl type=collect mthread=true maxthreads=64 ###################################################### # Run the update once a day and then update the links file 30 20 * * * /usr/local/nmis/bin/nmis.pl type=update mthread=true maxthreads=8 30 21 * * * /usr/local/nmis/bin/nmis.pl type=links ##################################################### # Run the interfaces four times an hour with Thresholding on!!! */15 * * * * /usr/local/nmis/bin/nmis.pl type=threshold mthread=true maxthreads=16 ###################################################### # Check to rotate the logs 7am every day 0 7 * * * /usr/sbin/logrotate /usr/local/nmis/conf/logrotate.conf ################################################## # save some stuff for backup every day 0 8 * * * crontab -l > /usr/local/nmis/conf/crontab.root # These file locations are Red Hat-specific. # For Debian, I use /etc/apache2/conf/httpd.conf # and /etc/apache2/sites-available. Un-comment and adjust for # your distro as needed. #0 8 * * * cp /etc/httpd/conf/httpd.conf /usr/local/nmis/conf/httpd.conf.backup #0 8 * * * cp /etc/httpd/conf.d/00nmis.conf /usr/local/nmis/conf/00nmis.conf.backup #0 8 * * * cat /etc/syslog.conf > /usr/local/nmis/conf/syslog.conf.backup
Again, this file was originally generated for Red Hat / CentOS. The lines to change for other distros (e. g. Debian) are the last three. Everything else should be fine.
After you're done, issuing a crontab -l is a good idea to make sure it's all there. Note that crontab -e on most GNU/Linux distros uses the traditional "vi" editor, whereas on Debian, "nano" is used.
Note that there is a reference in this crontab to a <nmisdir>/conf/logrotate.conf file. That file contains a reference to <nmisdir>/logs/ciscopix.log. This is for those who run Cisco PIX/ASA Firewalls. Unfortunately, this file is not in the tarball for NMIS, so you'll get a non-fatal "Hey, there's no ciscopix.log file for me to logrotate!" every day. Fortunately, that's easy to fix.
# touch <nmisdir>/logs/ciscopix.log
And now, go ahead and add your hosts to NMIS. There's a nice GUI for doing that which is pretty easy to use. Hey, if an MCSE like me can figure this out, anyone can. :-)
Time to celebrate! You're done! Enjoy your shiny new NMIS installation, and be sure to thank the teams that brought it to you. That would be the NMIS development team and Tobias Oetiker.
Copyright (C) 2010 C. Terrell Prudé, Jr.
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is available from the Free Software Foundation at their Web site, http://www.fsf.org/.