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.
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)
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 -
Update the package list and install the packages:
# aptitude update
# aptitude install icinga2
(Expect between 10 and 30 packages to be installed by this.)
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):
# aptitude install mariadb-{server,client}
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".
Add the web user to the monitoring group:
# usermod -a -G nagios www-data
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
Restart icinga2 to activate the new features:
# /etc/init.d/icinga2 restart
-
Create an authentication token so you can run the setup wizard from the web interface:
# icingacli setup token create
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
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"
You should see that several modules have been installed:
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
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
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.
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:
If everything looks okay, click on Next
You have now configured the essential functional parts of Icingaweb2.
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:
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.
On the Command Transport screen, leave the settings as they are and click on Next:
Leave the Monitoring Security setting as it is and click on Next:
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:
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).
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.