<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xml:id="wb_quickstart-icinga"
         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 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 a database with
  IDOUtils please read <xref linkend="wb_quickstart-idoutils" />
  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>
  </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:</para>

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

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

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

    <listitem>
      <para><link xlink:href="http://www.boutell.com/gd">GD</link> development
      libraries</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</programlisting>

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

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

  <para><emphasis>OpenSUSE</emphasis></para>

  <para>Please use yast to install the packages</para>

  <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 distributions 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</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. You will get help by using the --help
  flag:</para>

  <programlisting>./configure</programlisting>

  <para>Compile the Icinga source code. 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.</para>

  <programlisting>make install
make install-init
make install-config
make install-commandmode  </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
  <programlisting>make install-config</programlisting> 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>

  <para><citetitle>5) 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 an <emphasis>icingaadmin</emphasis> account for logging into
  the Icinga 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.</para>

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

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

  <programlisting>htpasswd /usr/local/icinga/etc/htpasswd.users &lt;USERNAME&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 / OpenSuSE</emphasis></para>

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

  <para><citetitle>6) 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>7) Start Icinga</citetitle></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>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><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.</para>

  <para>Please refer to the <link
  xlink:href="http://www.nagioswiki.org">Nagios Wiki</link> for more
  ressources.</para>

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

  <para>Congratulations! You sucessfully installed Icinga. Your journey into
  monitoring has just begun.</para>

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