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 20 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:
Icinga and the plugins will be installed underneath /usr/local/icinga
Icinga will be configured to monitor a few aspects of your local system (CPU load, disk usage, etc.)
The Icinga web interface will be accessible at http://localhost/icinga/ or http://yourdomain.com/icinga
A database which is filled by Icinga using IDOUtils
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.
Apache
GCC compiler
C/C++ development libraries
GD development libraries
libdbi/libdbi-drivers, database like mysql or postgresql.
You can install these packages by running the following commands (as root or sudo):
Fedora/RHEL/CentOS:
# yum install httpd gcc glibc glibc-common gd gd-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
Ubuntu
# apt-get install apache2 build-essential libgd2-xpm-dev
MySQL:
# apt-get install mysql mysql-libdbi0 libdbi0-dev libdbd-mysql
PostgreSQL:
# apt-get install postgresql libdbi0 libdbi0-dev libdbd-pgsql
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-0.8.4.tar.gz # cd icinga-0.8.4
Run the Icinga configure script and enable IDOUtils. You will get help by using the --help flag:
# ./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
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
Create Database, User, Grants in MySQL:
# 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 as follows (local user must be trusted)
#icinga local icinga icingauser 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
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 |
---|---|
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
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
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
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 ..."
© 2009 Icinga Development Team, http://www.icinga.org