<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="wb_quickstart-idoutils"
         xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:svg="http://www.w3.org/2000/svg"
         xmlns:m="http://www.w3.org/1998/Math/MathML"
         xmlns:html="http://www.w3.org/1999/xhtml"
         xmlns:db="http://docbook.org/ns/docbook">
  <title>Icinga with IDOUtils Quickstart</title>

  <para><citetitle>Introduction</citetitle></para>

  <para>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.</para>

  <para>No advanced installation options are discussed here - just the basics
  that will work for 95% of users who want to get started.</para>

  <para>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.</para>

  <para>Other distributions may inherit from these examples.</para>

  <para><emphasis role="bold">If you are planning to use Icinga without
  IDOUtils please read <xref linkend="wb_quickstart-icinga" />
  instead!</emphasis></para>

  <para><citetitle>What You'll End Up With</citetitle></para>

  <para>If you follow these instructions, here's what you'll end up
  with:</para>

  <itemizedlist>
    <listitem>
      <para>Icinga and the plugins will be installed underneath
      /usr/local/icinga</para>
    </listitem>

    <listitem>
      <para>Icinga will be configured to monitor a few aspects of your local
      system (CPU load, disk usage, etc.)</para>
    </listitem>

    <listitem>
      <para>The Icinga web interface will be accessible at
      http://localhost/icinga/ or http://yourdomain.com/icinga</para>
    </listitem>

    <listitem>
      <para>A database which is filled by Icinga using IDOUtils</para>
    </listitem>
  </itemizedlist>

  <para><citetitle>Prerequisites</citetitle></para>

  <para>During portions of the installation you'll need to have <emphasis
  role="bold">root</emphasis> access to your machine.</para>

  <para>Make sure you've installed the following packages on your system
  before continuing. IDOUtils use the <link
  xlink:href="http://libdbi.sourceforge.net">libdbi</link> 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.</para>

  <itemizedlist>
    <listitem>
      <para>Apache</para>
    </listitem>

    <listitem>
      <para>GCC compiler</para>
    </listitem>

    <listitem>
      <para>C/C++ development librariesr</para>
    </listitem>

    <listitem>
      <para><link xlink:href="http://www.boutell.com/gd/">GD</link>
      development libraries</para>
    </listitem>

    <listitem>
      <para>libdbi/libdbi-drivers, database like mysql</para>
    </listitem>
  </itemizedlist>

  <para>You can install these packages by running the following commands (as
  root or sudo):</para>

  <para><emphasis>Fedora</emphasis></para>

  <programlisting>yum install httpd gcc glibc glibc-common gd gd-devel 
yum install mysql</programlisting>

  <programlisting>yum install libdbi libdbi-devel libdbi-drivers libdbi-dbd-mysql</programlisting>

  <para><emphasis>Ubuntu</emphasis></para>

  <programlisting>apt-get install apache2 build-essential libgd2-xpm-dev
apt-get install mysql
apt-get install libdbi0 libdbi0-dev libdbd-mysql  </programlisting>

  <para><citetitle>1) Create Account Information</citetitle></para>

  <para>Become the root user.</para>

  <programlisting>su -l</programlisting>

  <para>Create a new <emphasis>icinga</emphasis> user account and give it a
  password.</para>

  <programlisting>/usr/sbin/useradd -m icinga
passwd icinga  </programlisting>

  <para>On some distribution you'll need to add the group in a single
  step:</para>

  <programlisting>/usr/sbin/groupadd icinga</programlisting>

  <para><citetitle>2) Download Icinga and the Plugins</citetitle></para>

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

  <programlisting>cd /usr/src</programlisting>

  <para>Either fetch the actual icinga-core snapshot from Icinga GIT</para>

  <programlisting>git clone git://git.icinga.org/icinga-core.git  </programlisting>

  <para><link xlink:href="http://www.icinga.org">Icinga Website</link></para>

  <para>Don't forget to download the</para>

  <para><link xlink:href="http://nagiosplugins.org/download">Nagios
  Plugins</link></para>

  <para><citetitle>3) Compile and Install Icinga with
  IDOUtils</citetitle></para>

  <para>Extract the Icinga source code tarball (or change directory to the GIT
  snapshot)</para>

  <programlisting>cd /usr/src/
tar xvzf icinga-0.8.tar.gz
cd icinga  </programlisting>

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

  <programlisting>./configure --enable-idoutils</programlisting>

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

  <programlisting>make all</programlisting>

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

  <programlisting>make install
make install-init
make install-config
make install-commandmode
make install-idoutils  </programlisting>

  <para>or shorter</para>

  <programlisting>make fullinstall</programlisting>

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

  <para><citetitle>4) Customize Configuration</citetitle></para>

  <para>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...</para>

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

  <programlisting>vi /usr/local/icinga/etc/objects/contacts.cfg</programlisting>

  <programlisting>cd /usr/local/icinga/etc/
cp idomod.cfg-sample idomod.cfg
cp ido2db.cfg-sample ido2db.cfg</programlisting>

  <programlisting>vi /usr/local/icinga/etc/icinga.cfg
#add line
broker_module=/usr/local/icinga/bin/idomod.o config_file=/usr/local/icinga/etc/idomod.cfg  </programlisting>

  <para><citetitle>5) Configure Database and IDOUtils</citetitle></para>

  <!--  <link xlink:href="http://www.phpmyadmin.net">phpMyAdmin</link> -->

  <programlisting>cd /usr/src/icinga/
cd module/idoutils/db
mysql -u root -p icinga &lt; mysql.sql  </programlisting>

  <programlisting>vi /usr/local/icinga/etc/ido2db.cfg</programlisting>

  <para><citetitle>6) Configure the Web Interface</citetitle></para>

  <para>Install the Icinga web config file in the Apache conf.d
  directory.</para>

  <programlisting>make install-webconf</programlisting>

  <para>Create a <emphasis>icingaadmin</emphasis> account for logging into the
  Icinga web interface. Remember the password you assign to this account -
  you'll need it later.</para>

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

  <para>To change the password of an existing user <emphasis
  role="bold">or</emphasis> to add a new user, take this command:</para>

  <programlisting>htpasswd /usr/local/icinga/etc/htpasswd.users &lt;USERNMAE&gt;</programlisting>

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

  <para><emphasis>Fedora</emphasis></para>

  <programlisting>service httpd restart</programlisting>

  <para><emphasis>Ubuntu</emphasis></para>

  <programlisting>/etc/init.d/apache2 reload</programlisting>

  <para><citetitle>7) Compile and Install the Nagios
  Plugins</citetitle></para>

  <para>Extract the Nagios plugins source code tarball.</para>

  <programlisting>cd /usr/src
tar xvzf nagios-plugins-1.4.13.tar.gz
cd nagios-plugins-1.4.13  </programlisting>

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

  <programlisting>./configure --prefix=/usr/local/icinga --with-nagios-user=icinga
make 
make install</programlisting>

  <para><citetitle>8) Start IDOUtils and Icinga</citetitle></para>

  <para><emphasis> <emphasis role="bold">Start IDOUtils</emphasis>
  </emphasis></para>

  <para>IDOUtils must be started and running <citetitle>before</citetitle>
  Icinga is started.</para>

  <para><emphasis>Start IDO</emphasis></para>

  <programlisting>/usr/local/icinga/bin/ido2db -c /usr/local/icinga/etc/ido2db.cfg  </programlisting>

  <para><emphasis>Stop IDO</emphasis></para>

  <programlisting>killall -9 ido2db
rm -f /usr/local/icinga/var/ido.sock  </programlisting>

  <para><emphasis> <emphasis role="bold">Start Icinga</emphasis>
  </emphasis></para>

  <para>Verify the sample Icinga configuration files.</para>

  <programlisting>/usr/local/icinga/bin/icinga -v /usr/local/icinga/etc/icinga.cfg  </programlisting>

  <para>If there are no errors, start Icinga.</para>

  <para><emphasis>Fedora, openSUSE</emphasis></para>

  <programlisting>service icinga start</programlisting>

  <para><emphasis>Ubuntu</emphasis></para>

  <programlisting>/etc/init.d/icinga start</programlisting>

  <para><emphasis role="bold">Check IDOUtils</emphasis></para>

  <para>Check your database being filled</para>

  <programlisting>mysql -u &lt;your_idouser&gt; -p use icinga;
SELECT count(servicecheck_id) as cnt FROM icinga_servicechecks;
quit</programlisting>

  <para><emphasis role="bold">Configure Icinga Startup</emphasis></para>

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

  <para><emphasis>Fedora, openSUSE</emphasis></para>

  <programlisting>chkconfig --add icinga
chkconfig icinga on</programlisting>

  <para><emphasis>Ubuntu</emphasis></para>

  <programlisting>ln -s /etc/init.d/icinga /etc/rcS.d/S99icinga</programlisting>

  <para><citetitle>8) Login to the Web Interface</citetitle></para>

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

  <programlisting>http://localhost/icinga/  </programlisting>

  <para>or</para>

  <programlisting>http://yourdomain.com/icinga/  </programlisting>

  <para>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.</para>

  <para><citetitle>9) Other Modifications</citetitle></para>

  <para>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.</para>

  <programlisting>iptables -A INPUT -p tcp -m tcp --dport 80 -j ACCEPT</programlisting>

  <para>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 <link xlink:href="http://www.nagioswiki.org">Nagios
  Wiki</link> for more ressources.</para>

  <para>There are several tweaks for the IDOUtils (former NDOUtils of Nagios)
  available.</para>

  <para><citetitle>10) You're Done</citetitle></para>

  <para>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 <link
  xlink:href="http://nagios.sourceforge.net/docs/3_0/toc.html"> official
  Nagios Documentation</link> for more configurations...</para>
</section>
