Megaphone Commons

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 jmaconsulting.biz -a 72.249.190.114

        DNS OK: 0.018 seconds response time. jmaconsulting.biz returns 72.249.190.114|time=0.018268s;;;0.000000

        root@rh5:/usr/lib/nagios/plugins# /usr/lib/nagios/plugins/check_dns -H jmaconsulting.biz -a 72.249.190.222

        DNS CRITICAL - expected '72.249.190.222' but got '72.249.190.114'

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

{{collapse(Show example,Hide example)

        object CheckCommand "dns" {

                import "ipv4-or-ipv6"

                command = [ PluginDir + "/check_dns" ]

                arguments = {

                        "-H" = {

                                value = "$dns_lookup$"

                                description = "The name or address you want to query."

                        }

                        "-s" = {

                                value = "$dns_server$"

                                description = "Optional DNS server you want to use for the lookup."

                        }

                        "-a" = {

                                value = "$dns_expected_answers$"

                                description = "Optional ip address or host you expect the DNS server to return. Host must end with a dot (.). This option can be repeated multiple times (Returns OK if any value match). If multiple addresses are returned at once, you have to match the whole string of addresses separated with commas (sorted alphabetically)."

                        }

                        "-a_old" = {

                                key = "-a"

                                value ="$dns_expected_answer$"

                        }

                        "-A" = {

                                set_if = "$dns_authoritative$"

                        }

                        "-w" = {

                                value = "$dns_wtime$"

                                description = "Return warning if elapsed time exceeds value."

                        }

                        "-c" = {

                                value = "$dns_ctime$"

                                description = "Return critical if elapsed time exceeds value."

                        }

                        "-t" = {

                                value = "$dns_timeout$"

                                description = "Seconds before connection times out. Defaults to 10."

                        }

                }

                vars.dns_lookup = "$host.name$"

                vars.dns_expected_answer = "$check_address$"

                vars.dns_timeout = 10

        }

}}

-   A **Service** object.  This defines which hosts have this check

    applied, and can optionally define variables.  Services can be

    anywhere in `/etc/icinga2/conf.d` but should be in

    the `services` subfolder. 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 host.vars.domains) {

          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` can be anywhere

    in `/etc/icinga2/conf.d` but should be in the `hosts` subfolder.