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:

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:

Please download the archive from http://www.icinga.org/download/. 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.14.tar.gz

Then change to the directory:

 #> cd icinga-web-1.14

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

	Note
	Starting with Apache 2.4 (testing versions of Debian / Ubuntu) the default web configuration folder has changed from /etc/apache2/conf.d to /etc/apache2/conf-available so you might have to add this option to the call of configure #> ./configure --with-web-apache-path=/etc/apache2/conf-available

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

	Note
	Starting with Apache 2.4 (testing versions of Debian / Ubuntu ) you have to enable the module #> a2enconf icinga-web

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.

Adjusting the SELinux settings

RHEL and derived distributions like Fedora and CentOS are shipped with activated SELinux (Security Enhanced Linux) running in "enforcing" mode. This may lead to "Internal Server Error" messages when you try to invoke the Icinga-CGIs.

Check if SELinux runs in enforcing mode

 #> getenforce

Set SELinux in "permissive" mode

 #> setenforce 0

To make this change permanent you have to adjust this setting in /etc/selinux/config and restart the system.

Instead of deactivating SELinux or setting it into permissive mode you can use the following commands to run the CGIs in enforcing/targeted mode. The semanage command will automatically add entries to /etc/selinux/targeted/contexts/files/file_contexts.local.

 #> semanage fcontext -a -t httpd_sys_content_t '/usr/local/icinga-web/app(/.*)?'
 #> semanage fcontext -a -t httpd_sys_content_t '/usr/local/icinga-web/lib(/.*)?'
 #> semanage fcontext -a -t httpd_sys_content_t '/usr/local/icinga-web/pub(/.*)?'
 #> semanage fcontext -a -t httpd_sys_rw_content_t '/usr/local/icinga-web/app/cache(/.*)?'
 #> semanage fcontext -a -t httpd_sys_rw_content_t '/usr/local/icinga-web/log(/.*)?'

Once you have defined the necessary contexts you have to apply the settings:

 #> chcon -R /usr/local/icinga-web

For details please take a look at http://www.linuxquestions.org/questions/blog/sag47-492023/selinux-and-icinga-34926/.

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

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.

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

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 needed SQL script from </path/to/icinga-web/etc/schema/>

and then import the script into your freshly created database:

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

Apache settings

This should be prepared:

	Note
	The file .htaccess has been removed in 1.9 and the options have been moved to the Apache configuration file.

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

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)

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

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?

"I cannot see my newly installed cronk?" or "after upgrade, I cannot access the reporting cronk"

Starting with 1.8.2, a new session cache was added which may cause irritations when upgrading icinga web / installing a new cronk or module. The resolution is rather simple

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

"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

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.