From 85fc79b3256d5c60dc6867b2aeb196f8cf9f49b7 Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Wed, 5 Feb 2014 17:17:19 +0100 Subject: [PATCH] Documentation: Add 'Monitoring Remote Clients' section. Fixes #5496 --- doc/3.15-monitoring-remote-clients.md | 194 ++++++++++++++++++++++++++ 1 file changed, 194 insertions(+) create mode 100644 doc/3.15-monitoring-remote-clients.md diff --git a/doc/3.15-monitoring-remote-clients.md b/doc/3.15-monitoring-remote-clients.md new file mode 100644 index 000000000..601c17842 --- /dev/null +++ b/doc/3.15-monitoring-remote-clients.md @@ -0,0 +1,194 @@ +## 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 only defines +additional macros (note the `+=` operator) as command parameters for the `oid` +(`community` is already set): + + object Host "remote-snmp-host" inherits "generic-host" { + ... + services["uptime"] = { + templates = [ "generic-service" ], + check_command = "snmp", + macros += { + "oid" = "1.3.6.1.2.1.1.3.0" + } + }, + macros = { + "address" = "192.168.1.101" + } + } + +#### 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" inherits "plugin-check-command" { + command = [ "$plugindir$/check_by_ssh", + "-l", "remoteuser", + "-H", "$address$", + "-C", "\"/usr/local/icinga/libexec/check_swap -w $warn$ -c $crit$\"" + ] + } + + object Host "remote-ssh-host" inherits "generic-host" { + ... + services["swap"] = { + templates = [ "generic-service" ], + check_command = "check_by_ssh_swap", + macros = { + "warn" = "50%", + "crit" = "75%" + } + }, + macros = { + "address" = "192.168.1.102" + } + } + + +#### 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 proprietary configuration format in nrpe.cfg while `check_nrpe` +> can be embedded into the Icinga 2 `CheckCommand` configuration syntax. + +Example: + + object CheckCommand "check_nrpe" inherits "plugin-check-command" { + command = [ "$plugindir$/check_nrpe", + "-H", "$address$", + "-c", "$remote_nrpe_command$", + ], + } + + object Host "remote-nrpe-host" inherits "generic-host" { + ... + services["users"] = { + templates = [ "generic-service" ], + check_command = "check_nrpe", + macros = { + "remote_nrpe_command" = "check_users" + } + }, + macros = { + "address" = "192.168.1.103" + } + } + +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 magnificant 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" inherits "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" + } + } + + object Host "remote-windows-host" inherits "generic-host" { + ... + services["users"] = { + templates = [ "generic-service" ], + check_command = "check_nscp", + macros += { + "remote_nscp_command" = "USEDDISKSPACE", + "partition" = "c", + "warn" = "70", + "crit" = "80" + } + }, + macros = { + "address" = "192.168.1.104" + } + } + +For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x). + + +#### 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. + + +