Icinga

Installation of the Icinga Web Frontend

Introducion

The new Icinga Web is under heavy development so please keep in mind that some information in this howto might change without any further notice. If you require more detailed information about installing, please check doc/INSTALL. More information about the overall architecture can be found on our website: http://www.icinga.org/architecture/. If you want know more about Icinga web development and the module architecture, please check out the development wiki of Icinga Web: https://dev.icinga.org/projects/icinga-web/wiki/

  1. Prerequisites

    Based on the fact that you have a running MySQL and PHP (with PEAR and CLI) environment and Icinga, Icinga-API and IDOUtils are running as well, you can continue with the second step. Otherwise:

    Ubuntu / Debian

    Make sure you have a repository/packages for PHP 5.2.x - RHEL/CentOS only support 5.1.6 out of the box.

    # apt-get install php5 php5-cli php-pear php5-xmlrpc php5-xsl php5-pdo php5-gd php5-ldap

    Fedora / RHEL / CentOS

    # yum install php php-cli php-pear php-xmlrpc php-xsl php-pdo php-gd php-ldap
    [Note] Note

    Currently, RHEL and CentOS provide old php 5.1.6 and pcre 6.6 packages. For running Icinga web you need at least php 5.2.3 and pcre 7.6 - you can use an external repository, pre-built packages or compile php and pcre yourself. Precompiled PCRE and PHP packages can be installed e.g. from Les RPM de Remi or http://www.jasonlitka.com/category/yum-repo-news/

    OpenSuSE

    Please use yast to install the packages "php5", "php5-pear", "php5-xmlrpc", "php5-xsl", "php5-<rdbm>", "php5-soap", "php5-gettext", "php5-ldap" und "php5-gd". The CLI is contained in the php5 package.

    [Note] Note

    At least in SLES10 SP2 the function "hash_hmac" is missing.

    Installing Icinga with IDOUtils and Icinga-API is described in the Icinga with IDOUtils Quickstart Guide and the Icinga-API section.

  2. The installation

    Please download the archive from http://sourceforge.net/projects/icinga/files/ or take your clone from the icinga-web.git to get the freshest branch:

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

    Unpack your tarball:

    # tar xzvf icinga-web-1.0.3.tar.gz

    Then change to the directory:

    # cd icinga-web

    Icinga Web provides several configure options e.g.

    # ./configure
                    --prefix=/usr/local/icinga-web
                    --with-web-user=www-data
                    --with-web-group=www-data
                    --with-db-type=mysql
                    --with-db-host=localhost
                    --with-db-port=3306
                    --with-db-name=icinga_web
                    --with-db-user=icinga_web
                    --with-db-pass=icinga_web
                    --with-icinga-api=/usr/local/icinga/share/icinga-api 
    [Note] Note

    Keep in mind that you configure the Icinga Web database not the Icinga IDOUtils database!

    Please use:

    # ./configure --help

    to see all configure options.

    Per default the Icinga Webinterface will be installed to /usr/local/icinga-web using:

    # ./configure
    # make install
    [Note] Note

    Using no options the installer expects the icinga-API to be found at /usr/local/icinga-api but you can use the option "--with-icinga-api" to specify another location. If you installed Icinga using the quickstart guide you should use the following syntax:

    # ./configure --with-icinga-api=/usr/local/icinga/share/icinga-api
  3. PHP dependencies

    Test the php dependencies with:

    # make testdeps

    All required tests should pass successfully. Maybe you have to alter the php.ini for the framework.

    In case of the gpc_magic_quote setting, you have to disable both entries (apache and cli php.ini). The locations depend on the distributions used.

    # vi /etc/php5/apache/php.ini
       magic_quotes_gpc = off
    
    # vi /etc/php5/cli/php.ini
       magic_quotes_gpc = off
    [Note] Note

    If one of these files is missing you'll get an agavi error complaining about the setting of "magic_quotes_qpc" because the default is "ON".

  4. Database creation

    Icinga Web requires its own database e.g. icinga_web. You can use the one from Icinga IDOUtils but it is recommended to keep this separated for upgrading purposes.

    Create a database user

    The user must have default data privileges like SELECT, UPDATE, INSERT, DELETE.

     SQL> GRANT USAGE ON *.* TO 'icinga_web'@'localhost' IDENTIFIED BY 'icinga_web';
     SQL> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX ON icinga_web.* TO 'icinga_web'@'localhost';
     SQL> FLUSH PRIVILEGES;

    MySQL

    # mysql -u root -p
      
     mysql> CREATE DATABASE icinga_web;
      
     mysql> GRANT USAGE ON *.* TO 'icinga_web'@'localhost' IDENTIFIED BY 'icinga_web' WITH MAX_QUERIES_PER_HOUR 0 MAX_CONNECTIONS_PER_HOUR 0 MAX_UPDATES_PER_HOUR 0;
       
     mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX ON icinga_web.* TO 'icinga_web'@'localhost';
     
     mysql> FLUSH PRIVILEGES ;
    
     mysql> quit

    Create Database

    Icinga Web ships with Doctrine so you can initialise, upgrade or drop the database directly using 'make'.

    # make db-initialize      - creates a spick-and-span database
    # make db-drop            - drops your database with a security query to avoid casualties
    # make db-upgrade         - upgrades old tables to a newer version (Just the same as db-initialize with a better name ;-))
    # make db-doc2sql         - if you require plain SQL scripts, use this option to generate SQL from Doctrine. This can be useful for packaging or manual db install

    To use the database creation commands you have to grant privileges to the user who will execute the commands on your dbms. If the user defined via configure is a low-privileged one, 'make' asks about a more privileged one e.g. a root user. If this does not work for you, alter 'etc/build.properties' to match the requirements of a root user.

    So a simple database install looks like this:

    # make db-initialize

    Manually create Database

    If you require manual database creation e.g. for package building, you can extract the plain SQL scripts using:

    # make db-doc2sql

    and then use the generated scripts on the freshly created database.

  5. Settings

    There are two different sections:

    * Settings of Icinga Web, escpecially database settings

    * Settings of the Icinga API which is mandatory as data source

    Settings of Icinga Web

    Normally you can set the database credentials during configure, but if you want to recheck or even change them, please adapt those to your needs.

    # vi  app/config/databases.xml
        <databases default="icinga_web">
                            <database name="icinga_web" class="AgaviDoctrineDatabase">
    
                                    <!--
                                            Doctrine dsn strings:
    
                                            http://www.doctrine-project.org/documentation/manual/1_1/en/introduction-to-connections
                                    -->
                                    <ae:parameter name="dsn">mysql://icinga_web:icinga_web@127.0.0.1:3306/icinga_web</ae:parameter>
    
                                    <!-- Generic credentials  -->
                                    <!-- <ae:parameter name="username">icinga_web</ae:parameter> -->
                                    <!-- <ae:parameter name="password">icinga_web</ae:parameter> -->
    
                                    <!-- DB encoding type -->
                                    <ae:parameter name="charset">utf8</ae:parameter>
    
                                    <!--
                                            Doctrine_Manager configuration
                                    -->
                                    <ae:parameter name="manager_attributes">
                                            <!-- This allows lazy loading of the models -->
                                            <ae:parameter name="Doctrine_Core::ATTR_MODEL_LOADING">CONSERVATIVE</ae:parameter>
                                    </ae:parameter>
    
                                    <!-- The path to our models -->
                                    <ae:parameter name="load_models">%core.module_dir%/AppKit/lib/database/models/generated</ae:parameter>
                                    <ae:parameter name="models_directory">%core.module_dir%/AppKit/lib/database/models</ae:parameter>
    
                            </database>

    Settings of Icinga API

    Those settings are directly within Icinga Web which provides the given information in an appropriate way to the Icinga API. Keep a look into app/modules/Web/config/module.xml for the IcingaApi factories: IcingaData and IcingaCommand.

    # vi app/modules/Web/config/module.xml

    In IcingaData you can set the credentials for the Icinga API e.g. using the Icinga IDOUtils database.

    Please keep in mind that you have to install IDOUtils before (according to the Icinga IDOUtils Quickstart Guide )

                                    <!--
                                            See doc/icinga-api-types.txt for options
                                    -->
                                    <setting name="api.interfaces.data">
                                            <!-- IcingaApi connection interface -->
                                            <ae:parameter name="api_type"<IcingaApi::CONNECTION_IDO>/ae:parameter>
    
                                            <!-- Suits for all interfaes -->
                                            <ae:parameter name="config_type">mysql</ae:parameter>
                                            <ae:parameter name="config_host">localhost</ae:parameter>
                                            <ae:parameter name="config_port">3306</ae:parameter>
    
                                            <!-- ###BEGIN_CONNECTION_IDO### -->
                                            <!-- Database specific (IcingaApi::CONNECTION_IDO) -->
                                            <ae:parameter name="config_database">icinga</ae:parameter>
                                            <ae:parameter name="config_user">icinga</ae:parameter>
                                            <ae:parameter name="config_password">icinga</ae:parameter>
                                            <ae:parameter name="config_table_prefix">icinga_</ae:parameter>
                                            <!-- ###END_CONNECTION_IDO### -->
    
                                    </setting> 

    In IcingaCommand you can specify the credentials for sending commands via Icinga Core command pipe - local or remote via SSH. Depending on 'enabled' those interfaces can be used or not (default is the local pipe).

                                 <setting name="api.interfaces.command">
                                            <ae:parameter name="pipe1">
                                                    <ae:parameter name="type">IcingaApi::COMMAND_PIPE</ae:parameter>
                                                    <ae:parameter name="enabled">true</ae:parameter>
    
                                                    <ae:parameter name="pipe">/usr/local/icinga/var/rw/icinga.cmd</ae:parameter>
    
                                                    <ae:parameter name="instance">default</ae:parameter>
                                                    <ae:parameter name="broadcast">false</ae:parameter>
                                            </ae:parameter>
    
                                            <!--
    
                                                    * This examples show how to send commands to specific instances
                                                    * Use 'instance' to send commands to this instance only
                                                    * Use 'brodcast' to send all commands to this instances!
    
                                            <ae:parameter name="pipe1-instance-test">
                                                    <ae:parameter name="type">IcingaApi::COMMAND_PIPE</ae:parameter>
                                                    <ae:parameter name="enabled">true</ae:parameter>
    
                                                    <ae:parameter name="pipe">/usr/local/icinga/var/rw/icinga.cmd</ae:parameter>
    
                                                    <ae:parameter name="instance">test</ae:parameter>
                                                    <ae:parameter name="broadcast">false</ae:parameter>
                                            </ae:parameter>
    
                                            <ae:parameter name="pipe1-broadcast">
                                                    <ae:parameter name="type">IcingaApi::COMMAND_PIPE</ae:parameter>
                                                    <ae:parameter name="enabled">false</ae:parameter>
    
                                                    <ae:parameter name="pipe">/usr/local/icinga/var/rw/icinga.cmd</ae:parameter>
    
                                                    <ae:parameter name="instance"></ae:parameter>
                                                    <ae:parameter name="broadcast">true</ae:parameter>
                                            </ae:parameter>
    
                                            -->
    
                                            <ae:parameter name="ssh1">
                                                    <ae:parameter name="type">IcingaApi::COMMAND_SSH</ae:parameter>
                                                    <ae:parameter name="enabled">false</ae:parameter>
    
                                                    <ae:parameter name="ssh_bin">/usr/bin/ssh</ae:parameter>
                                                    <ae:parameter name="ssh_user">icinga</ae:parameter>
                                                    <ae:parameter name="ssh_host">127.0.0.15</ae:parameter>
                                                    <ae:parameter name="ssh_port">22</ae:parameter>
                                                    <ae:parameter name="ssh_timeout">20</ae:parameter>
                                                    <ae:parameter name="ssh_pipe">/usr/local/icinga/var/rw/icinga.cmd</ae:parameter>
    
                                                    <ae:parameter name="instance">default</ae:parameter>
                                                    <ae:parameter name="broadcast">false</ae:parameter>
                                            </ae:parameter>
                                    </setting> 
    [Note] Note

    After changing those configs you need to clear the config cache again!

    # rm -rf app/cache/config/*.php
  6. Apache settings

    This should be prepared:

    • mod_rewrite enabled, maybe you have to create a link:

    # ln -s /etc/apache2/mods-available/rewrite.load /etc/apache2/mods-enabled/rewrite.load

    Using OpenSuSE you can use "a2enmod rewrite" to activate the module. If that doesn't work you have to edit the file "/etc/sysconfig/apache2". The module "rewrite" has to be appended to the line "APACHE_MODULES=...".

    • Any htaccess enabled alias settings

    Edit your .htaccess in /usr/local/icinga-web/pub:

    At line 14, change the RewriteBase direction to suit your needs:

     DirectoryIndex index.php
    
     Options -MultiViews -Indexes +FollowSymLinks
     Order allow,deny
     Allow from all
    
     <IfModule mod_rewrite.c>
        RewriteEngine On
    
        # This depends on your path
        # on independent hosts the base is '/'
        RewriteBase /icinga-web/
    
            # If the requested URL does not exist (it's likely an agavi route),
            # pass it as path info to index.php, the Agavi dispatch script.
            RewriteRule ^$ index.php?/ [QSA,L]
            RewriteCond %{REQUEST_FILENAME} !-f
            RewriteCond %{REQUEST_FILENAME} !-d
            RewriteRule (.*) index.php?/$1 [QSA,L]
     </IfModule>
    
     <IfModule mod_deflate.c>
            SetOutputFilter DEFLATE
    
            BrowserMatch ^Mozilla/4 gzip-only-text/html
            BrowserMatch ^Mozilla/4\.0[678] no-gzip
    
            BrowserMatch \bMSIE !no-gzip !gzip-only-text/html
            BrowserMatch \bMSI[E] !no-gzip !gzip-only-text/html
    
            Header append Vary User-Agent env=!dont-vary
     </IfModule>
    
     <IfDefine APACHE2>
            AcceptPathInf  On
     </IfDefine>
    
     #<IfModule mod_auth_basic.c>
     #       AuthType Basic
     #       AuthName "My http basic auth realm"
     #       AuthUserFile /path/to/my/htusers
     #       require valid-user
     #</IfModule>

    Go to the webservers configuration directory and create a new alias (maybe in /etc/apache2/conf.d/icinga-web.conf) :

    # vi /etc/apache2/conf.d/icinga-web.conf
      Alias /icinga-web /usr/local/icinga-web/pub
      <directory /usr/local/icinga-web/pub>
            AllowOverride All
      </directory>

    Clear cache:

    # rm /usr/local/icinga-web/app/cache/config/*.php

    Restart your Webserver:

    # service apache2 restart

    or

    # /etc/init.d/apache2 restart

    or

    # /etc/init.d/httpd restart
  7. Use It!

    Please ensure that your RDBMS, Apache, IDOUtils and Icinga are running!

    Go to the webpath (http://localhost/icinga-web/) and check if the webinterface starts without exceptions (database connections web and api). You can login with user 'root' and password 'password'.

    Have fun! :-)

  8. Test & Errors ?

    The following collection shows some useful information how to resolve errors - and what you should provide when reporting an error to the mailing lists or http://www.icinga-portal.org

    * Always provide the version - actual tar.gz or GIT?

    * Add your browser and the version

    * If the problem is related to the data source, provide extensive information about API, IDOUtils, Core (version, debug logs)

    Where to look?

    * Apache Error Logs, PHP Errors, PHP files cannot be found

    * /var/log/messages, /path/to/icinga/var/icinga.log Changes on Icinga Web Config (e.g. API IDOUtils credentials changed) are not used?

    * Delete the config cache in app/cache/config/*.php

    Icinga Web shows a blank page?

    * Apache Error Logs => mod_rewrite enabled, php dependencies ok? 'make testdeps'

    * .htaccess/vhost config => paths not correct?

    Icinga Web does not show any data?

    * Apache Error logs tell that IcingaApi.php was not found => recheck the install guide if Icinga API is installed and properly configured

    * DB access denied => check if the icinga web database connection settings are correct

    IDOUtils DB does not get filled with data?

    * "Error writing to data sink" => check IDOUtils (ido2db runs 2x - ok?), ido2db.cfg debug_level=-1, debug_verbosity=2, restart IDOUtils and look for errors in ido2db.debug

    * Nothing there => Check icinga.log if IDOMOD gets loaded if not enable the Event Broker Module in icinga.cfg like described in the Icinga Core with IDOUtils Quickstart Guide

    * IDOUtils DB-Schema is the current one? => If not check the upgrade path and docs of IDOUtils

    * Sockets correctly defined? => unix-socket or tcp-socket, the last one with or without SSL

    Testing the Web:

    # cd etc/tests/
    # php icingaWebTesting.php
    [Note] Note

    Remember - changing the php settings in php.ini requires an apache reload/restart!

    * PHP Fatal error: Allowed memory size of ... bytes exhausted (tried to allocate ... bytes) => Check your php.ini (both apache2 and cli) and adjust memory_limit to 128M or higher.

    * Could not connect to API. The API Connector returned the following message: getConnection failed: Database connection failed: SQLSTATE[28000] [1045] Access denied for user 'icinga'@'localhost' (using password: YES))

    => check your IDOUtils DB credentials in ido2db.cfg and add those to app/module/Web/config/module.xml as API credentials. With 1.0.3 you can set those values directly during configure

    * touch: cannot touch `/usr/local/icinga-web/.../cache/testfile.txt': Permission denied => Your configuration in the xml files will be pre-cached by the framework. It therefore needs special permissions on the caching directories. By running icingaWebTesting.php in etc/tests you will be asked to automatically fix this.

    * PHP Fatal error: Uncaught exception '...' with message 'Couldn't locate driver named mysql' => Make sure that the php pdo is installed and loaded in an appropriate way, even if make testdeps tells everything is fine.

    * Login is not shown => enable short_open_tag in your php.ini

    => edit open_basedir in your php.ini and add icinga web location and parent location of icinga api (e.g. /usr/local/icinga/share/).

    * Empty Icinga Web? => If mod_rewrite is enabled and 'index.php' appears in the request url the portal does not work. Try to remove the index.php from your url and everything should work

    * Counts in the Status Cronk do not match your configuration? => Check with the Backend, e.g. IDOUtils DB, selecting the counts for the status tables.

    If you have any updates on that please do not hesitate to report back! :-)