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
|
<!DOCTYPE html>
<html lang=en>
<head>
<title></title>
<meta charset="utf-8"/>
<link rel="shortcut icon" href="favicon.ico"/>
<link rel='stylesheet' href='../style.css'/>
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<header><h1>Icinga2 Master Installation</h1></header>
<main>
<p>
This tutorial will cover the installation of the Icinga2
monitoring application master node. This includes the base
program, the web frontend, and the web-based configuration tool.
This guide was made for Debian but should be similar
on other distributions.
</p>
<p>
I have a script available to automate the steps described in this
tutorial available
<a href=https://git.chudnick.com/server-scripts/tree/monitoring/icinga-master>from my git repo</a>.
<h2>Install Packages</h2>
<p>Here we will install the required packages. Icinga can use either MySQL
or PostgreSQL, however this tutorial will use MySQL/MariaDB.</p>
<pre><code>apt install icinga2 icingaweb2 icinga2-ido-mysql icingaweb2-module-director monitoring-plugins monitoring-plugins-contrib default-mysql-server</code></pre>
<h2>Secure MySQL</h2>
<p>This step is optional but strongly recommended.
The mysql_secure_installation script will harden your MySQL instance.</p>
<pre><code>mysql_secure_installation</code></pre>
<p>I recommend the following responses:
<ul>
<li><em>Switch to unix_socket authentication?</em><strong> Y</strong></li>
<li><em>Change the root password?</em><strong> Y</strong></li>
<li><em>Remove anonymous users?</em><strong> Y</strong></li>
<li><em>Disallow root login remotely?</em><strong> Y</strong></li>
<li><em>Remove the test database and access to it?</em><strong> Y</strong></li>
<li><em>Reload privilege tables now?</em><strong> Y</strong></li>
</ul>
</p>
<h2>Create Monitoring Database</h2>
<p>The next several sections will cover creating databases for the various
parts of Icinga. We'll start with the monitoring database.
The following command creates a MySQL database named <em>icinga2</em>
and grants permissions to a user named <em>ido_admin</em>. These values
are arbitrary, but I use them throughout the tutorial so I recommend leaving them
as is. You should definitely change the password though, which in the command
is <em>change me</em>. You will need this password and the passwords for the
other databases later, so make sure you save them.</p>
<pre><code>mysql -u root -e "CREATE DATABASE icinga2; GRANT SELECT, INSERT, UPDATE, DELETE, DROP, CREATE VIEW, INDEX, EXECUTE ON icinga2.* TO <em>ido_admin</em>@'localhost' IDENTIFIED BY '<em>change me</em>'; FLUSH PRIVILEGES;</code></pre>
<p>We then need to import the ido schema into the database.</p>
<pre><code>mysql -u root icinga2 </usr/share/icinga2-ido-mysql/schema/mysql.sql</code></pre>
<p>After importing the schema, we then write the configuration file that tells
the monitoring module how to connect to the database.</p>
<pre><code><strong>/etc/icinga2/features-available/ido-mysql.conf</strong>
library "db_ido_mysql"
object IdoMysqlConnection "ido-mysql" {
user = "ido_admin",
password = "<em>ido_password</em>",
host = "localhost",
database = "icinga2"
}"</code></pre>
<p>And finally we enable the monitoring module in Icinga.</p>
<pre><code>icinga2 feature enable ido-mysql</code></pre>
<h2>Create Icingaweb2 Database</h2>
<p>This step is nearly identical to the last. This time we create a database
named <em>icingaweb2</em> and grant permissions to the user named
<em>icingaweb2_admin</em>.</p>
<pre><code>mysql -u root -e "CREATE DATABASE icingaweb2;GRANT ALL ON icingaweb2.* TO 'icingaweb2_admin'@'localhost' IDENTIFIED BY '<em>changeme</em>'; FLUSH PRIVILEGES;</code></pre>
<p>Again we will need to import required schema into the database.</p>
<pre><code>mysql -u root icingaweb2 </usr/share/icingawbe2/etc/schema/mysql.schema.sql</code></pre>
<p>In this step we create the initial admin user that will be used to login
to the web interface. As is, this would create a user named <em>admin</em>
with the password <em>changme</em>. You should at least change the password.</p>
<pre><code>passhash="$(php -r "echo password_hash(\"<em>changeme</em>\", PASSWORD_DEFAULT);")"
mysql -u root -e "USE icingaweb2; INSERT INTO icingaweb_user (name, active, password_hash) VALUES (\"<em>admin</em>\", 1, \"$passhash\"); FLUSH PRIVILEGES;"</code></pre>
<h2>Create Icinga Director Database</h2>
<p>Here we create the database for Director. Director will require more
configuration later, so for now we will just be creating the database.</p>
<pre><code>mysql -u root -e "CREATE DATABASE director CHARACTER SET 'utf8'; GRANT ALL on director.* TO 'director'@'localhost' IDENTIFIED BY '$director_password';FLUSH PRIVILEGES;"</code></pre>
<h2>Setup Icinga2 API</h2>
<p>Run the following command to initialize the Icinga API.</p>
<pre><code>icinga2 api setup</code></pre>
<p>And then restart Icinga to apply the changes.</p>
<pre><code>systemctl restart icinga2</code></pre>
<h2>Configure Web Server</h2>
<p>In this section we will configure the web server for accessing
Icinga's web interface and Director configuration tool.
This tutorial will use nginx but apache could be used as well.
We'll start by installing the necessary packages.</p>
<pre><code>apt install nginx php-fpm</code></pre>
<p>Then we need to create the site configuration file.<p>
<pre><code><strong>/etc/nginx/sites-available/icingaweb2.conf</strong>
server {
listen 80;
server_name <em>monitoring.example.com</em>
location ~ ^/icingaweb2/index\.php(.*)$ {
fastcgi_pass unix:/var/run/php/php-fpm.sock;
fastcgi_index index.php;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
fastcgi_param REMOTE_USER $remote_user;
}
location ~ ^/icingaweb2(.+)? {
alias /usr/share/icingaweb2/public;
index index.php;
try_files $1 $uri $uri/ /icingaweb2/index.php$is_args$args;
}
<em># Not strictly necessary but allows you to get to icinga without
# specifying /icingaweb2 in the URL.</em>
location = / {
return 302 http://$host/icingaweb2;
}
}</code></pre>
<p>And then restart nginx to pick up the changes.</p>
<pre><code>systemctl restart nginx</code></pre>
<p>At this point we are done with the Icinga setup module and so we
can disable it.</p>
<pre><code>icingacli module disable setup</code></pre>
<h2>Write Configuration Files</h2>
<p>In this section we will write several configuration files. Icinga uses
the INI format for its web interface configuration files.</p>
<p>In this first file we tell Icinga about the various resources it should have
access to. These resources are the three databases created previously.
Replace the password in each section with the corresponding password you set
for that database earlier.</p>
<pre><code><strong>/etc/icingaweb2/resources.ini</strong>
[icinga2]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "icinga2"
username = "ido_admin"
password = "<em>ido password</em>"
charset = ""
use_ssl = "0"
[icingaweb2]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "icingaweb2"
username = "icingaweb2_admin"
password = "<em>ido password</em>"
charset = ""
use_ssl = "0"
[director]
type = "db"
db = "mysql"
host = "localhost"
port = ""
dbname = "director"
username = "director"
password = "<em>director password</em>"
charset = "utf8"
use_ssl = "0"
</code></pre>
<p>This file controls the authentication settings for the web interface.
Here we tell Icinga to look at the icingaweb2 database for
authentication purposes.</p>
<pre><code><strong>/etc/icingaweb2/authentication.ini</strong>
[icingaweb2]
backend = "db"
resource = "icingaweb2"</code></pre>
<p>Now we tell icinga which users should have admin permissions.
If you changed the username value from <em>admin</em> previously, be sure to update
it here.</p>
<pre><code><strong>/etc/icingaweb2/roles.ini</strong>
[admins]
users = "<em>admin</em>"
resource = "icingaweb2"</code></pre>
<p>Enable the web interface monitoring module.</p>
<pre><code>icingacli module enable monitoring</code></pre>
<p>Then write the configuration file pointing the monitoring module to the
monitoring database.</p>
<pre><code><strong>/etc/icingaweb2/modules/monitoring/backends.ini</strong>
[icinga]
type = "ido"
resource = "icinga2"</code></pre>
<p>Here we configure Icinga to use the API for communication.
You will need to get your unique API password generated during the API setup from
from <strong>/etc/icinga2/conf.d/api-users.conf</strong>.
<em>hostname</em> should be the FQDN of the server.</p>
<pre><code><strong>/etc/icingaweb2/modules/monitoring/commandtransports.ini</strong>
[icinga2]
transport = "api"
host = <em>hostname</em>
port = "5665"
username = "root"
password = "<em>api password</em>"</code></pre>
<p>Lastly, tell Icinga to protect variables with potentially sensitive values.</p>
<pre><code><strong>/etc/icingaweb2/modules/monitoring/config.ini</strong>
[security]
protected_customvars = "*pw*,*pass*,*community*"</code></pre>
<h2>Configure Director</h2>
<p>This section will cover configuring Director configuration tool.</p>
<p>Create Director module configuration directory.</p>
<pre><code>mkdir -p /etc/icingaweb2/modules/director</code></pre>
<p>Write the Director configuration file.</p>
<pre><code><strong>/etc/icingaweb2/modules/director/config.ini</strong>
[db]
resource = "director"</code></pre>
<p>Enable Director module and run the initial migration.</p>
<pre><code>icingacli module enable director
icingacli director migration run</code></pre>
<p>Write Director kickstart configuration file.</p>
<pre><code><strong>/etc/icingaweb2/modules/director/kickstart.ini</strong>
[config]
endpoint = "<em>hostname</em>"
username = "root"
password = "<em>api password</em>"</code></pre>
<p>Kickstart Director, then render and deploy the configuration.</p>
<pre><code>icingacli director kickstart run
icingacli director config render
icingacli director config deploy</code></pre>
<p>Director is setup at this point so we will shred the unneeded configuration
file containing sensitive information.</p>
<pre><code>shred -uz /etc/icingaweb2/modules/director/kickstart.ini</code></pre>
<h2>Login to your Monitoring Instance</h2>
<p>You are now ready to login to your monitoring instance with the admin
user created previously. Open a web browser and go to
http://<em>hostname</em>/icingaweb2. You should see a screen similar to this:</p>
<a href=../images/icinga-login.png><img src=../images/icinga-login.png alt="Icinagweb2 Login Screen"></a>
<h2>Next Steps</h2>
<p>In the following articles we will go through setting up Icinga2 agents on servers, and configure your monitoring instance through Icinga Director.</p>
<p>
<hr>
Consider <a href=../donate.html>donating</a> if this article was useful.
<a class=qr href=../images/bitcoin.png>[BTC]</a>
</p>
</main>
<footer>
<a href=../kb.html>Knowledge Base</a>
<br>
<a href=../index.html>www.chudnick.com</a>
</footer>
</body>
</html>
|
