Icinga 2 command definitions can seem daunting at first. This blog post provides a quick introduction to some of the concepts you need to be familiar with when writing your own command definitions.
In their most basic form command definitions need a command line:
object CheckCommand "my_http" {
import "plugin-check-command"
command = [ PluginDir + "/check_http" ]
}
The „plugin-check-command“ template tells Icinga how to execute commands, i.e. by executing an external plugin. There are a few other „*-check-command“ templates but for virtually all of your own check commands you’ll need to use „plugin-check-command“.
The check_http plugin needs at least one more argument to work:
$ /opt/local/libexec/nagios/check_http -I 127.0.0.1 HTTP OK: HTTP/1.1 200 OK - 342 bytes in 0.001 second response time |time=0.001344s;;;0.000000 size=342B;;;0
We can add this argument to our check command like this:
object CheckCommand "my_http" {
import "plugin-check-command"
command = [ PluginDir + "/check_http" ]
arguments = {
"-I" = {
value = "$my_http_address$"
description = "IP address or name."
required = true
}
}
vars.my_http_address = "$address$"
}
The ‚required‘ option tells Icinga to verify that the user specified a value for this argument.
We’re prefixing our custom attributes (my_http_address) with the name of the CheckCommand. This allows us to override specific custom attributes for HTTP checks on a per-host or per-service basis. If all
commands had the same custom attribute names (e.g. ‚timeout‘) this wouldn’t be possible:
object Host "test" {
...
// This affects all services on this host which use the my_http command
vars.my_http_address = "127.0.0.1"
}
In our next step we’re going to add a few optional arguments. The check_http plugin lets us specify the ‚Host‘ header and the URL that should be used. Adding optional arguments is rather simple:
"-H" = {
value = "$my_http_vhost$"
description = "Host name argument for servers using host headers"
}
"-u" = {
value = "$my_http_url$"
description = "URL to GET or POST (default: /)"
}
When Icinga encounters a command argument which uses an unresolvable macro (for example, because the user didn’t set a value for vars.my_http_vhost in their command, service or host) the entire argument is omitted.
Icinga can also add arguments only when certain conditions are met. In the next example I’m adding a new option ‚–sni‘ which is only added when the custom attribute my_http_sni is set to true:
"--sni" = {
description = "Enable SSL/TLS hostname extension support (SNI)"
set_if = "$my_http_sni$"
}
Note that the ‚–sni‘ option does not take an argument. Therefore we don’t need the ‚value‘ attribute for this argument.
When the ‚my_http_sni‘ custom attribute isn’t set at all Icinga defaults to not adding the argument.
There are a few more advanced topics for command arguments which aren’t covered in this blog post:
- Ordering arguments
- Using arrays for custom variables (with repeat_key/skip_key)
- Using functions for set_if/value
- Specifying an alternative ‚key‘
I might write another blog post at a later point in time which deals with those features. In the meantime these things are explained in the documentation.
