Unnoc version 1.0.10.1 2007-07-11 Jason Schoonover http://unnoc.org For Security info, see the doc/SECURITY file. Very important!! For legal and license info, see the doc/LICENSE and doc/LEGAL file. For the impatient, see the INSTALL.QUICK For the VMware appliance docs, see doc/README.vmware-appliance. INSTALLATION 1. System software installation The following server software is required by Unnoc: Apache 1.3.x or higher PHP 4.x or higher MySQL 4.x or higher Perl 5.8 or higher RRDTool 1.2.11 or higher MySQL module for PHP Perl Modules. The following perl modules are required for Unnoc to function properly. Below I have listed the CPAN distribution id's and paths to download the source. Check with your OS or distribution for easier ways to install them (like yum, apt-get, RPM's, etc): The following modules should be included in your perl distribution: Socket IPC::Open2 Fcntl IO::Handle POSIX Getopt::Std Net::SMTP Net::Ping If not, please download the appropriate modules from CPAN or by other means. These are modules that should be installed, they are required for Unnoc to run: BER and SNMP_Session.pm http://www.switch.ch/misc/leinen/snmp/perl/dist/ Debian apt: libsnmp-session-perl DBI Distribution id = T/TI/TIMB/DBI-1.48.tar.gz Debian apt: libdbi-perl DBD::mysql Distribution id =C/CA/CAPTTOFU/DBD-mysql-4.004.tar.gz Debian apt: libdbd-mysql-perl Net::SMTP Distribution id = G/GB/GBARR/libnet-1.19.tar.gz Net::Ping Distribution id = B/BB/BBB/Net-Ping-2.31.tar.gz Time::HiRes Distribution id = J/JH/JHI/Time-HiRes-1.9707.tar.gz Debian apt: libtime-hires-perl These modules are required by specific plugins. If you do not plan to use the plugins, then you do not need to install them. Net::Ping::External Distribution id = C/CO/COLINM/Net-Ping-External-0.10.tar.gz Debian apt: libnet-ping-external XML::Parser Distribution id = C/CO/COOPERCL/XML-Parser-2.31.tar.gz Debian apt: libxml-parser-perl IO::Socket Destribution id = G/GB/GBARR/IO-1.2301.tar.gz Debian apt: IO::Socket::SSL Distribution id = S/SU/SULLR/IO-Socket-SSL-1.06.tar.gz Debian apt: libio-socket-ssl-perl Net::LDAP Distribution id = G/GB/GBARR/perl-ldap-0.34.tar.gz Debian apt: libnet-ldap-perl DBD::Pg Distribution id = D/DB/DBDPG/DBD-Pg-1.49.tar.gz Debian apt: libdbd-pg-perl Mail::POP3::Client Distribution id = S/SD/SDOWD/Mail-POP3Client-2.17.tar.gz Debian apt: libmail-pop3client-perl VMware::VIRuntime http://sourceforge.net/projects/viperltoolkit This module is required by Math::BigInt when it does its own calculations on the 64-bit counters. If you do not plan to use SNMP version 2c, then you do not need to install this. If you do want to use 2c, then install FastCalc Math::BigInt::FastCalc Distribution id =T/TE/TELS/math/Math-BigInt-FastCalc-0.14.tar.gz Debian apt: (none that I could find) You can either install these via CPAN, like this: # perl -MCPAN -e shell cpan> install Mail::POP3Client cpan> install Net::SMTP cpan> install Net::Ping ... Or you can install them via your own distrubtion, or OS via apt-get, yum, emerge, or an RPM. Please run the perl-module-checker.pl script, located in the root of the tar file. This will tell you which modules are installed and which are missing: # ./perl-module-checker.pl Checking Core modules: looking for 13 modules Checking Plugin modules: looking for 10 modules Perl version 5.8.8 found Checking BER... ok Checking DBD::Pg... ok Checking DBD::mysql... ok Checking DBI... ok Checking Fcntl... ok Checking Getopt::Std... ok Checking IO::Handle... ok Checking IO::Socket... ok Checking IO::Socket::SSL... ok Checking IPC::Open2... ok Checking Mail::POP3Client... ok Checking Net::LDAP... ok Checking Net::LDAP::Util... ok Checking Net::LDAPS... ok Checking Net::Ping... ok Checking Net::Ping::External... ok Checking Net::SMTP... ok Checking POSIX... ok Checking SNMP_Session... ok Checking Socket... ok Checking Time::HiRes... ok Checking VMware::VIRuntime... ok Checking XML::Parser... ok ------------------------------------ Summary: Core Modules Found: 13 (0 missing) Plugin Modules Found: 10 (0 missing) ------------------------------------ All OK Once all of the system software is installed, you can proceed to the next step. 2. Decide whether Unnoc will run as root or a non-privileged user. NOTE: If you would like to run unnoc as a non-privileged user, be aware that the latency times are going to be off slightly. This is due to Net::Ping::External. If ping latency times are not that important to you, then you should run unnoc is non-privileged mode. If you decide to run in non-privileged mode, make a user for it: # useradd unnoc For the remainder of the document, I will assume that we are running in non-privileged mode and that the user is "unnoc" and the group is "unnoc" 3. Move unnoc-1.0.10.1/unnoc to your webroot as "unnoc" (or whatever you want to call it). This is referred to as your "webroot", so any reference to webroot or /webroot will be this directory. Change the permissions to the unnoc user: Make sure you are in the directory that you untarred unnoc. # mv unnoc-1.0.10.1/unnoc /var/www/unnoc/ # chown unnoc:unnoc -R /var/www/unnoc/ For the remainder of this document, I will refer to this as /webroot. 4. Create the database: # mysqladmin -p create unnoc # mysql unnoc -p < unnoc-1.0.10.1/mysql_table 5. Decide whether or not you want to run in daemon mode or crontab mode. Crontab mode is the older of the two. Unnoc was originally written to run from crontab. Daemon mode is new. It was added in 1.0.9, it helps alleviate the load on the unnoc server by spreading things out a bit. ****************************************** ** CHOOSE ONLY ONE OF THESE TWO METHODS ** ****************************************** If in doubt, use the daemon mode. It is newer. The crontab mode might eventually go away. --------------------- Method 1: Daemon Mode If you are using daemon mode, find the appropriate init.d file in the scripts/init.d directory and copy to your /etc/init.d. If the file doesnt exist for your particular OS/distro, please consider contributing one. Debian / Ubuntu: # cp scripts/init.d/debian/unnocd /etc/init.d/unnocd # update-rc.d unnocd defaults 90 15 Fedora / Redhat: # cp scripts/init.d/fedora/unnocd /etc/init.d/unnocd # chkconfig --add unnocd # chkconfig unnocd on Be sure to set the daemon_concurrent, daemon_user and daemon_group vars in the unnoc.conf file that is appropriate for your installation. --------------------- Method 2: Crontab mode If you are using crontab, simply add the crontab entry to your /etc/crontab and you are done. Something like this: * * * * * unnoc /webroot/bin/unnoc-cron.pl /webroot See the README.daemon file for more information. See the README.cron_wrapper file for more information. 6. Unnoc configuration Now that you have all of the system software installed on your server and you have unnoc installed to /webroot. It is time to configure: - Apache - unnoc.conf - index.php --------------------- Apache It's recommended that you make a virtualhost for unnoc to live in, something like noc.domain.com and set the documentroot to what ever you put /webroot. This helps all of the paths to stay nice and clean and contained in one webroot. I've included an example apache2.conf file that you can use if you use apache2.conf. Regardless of whether or not you use a virtualhost, make sure that you remove access to the etc/ directory, because that could contain sensitive information. --------------------- unnoc.conf Update all of the variables to your liking. Add in hosts, servers and devices to be monitored, either see README.add_hosts for the syntax or see the example unnoc.conf file. Also see the README.config and the other README.* files for more explanations on all the plugins and the variables See the following README files for the respective host types: Linux/UNIX/Microsoft README.add_hosts, README.hosts Network Appliances README.netapp VMware VI3 README.vmware EM01 Environment Sensor README.em01 Barracuda SPAM Firewalls README.barracuda-spam-firewall Apple Airports README.apple-airports Cisco Aironets README.aironets APC products README.apc OpenLDAP monitoring README.openldap MySQL monitoring README.mysql PostgreSQL monitoring README.postgresql All others (generic) README.add_hosts, README.hosts The easiest way to configure is to take a look at the example config files provided. I've provided a number of them, as well as the demo config located http://unnoc.org/demo_files/unnoc.conf.txt --------------------- index.php I've included a few index.php files that show what all you can do with it. I'd like to include different ones in future release, however these will have to suffice for now. There's only a few parts that are really required. The check_hosts() feature will check the mysql database and print a dot (defined in the unnoc.conf) based on if it's got problems or is okay. The easiest way to configure is to take a look at the example index files provided. I've provided a number of them, as well as the demo index located http://unnoc.org/demo_files/index.php.txt 7. Device configuration For blackbox devices, usually there is some sort of option to enable SNMP monitoring. It requires a ro community (not the rw community). This is traditionally called 'public'. For OS servers, it's kind of beyond the scope of this document, however here's some quick instructions that I use to get a server snmpd enabled: ---------------- For Linux/UNIX Install the latest version of Net-SNMP 5.x on the server (usually comes with your distro/OS) # vi /etc/snmp/snmpd.conf (paths may vary) Tell snmp what you want it to monitor, add in disk limits, processes with minimums and maximums, and load average limits. I've included a few snmpd.conf example files in the examples/ directory, feel free to use those how you want Start/Restart SNMP # /etc/init.d/snmpd start You can check to make sure that snmp is working properly by using some of the tools that come with net-snmp, use snmpwalk to look at all of the MIB's available: # snmpwalk -v 1 -c public localhost ---------------- For MS Windows You need to install the SNMP Service from the "Add Programs -> Add Windows Components." You might need the software OS installation CD. To configure, go to "Control Panel -> Administrative Tools ->Services -> SNMP Service" Set the community name and the unnoc host (if you're worried about security) under "Allowed hosts" Once SNMP is installed, you can test the same way from the command line on the unnoc server (assuming "public" is the community): # snmpwalk -v 1 -c public server 8. You can start unnoc once everything is installed, and add the servers one at a time. ------------------- Method 1: Cron Mode If you are using the crontab method, then update your /etc/crontab to start running the unnoc-cron.pl perl script. You just need one line: * * * * * unnoc /var/www/unnoc/bin/unnoc-cron.pl /var/www/unnoc Unnoc-cron reads the configuration file every time, so once you have added/changed/removed any hosts, it wil automatically pick these up. Details will be in the log/unnoc-cron.log file ------------------- Method 2: Daemon mode If you are running in daemon mode, then you can simply start the server like this: # /etc/init.d/unnocd start Since it is a daemon, it reads the configuration on startup. So when you add/remove/change hosts, you will need to reload the daemon with a HUP. You can either kill -HUP the process, or use the reload from the init.d script: # /etc/init.d/unnocd reload Details will be in the log/unnocd.log file For explanations of the files, see the FILES documentation For more documentation, take a look at the doc/README.* files vim:tw=72:wm=1