Keywords: Supervision, Icinga, Nagios, Linux

Installation of the Icinga-Web Frontend
Prev | Chapter 6. User Interfaces | Next

## 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: Icinga-Wiki

This installation guide describes the installation of Icinga-Web with MySQL as underlying database. Icinga-Web also supports Oracle and PostgreSQL as database backends.

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 (CentOS <= 5.4) 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 php5-mysql

   | Note
   For Ubuntu you install the required PDO extensions with php5 and php5-mysql! There is no php5-pdo package available.

   Fedora / RHEL / CentOS

        #> yum install php php-cli php-pear php-xmlrpc php-xsl php-pdo php-gd php-ldap php-mysql

   | 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", "php5-gd" and "php5-mysql". The CLI is contained in the php5 package.

   | 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.4.0.tar.gz

   Then change to the directory:

        #> cd icinga-web-1.4.0

   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-web-path=/icinga-web
                       --with-web-apache-path=/etc/apache2/conf.d
                       --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
                       --with-api-type=APICON API type (default CONNECTION_IDO)
                       --with-api-subtype=TYPE DB driver or network connection
                       --with-api-host=HOST Host to connect (DB or other) (default localhost)
                       --with-api-port=PORT Port for connection (default 3306)
                       --with-api-socket=PATH Path to socket (default none)

   | Note
   Keep in mind that you configure the Icinga Web database not the Icinga IDOUtils database! User and group name of the web process depend on the distribution used.

   Please use:

        #> ./configure --help

   to see all configure options.

   | Note
   Using no options the installer expects the icinga-API to be found at /usr/local/icinga/share/icinga-api.

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

        #> ./configure
        #> make install

   Install the new Apache configuration

        #> make install-apache-config

   If you don't need an alias, you can alternatively use the old behaviour setting a symlink instead:

        #> make install-javascript

   Make reports after install:

        #> make install-done

        Installation of icinga-web succeeded.
        Please check the new Apache2 configuration (etc/apache2/icinga-web.conf).

   Other useful target:

        #> make icinga-reset-password

   Reset password for any account on icinga-web.

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). If you use php < 5.3.0, you have to set "safe_mode" to "off". The locations depend on the distributions used.

        #> vi /etc/php5/apache/php.ini
          magic_quotes_gpc = off
          safe_mode = off

        #> vi /etc/php5/cli/php.ini
          magic_quotes_gpc = off

   | 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';

   MySQL

        # mysql -u root -p

        mysql> CREATE DATABASE icinga_web;

               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;

               GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, INDEX ON icinga_web.* TO 'icinga_web'@'localhost';

               quit

   Create Database

   Icinga Web ships with Doctrine so you can initialise 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-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

   | Note
   Optional: Your specific Icinga database settings can be set in app/config/.site.xml and will be used in the first place. This won't get overwritten during upgrade process.

           <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/icinga-io.xml.xml for the IcingaApi factories: IcingaData and IcingaCommand.

        #> vi app/modules/Web/config/icinga-io.xml

   | Note
   Optional: Your specific Icinga connection settings like api credentials config can be set in app/modules/Web/config/icinga-io.site.xml and will be used in the first place. This won't get overwritten during upgrade process.

   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
   After changing those configs you need to clear the config cache again!

        #> rm -rf app/cache/config/*.php

   or /path/to/clearcache.sh

        #> /usr/local/icinga-web/bin/clearcache.sh

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 or SLES 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=...".

     Using Debian or Ubuntu "a2enmod rewrite" activates the module as well.

     The httpd of RHEL / Fedora / CentOS already supports rewriting so you don't have to change anything in this regard.

   - Any htaccess enabled alias settings

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

     At line 14, change the RewriteBase direction to suit to 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. Look if the created config by make install-apache-config suits to your configuration. Or create new aliases (maybe in /etc/apache2/conf.d/icinga-web.conf) :

       #> cat /etc/apache2/icinga-web.conf

       # icinga-web apache configuration
       # - Enable all options .htaccess
       # - Add extjs library to alias
       #

       Alias /icinga-web/js/ext3 /usr/local/icinga-web/lib/ext3
       Alias /icinga-web /usr/local/icinga-web/pub

       <Directory /usr/local/icinga-web/lib/ext3>
           Order allow,deny
           Allow from all
       </Directory>

       <Directory /usr/local/icinga-web/pub>
           DirectoryIndex index.php
           Options FollowSymLinks
           AllowOverride all
           Order allow,deny
           Allow from all
       </Directory>

   Clear cache:

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

   or /path/to/clearcache.sh

       #> /usr/local/icinga-web/bin/clearcache.sh

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

   use /path/to/clearcache.sh

       #> /usr/local/icinga-web/bin/clearcache.sh

   Icinga Web shows a blank page?

   * Apache Error Logs => mod_rewrite enabled, php dependencies ok? 'make testdeps'. Using Debian you may find something like the following: ".htaccess: Invalid command 'RewriteEngine', perhaps misspelled or defined by a module not included in the server configuration"

   * .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
   If you are using your root account for testing then make sure in advance that the specified web user has a valid shell. Otherwise some tests might fail. Depending on the version used you might experience wrong permissions on /usr/local/icinga-web/app/data/log resulting in Icinga-Web showing "loading" coming to no end!

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

   * PHP Fatal error: Uncaught exception 'AgaviCacheException' with message 'Failed to write cache file /usr/local/icinga-web/app/cache/config/config_handlers.xml_development__xxxx.php" generated from configuration file /usr/local/icinga-web/app/config/config_handlers.xml". Please make sure you have set correct write permissions for directory /usr/local/icinga-web/app/cache.... = > Check /etc/php5/apache/php.ini, set safe_mode = off.

   * 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 Icinga Web configuration as preferred DB credentials for IDO (see above). 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

   * Login possible but Icinga Web keeps loading data...

   * Request failed, Ressource /icinga-web/appkit/ext/application State could not be loaded - is the url correct? => mod_rewrite enabled ?

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

   * No Data shown in Cronks? => Make sure that all permissions are set correctly, escecially the log/

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

Prev | Up | Next
Information On CGI parameters | Home | Upgrading Icinga-Web and Icinga-Web Database

© 2009-2011 Icinga Development Team, http://www.icinga.org