summaryrefslogtreecommitdiffstats
path: root/doc/20-Advanced-Topics.md
blob: 4f47e0250196acaccef07b1de760da78e4383d90 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
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.