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

## Installation of the Icinga-Web Frontend

Introduction

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 or PostgreSQL as underlying database. Icinga-Web also supports Oracle as database backend.

1. Prerequisites

   MySQL

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

     - Ubuntu / Debian

            #> apt-get install php5 php5-cli php-pear php5-xmlrpc php5-xsl php5-pdo php5-soap 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-soap php-gd php-ldap php-mysql

       | Note

       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. 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 is described in the Icinga with IDOUtils Quickstart Guide

   PostgreSQL

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

     - Ubuntu / Debian

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

       | Note
       For Ubuntu you install the required PDO extensions with php5 and php5-pgsql! 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-pgsql

       | Note

       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. 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 is described in the Icinga with IDOUtils Quickstart Guide

   The installation

   Please download the archive from http://sourceforge.net/projects/icinga/files/. If your need a function only available in the latest developer version then 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.7.0.tar.gz

   Then change to the directory:

        #> cd icinga-web-1.7.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-conf-dir=etc/conf.d
                       --with-log-folder=log
                       --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.

   To configure Icinga-Web for PostgreSQL please execute the following command:

        #> ./configure --with-db-type=pgsql --with-db-port=5432

   If Icinga is running using pqsql as well then please supply the api-options as well:

        #> ./configure --with-db-type=pgsql --with-db-port=5432 \
           --with-api-subtype=pgsql --with-api-port=5432

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

        #> ./configure
        #> make install

   This may take a while so please be patient ;-).

   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.

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

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

                 FLUSH PRIVILEGES;

                 quit

   - PostgreSQL

          #> su - postgres

          $ psql

          postgres=# CREATE USER icinga_web;

          postgres=# ALTER USER icinga_web WITH PASSWORD 'icinga_web' CREATEDB;

          <Ctrl>+<D>

   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.

   PostgreSQL

   Please edit the file `pg_hba.conf` and add the following lines:

        #> vi /etc/postgresql/9.x/main/pg_hba.conf

        # database administrative login by UNIX sockets
        local all postgres ident

        # TYPE DATABASE USER CIDR-ADDRESS METHOD
        #icinga_web
        local icinga_web icinga_web trust

        # "local" is for Unix domain socket connections only
        local all all trust

        # IPv4 local connections
        host all all 127.0.0.1/32 trust

        # IPV6 local connections
        host all all ::1/128 trust

   Please keep in mind to restart PostgreSQL afterwards:

        #> /etc/init.d/postgresql reload

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

   | Note

   You may find it easier to use syntax highlighting while editing xml structures to differ between comments and xml tags.

   Edit `/etc/vim/vimrc`

        " Vim5 and later versions support syntax highlighting. Uncommenting the next
        " line enables syntax highlighting by default.
        syntax on

   or `/etc/nanorc`

        ## HTML
        include "/usr/share/nano/html.nanorc"

        #> vi app/config/databases.xml

   | Note

   Optional: Your specific Icinga database settings can be set in `etc/conf.d/database.xml` (or where your web_conf_path directive points to) and will be used in the first place. This won't get overwritten during upgrade process. There are two databases : 'icinga_web' (for internal use, created above) and 'icinga', which is the database ido2db writes to. (if using oracle, you must use icingaOracle as the dsn driver)

          <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
                -->
                <!-- ##### MySQL ##### -->
                <ae:parameter name="dsn">mysql://icinga_web:icinga_web@127.0.0.1:3306/icinga_web</ae:parameter>
                <!-- ##### PostgreSQL ##### -->
                <ae:parameter name="dsn">pgsql://icinga_web:icinga_web@localhost:5432/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>

             <-- The ido2db  icinga database-->
             <database name="icinga" class="AgaviDoctrineDatabase">

                <!--
                   Doctrine dsn strings:

                   http://www.doctrine-project.org/documentation/manual/1_1/en/introduction-to-connections
                -->
                <!-- ##### MySQL ##### -->
                <ae:parameter name="dsn">mysql://icinga:icinga@127.0.0.1:3306/icinga</ae:parameter>
                <!-- ##### PostgreSQL ##### -->
                <ae:parameter name="dsn">pgsql://icinga:icinga@localhost:5432/icinga</ae:parameter>

                <!-- Generic credentials  -->
                <!-- <ae:parameter name="username">icinga</ae:parameter> -->
                <!-- <ae:parameter name="password">icinga</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%/Api/lib/database/models/generated</ae:parameter>
                <ae:parameter name="models_directory">%core.module_dir%/Api/lib/database/models</ae:parameter>

             </database>
          </databases>

   In the `access.xml` you can specify the locations of your command pipe and the access credentials and method (ssh or via local console). Also you define here, which icinga instance is mapped to which host.

               <!-- Map your instances to hosts here -->
               <instances>
                   <instance name="default">localhost</instance>
               </instances>
               <!-- default location of the icinga pipe -->
               <defaults>
                   <access>
                       <write>
                           <files>
                               <resource name="icinga_pipe">/usr/local/icinga/var/rw/icinga.cmd</resource>
                           </files>
                       </write>
                   </access>
               </defaults>

               <!-- Hosts that can be accessed via the console interface -->
               <hosts>
                   <host name="localhost">
                       <type>local</type>
                       <!-- Only allow access to these files, folders or executables -->
                       <access useDefaults="true">
                           <read>
                               <files>
                                   <resource name="test">test</resource>
                               </files>
                           </read>
                       </access>
                   </host>

                   <!--  Example for ssh connection with user/password auth -->
                   <host name="remot_host">
                       <type>ssh</type>
                       <ssh-config>
                           <host>localhost</host>
                           <port>22</port>
                           <auth>
                               <type>password</type>
                               <user>john</user>
                               <password>doe</password>
                           </auth>
                       </ssh-config>

                       <access useDefaults="true" />

                   </host>
             </hosts>

   | 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

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

6. 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! :-)

7. Test & Errors?

   | Note
   The following section tries to give some hints on common problems but due to the nature of "written" material the wiki page will most probably be more current than this manual so if you don't find a solution here then have a look over there.

   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 - package, current tar.gz, or GIT?

   - Add your browser and the version

   - If the problem is related to the data source, provide extensive information about 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?

   - 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 (make sure PHPUnit is installed):

        $> make test

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

     | Note
     This may also be an SELinux issue.

   - [PHP Error] strtotime(): It is not safe to rely on the system's timezone settings. You are *required* to use the date.timezone setting or the date_default_timezone_set() function. In case you used any of those methods and you are still getting this warning, you most likely misspelled the timezone identifier. We selected 'Europe/Berlin' for 'CEST/2.0/DST' instead [line 1548 of /home/xxx/icinga/icinga-web/lib/doctrine/lib/Doctrine/Record.php] = > You have to define date.timezone in your `php.ini`.

   - 500 internal server error! Uncaught exception AgaviException thrown! Your default timezone is 'System/Localtime', ... => You have to define date.timezone in your `php.ini`.

   - 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, Resource /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, especially the log/. Furthermore, you can debug the data in your browser.

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

Prev | Up | Next
Executing CGIs on the command line | Home | Upgrading Icinga-Web and Icinga-Web Database

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