diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/20-Advanced-Topics.md | 380 |
1 files changed, 380 insertions, 0 deletions
diff --git a/doc/20-Advanced-Topics.md b/doc/20-Advanced-Topics.md new file mode 100644 index 0000000..4f47e02 --- /dev/null +++ b/doc/20-Advanced-Topics.md @@ -0,0 +1,380 @@ +# Advanced Topics <a id="advanced-topics"></a> + +This chapter provides details for advanced Icinga Web 2 topics. + +* [Global URL parameters](20-Advanced-Topics.md#global-url-parameters) +* [VirtualHost configuration](20-Advanced-Topics.md#virtualhost-configuration) +* [Advanced Authentication Tips](20-Advanced-Topics.md#advanced-topics-authentication-tips) +* [Source installation](20-Advanced-Topics.md#installing-from-source) +* [Automated setup](20-Advanced-Topics.md#web-setup-automation) +* [Kiosk Mode Configuration](20-Advanced-Topics.md#kiosk-mode) + +## Global URL Parameters <a id="global-url-parameters"></a> + +Parameters starting with `_` are for development purposes only. + +Parameter | Value | Description +------------------|---------------|-------------------------------- +showFullscreen | - | Hides the left menu and optimizes the layout for full screen resolution. +showCompact | - | Provides a compact view. Hides the title and upper menu. This is helpful to embed a dashboard item into an external iframe. +format | json/csv/sql | Selected views can be exported as JSON or CSV. This also is available in the upper menu. You can also export the SQL queries for manual analysis. +\_dev | 0/1 | Whether the server should return compressed or full JS/CSS files. This helps debugging browser console errors. + + + +Examples for `showFullscreen`: + +http://localhost/icingaweb2/dashboard?showFullscreen +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&showFullscreen + +Examples for `showCompact`: + +http://localhost/icingaweb2/dashboard?showCompact&showFullscreen +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&showCompact + +Examples for `format`: + +http://localhost/icingaweb2/monitoring/list/services?format=json +http://localhost/icingaweb2/monitoring/list/services?service_problem=1&sort=service_severity&dir=desc&format=csv + + +## VirtualHost Configuration <a id="virtualhost-configuration"></a> + +This describes how to run Icinga Web 2 on your FQDN's `/` entry point without +any redirect to `/icingaweb2`. + +### VirtualHost Configuration for Apache <a id="virtualhost-configuration-apache"></a> + +Use the setup CLI commands to generate the default Apache configuration which serves +Icinga Web 2 underneath `/icingaweb2`. + +The next steps are to create the VirtualHost configuration: + +* Copy the `<Directory "/usr/share/icingaweb2/public">` into the main VHost configuration. Don't forget to correct the indent. +* Set the `DocumentRoot` variable to look into `/usr/share/icingaweb2/public` +* Modify the `RewriteBase` variable to use `/` instead of `/icingaweb2` + +Example on RHEL/CentOS: + +``` +vim /etc/httpd/conf.d/web.icinga.com.conf + +<VirtualHost *:80> + ServerName web.icinga.com + + ## Vhost docroot + # modified for Icinga Web 2 + DocumentRoot "/usr/share/icingaweb2/public" + + ## Rewrite rules + RewriteEngine On + + <Directory "/usr/share/icingaweb2/public"> + Options SymLinksIfOwnerMatch + AllowOverride None + + <IfModule mod_authz_core.c> + # Apache 2.4 + <RequireAll> + Require all granted + </RequireAll> + </IfModule> + + <IfModule !mod_authz_core.c> + # Apache 2.2 + Order allow,deny + Allow from all + </IfModule> + + SetEnv ICINGAWEB_CONFIGDIR "/etc/icingaweb2" + + EnableSendfile Off + + <IfModule mod_rewrite.c> + RewriteEngine on + # modified base + RewriteBase / + RewriteCond %{REQUEST_FILENAME} -s [OR] + RewriteCond %{REQUEST_FILENAME} -l [OR] + RewriteCond %{REQUEST_FILENAME} -d + RewriteRule ^.*$ - [NC,L] + RewriteRule ^.*$ index.php [NC,L] + </IfModule> + + <IfModule !mod_rewrite.c> + DirectoryIndex error_norewrite.html + ErrorDocument 404 /error_norewrite.html + </IfModule> + </Directory> +</VirtualHost> +``` + +Reload Apache and open the FQDN in your web browser. + +``` +systemctl reload httpd +``` + +## Advanced Authentication Tips <a id="advanced-topics-authentication-tips"></a> + +### Manual User Creation for Database Authentication Backend <a id="advanced-topics-authentication-tips-manual-user-database-auth"></a> + +Icinga Web 2 v2.5+ uses the [native password hash algorithm](https://php.net/manual/en/faq.passwords.php) +provided by PHP 5.6+. + +In order to generate a password, run the following command with the PHP CLI >= 5.6: + +``` +php -r 'echo password_hash("yourtopsecretpassword", PASSWORD_DEFAULT);' +``` + +Please note that the hashed output changes each time. This is expected. + +Insert the user into the database using the generated password hash. + +``` +INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$2y$10$bEKU6.1bRYjE7wxktqfeO.IGV9pYAkDBeXEbjMFSNs26lKTI0JQ1q'); +``` + +#### Puppet <a id="advanced-topics-authentication-tips-manual-user-database-auth-puppet"></a> + +Please do note that the `$` character needs to be escaped with a leading backslash in your +Puppet manifests. + +Example from [puppet-icingaweb2](https://github.com/Icinga/puppet-icingaweb2): + +``` + exec { 'create default user': + command => "mysql -h '${db_host}' -P '${db_port}' -u '${db_username}' -p'${db_password}' '${db_name}' -Ns -e 'INSERT INTO icingaweb_user (name, active, password_hash) VALUES (\"icingaadmin\", 1, \"\$2y\$10\$QnXfBjl1RE6TqJcY85ZKJuP9AvAV3ont9QihMTFQ/D/vHmAWaz.lG\")'", + refreshonly => true, + } +``` + + +## Icinga Web 2 Manual Setup <a id="web-setup-manual-from-source"></a> + +If you have chosen not to run the setup wizard, you will need further knowledge +about + +* manual creation of the Icinga Web 2 database `icingaweb2` including a default user (optional as authentication and session backend) +* additional configuration for the application +* additional configuration for the monitoring module (e.g. the IDO database and external command pipe from Icinga 2) + +This comes in handy if you are planning to deploy Icinga Web 2 automatically using +Puppet, Ansible, Chef, etc. + +> **Warning** +> +> Read the documentation on the respective linked configuration sections before +> deploying the configuration manually. +> +> If you are unsure about certain settings, use the setup wizard as described in the +> [installation instructions](02-Installation.md) once and then collect the generated +> configuration as well as sql dumps. + +### Icinga Web 2 Manual Database Setup <a id="web-setup-manual-from-source-database"></a> + +Create the database and add a new user as shown below for MySQL/MariaDB: + +``` +sudo mysql -p + +CREATE DATABASE icingaweb2; +GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icingaweb2.* TO 'icingaweb2'@'localhost' IDENTIFIED BY 'icingaweb2'; +quit + +mysql -p icingaweb2 < /usr/share/icingaweb2/schema/mysql.schema.sql +``` + + +Then generate a new password hash as described in the [authentication docs](05-Authentication.md#authentication-configuration-db-setup) +and use it to insert a new user called `icingaadmin` into the database. + +``` +mysql -p icingaweb2 + +INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('icingaadmin', 1, '$1$EzxLOFDr$giVx3bGhVm4lDUAw6srGX1'); +quit +``` + +### Icinga Web 2 Manual Configuration <a id="web-setup-manual-from-source-config"></a> + + +[resources.ini](04-Resources.md#resources) providing the details for the Icinga Web 2 and +Icinga 2 IDO database configuration. Example for MySQL: + +``` +vim /etc/icingaweb2/resources.ini + +[icingaweb2] +type = "db" +db = "mysql" +host = "localhost" +port = "3306" +dbname = "icingaweb2" +username = "icingaweb2" +password = "icingaweb2" + + +[icinga2] +type = "db" +db = "mysql" +host = "localhost" +port = "3306" +dbname = "icinga" +username = "icinga" +password = "icinga" +``` + +[config.ini](03-Configuration.md#configuration) defining general application settings. + +``` +vim /etc/icingaweb2/config.ini + +[logging] +log = "syslog" +level = "ERROR" +application = "icingaweb2" + + +[preferences] +type = "db" +resource = "icingaweb2" +``` + +[authentication.ini](05-Authentication.md#authentication) for e.g. using the previously created database. + +``` +vim /etc/icingaweb2/authentication.ini + +[icingaweb2] +backend = "db" +resource = "icingaweb2" +``` + + +[roles.ini](06-Security.md#security) granting the previously added `icingaadmin` user all permissions. + +``` +vim /etc/icingaweb2/roles.ini + +[admins] +users = "icingaadmin" +permissions = "*" +``` + +### Icinga Web 2 Manual Configuration Monitoring Module <a id="web-setup-manual-from-source-config-monitoring-module"></a> + + +**config.ini** defining additional security settings. + +``` +vim /etc/icingaweb2/modules/monitoring/config.ini + +[security] +protected_customvars = "*pw*,*pass*,community" +``` + +**backends.ini** referencing the Icinga 2 DB IDO resource. + +``` +vim /etc/icingaweb2/modules/monitoring/backends.ini + +[icinga2] +type = "ido" +resource = "icinga2" +``` + +**commandtransports.ini** defining the Icinga 2 API command transport. + +``` +vim /etc/icingaweb2/modules/monitoring/commandtransports.ini + +[icinga2] +transport = "api" +host = "localhost" +port = "5665" +username = "api" +password = "api" +``` + +### Icinga Web 2 Manual Setup Login <a id="web-setup-manual-from-source-login"></a> + +Finally visit Icinga Web 2 in your browser to login as `icingaadmin` user: `/icingaweb2`. + +## Automating the Installation of Icinga Web 2 <a id="web-setup-automation"></a> + +Prior to creating your own script, please look into the official resources +which may help you already: + +* [Puppet module](https://icinga.com/products/integrations/puppet/) +* [Chef cookbook](https://icinga.com/products/integrations/chef/) + +If you are automating the installation of Icinga Web 2, you may want to skip the wizard and do things yourself. +These are the steps you'd need to take assuming you are using MySQL/MariaDB. If you are using PostgreSQL please adapt +accordingly. Note you need to have successfully completed the Icinga 2 installation, installed the Icinga Web 2 packages +and all the other steps described above first. + +1. Install PHP dependencies: `php`, `php-intl`, `php-imagick`, `php-gd`, `php-mysql`, `php-curl`, `php-mbstring` used +by Icinga Web 2. +2. Create a database for Icinga Web 2, i.e. `icingaweb2`. +3. Import the database schema: `mysql -D icingaweb2 < /usr/share/icingaweb2/schema/mysql.schema.sql`. +4. Insert administrator user in the `icingaweb2` database: +`INSERT INTO icingaweb_user (name, active, password_hash) VALUES ('admin', 1, '<hash>')`, where `<hash>` is the output +of `php -r 'echo password_hash("yourtopsecretpassword", PASSWORD_DEFAULT);'`. +5. Make sure the `ido-mysql` and `api` features are enabled in Icinga 2: `icinga2 feature enable ido-mysql` and +`icinga2 feature enable api`. +6. Generate Apache/nginx config. This command will print an apache config for you on stdout: +`icingacli setup config webserver apache`. Similarly for nginx. You need to place that configuration in the right place, +for example `/etc/apache2/sites-enabled/icingaweb2.conf`. +7. Add `www-data` user to `icingaweb2` group if not done already (`usermod -a -G icingaweb2 www-data`). +8. Create the Icinga Web 2 configuration in `/etc/icingaweb2`. The directory can be easily created with: +`icingacli setup config directory`. This command ensures that the directory has the appropriate ownership and +permissions. If you want to create the directory manually, make sure to chown the group to `icingaweb2` and set the +access mode to `2770`. + +The structure of the configurations looks like the following: + +``` +/etc/icingaweb2/ +/etc/icingaweb2/authentication.ini +/etc/icingaweb2/modules +/etc/icingaweb2/modules/monitoring +/etc/icingaweb2/modules/monitoring/config.ini +/etc/icingaweb2/modules/monitoring/instances.ini +/etc/icingaweb2/modules/monitoring/backends.ini +/etc/icingaweb2/roles.ini +/etc/icingaweb2/config.ini +/etc/icingaweb2/enabledModules +/etc/icingaweb2/enabledModules/monitoring +/etc/icingaweb2/enabledModules/doc +/etc/icingaweb2/resources.ini +``` + +Have a look [here](20-Advanced-Topics.md#web-setup-manual-from-source-config) for the contents of the files. + +## Kiosk Mode Configuration <a id="kiosk-mode"></a> + +Be aware that when you create a kiosk user every person who has access to the kiosk is able to perform tasks on it. +Therefore you would need to create a user in the `roles.ini` in `/etc/icingaweb2/roles.ini`. + + [kioskusers] + users = "kiosk" + +If you need special permissions you should add those permissions to the user via the admin account in icingaweb2 to the role of the kiosk user. + +For the Dashboard system where you want to display the kiosk you can add also the following part into the `icingaweb2.conf`. +So it starts directly into the kiosk mode. +If you want to show a specific Dashboard you can enforce this onto the kiosk user via the [enforceddashboard](https://github.com/Thomas-Gelf/icingaweb2-module-enforceddashboard) module. + +``` +<ifmodule mod_authz_core.c> + # Apache 2.4 + SetEnvIf Remote_Addr "X.X.X.X" REMOTE_USER=kiosk + <requireall> + Require all granted + </requireall> +</ifmodule> +``` + +Replace Remote_Addr with the IP where the kiosk user is accessing the Web to restrict further usage from other IPs. |