Icinga

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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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] 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! :-)