On my previous post – Install Icinga Core on the Raspberry Pi – I ran through a basic installation of Icinga on the Raspberry Pi with Raspbian. Over the next few posts I’m hoping to lay out some basics about the configuration of Icinga. This will include looking at the default paths, some config files, out of the box plugins and remote monitoring. There’s nothing here you can’t get from the official documentation, but it’ll hopefully be a useful intro.
NOTE: while a lot of this is stated as Raspberry Pi specific it’s really just general Icinga configuration on a Debian based system (e.g. Ubuntu).
Icinga Default Paths
When Icinga is installed from apt, the default configuration location is /etc/icinga. Under here you have:
- the primary .cfg files for cgi, commands, icinga, ido2db, idomod and resource.
- the apache2 conf file for the virtual server. There is a symbolic link to this file from /etc/apache2/conf.d/icinga.conf.
- the modules directory – this only has the idoutils.cfg file
- the objects directory – this contains the out of box .cfg files (more detail on this later)
- the stylesheets directory for the css files.
The default path for the application is /usr/share/icinga. This contains the htdocs directory for the Apache virtual server mentioned above.
Default Icinga Configuration Files
All of the objects in Icinga are defined in .cfg files. When the service loads these are read and interpreted by Icinga. If you open /etc/icinga/icinga.cfg you’ll see the following section near the top:
# Debian uses by default a configuration directory where icinga-common,
# other packages and the local admin can dump or link configuration
# files into.
This is an example of a config path being defined in the main icinga.cfg. Any .cfg files found in this path will be read in by Icinga on start-up.
As mentioned earlier the objects directory has the following files out of the box:
- contacts_icinga.cfg – the default contact (root) and contact groups (admins) for notifications.
- extinfo_icinga.cfg – the default host extension information. This definition is deprecated and the directives can be rolled into the host definition.
- generic-host_icinga.cfg – the default host definition template.
- generic-service_icinga.cfg – the default service definition template.
- hostgroups_icinga.cfg – the default host groups definition.
- ido2db_check_proc.cfg – the definitions of services and commands to monitor the ido2db processes.
- localhost_icinga.cfg – the default definitions for the localhost host and services. Everything you see in this file makes up the localhost objects in Icinga (plus the ido2db service defined above)
- services_icinga.cfg – the default service definitions (HTTP and SSH).
- timeperiods_icinga.cfg – the default time period definitions.
A .cfg file is typically made up of definitions and a definition is made up of directives (properties) – some of which are mandatory – which can be inherited from other object definitions. For example a host definition could be created with a few unique directives and then a host template can be inherited to put values against all other directives.
All object definitions can be found in the official documentation here. It provides a comprehensive description of the objects and all the directives.
Custom Icinga Configuration Files
When you create your own configuration files, these can be placed in the objects folder mentioned above or a completely separate folder. If you use a separate folder (e.g. userobjects), then a line should be added to the icinga.cfg file like:
Ensure the permissions on this folder match the objects folder – root:root 755 on the folder and root:root 744 on the files inside.
Once added, restart the Icinga service:
foo@raspberrypi ~ $ sudo service icinga restart
Your own custom cfg files can hold a single type of definition or multiple definition types. Organise them the best way it suites the support model of the devices being monitored. For example in a smaller environment you might have a file per host definition (named the same as the host) and one for all your service definitions. I tend to create custom files for most things to make the configuration easier to migrate and for understanding and readability.
In part two I’ll cover the plugins installed with Icinga, some configuration files and adding a simple host.