Icinga

Icinga with IDOUtils Quickstart

Introduction

This guide is intended to provide you with simple instructions on how to install Icinga from source (code) and have it monitoring your local machine within 30 minutes.

No advanced installation options are discussed here - just the basics that will work for most of the users who want to get started.

This guide will give you examples for currently three different Linux distributions: Fedora, Ubuntu and openSuSE. Similar distributions may work as well. That should include RedHat, CentOS, Debian and SLES.

Other distributions may inherit from these examples.

If you are planning to use Icinga without IDOUtils please read “Icinga Quickstart” instead!

What You'll End Up With

If you follow these instructions, here's what you'll end up with:

Prerequisites

During portions of the installation you'll need to have root access to your machine.

Make sure you've installed the following packages on your system before continuing. IDOUtils use the libdbi and the libdbi-drivers for several databases. The development libraries are also required. The following examples will show how to install the IDOUtils with the libdbi using MySQL or PostgreSQL.

New features for the IDOUtils:

SSL- encryption between idomod and ido2db

If you want to use SSL-Encryption you'll need openssl and openssl-devel/libssl-dev (Ubuntu) to be installed !

Oracle Database Support

If you want Oracle as RDBM you'll need to install ocilib next to libdbi. Get it from http://orclib.sourceforge.net/ and point configure to your Oracle libraries and header files e.g. from the Oracle instant client:

 # ./configure --with-oracle-headers-path=/path/to/instantclient/sdk/include --with-oracle-lib-path=/path/to/instantclient/
 # make
 # make install

Install packages

You can install your packages by running the following commands (as root or sudo):

Fedora/RHEL/CentOS:

 # yum install httpd gcc glibc glibc-common gd gd-devel
 # yum install libjpeg libjpeg-devel libpng libpng-devel

MySQL:

 # yum install mysql mysql-server libdbi libdbi-devel libdbi-drivers libdbi-dbd-mysql

PostgreSQL:

 # yum install postgresql postgresql-server libdbi libdbi-devel libdbi-drivers libdbi-dbd-pgsql

Debian/Ubuntu:

 # apt-get install apache2 build-essential libgd2-xpm-dev
 # apt-get install libjpeg62 libjpeg62-dev libpng12 libpng12-dev
[Note] Note

The numbers <62/12> might differ, depending on your distribution

MySQL:

 # apt-get install mysql-server mysql-client libdbi0 libdbi0-dev libdbd-mysql

PostgreSQL:

 # apt-get install postgresql libdbi0 libdbi0-dev libdbd-pgsql

openSuSE:

Please use yast to install the necessary packages

Create Account Information

Become the root user.

 # su -l

Create a new Icinga user account and give it a password.

 # /usr/sbin/useradd -m icinga 
 # passwd icinga 

On some distributions you'll need to add the group in a single step:

 # /usr/sbin/groupadd icinga

Download Icinga and the Plugins

Change to your local source directory i.e. /usr/src

 # cd /usr/src

Either fetch the actual icinga-core snapshot from Icinga GIT

 # git clone git://git.icinga.org/icinga-core.git  

or from the Icinga Website . Don't forget to download the Nagios Plugins

Compile and Install Icinga with IDOUtils

Extract the Icinga source code tarball (or change directory to the GIT snapshot)

 # cd /usr/src/ 
 # tar xvzf icinga-1.0.tar.gz 
 # cd icinga-1.0

Run the Icinga configure script and enable IDOUtils. You will get help by using the --help flag:

 # ./configure --enable-idoutils

With SSL-encryption:

 # ./configure --enable-idoutils --enable-ssl

With Oracle database support:

 # ./configure --enable-idoutils --enable-oracle

If you didn't install ocilib to the default path (/usr/local) you can point configure to the lib/inc directories:

 # ./configure --enable-idoutils --enable-oracle --with-ocilib-lib=/path/to/ocilib/lib --with-ocilib-inc=/path/to/ocilib/include
[Note] Note

If you want to change RDBM from Oracle to others, you need to recompile and reinstall IDOUtils!

 # make distclean
 # ./configure --enable-idoutils

Compile the Icinga source code. There is also an extra option for IDOUtils (make idoutils) if you need to recompile only this module. To see available options, only use "make".

 # make all

Install binaries, init script, sample config files and set permissions on the external command directory. Also install the IDOUtils.

 # make install 
 # make install-init 
 # make install-config 
 # make install-commandmode 
 # make install-idoutils 

or shorter

 # make fullinstall

Don't start Icinga yet - there's still more that needs to be done...

Customize Configuration

Sample configuration files have been installed by using make install-config into /usr/local/icinga/etc/. You'll need to make just one change before you proceed...

Edit the /usr/local/icinga/etc/objects/contacts.cfg config file with your favourite editor and change the email address associated with the icingaadmin contact definition to the address you'd like to use for receiving alerts.

 # vi /usr/local/icinga/etc/objects/contacts.cfg
 # cd /usr/local/icinga/etc/
 # cp idomod.cfg-sample idomod.cfg
 # cp ido2db.cfg-sample ido2db.cfg

If you want to enable SSL-encryption and you configured the IDOUtils with ./configure --enable-ssl, you have to change idomod.cfg and ido2db.cfg:

 # use_ssl=1
 # socket_type=tcp 
[Note] Note

If SSL is enabled in ido2db but not in the different idomod clients - data from those instances will be lost - that's guaranteed! SSL configuration has to be the same on all nodes!!!

Enable the idomod event broker module:

Search for broker_module and uncomment the example or edit it matching your filenames in:

 # vi /usr/local/icinga/etc/icinga.cfg

Creation of database and IDOUtils

MySQL:

Create Database, User, Grants:

 # mysql -u root -p

 mysql> CREATE DATABASE icinga;

 GRANT USAGE ON *.* TO 'icinga'@'localhost' IDENTIFIED BY 'icinga' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0;

 GRANT SELECT , INSERT , UPDATE , DELETE ON icinga.* TO 'icinga'@'localhost';

 FLUSH PRIVILEGES ;

 quit

Import database scheme for MySQL:

 # cd /path/to/icinga-src/module/idoutils/db 
 # mysql -u root -p icinga < mysql.sql

Edit the DB config file to customize IDOUtils

 # vi /usr/local/icinga/etc/ido2db.cfg

 db_servertype=mysql
 db_port=3306
 db_user=icinga
 db_pass=icinga

PostgreSQL:

Create database and User:

 # su - postgres
 $psql
 postgres=# CREATE USER icingauser;
 postgres=# ALTER USER icingauser WITH PASSWORD 'icingauser';
 postgres=# CREATE DATABASE icinga;
 

Debian:

 # vi /etc/postgresql/8.x/main/pg_hba.conf

Fedora/RHEL/CentOS:

 # vi /var/lib/pgsql/data/pg_hba.conf

Edit the config e.g. like this (local user must be trusted)

 # database administrative login by UNIX sockets
 local    all        postgres                  ident
 # TYPE   DATABASE   USER       CIDR-ADDRESS   METHOD 
 #icinga
 local    icinga     icingauser                trust
 # "local" is for Unix domain socket connections only
 local    all        all                       trust
 # IPv4 local connections
 local    all        all        127.0.0.1/32   trust
 # IPV6 local connections
 local    all        all        ::1/128        trust

Reload and configure database scheme.

 # /etc/init.d/postgresql-8.x reload
 # cd /path/to/icinga-src/module/idoutils/db
 # psql -U icingauser -d icinga < pgsql.sql

Edit the DB config file to customize IDOUtils

 # vi /usr/local/icinga/etc/ido2db.cfg
 db_servertype=pgsql
 db_port=5432
 db_user=icingauser
 db_pass=icingauser

Oracle:

Create a database schema and username/password (refer to the Oracle documentation at http://www.oracle.com or consult your DBA). Import the database scheme with sqlplus (or your preferred method). Copy module/idoutils/db/oracle.sql to $ORACLE_HOME

 # su - oracle
 $ sqlplus dbuser/dbpass
 SQL> @oracle.sql

Edit the DB config file to customize IDOUtils. Remember that Oracle ignores the db host, instead point db_name to //DBSERVER/DBNAME

# vi /usr/local/icinga/etc/ido2db.cfg
  db_servertype=oracle
  db_port=1521
  db_user=icinga
  db_pass=icinga

Configure the Web Interface

Install the Icinga web config file in the Apache conf.d directory.

 # make install-webconf

Create an icingaadmin account for logging into the Icinga web interface. Remember the password you assign to this account - you'll need it later.

 # htpasswd -c /usr/local/icinga/etc/htpasswd.users icingaadmin

To change the password of an existing user or to add a new user, take this command:

 # htpasswd /usr/local/icinga/etc/htpasswd.users <USERNAME>
[Note] Note

Depending on your distribution/Apache-version you may have to use htpasswd2 instead.

Reload/Restart Apache to make the new settings take effect.

Fedora/RHEL/CentOS:

 # service httpd restart

Debian/Ubuntu/openSuSE:

 # /etc/init.d/apache2 reload

Compile and Install the Nagios Plugins

Extract the Nagios plugins source code tarball.

 # cd /usr/src 
 # tar xvzf nagios-plugins-1.4.13.tar.gz 
 # cd nagios-plugins-1.4.13  

Compile and install the plugins by changing install directory to /usr/local/icinga

 # ./configure --prefix=/usr/local/icinga --with-nagios-user=icinga 
 # make 
 # make install 

Start IDOUtils and Icinga

Start IDOUtils

IDOUtils must be started and running before Icinga is started.

Start IDOUtils:

 # /etc/init.d/ido2db start

Stop IDOUtils:

 # /etc/init.d/ido2db stop

Verify the sample Icinga configuration files.

 #/usr/local/icinga/bin/icinga -v /usr/local/icinga/etc/icinga.cfg 

If there are no errors, start Icinga.

Fedora/RHEL/CentOS:

 service icinga start

Debian/Ubuntu/openSuSE:

 # /etc/init.d/icinga start

Configure Icinga Startup

Add Icinga to the list of system services and have it automatically start when the system boots (make sure you have installed the init script before).

Fedora/RHEL/CentOS/openSuSE:

 # chkconfig --add icinga chkconfig icinga on

Debian/Ubuntu:

 # ln -s /etc/init.d/icinga /etc/rcS.d/S99icinga

Login to the Web Interface

You should now be able to access the Icinga web interface at the URL below. You'll be prompted for the username ( icingaadmin ) and password you specified earlier.

 http://localhost/icinga/

or

 http://yourdomain.com/icinga/ 

Click on the "Service Detail" navbar link to see details of what's being monitored on your local machine. It will take a few minutes for Icinga to check all the services associated with your machine.

Other Modifications

Make sure your system's firewall rules are configured to allow access to the web server if you want to access the Icinga interface remotely.

 # iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT

Setting up your mail transfer agent (MTA) like exim, sendmail or postfix to allow Icinga sending notification emails won't be explained here. Please refer to the Nagios Wiki for more resources.

There are several tweaks for the IDOUtils (former NDOUtils of Nagios) available.

You're Done

Congratulations! You successfully installed Icinga with IDOUtils. Your journey into monitoring has just begun. You'll no doubt want to monitor more than just your local machine, so check out the chapter on "Getting Started" about "Monitoring ..."