icinga2/doc/3.15-monitoring-remote-clients.md

Monitoring Remote Clients

Agent-less Checks

If the remote service is available using a network protocol and port, and a check plugin is available, you don't necessarily need a local client installed. Rather choose a plugin and configure all parameters and thresholds. The Icinga 2 Template Library already ships various examples.

Agent-based Checks

If the remote services are not directly accessible through the network, a local agent installation exposing the results to check queries can become handy.

SNMP

The SNMP daemon runs on the remote system and answers SNMP queries by plugin binaries. The Monitoring Plugins package ships the check_snmp plugin binary, but there are plenty of existing plugins for specific use cases already around, for example monitoring Cisco routers.

The following example uses the SNMP ITL CheckCommand and just overrides the oid macro. A service is created for all hosts which have the community macro set.

apply Service "uptime" {
  import "generic-service"

  templates = [ "generic-service" ]
  check_command = "snmp"
  macros.oid = "1.3.6.1.2.1.1.3.0"

  assign where host.macros.community
}

SSH

Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching its return code and output. check_by_ssh is available in the Monitoring Plugins package.

object CheckCommand "check_by_ssh_swap" {
  import "plugin-check-command"

  command = [ PluginDir + "/check_by_ssh",
              "-l", "remoteuser",
              "-H", "$address$",
              "-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\""
            ]
}

apply Service "swap" {
  import "generic-service"
  check_command = "check_by_ssh_swap"
  macros = {
        "warn" = "50%"
        "crit" = "75%"
  }
  
  assign where host.name == "remote-ssh-host"
}

NRPE

NRPE runs as daemon on the remote client including the required plugins and command definitions. Icinga 2 calls the check_nrpe plugin binary in order to query the configured command on the remote client.

Note

The NRPE daemon uses its own configuration format in nrpe.cfg while check_nrpe can be embedded into the Icinga 2 CheckCommand configuration syntax.

Example:

object CheckCommand "check_nrpe" {
  import "plugin-check-command"

  command = [
    PluginDir + "/check_nrpe",
    "-H", "$address$",
    "-c", "$remote_nrpe_command$",
  ]
}

apply Service "users" {
  import "generic-service"

  check_command = "check_nrpe"
  macros.remote_nrpe_command = "check_users"

  assign where host.name == "remote-nrpe-host"
}

nrpe.cfg:

command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10

NSClient++

NSClient++ works on both Windows and Linux platforms and is well known for its magnificent Windows support. There are alternatives like the WMI interface, but using NSClient++ will allow you to run local scripts similar to check plugins fetching the required output and performance counters.

Note

The NSClient++ agent uses its own proprietary configuration format while check_nt can be embedded into the Icinga 2 CheckCommand configuration syntax.

Example:

object CheckCommand "check_nscp" {
  import "plugin-check-command"

  command = [
    PluginDir + "/check_nt",
    "-H", "$address$",
    "-p", "$port$",
    "-v", "$remote_nscp_command$",
    "-l", "$partition$",
    "-w", "$warn$",
    "-c", "$crit$",
    "-s", "$pass$"
  ]

  macros = {
    "port" = "12489"
    "pass" = "supersecret"
  }
}

apply Service "users" {
  import "generic-service"

  check_command = "check_nscp"

  macros += {
    remote_nscp_command = "USEDDISKSPACE"
    partition = "c"
    warn = "70"
    crit = "80"
  }

  assign where host.name == "remote-windows-host"
}

For details on the NSClient++ configuration please refer to the official documentation.

** Note **

The format of the NSClient++ configuration file has changed from 0.3.x to 0.4!

Icinga 2 Agent

A dedicated Icinga 2 agent supporting all platforms and using the native Icinga 2 communication protocol supported with SSL certificates, IPv4/IPv6 support, etc. is on the development roadmap. Meanwhile remote checkers in a Cluster setup could act as immediate replacement, but without any local configuration - or pushing their standalone configuration back to the master node including their check result messages.

Passive Check Results and SNMP Traps

Note

The host and service object configuration must be available on the Icinga 2 server in order to process passive check results.

NSCA-NG

NSCA-ng provides a client-server pair that allows the remote sender to push check results into the Icinga 2 ExternalCommandListener feature.

The Icinga 2 Vagrant Demo VM ships a demo integration and further samples.

SNMP Traps

SNMP Traps can be received and filtered by using SNMPTT and specific trap handlers passing the check results to Icinga 2.