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.

For instructions on how to install Icinga on FreeBSD please read Icinga on FreeBSD instead.

Other distributions may inherit from these examples.

What You'll End Up With

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

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.

Optional

At one time or another you may need to use SNMP-based checks so it is a good idea to install the required packages now. Otherwise some plugins are not compiled i.e. not available when you need them and it would require a recompile of the plugins.

You can install these packages by running the following commands (as root or using sudo).

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

For sending commands from the classic web interface to Icinga, you'll need to create a new group icinga-cmd. Add the webuser and the Icinga user to this group:

 #> /usr/sbin/groupadd icinga-cmd
 #> /usr/sbin/usermod -a -G icinga-cmd icinga
 #> /usr/sbin/usermod -a -G icinga-cmd www-data

(or www, wwwrun, apache, depending on the distribution)

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

 #> cd /usr/src

Get the current source from the Icinga Website.

Don't forget to download the Monitoring Plugins.

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

 #> cd /usr/src/
 #> tar xvzf icinga-1.14.tar.gz
 #> cd icinga-1.14

Run the Icinga configure script. You will get help by using the --help flag.

 #> ./configure --with-command-group=icinga-cmd --disable-idoutils

Current/upcoming distributions (RedHat/CentOS 7, Fedora 20, Debian 8/Jessie, Gentoo, etc.) support the usage of systemd instead of SysVinit system.

Icinga 1.x already got the required systemd files patched into, and the rpms natively install them. Installing from source may require the following

#> ./configure [...] --with-systemd-unit-dir=/usr/lib/systemd/system --with-systemd-sysconfig-dir=/etc/sysconfig
#> make install-systemd

Then enable the systemd service and start icinga.

#> systemctl enable icinga
#> systemctl start icinga

Status

#> systemctl status icinga

Compile the Icinga source code. To see available options, only use "make".

 #> make all

Install binaries, init script, sample config files, some eventhandlers, and set permissions on the external command directory.

 #> make install
 #> make install-init
 #> make install-config
 #> make install-eventhandlers
 #> make install-commandmode

or shorter

 #> make fullinstall
 #> make install-config

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

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

Icinga ships with the Classic Web Interface ("the CGIs") which can be installed via

 #> make cgis
 #> make install-cgis
 #> make install-html

If you are interested in the new Icinga Web, please refer to Install Icinga Web Interface.

Install the Icinga Classic web config file in the Apache conf.d directory (conf-available starting with Apache 2.4).

 #> make install-webconf

Create an icingaadmin account for logging into the Icinga classic web interface. If you want to change it later, use the same command. Remember the password you assign to this account - you'll need it later.

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

If you want to change it later or want to add another user, use the following command:

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

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

Extract the plugins source code tarball.

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

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

 #> ./configure \
    --prefix=/usr/local/icinga --with-cgiurl=/icinga/cgi-bin \
    --with-nagios-user=icinga --with-nagios-group=icinga
 #> make
 #> make install

RHEL and derived distributions like Fedora and CentOS are shipped with activated SELinux (Security Enhanced Linux) running in "enforcing" mode. This may lead to "Internal Server Error" messages when you try to invoke the Icinga-CGIs.

Check if SELinux runs in enforcing mode

 #> getenforce

Set SELinux in "permissive" mode

 #> setenforce 0

To make this change permanent you have to adjust this setting in /etc/selinux/config and restart the system.

Instead of deactivating SELinux or setting it into permissive mode you can use the following commands to run the CGIs in enforcing/targeted mode. The semanage command will automatically add entries to /etc/selinux/targeted/contexts/files/file_contexts.local.

 #> semanage fcontext -a -t httpd_sys_script_exec_t '/usr/local/icinga/sbin(/.*)?'
 #> semanage fcontext -a -t httpd_sys_content_t '/usr/local/icinga/share(/.*)?'
 #> semanage fcontext -a -t httpd_sys_rw_content_t '/usr/local/icinga/var(/.*)?'

Once you have defined the necessary contexts you have to apply the settings:

 #> chcon -R /usr/local/icinga/sbin
 #> chcon -R /usr/local/icinga/share
 #> chcon -R /usr/local/icinga/var/rw

For details please take a look at http://www.linuxquestions.org/questions/blog/sag47-492023/selinux-and-icinga-34926/.

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).

You should now be able to access the Icinga classic 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.

Make sure your system's firewall rules are configured to allow access to the web server if you want to access the Icinga classic 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.

Congratulations! You successfully installed Icinga. 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 ..."