====== Installing Icinga2 under Debian ======

This installation follows generally the same steps as shown in the [[https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/getting-started|official documents]], however I think the steps here are laid out a bit more clearly.


===== Installing Icinga2 =====

  - Set up the icinga repository in **/etc/apt/sources.list.d/icinga.list**:<code>deb http://packages.icinga.com/debian icinga-XXXX main</code>
    * Substitute "buster", "bullseye" etc as appropriate in place of **XXXX**
    * If you're running Devuan, stick to the equivalent Debian release names (Ascii=Stretch, Beowulf=Buster, Chimaera=Bullseye, Daedalus=Bookworm, etc)
  - Add the Icinga signing key (you may first need to install the package **gnupg** for this to work):<code># wget -O - https://packages.icinga.com/icinga.key | apt-key add -</code>
  - Update the package list and install the packages:<code># aptitude update
# aptitude install icinga2</code>(Expect between 10 and 30 packages to be installed by this.)

===== Installing Icingaweb2 =====

If you also want the **icingaweb2** web interface (typically used on a Master or Satellite machine; not often used on an Agent (formerly called Endpoint) node):
  - Install the database (you need this installed and fully functional before the installation of Icingaweb2 can work):<code># aptitude install mariadb-{server,client}</code>
  - Install the Icingaweb2 packages:<code># aptitude install apache2 icinga{cli,web2} icinga2-ido-mysql icingaweb2-module-{doc,monitoring} php-pdo-mysql</code>(Expect about 50 to 70 more packages to be installed by this.)
    * If prompted to "Enable Icinga 2's ido-mysql feature", say "yes".
    * If prompted to "Configure database for icinga2-ido-mysql with dbconfig-common", say "yes".
  - Add the web user to the monitoring group:<code># usermod -a -G nagios www-data</code>
  - Turn on the **ido-mysql** feature, to enable local storage of events in MySQL, and the **command** feature to allow icingaweb2 to send commands to icinga:<code># icinga2 feature enable ido-mysql command</code>
  - Restart icinga2 to activate the new features:<code># /etc/init.d/icinga2 restart</code>
  - At this point **icingaweb2** should be available at http://your.icinga.mac.hine/icingaweb2, although it won't be possible to log into it yet
  - Create an authentication token so you can run the setup wizard from the web interface:<code># icingacli setup token create</code>
  - You will get a token along the lines of **29b7d0094b35689a** which you can then paste into the setup wizard
    * If you get the error message "ERROR: There is no such module or command: 'setup'" you need to enable the setup module first:<code># icingacli module enable setup</code>



===== Configuring Icingaweb2 =====

  * Note that the Icingaweb2 installation scripts __really__ do not get on well with MariaDB's "root + localhost = passwordless" access facility, so you should create a password for the MariaDB root user at this point:<code># mysql -e "grant all on *.* to 'root'@'localhost' identified by 'Y0ur53cr3tP455w0rd'"</code>
Open http://your.icinga.ser.ver/icingaweb2/setup in a browser, paste in the token you created above, and click "Next"
  - You should see that several modules have been installed:
      * Doc
      * Monitoring
      * Test
      * Translation
      * Newer versions of Icinga will also show:
        * Migrate
  - The "Monitoring" module should already be enabled.  Click on "Next"
  - Anything __red__ on the next page needs to be sorted out before you can complete setup.
    * The most likely thing is that "The PHP config `date.timezone' is not defined."
    * Edit **/etc/php5/apache2/php.ini** and search for the line: **;date.timezone =**
    * Add immediately after this the line **date.timezone = Europe/London**
      * Adjust for your required timezone - zones are specified using the same list as you can find from **dpkg-reconfigure tzdata**
    * Reload Apache:<code># /etc/init.d/apache2 reload</code>
    * Click on **Refresh** at the bottom of the page, and **Default timezone** should now confirm your desired timezone, in Green
  - Anything in __sickly yellow__ on this screen indicates an item which isn't correctly configured, but is optional, so if you don't need the feature, you can ignore it.  There are two for PostgreSQL, for example, which you're very unlikely to want to configure since you've already got MySQL working.
  - Once there are no red items displayed, click on **Next** at the bottom of the page.
  - **Authentication type** should be **Database** unless you have some setup not catered for in these instructions.  Click on **Next**.
  - On the following screen you need to enter details for the **Database Resource** for authentication
    * I think it isn't at all obvious which things you can just make up and set to anything you like, and which have to match something previously entered.  Use the following:
      * **Resource Name** = icingaweb_db
      * **Database Type** = MySQL
      * **Host** = localhost
      * **Port** = <blank>
      * **Database Name** = icingaweb_db
      * **Username** = root
      * **Password** = <the password you set for the root user when installing MySQL, or the system root password if you use MariaDB>
      * **Character Set** = <blank>
      * **Persistent** = <empty, not selected>
      * **Use SSL** = <empty, not selected>
    * Click on **Validate Configuration** to make sure you entered the MySQL root password correctly, and you should get the message "The configuration has been successfully validated."
    * Click on **Next** if everything looks good.
  - Leave the **Authentication Backend** set to "icingaweb2" and click on **Next**
  - In **Administration** you can set up your first Icingaweb2 user.  This user will be an adminstrator, and can later set up further users.
    * Enter the required username and password, then click on **Next**
  - Under **Application Configuration** just leave all settings as they are and click on **Next**:
    * **Show Stacktraces** = <selected>
    * **User Preference Storage Type** = Database
    * **Logging Type** = Syslog
    * **Logging Level** = Error
    * **Application Prefix** = icingaweb2
    * **Facility** = user
  - You now see a summary screen showing:
    * Database Setup
    * Application Configuration
    * Authentication
    * Resource
  - If everything looks okay, click on **Next**

You have now configured the essential functional parts of Icingaweb2.

===== Configuring Icingaweb2, part 2 =====

The next screen shows "Welcome to the configuration of the monitoring module for Icinga Web 2!".  Click on **Next**

  - On the **Monitoring Backend** screen, leave settings as they are and click on **Next**:
    * **Backend Name** = icinga
    * **Backend Type** = IDO
  - On the **Monitoring IDO Resource** screen, enter the following values:
    * **Resource Name** = icinga_ido
    * **Database Type** = MySQL
    * **Host** = localhost
    * **Port** = <blank>
    * **Database Name** = icinga2
    * **Username** = root
    * **Password** = <the password you set for the root user when installing MySQL>
    * **Character Set** = <blank>
    * **Persistent** = <empty, not selected>
    * **Use SSL** = <empty, not selected>
    * Click on **Validate Configuration** to make sure you entered the MySQL root password correctly, and you should get the message "The configuration has been successfully validated.", followed by a Validation Log showing something like:<code>Connection to icinga2 as root on localhost: successful
have_ssl: DISABLED
protocol_version: 10
version: 10.5.12-MariaDB-0+deb11u1
version_compile_os: debian-linux-gnu</code>
    * Click on **Next** if everything looks good.
  - On the **Command Transport** screen, leave the settings as they are and click on **Next**:
    * **Transport Name** = icinga2
    * **Transport Type** = Local Command File
    * **Command File** = /var/run/icinga2/cmd/icinga2.cmd
  - Leave the **Monitoring Security** setting as it is and click on **Next**:
    * **Protected Custom Variables** = *pw*,*pass*,community
  - The next screen shows a summary of:
    * Monitoring Backend
    * Command Transport
    * Monitoring Security
  - If everything looks okay, click on **Finish**

You should now see a screen headed **Congratulations! Icinga Web 2 has been successfully set up.** containing something similar to:<code>Creating new database "icingaweb_db"...
Creating database schema...
Login "root" already exists...
Required privileges were already granted to login "root".
The database has been fully set up!

General configuration has been successfully written to: /etc/icingaweb2/config.ini

Authentication configuration has been successfully written to: /etc/icingaweb2/authentication.ini
Account "Slartibartfast" has been successfully created.
Account "Slartibartfast" has been successfully defined as initial administrator.

User Group Backend configuration has been successfully written to: /etc/icingaweb2/groups.ini
User Group "Administrators" has been successfully created.
Account "Slartibartfast" has been successfully added as member to user group "Administrators".

Resource configuration has been successfully written to: /etc/icingaweb2/resources.ini

Monitoring backend configuration has been successfully written to: /etc/icingaweb2/modules/monitoring/backends.ini
Resource configuration has been successfully updated: /etc/icingaweb2/resources.ini

Command transport configuration has been successfully created: /etc/icingaweb2/modules/monitoring/commandtransports.ini

Monitoring security configuration has been successfully created: /etc/icingaweb2/modules/monitoring/config.ini

Module "monitoring" has been successfully enabled.</code>

Click on the link at the right hand side **Login to Icinga Web 2**, enter the administrator username and password you set up previously, and click on **Login**.

You should now see that the machine is already monitoring itself.  The default setup appears to contain 12 service checks:
  * apt
  * disk
  * desk /
  * http
  * icinga
  * load
  * ping4
  * ping6
  * procs
  * ssh
  * swap
  * users

Since we didn't install the package **monitoring-plugins-basic** yet, these service checks should all be showing **unknown**.

Fixing that is simple:<code># aptitude install monitoring-plugins-basic</code>The service checks will gradually turn green (or yellow or red, if your machine is not in as good a state as you hoped it was).
===== Surprises =====

If you don't seem to be getting notifications sent out when they should be, and you've checked that the machine can send emails, you may find that Icinga2 doesn't have the **notification** feature enabled (why not?  I have no idea; it would seem to be sensible that if you go to the bother of defining notifications and users in your config files, you actually would like some notifications to be sent out, but no - this is not the default until you turn that feature on...).

<code># icinga2 feature list
Disabled features: compatlog debuglog gelf graphite influxdb livestatus notification opentsdb statusdata syslog
Enabled features: api checker command ido-mysql mainlog perfdata
# icinga2 feature enable notification
Enabling feature notification. Make sure to restart Icinga 2 for these changes to take effect.
# /etc/init.d/icinga2 reload
[ ok ] checking Icinga2 configuration.
[ ok ] icinga2 is running.
[ ok ] Reloading icinga2 monitoring daemon: icinga2.</code>

(Note that even though it says "Make sure to restart Icinga 2 for these changes to take effect", a gentler "reload" operation **is** sufficient.)

----
[[.:|Go up]]\\
Return to [[:|main index]].