Table of Contents

Installing Icinga2 under Debian

This installation follows generally the same steps as shown in the official documents, however I think the steps here are laid out a bit more clearly.

Installing Icinga2

  1. Set up the icinga repository in /etc/apt/sources.list.d/icinga.list:
    deb http://packages.icinga.com/debian icinga-XXXX main
    • 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)
  2. Add the Icinga signing key (you may first need to install the package gnupg for this to work):
    # wget -O - https://packages.icinga.com/icinga.key | apt-key add -
  3. Update the package list and install the packages:
    # aptitude update
# aptitude install icinga2

    (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):

  1. Install the database (you need this installed and fully functional before the installation of Icingaweb2 can work):
    # aptitude install mariadb-{server,client}
  2. Install the Icingaweb2 packages:
    # aptitude install apache2 icinga{cli,web2} icinga2-ido-mysql icingaweb2-module-{doc,monitoring} php-pdo-mysql

    (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".
  3. Add the web user to the monitoring group:
    # usermod -a -G nagios www-data
  4. 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:
    # icinga2 feature enable ido-mysql command
  5. Restart icinga2 to activate the new features:
    # /etc/init.d/icinga2 restart
  6. 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
  7. Create an authentication token so you can run the setup wizard from the web interface:
    # icingacli setup token create
  8. 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:
      # icingacli module enable setup

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:
    # mysql -e "grant all on *.* to 'root'@'localhost' identified by 'Y0ur53cr3tP455w0rd'"

Open http://your.icinga.ser.ver/icingaweb2/setup in a browser, paste in the token you created above, and click "Next"

  1. You should see that several modules have been installed:
    • Doc
    • Monitoring
    • Test
    • Translation
    • Newer versions of Icinga will also show:
      • Migrate
  2. The "Monitoring" module should already be enabled. Click on "Next"
  3. 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:
      # /etc/init.d/apache2 reload
    • Click on Refresh at the bottom of the page, and Default timezone should now confirm your desired timezone, in Green
  4. 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.
  5. Once there are no red items displayed, click on Next at the bottom of the page.
  6. Authentication type should be Database unless you have some setup not catered for in these instructions. Click on Next.
  7. 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.
  8. Leave the Authentication Backend set to "icingaweb2" and click on Next
  9. 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
  10. 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
  11. You now see a summary screen showing:
    • Database Setup
    • Application Configuration
    • Authentication
    • Resource
  12. 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

  1. On the Monitoring Backend screen, leave settings as they are and click on Next:
    • Backend Name = icinga
    • Backend Type = IDO
  2. 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:
      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
    • Click on Next if everything looks good.
  3. 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
  4. Leave the Monitoring Security setting as it is and click on Next:
    • Protected Custom Variables = *pw*,*pass*,community
  5. The next screen shows a summary of:
    • Monitoring Backend
    • Command Transport
    • Monitoring Security
  6. 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: 

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.

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: 

# aptitude install monitoring-plugins-basic

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…). 

# 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.

(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.

Powered by DokuWiki