summaryrefslogtreecommitdiff
path: root/articles/icinga-master.html
diff options
context:
space:
mode:
Diffstat (limited to 'articles/icinga-master.html')
-rw-r--r--articles/icinga-master.html276
1 files changed, 276 insertions, 0 deletions
diff --git a/articles/icinga-master.html b/articles/icinga-master.html
new file mode 100644
index 0000000..0cafcdd
--- /dev/null
+++ b/articles/icinga-master.html
@@ -0,0 +1,276 @@
1<!DOCTYPE html>
2<html lang=en>
3 <head>
4 <title></title>
5 <meta charset="utf-8"/>
6 <link rel="shortcut icon" href="favicon.ico"/>
7 <link rel='stylesheet' href='../style.css'/>
8 <meta name="viewport" content="width=device-width, initial-scale=1">
9 </head>
10<body>
11<header><h1>Icinga2 Master Installation</h1></header>
12<main>
13<p>
14This tutorial will cover the installation of the Icinga2
15monitoring application master node. This includes the base
16program, the web frontend, and the web-based configuration tool.
17This guide was made for Debian but should be similar
18on other distributions.
19</p>
20<p>
21I have a script available to automate the steps described in this
22tutorial available
23<a href=https://git.chudnick.com/server-scripts/tree/monitoring/icinga-master>from my git repo</a>.
24<h2>Install Packages</h2>
25<p>Here we will install the required packages. Icinga can use either MySQL
26or PostgreSQL, however this tutorial will use MySQL/MariaDB.</p>
27<pre><code>apt install icinga2 icingaweb2 icinga2-ido-mysql icingaweb2-module-director monitoring-plugins monitoring-plugins-contrib default-mysql-server</code></pre>
28<h2>Secure MySQL</h2>
29<p>This step is optional but strongly recommended.
30The mysql_secure_installation script will harden your MySQL instance.</p>
31<pre><code>mysql_secure_installation</code></pre>
32<p>I recommend the following responses:
33<ul>
34 <li><em>Switch to unix_socket authentication?</em><strong> Y</strong></li>
35 <li><em>Change the root password?</em><strong> Y</strong></li>
36 <li><em>Remove anonymous users?</em><strong> Y</strong></li>
37 <li><em>Disallow root login remotely?</em><strong> Y</strong></li>
38 <li><em>Remove the test database and access to it?</em><strong> Y</strong></li>
39 <li><em>Reload privilege tables now?</em><strong> Y</strong></li>
40</ul>
41</p>
42
43<h2>Create Monitoring Database</h2>
44<p>The next several sections will cover creating databases for the various
45parts of Icinga. We'll start with the monitoring database.
46The following command creates a MySQL database named <em>icinga2</em>
47and grants permissions to a user named <em>ido_admin</em>. These values
48are arbitrary, but I use them throughout the tutorial so I recommend leaving them
49as is. You should definitely change the password though, which in the command
50is <em>change me</em>. You will need this password and the passwords for the
51other databases later, so make sure you save them.</p>
52<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>
53
54<p>We then need to import the ido schema into the database.</p>
55
56<pre><code>mysql -u root icinga2 &lt;/usr/share/icinga2-ido-mysql/schema/mysql.sql</code></pre>
57
58<p>After importing the schema, we then write the configuration file that tells
59the monitoring module how to connect to the database.</p>
60<pre><code><strong>/etc/icinga2/features-available/ido-mysql.conf</strong>
61library "db_ido_mysql"
62object IdoMysqlConnection "ido-mysql" {
63 user = "ido_admin",
64 password = "<em>ido_password</em>",
65 host = "localhost",
66 database = "icinga2"
67}"</code></pre>
68
69<p>And finally we enable the monitoring module in Icinga.</p>
70<pre><code>icinga2 feature enable ido-mysql</code></pre>
71
72<h2>Create Icingaweb2 Database</h2>
73<p>This step is nearly identical to the last. This time we create a database
74named <em>icingaweb2</em> and grant permissions to the user named
75<em>icingaweb2_admin</em>.</p>
76<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>
77
78<p>Again we will need to import required schema into the database.</p>
79<pre><code>mysql -u root icingaweb2 &lt;/usr/share/icingawbe2/etc/schema/mysql.schema.sql</code></pre>
80
81
82<p>In this step we create the initial admin user that will be used to login
83to the web interface. As is, this would create a user named <em>admin</em>
84with the password <em>changme</em>. You should at least change the password.</p>
85<pre><code>passhash="$(php -r "echo password_hash(\"<em>changeme</em>\", PASSWORD_DEFAULT);")"
86mysql -u root -e "USE icingaweb2; INSERT INTO icingaweb_user (name, active, password_hash) VALUES (\"<em>admin</em>\", 1, \"$passhash\"); FLUSH PRIVILEGES;"</code></pre>
87
88<h2>Create Icinga Director Database</h2>
89<p>Here we create the database for Director. Director will require more
90configuration later, so for now we will just be creating the database.</p>
91<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>
92
93<h2>Setup Icinga2 API</h2>
94<p>Run the following command to initialize the Icinga API.</p>
95<pre><code>icinga2 api setup</code></pre>
96<p>And then restart Icinga to apply the changes.</p>
97<pre><code>systemctl restart icinga2</code></pre>
98
99<h2>Configure Web Server</h2>
100<p>In this section we will configure the web server for accessing
101Icinga's web interface and Director configuration tool.
102This tutorial will use nginx but apache could be used as well.
103We'll start by installing the necessary packages.</p>
104<pre><code>apt install nginx php-fpm</code></pre>
105<p>Then we need to create the site configuration file.<p>
106<pre><code><strong>/etc/nginx/sites-available/icingaweb2.conf</strong>
107server {
108 listen 80;
109 server_name <em>monitoring.example.com</em>
110 location ~ ^/icingaweb2/index\.php(.*)$ {
111 fastcgi_pass unix:/var/run/php/php-fpm.sock;
112 fastcgi_index index.php;
113 include fastcgi_params;
114 fastcgi_param SCRIPT_FILENAME /usr/share/icingaweb2/public/index.php;
115 fastcgi_param ICINGAWEB_CONFIGDIR /etc/icingaweb2;
116 fastcgi_param REMOTE_USER $remote_user;
117 }
118
119 location ~ ^/icingaweb2(.+)? {
120 alias /usr/share/icingaweb2/public;
121 index index.php;
122 try_files $1 $uri $uri/ /icingaweb2/index.php$is_args$args;
123 }
124
125 <em># Not strictly necessary but allows you to get to icinga without
126 # specifying /icingaweb2 in the URL.</em>
127 location = / {
128 return 302 http://$host/icingaweb2;
129 }
130
131}</code></pre>
132<p>And then restart nginx to pick up the changes.</p>
133<pre><code>systemctl restart nginx</code></pre>
134
135<p>At this point we are done with the Icinga setup module and so we
136can disable it.</p>
137<pre><code>icingacli module disable setup</code></pre>
138
139<h2>Write Configuration Files</h2>
140<p>In this section we will write several configuration files. Icinga uses
141the INI format for its web interface configuration files.</p>
142<p>In this first file we tell Icinga about the various resources it should have
143access to. These resources are the three databases created previously.
144Replace the password in each section with the corresponding password you set
145for that database earlier.</p>
146<pre><code><strong>/etc/icingaweb2/resources.ini</strong>
147[icinga2]
148type = "db"
149db = "mysql"
150host = "localhost"
151port = ""
152dbname = "icinga2"
153username = "ido_admin"
154password = "<em>ido password</em>"
155charset = ""
156use_ssl = "0"
157
158[icingaweb2]
159type = "db"
160db = "mysql"
161host = "localhost"
162port = ""
163dbname = "icingaweb2"
164username = "icingaweb2_admin"
165password = "<em>ido password</em>"
166charset = ""
167use_ssl = "0"
168
169
170[director]
171type = "db"
172db = "mysql"
173host = "localhost"
174port = ""
175dbname = "director"
176username = "director"
177password = "<em>director password</em>"
178charset = "utf8"
179use_ssl = "0"
180</code></pre>
181
182<p>This file controls the authentication settings for the web interface.
183Here we tell Icinga to look at the icingaweb2 database for
184authentication purposes.</p>
185<pre><code><strong>/etc/icingaweb2/authentication.ini</strong>
186[icingaweb2]
187backend = "db"
188resource = "icingaweb2"</code></pre>
189
190<p>Now we tell icinga which users should have admin permissions.
191If you changed the username value from <em>admin</em> previously, be sure to update
192it here.</p>
193<pre><code><strong>/etc/icingaweb2/roles.ini</strong>
194[admins]
195users = "<em>admin</em>"
196resource = "icingaweb2"</code></pre>
197
198<p>Enable the web interface monitoring module.</p>
199<pre><code>icingacli module enable monitoring</code></pre>
200<p>Then write the configuration file pointing the monitoring module to the
201monitoring database.</p>
202<pre><code><strong>/etc/icingaweb2/modules/monitoring/backends.ini</strong>
203[icinga]
204type = "ido"
205resource = "icinga2"</code></pre>
206
207<p>Here we configure Icinga to use the API for communication.
208You will need to get your unique API password generated during the API setup from
209from <strong>/etc/icinga2/conf.d/api-users.conf</strong>.
210<em>hostname</em> should be the FQDN of the server.</p>
211<pre><code><strong>/etc/icingaweb2/modules/monitoring/commandtransports.ini</strong>
212[icinga2]
213transport = "api"
214host = <em>hostname</em>
215port = "5665"
216username = "root"
217password = "<em>api password</em>"</code></pre>
218
219<p>Lastly, tell Icinga to protect variables with potentially sensitive values.</p>
220<pre><code><strong>/etc/icingaweb2/modules/monitoring/config.ini</strong>
221[security]
222protected_customvars = "*pw*,*pass*,*community*"</code></pre>
223
224
225<h2>Configure Director</h2>
226<p>This section will cover configuring Director configuration tool.</p>
227<p>Create Director module configuration directory.</p>
228<pre><code>mkdir -p /etc/icingaweb2/modules/director</code></pre>
229
230<p>Write the Director configuration file.</p>
231<pre><code><strong>/etc/icingaweb2/modules/director/config.ini</strong>
232[db]
233resource = "director"</code></pre>
234
235<p>Enable Director module and run the initial migration.</p>
236<pre><code>icingacli module enable director
237icingacli director migration run</code></pre>
238
239<p>Write Director kickstart configuration file.</p>
240<pre><code><strong>/etc/icingaweb2/modules/director/kickstart.ini</strong>
241[config]
242endpoint = "<em>hostname</em>"
243username = "root"
244password = "<em>api password</em>"</code></pre>
245
246<p>Kickstart Director, then render and deploy the configuration.</p>
247<pre><code>icingacli director kickstart run
248icingacli director config render
249icingacli director config deploy</code></pre>
250
251<p>Director is setup at this point so we will shred the unneeded configuration
252file containing sensitive information.</p>
253<pre><code>shred -uz /etc/icingaweb2/modules/director/kickstart.ini</code></pre>
254
255<h2>Login to your Monitoring Instance</h2>
256<p>You are now ready to login to your monitoring instance with the admin
257user created previously. Open a web browser and go to
258http://<em>hostname</em>/icingaweb2. You should see a screen similar to this:</p>
259<a href=../images/icinga-login.png><img src=../images/icinga-login.png alt="Icinagweb2 Login Screen"></a>
260
261<h2>Next Steps</h2>
262<p>In the following articles we will go through setting up Icinga2 agents on servers, and configure your monitoring instance through Icinga Director.</p>
263<p>
264<hr>
265Consider <a href=../donate.html>donating</a> if this article was useful.
266<a class=qr href=../images/bitcoin.png>[BTC]</a>
267</p>
268 </main>
269 <footer>
270 <a href=../kb.html>Knowledge Base</a>
271 <br>
272 <a href=../index.html>www.chudnick.com</a>
273 </footer>
274</body>
275</html>
276