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

## <a id="monitoring-remote-clients"></a> Monitoring Remote Clients

### Agent-less Checks

If the remote service is available using a network protocol and port,
and a [check plugin](#setting-up-check-plugins) 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](#itl)
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](#setting-up-check-plugins) ships
the `check_snmp` plugin binary, but there are plenty of [existing plugins](#integrate-additional-plugins)
for specific use cases already around, for example monitoring Cisco routers.

The following example uses the [SNMP ITL](#itl-snmp) `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](#setting-up-check-plugins).

    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](http://docs.icinga.org/latest/en/nrpe.html) 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++](http://nsclient.org) 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](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).

> ** 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](https://dev.icinga.org/projects/i2?jump=issues).
Meanwhile remote checkers in a [Cluster](#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](http://www.nsca-ng.org) 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](#vagrant) ships a demo integration and further samples.


#### SNMP Traps

SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourceforge.net/) and specific trap handlers
passing the check results to Icinga 2.