{{last_updated_at}} by {{last_updated_by}}

Add New Checks to Icinga2

To configure a new check in Icinga, you need 4 components:

  • A plugin file.  This is a command-line executable (script or binary) that can be run independently of Icinga.  It should return an errorlevel of 0, 1, 2, or 3, corresponding to "OK", "Warning", "Critical", and "Unknown".  These reside in the plugin folder, which is /usr/lib/nagios/plugins.  These should always be testable on the command line.  E.g.:
root@rh5:/usr/lib/nagios/plugins# /usr/lib/nagios/plugins/check_dns -H -a
DNS OK: 0.018 seconds response time. returns|time=0.018268s;;;0.000000
root@rh5:/usr/lib/nagios/plugins# /usr/lib/nagios/plugins/check_dns -H -a
DNS CRITICAL - expected '' but got ''
  • A CheckCommand object.  This maps variables defined in Icinga to the command-line arguments the plugin requires.  CheckCommands can be anywhere in /etc/icinga2/conf.d (localhost only) or /etc/icinga2/zones.d/global-templates (distributed to all satellites).  Please use icinga::/etc/icinga2/zones.d/global-templates/CheckCommands for CheckCommands.   Place Icinga ships with many CheckCommands which are in /usr/share/icinga2/include/command-plugins.conf. CheckCommands can also define default values for arguments.  For instance, the check_dns plugin has a CheckCommand object as follows:

Show example

  • A Service object.  This defines which hosts have this check applied, and can optionally define variables.  Services should be in the /etc/icinga2/zones.d/master/services folder. The civicrm check is a simple one - only one CiviCRM check can be defined per host, and is only added if the three relevant variables are defined.  It looks like this:

    apply Service "civicrm" {
      import "generic-service"
      check_command = "civicrm"
      assign where host.vars.cms && host.vars.crm_site_key && host.vars.crm_api_key

    The DNS check iterates over an array of one or more domains.  It doesn't need an assign where statement as a consequence (if the array is empty, no checks are added) but the syntax for iterating is different:

    apply Service for (domain => config in {
      import "generic-service"
      check_command = "dns"
      vars += config
  • A Host object.  Each server has a Host object - to run a service against 10 hosts, you would define 10 host objects.  Hosts contain all the host-specific variables.  Hosts should be in the /etc/icinga2/zones.d/master/hosts folder.

Updated by Jon Goldberg over 2 years ago · 6 revisions