granicus.if.org Git - icinga2/blob - doc/7-configuring-icinga-2.md

   1 # <a id="configuring-icinga2"></a> Configuring Icinga 2
   2
   3 ## <a id="global-constants"></a> Global Constants
   4
   5 Icinga 2 provides a number of special global constants. Some of them can be overridden using the `--define` command line parameter:
   6
   7 Variable            |Description
   8 --------------------|-------------------
   9 PrefixDir           |**Read-only.** Contains the installation prefix that was specified with cmake -DCMAKE_INSTALL_PREFIX. Defaults to "/usr/local".
  10 SysconfDir          |**Read-only.** Contains the path of the sysconf directory. Defaults to PrefixDir + "/etc".
  11 ZonesDir            |**Read-only.** Contains the path of the zones.d directory. Defaults to SysconfDir + "/zones.d".
  12 LocalStateDir       |**Read-only.** Contains the path of the local state directory. Defaults to PrefixDir + "/var".
  13 RunDir              |**Read-only.** Contains the path of the run directory. Defaults to LocalStateDir + "/run".
  14 PkgDataDir          |**Read-only.** Contains the path of the package data directory. Defaults to PrefixDir + "/share/icinga2".
  15 StatePath           |**Read-write.** Contains the path of the Icinga 2 state file. Defaults to LocalStateDir + "/lib/icinga2/icinga2.state".
  16 ObjectsPath         |**Read-write.** Contains the path of the Icinga 2 objects file. Defaults to LocalStateDir + "/cache/icinga2/icinga2.debug".
  17 PidPath             |**Read-write.** Contains the path of the Icinga 2 PID file. Defaults to RunDir + "/icinga2/icinga2.pid".
  18 Vars                |**Read-write.** Contains a dictionary with global custom attributes. Not set by default.
  19 NodeName            |**Read-write.** Contains the cluster node name. Set to the local hostname by default.
  20 ApplicationType     |**Read-write.** Contains the name of the Application type. Defaults to "icinga/IcingaApplication".
  21 EnableNotifications |**Read-write.** Whether notifications are globally enabled. Defaults to true.
  22 EnableEventHandlers |**Read-write.** Whether event handlers are globally enabled. Defaults to true.
  23 EnableFlapping      |**Read-write.** Whether flap detection is globally enabled. Defaults to true.
  24 EnableHostChecks    |**Read-write.** Whether active host checks are globally enabled. Defaults to true.
  25 EnableServiceChecks |**Read-write.** Whether active service checks are globally enabled. Defaults to true.
  26 EnablePerfdata      |**Read-write.** Whether performance data processing is globally enabled. Defaults to true.
  27 UseVfork            |**Read-write.** Whether to use vfork(). Only available on *NIX. Defaults to true.
  28
  29 ## <a id="reserved-keywords"></a> Reserved Keywords
  30
  31 These keywords are reserved by the configuration parser and must not be
  32 used as constants or custom attributes.
  33
  34     object
  35     template
  36     include
  37     include_recursive
  38     library
  39     null
  40     partial
  41     true
  42     false
  43     const
  44     apply
  45     to
  46     where
  47     import
  48     assign
  49     ignore
  50     zone
  51     in
  52
  53 You can escape reserved keywords using the `@` character. The following example
  54 will try to set `vars.include` which references a reserved keyword and generates
  55 the following error:
  56
  57
  58     [2014-09-15 17:24:00 +0200] critical/config: Location:
  59     /etc/icinga2/conf.d/hosts/localhost.conf(13):   vars.sla = "24x7"
  60     /etc/icinga2/conf.d/hosts/localhost.conf(14):
  61     /etc/icinga2/conf.d/hosts/localhost.conf(15):   vars.include = "some cmdb export field"
  62                                                          ^^^^^^^
  63     /etc/icinga2/conf.d/hosts/localhost.conf(16): }
  64     /etc/icinga2/conf.d/hosts/localhost.conf(17):
  65
  66     Config error: in /etc/icinga2/conf.d/hosts/localhost.conf: 15:8-15:14: syntax error, unexpected include (T_INCLUDE), expecting T_IDENTIFIER
  67     [2014-09-15 17:24:00 +0200] critical/config: 1 errors, 0 warnings.
  68
  69 You can escape the `include` key with an additional `@` character becoming `vars.@include`:
  70
  71     object Host "localhost" {
  72       import "generic-host"
  73
  74       address = "127.0.0.1"
  75       address6 = "::1"
  76
  77       vars.os = "Linux"
  78       vars.sla = "24x7"
  79
  80       vars.@include = "some cmdb export field"
  81     }
  82
  83
  84 ## <a id="configuration-syntax"></a> Configuration Syntax
  85
  86 ### <a id="object-definition"></a> Object Definition
  87
  88 Icinga 2 features an object-based configuration format. You can define new
  89 objects using the `object` keyword:
  90
  91     object Host "host1.example.org" {
  92       display_name = "host1"
  93
  94       address = "192.168.0.1"
  95       address6 = "::1"
  96     }
  97
  98 In general you need to write each statement on a new line. Expressions started
  99 with `{`, `(` and `[` extend until the matching closing character and can be broken
 100 up into multiple lines.
 101
 102 Alternatively you can write multiple statements on a single line by separating
 103 them with a semicolon:
 104
 105     object Host "host1.example.org" {
 106       display_name = "host1"
 107
 108       address = "192.168.0.1"; address6 = "::1"
 109     }
 110
 111 Each object is uniquely identified by its type (`Host`) and name
 112 (`host1.example.org`). Some types have composite names, e.g. the
 113 `Service` type which uses the `host_name` attribute and the name
 114 you specified to generate its object name.
 115
 116 Exclamation marks (!) are not permitted in object names.
 117
 118 Objects can contain a comma-separated list of property
 119 declarations. Instead of commas semicolons may also be used.
 120 The following data types are available for property values:
 121
 122 ### Expressions
 123
 124 The following expressions can be used on the right-hand side of dictionary
 125 values.
 126
 127 #### <a id="numeric-literals"></a> Numeric Literals
 128
 129 A floating-point number.
 130
 131 Example:
 132
 133     -27.3
 134
 135 #### <a id="duration-literals"></a> Duration Literals
 136
 137 Similar to floating-point numbers except for the fact that they support
 138 suffixes to help with specifying time durations.
 139
 140 Example:
 141
 142     2.5m
 143
 144 Supported suffixes include ms (milliseconds), s (seconds), m (minutes),
 145 h (hours) and d (days).
 146
 147 Duration literals are converted to seconds by the config parser and
 148 are treated like numeric literals.
 149
 150 #### <a id="string-literals"></a> String Literals
 151
 152 A string.
 153
 154 Example:
 155
 156     "Hello World!"
 157
 158 Certain characters need to be escaped. The following escape sequences
 159 are supported:
 160
 161 Character                 | Escape sequence
 162 --------------------------|------------------------------------
 163 "                         | \\"
 164 \\                        | \\\\
 165 &lt;TAB&gt;               | \\t
 166 &lt;CARRIAGE-RETURN&gt;   | \\r
 167 &lt;LINE-FEED&gt;         | \\n
 168 &lt;BEL&gt;               | \\b
 169 &lt;FORM-FEED&gt;         | \\f
 170
 171 In addition to these pre-defined escape sequences you can specify
 172 arbitrary ASCII characters using the backslash character (\\) followed
 173 by an ASCII character in octal encoding.
 174
 175 #### <a id="multiline-string-literals"></a> Multi-line String Literals
 176
 177 Strings spanning multiple lines can be specified by enclosing them in
 178 {{{ and }}}.
 179
 180 Example:
 181
 182     {{{This
 183     is
 184     a multi-line
 185     string.}}}
 186
 187 Unlike in ordinary strings special characters do not have to be escaped
 188 in multi-line string literals.
 189
 190 #### <a id="boolean-literals"></a> Boolean Literals
 191
 192 The keywords `true` and `false` are equivalent to 1 and 0 respectively.
 193
 194 #### <a id="null-value"></a> Null Value
 195
 196 The `null` keyword can be used to specify an empty value.
 197
 198 #### <a id="dictionary"></a> Dictionary
 199
 200 An unordered list of key-value pairs. Keys must be unique and are
 201 compared in a case-insensitive manner.
 202
 203 Individual key-value pairs must either be comma-separated or on separate lines.
 204 The comma after the last key-value pair is optional.
 205
 206 Example:
 207
 208     {
 209       address = "192.168.0.1"
 210       port = 443
 211     }
 212
 213 Identifiers may not contain certain characters (e.g. space) or start
 214 with certain characters (e.g. digits). If you want to use a dictionary
 215 key that is not a valid identifier you can enclose the key in double
 216 quotes.
 217
 218 Setting a dictionary key to null causes the key and its value to be
 219 removed from the dictionary.
 220
 221 #### <a id="array"></a> Array
 222
 223 An ordered list of values.
 224
 225 Individual array elements must be comma-separated.
 226 The comma after the last element is optional.
 227
 228 Example:
 229
 230     [ "hello", 42 ]
 231
 232 An array may simultaneously contain values of different types, such as
 233 strings and numbers.
 234
 235 #### <a id="expression-operators"></a> Operators
 236
 237 The following operators are supported in expressions:
 238
 239 Operator | Examples (Result)                             | Description
 240 ---------|-----------------------------------------------|--------------------------------
 241 !        | !"Hello" (false), !false (true)               | Logical negation of the operand
 242 ~        | ~true (false)                                 | Bitwise negation of the operand
 243 +        | 1 + 3 (4), "hello " + "world" ("hello world") | Adds two numbers; concatenates strings
 244 -        | 3 - 1 (2)                                     | Subtracts two numbers
 245 *        | 5m * 10 (3000)                                | Multiplies two numbers
 246 /        | 5m / 5 (60)                                   | Divides two numbers
 247 &        | 7 & 3 (3)                                     | Binary AND
 248 &#124;   | 2 &#124; 3 (3)                                | Binary OR
 249 &&       | true && false (false)                         | Logical AND
 250 &#124;&#124; | true &#124;&#124; false (true)            | Logical OR
 251 <        | 3 < 5 (true)                                  | Less than
 252 >        | 3 > 5 (false)                                 | Greater than
 253 <=       | 3 <= 3 (true)                                 | Less than or equal
 254 >=       | 3 >= 3 (true)                                 | Greater than or equal
 255 <<       | 4 << 8 (1024)                                 | Left shift
 256 >>       | 1024 >> 4 (64)                                | Right shift
 257 ==       | "hello" == "hello" (true), 3 == 5 (false)     | Equal to
 258 !=       | "hello" != "world" (true), 3 != 3 (false)     | Not equal to
 259 in       | "foo" in [ "foo", "bar" ] (true)              | Element contained in array
 260 !in      | "foo" !in [ "bar", "baz" ] (true)             | Element not contained in array
 261 ()       | (3 + 3) * 5                                   | Groups sub-expressions
 262
 263 Constants may be used in expressions:
 264
 265     const MyCheckInterval = 10m
 266
 267     ...
 268
 269     {
 270       check_interval = MyCheckInterval / 2.5
 271     }
 272
 273 #### <a id="function-calls"></a> Function Calls
 274
 275 Functions can be called using the `()` operator:
 276
 277     const MyGroups = [ "test1", "test" ]
 278
 279     {
 280       check_interval = len(MyGroups) * 1m
 281     }
 282
 283 > **Tip**
 284 >
 285 > Use these functions in [apply](#using-apply) rule expressions.
 286
 287     assign where match("192.168.*", host.address)
 288
 289
 290 Function                        | Description
 291 --------------------------------|-----------------------
 292 regex(pattern, text)            | Returns true if the regex pattern matches the text, false otherwise.
 293 match(pattern, text)            | Returns true if the wildcard pattern matches the text, false otherwise.
 294 len(value)                      | Returns the length of the value, i.e. the number of elements for an array or dictionary, or the length of the string in bytes.
 295 union(array, array, ...)        | Returns an array containing all unique elements from the specified arrays.
 296 intersection(array, array, ...) | Returns an array containing all unique elements which are common to all specified arrays.
 297 keys(dict)                      | Returns an array containing the dictionary's keys.
 298 string(value)                   | Converts the value to a string.
 299 number(value)                   | Converts the value to a number.
 300 bool(value)                     | Converts the value to a bool.
 301 random()                        | Returns a random value between 0 and RAND_MAX (as defined in stdlib.h).
 302 log(value)                      | Writes a message to the log. Non-string values are converted to a JSON string.
 303 log(severity, facility, value)  | Writes a message to the log. `severity` can be one of `LogDebug`, `LogNotice`, `LogInformation`, `LogWarning`, and `LogCritical`. Non-string values are converted to a JSON string.
 304 exit(integer)                   | Terminates the application.
 305
 306 ### <a id="dictionary-operators"></a> Dictionary Operators
 307
 308 In addition to the `=` operator shown above a number of other operators
 309 to manipulate dictionary elements are supported. Here's a list of all
 310 available operators:
 311
 312 #### <a id="operator-assignment"></a> Operator =
 313
 314 Sets a dictionary element to the specified value.
 315
 316 Example:
 317
 318     {
 319       a = 5
 320       a = 7
 321     }
 322
 323 In this example `a` has the value `7` after both instructions are executed.
 324
 325 #### <a id="operator-additive-assignment"></a> Operator +=
 326
 327 The += operator is a shortcut. The following expression:
 328
 329     {
 330       a = [ "hello" ]
 331       a += [ "world" ]
 332     }
 333
 334 is equivalent to:
 335
 336     {
 337       a = [ "hello" ]
 338       a = a + [ "world" ]
 339     }
 340
 341 #### <a id="operator-substractive-assignment"></a> Operator -=
 342
 343 The -= operator is a shortcut. The following expression:
 344
 345     {
 346       a = 10
 347       a -= 5
 348     }
 349
 350 is equivalent to:
 351
 352     {
 353       a = 10
 354       a = a - 5
 355     }
 356
 357 #### <a id="operator-multiply-assignment"></a> Operator \*=
 358
 359 The *= operator is a shortcut. The following expression:
 360
 361     {
 362       a = 60
 363       a *= 5
 364     }
 365
 366 is equivalent to:
 367
 368     {
 369       a = 60
 370       a = a * 5
 371     }
 372
 373 #### <a id="operator-dividing-assignment"></a> Operator /=
 374
 375 The /= operator is a shortcut. The following expression:
 376
 377     {
 378       a = 300
 379       a /= 5
 380     }
 381
 382 is equivalent to:
 383
 384     {
 385       a = 300
 386       a = a / 5
 387     }
 388
 389 ### <a id="indexer"></a> Indexer
 390
 391 The indexer syntax provides a convenient way to set dictionary elements.
 392
 393 Example:
 394
 395     {
 396       hello.key = "world"
 397     }
 398
 399 Example (alternative syntax):
 400
 401     {
 402       hello["key"] = "world"
 403     }
 404
 405 This is equivalent to writing:
 406
 407     {
 408       hello += {
 409         key = "world"
 410       }
 411     }
 412
 413 ### <a id="template-imports"></a> Template Imports
 414
 415 Objects can import attributes from other objects.
 416
 417 Example:
 418
 419     template Host "default-host" {
 420       vars.colour = "red"
 421     }
 422
 423     template Host "test-host" {
 424       import "default-host"
 425
 426       vars.colour = "blue"
 427     }
 428
 429     object Host "localhost" {
 430       import "test-host"
 431
 432       address = "127.0.0.1"
 433       address6 = "::1"
 434     }
 435
 436 The `default-host` and `test-host` objects are marked as templates
 437 using the `template` keyword. Unlike ordinary objects templates are not
 438 instantiated at run-time. Parent objects do not necessarily have to be
 439 templates, however in general they are.
 440
 441 The `vars` dictionary for the `localhost` object contains all three
 442 custom attributes and the custom attribute `colour` has the value `"blue"`.
 443
 444 Parent objects are resolved in the order they're specified using the
 445 `import` keyword.
 446
 447 ### <a id="constants"></a> Constants
 448
 449 Global constants can be set using the `const` keyword:
 450
 451     const VarName = "some value"
 452
 453 Once defined a constant can be accessed from any file. Constants cannot be changed
 454 once they are set.
 455
 456 There is a defined set of [global constants](#global-constants) which allow
 457 you to specify application settings.
 458
 459 ### <a id="apply"></a> Apply
 460
 461 The `apply` keyword can be used to create new objects which are associated with
 462 another group of objects.
 463
 464     apply Service "ping" to Host {
 465       import "generic-service"
 466
 467       check_command = "ping4"
 468
 469       assign where host.name == "localhost"
 470     }
 471
 472 In this example the `assign where` condition is a boolean expression which is
 473 evaluated for all objects of type `Host` and a new service with name "ping"
 474 is created for each matching host. [Expression operators](#expression-operators)
 475 may be used in `assign where` conditions.
 476
 477 The `to` keyword and the target type may be omitted if there is only one target
 478 type, e.g. for the `Service` type.
 479
 480 Depending on the object type used in the `apply` expression additional local
 481 variables may be available for use in the `where` condition:
 482
 483 Source Type       | Target Type | Variables
 484 ------------------|-------------|--------------
 485 Service           | Host        | host
 486 Dependency        | Host        | host
 487 Dependency        | Service     | host, service
 488 Notification      | Host        | host
 489 Notification      | Service     | host, service
 490 ScheduledDowntime | Host        | host
 491 ScheduledDowntime | Service     | host, service
 492
 493 Any valid config attribute can be accessed using the `host` and `service`
 494 variables. For example, `host.address` would return the value of the host's
 495 "address" attribute - or null if that attribute isn't set.
 496
 497 ### <a id="group-assign"></a> Group Assign
 498
 499 Group objects can be assigned to specific member objects using the `assign where`
 500 and `ignore where` conditions.
 501
 502     object HostGroup "linux-servers" {
 503       display_name = "Linux Servers"
 504
 505       assign where host.vars.os == "Linux"
 506     }
 507
 508 In this example the `assign where` condition is a boolean expression which is evaluated
 509 for all objects of the type `Host`. Each matching host is added as member to the host group
 510 with the name "linux-servers". Membership exclusion can be controlled using the `ignore where`
 511 condition. [Expression operators](#expression-operators) may be used in `assign where` and
 512 `ignore where` conditions.
 513
 514 Source Type       | Variables
 515 ------------------|--------------
 516 HostGroup         | host
 517 ServiceGroup      | host, service
 518 UserGroup         | user
 519
 520
 521 ### <a id="boolean-values"></a> Boolean Values
 522
 523 The `assign where` and `ignore where` statements, the `!`, `&&` and `||`
 524 operators as well as the `bool()` function convert their arguments to a
 525 boolean value based on the following rules:
 526
 527 Description          | Example Value     | Boolean Value
 528 ---------------------|-------------------|--------------
 529 Empty value          | null              | false
 530 Zero                 | 0                 | false
 531 Non-zero integer     | -23945            | true
 532 Empty string         | ""                | false
 533 Non-empty string     | "Hello"           | true
 534 Empty array          | []                | false
 535 Non-empty array      | [ "Hello" ]       | true
 536 Empty dictionary     | {}                | false
 537 Non-empty dictionary | { key = "value" } | true
 538
 539 For a list of supported expression operators for `assign where` and `ignore where`
 540 statements, see [expression operators](#expression-operators).
 541
 542 ### <a id="comments"></a> Comments
 543
 544 The Icinga 2 configuration format supports C/C++-style and shell-style comments.
 545
 546 Example:
 547
 548     /*
 549      This is a comment.
 550      */
 551     object Host "localhost" {
 552       check_interval = 30 // this is also a comment.
 553       retry_interval = 15 # yet another comment
 554     }
 555
 556 ### <a id="includes"></a> Includes
 557
 558 Other configuration files can be included using the `include` directive.
 559 Paths must be relative to the configuration file that contains the
 560 `include` directive.
 561
 562 Example:
 563
 564     include "some/other/file.conf"
 565     include "conf.d/*.conf"
 566
 567 Wildcard includes are not recursive.
 568
 569 Icinga also supports include search paths similar to how they work in a
 570 C/C++ compiler:
 571
 572     include <itl>
 573
 574 Note the use of angle brackets instead of double quotes. This causes the
 575 config compiler to search the include search paths for the specified
 576 file. By default $PREFIX/share/icinga2 is included in the list of search
 577 paths. Additional include search paths can be added using
 578 [command-line options](#cmdline).
 579
 580 Wildcards are not permitted when using angle brackets.
 581
 582 ### <a id="recursive-includes"></a> Recursive Includes
 583
 584 The `include_recursive` directive can be used to recursively include all
 585 files in a directory which match a certain pattern.
 586
 587 Example:
 588
 589     include_recursive "conf.d", "*.conf"
 590     include_recursive "templates"
 591
 592 The first parameter specifies the directory from which files should be
 593 recursively included.
 594
 595 The file names need to match the pattern given in the second parameter.
 596 When no pattern is specified the default pattern "*.conf" is used.
 597
 598 ### <a id="library"></a> Library directive
 599
 600 The `library` directive can be used to manually load additional
 601 libraries. Libraries can be used to provide additional object types and
 602 functions.
 603
 604 Example:
 605
 606     library "snmphelper"
 607
 608
 609
 610 ## <a id="object-types"></a> Object Types
 611
 612 ### <a id="objecttype-host"></a> Host
 613
 614 A host.
 615
 616 Example:
 617
 618     object Host "localhost" {
 619       display_name = "The best host there is"
 620       address = "127.0.0.1"
 621       address6 = "::1"
 622
 623       groups = [ "all-hosts" ]
 624
 625       check_command = "hostalive"
 626     }
 627
 628 Attributes:
 629
 630   Name            |Description
 631   ----------------|----------------
 632   display_name    |**Optional.** A short description of the host.
 633   address         |**Optional.** The host's address. Available as command runtime macro `$address$` if set.
 634   address6        |**Optional.** The host's address. Available as command runtime macro `$address6$` if set.
 635   groups          |**Optional.** A list of host groups this host belongs to.
 636   vars            |**Optional.** A dictionary containing custom attributes that are specific to this host.
 637   check\_command  |**Required.** The name of the check command.
 638   max\_check\_attempts|**Optional.** The number of times a host is re-checked before changing into a hard state. Defaults to 3.
 639   check\_period   |**Optional.** The name of a time period which determines when this host should be checked. Not set by default.
 640   check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the host is in a `HARD` state. Defaults to 5 minutes.
 641   retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the host is in a `SOFT` state. Defaults to 1 minute.
 642   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
 643   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
 644   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
 645   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
 646   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to true.
 647   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
 648   event\_command  |**Optional.** The name of an event command that should be executed every time the host's state changes or the host is in a `SOFT` state.
 649   flapping\_threshold|**Optional.** The flapping threshold in percent when a host is considered to be flapping.
 650   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
 651   zone            |**Optional.** The zone this object is a member of.
 652   notes           |**Optional.** Notes for the host.
 653   notes_url       |**Optional.** Url for notes for the host (for example, in notification commands).
 654   action_url      |**Optional.** Url for actions for the host (for example, an external graphing tool).
 655   icon_image      |**Optional.** Icon image for the host. Used by external interfaces only.
 656   icon_image_alt  |**Optional.** Icon image description for the host. Used by external interface only.
 657
 658 > **Best Practice**
 659 >
 660 > The `address` and `address6` attributes are required for running commands using
 661 > the `$address$` and `$address6$` runtime macros.
 662
 663
 664 ### <a id="objecttype-hostgroup"></a> HostGroup
 665
 666 A group of hosts.
 667
 668 > **Best Practice**
 669 >
 670 > Assign host group members using the [group assign](#group-assign) rules.
 671
 672 Example:
 673
 674     object HostGroup "my-hosts" {
 675       display_name = "My hosts"
 676     }
 677
 678 Attributes:
 679
 680   Name            |Description
 681   ----------------|----------------
 682   display_name    |**Optional.** A short description of the host group.
 683   groups          |**Optional.** An array of nested group names.
 684
 685 ### <a id="objecttype-service"></a> Service
 686
 687 Service objects describe network services and how they should be checked
 688 by Icinga 2.
 689
 690 > **Best Practice**
 691 >
 692 > Rather than creating a `Service` object for a specific host it is usually easier
 693 > to just create a `Service` template and use the `apply` keyword to assign the
 694 > service to a number of hosts.
 695 > Check the [apply](#using-apply) chapter for details.
 696
 697 Example:
 698
 699     object Service "uptime" {
 700       host_name = "localhost"
 701
 702       display_name = "localhost Uptime"
 703
 704       check_command = "check_snmp"
 705
 706       vars.community = "public"
 707       vars.oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
 708
 709       check_interval = 60s
 710       retry_interval = 15s
 711
 712       groups = [ "all-services", "snmp" ]
 713     }
 714
 715 Attributes:
 716
 717   Name            |Description
 718   ----------------|----------------
 719   display_name    |**Optional.** A short description of the service.
 720   host_name       |**Required.** The host this service belongs to. There must be a `Host` object with that name.
 721   name            |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
 722   groups          |**Optional.** The service groups this service belongs to.
 723   vars            |**Optional.** A dictionary containing custom attributes that are specific to this service.
 724   check\_command  |**Required.** The name of the check command.
 725   max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3.
 726   check\_period   |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
 727   check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a `HARD` state. Defaults to 5 minutes.
 728   retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a `SOFT` state. Defaults to 1 minute.
 729   enable\_notifications|**Optional.** Whether notifications are enabled. Defaults to true.
 730   enable\_active\_checks|**Optional.** Whether active checks are enabled. Defaults to true.
 731   enable\_passive\_checks|**Optional.** Whether passive checks are enabled. Defaults to true.
 732   enable\_event\_handler|**Optional.** Enables event handlers for this host. Defaults to true.
 733   enable\_flapping|**Optional.** Whether flap detection is enabled. Defaults to true.
 734   enable\_perfdata|**Optional.** Whether performance data processing is enabled. Defaults to true.
 735   event\_command  |**Optional.** The name of an event command that should be executed every time the service's state changes or the service is in a `SOFT` state.
 736   flapping\_threshold|**Optional.** The flapping threshold in percent when a service is considered to be flapping.
 737   volatile        |**Optional.** The volatile setting enables always `HARD` state types if `NOT-OK` state changes occur.
 738   zone            |**Optional.** The zone this object is a member of.
 739   notes           |**Optional.** Notes for the service.
 740   notes_url       |**Optional.** Url for notes for the service (for example, in notification commands).
 741   action_url      |**Optional.** Url for actions for the service (for example, an external graphing tool).
 742   icon_image      |**Optional.** Icon image for the service. Used by external interfaces only.
 743   icon_image_alt  |**Optional.** Icon image description for the service. Used by external interface only.
 744
 745
 746 Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
 747 you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
 748
 749 ### <a id="objecttype-servicegroup"></a> ServiceGroup
 750
 751 A group of services.
 752
 753 > **Best Practice**
 754 >
 755 > Assign service group members using the [group assign](#group-assign) rules.
 756
 757 Example:
 758
 759     object ServiceGroup "snmp" {
 760       display_name = "SNMP services"
 761     }
 762
 763 Attributes:
 764
 765   Name            |Description
 766   ----------------|----------------
 767   display_name    |**Optional.** A short description of the service group.
 768   groups          |**Optional.** An array of nested group names.
 769
 770
 771 ### <a id="objecttype-user"></a> User
 772
 773 A user.
 774
 775 Example:
 776
 777     object User "icingaadmin" {
 778       display_name = "Icinga 2 Admin"
 779       groups = [ "icingaadmins" ]
 780       email = "icinga@localhost"
 781       pager = "icingaadmin@localhost.localdomain"
 782
 783       period = "24x7"
 784
 785       states = [ OK, Warning, Critical, Unknown ]
 786       types = [ Problem, Recovery ]
 787
 788       vars.additional_notes = "This is the Icinga 2 Admin account."
 789     }
 790
 791 Available notification state filters:
 792
 793     OK
 794     Warning
 795     Critical
 796     Unknown
 797     Up
 798     Down
 799
 800 Available notification type filters:
 801
 802     DowntimeStart
 803     DowntimeEnd
 804     DowntimeRemoved
 805     Custom
 806     Acknowledgement
 807     Problem
 808     Recovery
 809     FlappingStart
 810     FlappingEnd
 811
 812 Attributes:
 813
 814   Name            |Description
 815   ----------------|----------------
 816   display_name    |**Optional.** A short description of the user.
 817   email           |**Optional.** An email string for this user. Useful for notification commands.
 818   pager           |**Optional.** A pager string for this user. Useful for notification commands.
 819   vars            |**Optional.** A dictionary containing custom attributes that are specific to this user.
 820   groups          |**Optional.** An array of group names.
 821   enable_notifications|**Optional.** Whether notifications are enabled for this user.
 822   period          |**Optional.** The name of a time period which determines when a notification for this user should be triggered. Not set by default.
 823   types           |**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
 824   states          |**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
 825   zone            |**Optional.** The zone this object is a member of.
 826
 827
 828 ### <a id="objecttype-usergroup"></a> UserGroup
 829
 830 A user group.
 831
 832 > **Best Practice**
 833 >
 834 > Assign user group members using the [group assign](#group-assign) rules.
 835
 836 Example:
 837
 838     object UserGroup "icingaadmins" {
 839         display_name = "Icinga 2 Admin Group"
 840     }
 841
 842 Attributes:
 843
 844   Name            |Description
 845   ----------------|----------------
 846   display_name    |**Optional.** A short description of the user group.
 847   groups          |**Optional.** An array of nested group names.
 848   zone            |**Optional.** The zone this object is a member of.
 849
 850
 851
 852 ### <a id="objecttype-checkcommand"></a> CheckCommand
 853
 854 A check command definition. Additional default command custom attributes can be
 855 defined here.
 856
 857 Example:
 858
 859     object CheckCommand "check_http" {
 860       import "plugin-check-command"
 861
 862       command = [ PluginDir + "/check_http" ]
 863
 864       arguments = {
 865         "-H" = "$http_vhost$"
 866         "-I" = "$http_address$"
 867         "-u" = "$http_uri$"
 868         "-p" = "$http_port$"
 869         "-S" = {
 870           set_if = "$http_ssl$"
 871         }
 872         "--sni" = {
 873           set_if = "$http_sni$"
 874         }
 875         "-a" = {
 876           value = "$http_auth_pair$"
 877           description = "Username:password on sites with basic authentication"
 878         }
 879         "--no-body" = {
 880           set_if = "$http_ignore_body$"
 881         }
 882         "-r" = "$http_expect_body_regex$"
 883         "-w" = "$http_warn_time$"
 884         "-c" = "$http_critical_time$"
 885         "-e" = "$http_expect$"
 886       }
 887
 888       vars.http_address = "$address$"
 889       vars.http_ssl = false
 890       vars.http_sni = false
 891     }
 892
 893
 894 Attributes:
 895
 896   Name            |Description
 897   ----------------|----------------
 898   methods         |**Required.** The "execute" script method takes care of executing the check. In virtually all cases you should import the "plugin-check-command" template to take care of this setting.
 899   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command. When using the "arguments" attribute this must be an array.
 900   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 901   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 902   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
 903   zone            |**Optional.** The zone this object is a member of.
 904   arguments       |**Optional.** A dictionary of command arguments.
 905
 906
 907 Command arguments can be defined as key-value-pairs in the `arguments`
 908 dictionary. If the argument requires additional configuration for example
 909 a `description` attribute or an optional condition, the value can be defined
 910 as dictionary specifying additional options.
 911
 912 Service:
 913
 914     vars.x_val = "My command argument value."
 915     vars.have_x = "true"
 916
 917 CheckCommand:
 918
 919     arguments = {
 920       "-X" = {
 921         value = "$x_val$"
 922         description = "My plugin requires this argument for doing X."
 923         required = false    /* optional, no error if not set */
 924         skip_key = false    /* always use "-X <value>" */
 925         set_if = "$have_x$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 926         order = -1          /* first position */
 927       }
 928       "-Y" = {
 929         value = "$y_val$"
 930         description = "My plugin requires this argument for doing Y."
 931         required = false    /* optional, no error if not set */
 932         skip_key = true     /* don't prefix "-Y" only use "<value>" */
 933         set_if = "$have_y$" /* only set if variable defined and resolves to a numeric value. String values are not supported */
 934         order = 0           /* second position */
 935       }
 936     }
 937
 938   Option      | Description
 939   ------------|--------------
 940   value       | Optional argument value.
 941   description | Optional argument description.
 942   required    | Required argument. Execution error if not set. Defaults to false (optional).
 943   skip_key    | Use the value as argument and skip the key.
 944   set_if      | Argument is added if the macro resolves to a defined numeric value. String values are not supported.
 945   order       | Set if multiple arguments require a defined argument order.
 946
 947 Argument order:
 948     `..., -3, -2, -1, <un-ordered keys>, 1, 2, 3, ...`
 949
 950
 951 ### <a id="objecttype-notificationcommand"></a> NotificationCommand
 952
 953 A notification command definition.
 954
 955 Example:
 956
 957     object NotificationCommand "mail-service-notification" {
 958       import "plugin-notification-command"
 959
 960       command = [
 961         SysconfDir + "/icinga2/scripts/mail-notification.sh"
 962       ]
 963
 964       env = {
 965         NOTIFICATIONTYPE = "$notification.type$"
 966         SERVICEDESC = "$service.name$"
 967         HOSTALIAS = "$host.display_name$"
 968         HOSTADDRESS = "$address$"
 969         SERVICESTATE = "$service.state$"
 970         LONGDATETIME = "$icinga.long_date_time$"
 971         SERVICEOUTPUT = "$service.output$"
 972         NOTIFICATIONAUTHORNAME = "$notification.author$"
 973         NOTIFICATIONCOMMENT = "$notification.comment$"
 974         HOSTDISPLAYNAME = "$host.display_name$"
 975         SERVICEDISPLAYNAME = "$service.display_name$"
 976         USEREMAIL = "$user.email$"
 977       }
 978     }
 979
 980 Attributes:
 981
 982   Name            |Description
 983   ----------------|----------------
 984   methods         |**Required.** The "execute" script method takes care of executing the notification. In virtually all cases you should import the "plugin-notification-command" template to take care of this setting.
 985   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
 986   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
 987   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
 988   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
 989   zone            |**Optional.** The zone this object is a member of.
 990   arguments       |**Optional.** A dictionary of command arguments.
 991
 992 Command arguments can be used the same way as for `CheckCommand` objects.
 993
 994
 995 ### <a id="objecttype-eventcommand"></a> EventCommand
 996
 997 An event command definition.
 998
 999 Example:
1000
1001     object EventCommand "restart-httpd-event" {
1002       import "plugin-event-command"
1003
1004       command = "/opt/bin/restart-httpd.sh"
1005     }
1006
1007
1008 Attributes:
1009
1010   Name            |Description
1011   ----------------|----------------
1012   methods         |**Required.** The "execute" script method takes care of executing the event handler. In virtually all cases you should import the "plugin-event-command" template to take care of this setting.
1013   command         |**Required.** The command. This can either be an array of individual command arguments. Alternatively a string can be specified in which case the shell interpreter (usually /bin/sh) takes care of parsing the command.
1014   env             |**Optional.** A dictionary of macros which should be exported as environment variables prior to executing the command.
1015   vars            |**Optional.** A dictionary containing custom attributes that are specific to this command.
1016   timeout         |**Optional.** The command timeout in seconds. Defaults to 60 seconds.
1017   arguments       |**Optional.** A dictionary of command arguments.
1018
1019 Command arguments can be used the same way as for `CheckCommand` objects.
1020
1021
1022 ### <a id="objecttype-notification"></a> Notification
1023
1024 Notification objects are used to specify how users should be notified in case
1025 of host and service state changes and other events.
1026
1027 > **Best Practice**
1028 >
1029 > Rather than creating a `Notification` object for a specific host or service it is
1030 > usually easier to just create a `Notification` template and use the `apply` keyword
1031 > to assign the notification to a number of hosts or services. Use the `to` keyword
1032 > to set the specific target type for `Host` or `Service`.
1033 > Check the [notifications](#notifications) chapter for detailed examples.
1034
1035 Example:
1036
1037     object Notification "localhost-ping-notification" {
1038       host_name = "localhost"
1039       service_name = "ping4"
1040
1041       command = "mail-notification"
1042
1043       users = [ "user1", "user2" ]
1044
1045       types = [ Problem, Recovery ]
1046     }
1047
1048 Attributes:
1049
1050   Name                      | Description
1051   --------------------------|----------------
1052   host_name                 | **Required.** The name of the host this notification belongs to.
1053   service_name              | **Optional.** The short name of the service this notification belongs to. If omitted this notification object is treated as host notification.
1054   vars                      | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
1055   users                     | **Optional.** A list of user names who should be notified.
1056   user_groups               | **Optional.** A list of user group names who should be notified.
1057   times                     | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
1058   command                   | **Required.** The name of the notification command which should be executed when the notification is triggered.
1059   interval                  | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](#disable-renotification) are disabled.
1060   period                    | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
1061   zone                      |**Optional.** The zone this object is a member of.
1062   types                     | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched.
1063   states                    | **Optional.** A list of state filters when this notification should be triggered. By default everything is matched.
1064
1065 Available notification state filters:
1066
1067     OK
1068     Warning
1069     Critical
1070     Unknown
1071     Up
1072     Down
1073
1074 Available notification type filters:
1075
1076     DowntimeStart
1077     DowntimeEnd
1078     DowntimeRemoved
1079     Custom
1080     Acknowledgement
1081     Problem
1082     Recovery
1083     FlappingStart
1084     FlappingEnd
1085
1086
1087
1088 ### <a id="objecttype-timeperiod"></a> TimePeriod
1089
1090 Time periods can be used to specify when hosts/services should be checked or to limit
1091 when notifications should be sent out.
1092
1093 Example:
1094
1095     object TimePeriod "24x7" {
1096       import "legacy-timeperiod"
1097
1098       display_name = "Icinga 2 24x7 TimePeriod"
1099
1100       ranges = {
1101         monday = "00:00-24:00"
1102         tuesday = "00:00-24:00"
1103         wednesday = "00:00-24:00"
1104         thursday = "00:00-24:00"
1105         friday = "00:00-24:00"
1106         saturday = "00:00-24:00"
1107         sunday = "00:00-24:00"
1108       }
1109     }
1110
1111 Attributes:
1112
1113   Name            |Description
1114   ----------------|----------------
1115   display_name    |**Optional.** A short description of the time period.
1116   methods         |**Required.** The "update" script method takes care of updating the internal representation of the time period. In virtually all cases you should import the "legacy-timeperiod" template to take care of this setting.
1117   zone            |**Optional.** The zone this object is a member of.
1118   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1119
1120 The `/etc/icinga2/conf.d/timeperiods.conf` file is usually used to define
1121 timeperiods including this one.
1122
1123
1124 ### <a id="objecttype-scheduleddowntime"></a> ScheduledDowntime
1125
1126 ScheduledDowntime objects can be used to set up recurring downtimes for hosts/services.
1127
1128 > **Best Practice**
1129 >
1130 > Rather than creating a `ScheduledDowntime` object for a specific host or service it is usually easier
1131 > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the
1132 > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target
1133 > type for `Host` or `Service`.
1134 > Check the [recurring downtimes](#recurring-downtimes) example for details.
1135
1136 Example:
1137
1138     object ScheduledDowntime "some-downtime" {
1139       host_name = "localhost"
1140       service_name = "ping4"
1141
1142       author = "icingaadmin"
1143       comment = "Some comment"
1144
1145       fixed = false
1146       duration = 30m
1147
1148       ranges = {
1149         "sunday" = "02:00-03:00"
1150       }
1151     }
1152
1153 Attributes:
1154
1155   Name            |Description
1156   ----------------|----------------
1157   host_name       |**Required.** The name of the host this scheduled downtime belongs to.
1158   service_name    |**Optional.** The short name of the service this scheduled downtime belongs to. If omitted this downtime object is treated as host downtime.
1159   author          |**Required.** The author of the downtime.
1160   comment         |**Required.** A comment for the downtime.
1161   fixed           |**Optional.** Whether this is a fixed downtime. Defaults to true.
1162   duration        |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
1163   zone            |**Optional.** The zone this object is a member of.
1164   ranges          |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
1165
1166 ScheduledDowntime objects have composite names, i.e. their names are based
1167 on the `host_name` and `service_name` attributes and the
1168 name you specified. This means you can define more than one object
1169 with the same (short) name as long as one of the `host_name` and
1170 `service_name` attributes has a different value.
1171
1172
1173 ### <a id="objecttype-dependency"></a> Dependency
1174
1175 Dependency objects are used to specify dependencies between hosts and services. Dependencies
1176 can be defined as Host-to-Host, Service-to-Service, Service-to-Host, or Host-to-Service
1177 relations.
1178
1179 > **Best Practice**
1180 >
1181 > Rather than creating a `Dependency` object for a specific host or service it is usually easier
1182 > to just create a `Dependency` template and use the `apply` keyword to assign the
1183 > dependency to a number of hosts or services. Use the `to` keyword to set the specific target
1184 > type for `Host` or `Service`.
1185 > Check the [dependencies](#dependencies) chapter for detailed examples.
1186
1187 Service-to-Service Example:
1188
1189     object Dependency "webserver-internet" {
1190       parent_host_name = "internet"
1191       parent_service_name = "ping4"
1192
1193       child_host_name = "webserver"
1194       child_service_name = "ping4"
1195
1196       states = [ OK, Warning ]
1197
1198       disable_checks = true
1199     }
1200
1201 Host-to-Host Example:
1202
1203     object Dependency "webserver-internet" {
1204       parent_host_name = "internet"
1205
1206       child_host_name = "webserver"
1207
1208       states = [ Up ]
1209
1210       disable_checks = true
1211     }
1212
1213 Attributes:
1214
1215   Name                  |Description
1216   ----------------------|----------------
1217   parent_host_name      |**Required.** The parent host.
1218   parent_service_name   |**Optional.** The parent service. If omitted this dependency object is treated as host dependency.
1219   child_host_name       |**Required.** The child host.
1220   child_service_name    |**Optional.** The child service. If omitted this dependency object is treated as host dependency.
1221   disable_checks        |**Optional.** Whether to disable checks when this dependency fails. Defaults to false.
1222   disable_notifications |**Optional.** Whether to disable notifications when this dependency fails. Defaults to true.
1223   period                |**Optional.** Time period during which this dependency is enabled.
1224   zone                  |**Optional.** The zone this object is a member of.
1225   states                |**Optional.** A list of state filters when this dependency should be OK. Defaults to [ OK, Warning ] for services and [ Up ] for hosts.
1226
1227 Available state filters:
1228
1229     OK
1230     Warning
1231     Critical
1232     Unknown
1233     Up
1234     Down
1235
1236 When using [apply rules](#using-apply) for dependencies, you can leave out certain attributes which will be
1237 automatically determined by Icinga 2.
1238
1239 Service-to-Host Dependency Example:
1240
1241     apply Dependency "internet" to Service {
1242       parent_host_name = "dsl-router"
1243       disable_checks = true
1244
1245       assign where host.name != "dsl-router"
1246     }
1247
1248 This example sets all service objects matching the assign condition into a dependency relation to
1249 the parent host object `dsl-router` as implicit child services.
1250
1251 Service-to-Service-on-the-same-Host Dependency Example:
1252
1253     apply Dependency "disable-nrpe-checks" to Service {
1254       parent_service_name = "nrpe-health"
1255
1256       assign where service.check_command == "nrpe"
1257       ignore where service.name == "nrpe-health"
1258     }
1259
1260 This example omits the `parent_host_name` attribute and Icinga 2 automatically sets its value to the name of the
1261 host object matched by the apply rule condition. All services where apply matches are made implicit child services
1262 in this dependency relation.
1263
1264
1265 Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
1266 name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
1267 `child_service_name` attributes has a different value.
1268
1269
1270 ### <a id="objecttype-perfdatawriter"></a> PerfdataWriter
1271
1272 Writes check result performance data to a defined path using macro
1273 pattern consisting of custom attributes and runtime macros.
1274
1275 Example:
1276
1277     library "perfdata"
1278
1279     object PerfdataWriter "pnp" {
1280       host_perfdata_path = "/var/spool/icinga2/perfdata/host-perfdata"
1281
1282       service_perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata"
1283
1284       host_format_template = "DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$"
1285       service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
1286
1287       rotation_interval = 15s
1288     }
1289
1290 Attributes:
1291
1292   Name                    |Description
1293   ------------------------|----------------
1294   host_perfdata\_path     |**Optional.** Path to the host performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/host-perfdata".
1295   service_perfdata\_path  |**Optional.** Path to the service performance data file. Defaults to LocalStateDir + "/spool/icinga2/perfdata/service-perfdata".
1296   host_temp\_path         |**Optional.** Path to the temporary host file. Defaults to LocalStateDir + "/spool/icinga2/tmp/host-perfdata".
1297   service_temp\_path      |**Optional.** Path to the temporary service file. Defaults to LocalStateDir + "/spool/icinga2/tmp/service-perfdata".
1298   host_format\_template   |**Optional.** Host Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1299   service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
1300   rotation\_interval      |**Optional.** Rotation interval for the files specified in `{host,service}_perfdata_path`. Defaults to 30 seconds.
1301
1302 When rotating the performance data file the current UNIX timestamp is appended to the path specified
1303 in `host_perfdata_path` and `service_perfdata_path` to generate a unique filename.
1304
1305
1306 ### <a id="objecttype-graphitewriter"></a> GraphiteWriter
1307
1308 Writes check result metrics and performance data to a defined
1309 Graphite Carbon host.
1310
1311 Example:
1312
1313     library "perfdata"
1314
1315     object GraphiteWriter "graphite" {
1316       host = "127.0.0.1"
1317       port = 2003
1318     }
1319
1320 Attributes:
1321
1322   Name                  |Description
1323   ----------------------|----------------------
1324   host                  |**Optional.** Graphite Carbon host address. Defaults to '127.0.0.1'.
1325   port                  |**Optional.** Graphite Carbon port. Defaults to 2003.
1326   host_name_template    |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$".
1327   service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$".
1328
1329 Metric prefix names can be modified using [runtime macros](#runtime-macros).
1330
1331 Example with your custom [global constant](#global-constants) `GraphiteEnv`:
1332
1333     const GraphiteEnv = "icinga.env1"
1334
1335     host_name_template = GraphiteEnv + ".$host.name$"
1336     service_name_template = GraphiteEnv + ".$host.name$.$service.name$"
1337
1338 ### <a id="objecttype-gelfwriter"></a> GelfWriter
1339
1340 Writes event log entries to a defined GELF receiver host (Graylog2, Logstash).
1341
1342 Example:
1343
1344     library "perfdata"
1345
1346     object GelfWriter "gelf" {
1347       host = "127.0.0.1"
1348       port = 12201
1349     }
1350
1351 Attributes:
1352
1353   Name                  |Description
1354   ----------------------|----------------------
1355   host                  |**Optional.** GELF receiver host address. Defaults to '127.0.0.1'.
1356   port                  |**Optional.** GELF receiver port. Defaults to `12201`.
1357   source                |**Optional.** Source name for this instance. Defaults to `icinga2`.
1358
1359
1360 ### <a id="objecttype-idomysqlconnection"></a> IdoMySqlConnection
1361
1362 IDO database adapter for MySQL.
1363
1364 Example:
1365
1366     library "db_ido_mysql"
1367
1368     object IdoMysqlConnection "mysql-ido" {
1369       host = "127.0.0.1"
1370       port = 3306
1371       user = "icinga"
1372       password = "icinga"
1373       database = "icinga"
1374       table_prefix = "icinga_"
1375       instance_name = "icinga2"
1376       instance_description = "icinga2 instance"
1377
1378       cleanup = {
1379         downtimehistory_age = 48h
1380         logentries_age = 31d
1381       }
1382
1383       categories = DbCatConfig | DbCatState
1384     }
1385
1386 Attributes:
1387
1388   Name            |Description
1389   ----------------|----------------
1390   host            |**Optional.** MySQL database host address. Defaults to "localhost".
1391   port            |**Optional.** MySQL database port. Defaults to 3306.
1392   user            |**Optional.** MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
1393   password        |**Optional.** MySQL database user's password. Defaults to "icinga".
1394   database        |**Optional.** MySQL database name. Defaults to "icinga".
1395   table\_prefix   |**Optional.** MySQL database table prefix. Defaults to "icinga\_".
1396   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
1397   instance\_description|**Optional.** Description for the Icinga 2 instance.
1398   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability-db-ido). Defaults to "true".
1399   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
1400   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
1401   categories      |**Optional.** The types of information that should be written to the database.
1402
1403 Cleanup Items:
1404
1405   Name            | Description
1406   ----------------|----------------
1407   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
1408   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
1409   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
1410   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
1411   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
1412   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
1413   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
1414   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
1415   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
1416   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
1417   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
1418   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
1419   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
1420   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
1421   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
1422
1423 Data Categories:
1424
1425   Name                 | Description            | Required by
1426   ---------------------|------------------------|--------------------
1427   DbCatConfig          | Configuration data     | Icinga Web/Reporting
1428   DbCatState           | Current state data     | Icinga Web/Reporting
1429   DbCatAcknowledgement | Acknowledgements       | Icinga Web/Reporting
1430   DbCatComment         | Comments               | Icinga Web/Reporting
1431   DbCatDowntime        | Downtimes              | Icinga Web/Reporting
1432   DbCatEventHandler    | Event handler data     | Icinga Web/Reporting
1433   DbCatExternalCommand | External commands      | Icinga Web/Reporting
1434   DbCatFlapping        | Flap detection data    | Icinga Web/Reporting
1435   DbCatCheck           | Check results          | --
1436   DbCatLog             | Log messages           | Icinga Web/Reporting
1437   DbCatNotification    | Notifications          | Icinga Web/Reporting
1438   DbCatProgramStatus   | Program status data    | Icinga Web/Reporting
1439   DbCatRetention       | Retention data         | Icinga Web/Reporting
1440   DbCatStateHistory    | Historical state data  | Icinga Web/Reporting
1441
1442 Multiple categories can be combined using the `|` operator. In addition to
1443 the category flags listed above the `DbCatEverything` flag may be used as
1444 a shortcut for listing all flags.
1445
1446 External interfaces like Icinga Web require everything except `DbCatCheck`
1447 which is the default value if `categories` is not set.
1448
1449 ### <a id="objecttype-idomysqlconnection"></a> IdoPgSqlConnection
1450
1451 IDO database adapter for PostgreSQL.
1452
1453 Example:
1454
1455     library "db_ido_pgsql"
1456
1457     object IdoMysqlConnection "pgsql-ido" {
1458       host = "127.0.0.1"
1459       port = 5432
1460       user = "icinga"
1461       password = "icinga"
1462       database = "icinga"
1463       table_prefix = "icinga_"
1464       instance_name = "icinga2"
1465       instance_description = "icinga2 instance"
1466
1467       cleanup = {
1468         downtimehistory_age = 48h
1469         logentries_age = 31d
1470       }
1471
1472       categories = DbCatConfig | DbCatState
1473     }
1474
1475 Attributes:
1476
1477   Name            |Description
1478   ----------------|----------------
1479   host            |**Optional.** PostgreSQL database host address. Defaults to "localhost".
1480   port            |**Optional.** PostgreSQL database port. Defaults to "5432".
1481   user            |**Optional.** PostgreSQL database user with read/write permission to the icinga database. Defaults to "icinga".
1482   password        |**Optional.** PostgreSQL database user's password. Defaults to "icinga".
1483   database        |**Optional.** PostgreSQL database name. Defaults to "icinga".
1484   table\_prefix   |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_".
1485   instance\_name  |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default".
1486   instance\_description|**Optional.** Description for the Icinga 2 instance.
1487   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability-db-ido). Defaults to "true".
1488   failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s".
1489   cleanup         |**Optional.** Dictionary with items for historical table cleanup.
1490   categories      |**Optional.** The types of information that should be written to the database.
1491
1492 Cleanup Items:
1493
1494   Name            | Description
1495   ----------------|----------------
1496   acknowledgements_age |**Optional.** Max age for acknowledgements table rows (entry_time). Defaults to 0 (never).
1497   commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never).
1498   contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never).
1499   contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never).
1500   downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never).
1501   eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never).
1502   externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never).
1503   flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never).
1504   hostchecks_age |**Optional.** Max age for hostalives table rows (start_time). Defaults to 0 (never).
1505   logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never).
1506   notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never).
1507   processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never).
1508   statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never).
1509   servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never).
1510   systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never).
1511
1512 Data Categories:
1513
1514   Name                 | Description            | Required by
1515   ---------------------|------------------------|--------------------
1516   DbCatConfig          | Configuration data     | Icinga Web/Reporting
1517   DbCatState           | Current state data     | Icinga Web/Reporting
1518   DbCatAcknowledgement | Acknowledgements       | Icinga Web/Reporting
1519   DbCatComment         | Comments               | Icinga Web/Reporting
1520   DbCatDowntime        | Downtimes              | Icinga Web/Reporting
1521   DbCatEventHandler    | Event handler data     | Icinga Web/Reporting
1522   DbCatExternalCommand | External commands      | Icinga Web/Reporting
1523   DbCatFlapping        | Flap detection data    | Icinga Web/Reporting
1524   DbCatCheck           | Check results          | --
1525   DbCatLog             | Log messages           | Icinga Web/Reporting
1526   DbCatNotification    | Notifications          | Icinga Web/Reporting
1527   DbCatProgramStatus   | Program status data    | Icinga Web/Reporting
1528   DbCatRetention       | Retention data         | Icinga Web/Reporting
1529   DbCatStateHistory    | Historical state data  | Icinga Web/Reporting
1530
1531 Multiple categories can be combined using the `|` operator. In addition to
1532 the category flags listed above the `DbCatEverything` flag may be used as
1533 a shortcut for listing all flags.
1534
1535 External interfaces like Icinga Web require everything except `DbCatCheck`
1536 which is the default value if `categories` is not set.
1537
1538 ### <a id="objecttype-livestatuslistener"></a> LiveStatusListener
1539
1540 Livestatus API interface available as TCP or UNIX socket. Historical table queries
1541 require the `CompatLogger` feature enabled pointing to the log files using the
1542 `compat_log_path` configuration attribute.
1543
1544 Example:
1545
1546     library "livestatus"
1547
1548     object LivestatusListener "livestatus-tcp" {
1549       socket_type = "tcp"
1550       bind_host = "127.0.0.1"
1551       bind_port = "6558"
1552     }
1553
1554     object LivestatusListener "livestatus-unix" {
1555       socket_type = "unix"
1556       socket_path = "/var/run/icinga2/cmd/livestatus"
1557     }
1558
1559 Attributes:
1560
1561   Name            |Description
1562   ----------------|----------------
1563   socket\_type      |**Optional.** Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
1564   bind\_host        |**Optional.** Only valid when socket\_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
1565   bind\_port        |**Optional.** Only valid when `socket_type` is "tcp". Port to listen on for connections. Defaults to 6558.
1566   socket\_path      |**Optional.** Only valid when `socket_type` is "unix". Specifies the path to the UNIX socket file. Defaults to RunDir + "/icinga2/cmd/livestatus".
1567   compat\_log\_path |**Optional.** Required for historical table queries. Requires `CompatLogger` feature enabled. Defaults to LocalStateDir + "/log/icinga2/compat"
1568
1569 > **Note**
1570 >
1571 > UNIX sockets are not supported on Windows.
1572
1573 ### <a id="objecttype-statusdatawriter"></a> StatusDataWriter
1574
1575 Periodically writes status data files which are used by the Classic UI and other third-party tools.
1576
1577 Example:
1578
1579     library "compat"
1580
1581     object StatusDataWriter "status" {
1582         status_path = "/var/cache/icinga2/status.dat"
1583         objects_path = "/var/cache/icinga2/objects.path"
1584         update_interval = 30s
1585     }
1586
1587 Attributes:
1588
1589   Name            |Description
1590   ----------------|----------------
1591   status\_path    |**Optional.** Path to the status.dat file. Defaults to LocalStateDir + "/cache/icinga2/status.dat".
1592   objects\_path   |**Optional.** Path to the objects.cache file. Defaults to LocalStateDir + "/cache/icinga2/objects.cache".
1593   update\_interval|**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1594
1595
1596 ### <a id="objecttype-externalcommandlistener"></a> ExternalCommandListener
1597
1598 Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
1599
1600 Example:
1601
1602     library "compat"
1603
1604     object ExternalCommandListener "external" {
1605         command_path = "/var/run/icinga2/cmd/icinga2.cmd"
1606     }
1607
1608 Attributes:
1609
1610   Name            |Description
1611   ----------------|----------------
1612   command\_path   |**Optional.** Path to the command pipe. Defaults to RunDir + "/icinga2/cmd/icinga2.cmd".
1613
1614 ### <a id="objecttype-compatlogger"></a> CompatLogger
1615
1616 Writes log files in a format that's compatible with Icinga 1.x.
1617
1618 Example:
1619
1620     library "compat"
1621
1622     object CompatLogger "my-log" {
1623       log_dir = "/var/log/icinga2/compat"
1624       rotation_method = "HOURLY"
1625     }
1626
1627 Attributes:
1628
1629   Name            |Description
1630   ----------------|----------------
1631   log\_dir        |**Optional.** Path to the compat log directory. Defaults to LocalStateDir + "/log/icinga2/compat".
1632   rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
1633
1634
1635 ### <a id="objecttype-checkresultreader"></a> CheckResultReader
1636
1637 Reads Icinga 1.x check results from a directory. This functionality is provided
1638 to help existing Icinga 1.x users and might be useful for certain cluster
1639 scenarios.
1640
1641 Example:
1642
1643     library "compat"
1644
1645     object CheckResultReader "reader" {
1646       spool_dir = "/data/check-results"
1647     }
1648
1649 Attributes:
1650
1651   Name            |Description
1652   ----------------|----------------
1653   spool\_dir      |**Optional.** The directory which contains the check result files. Defaults to LocalStateDir + "/lib/icinga2/spool/checkresults/".
1654
1655
1656 ### <a id="objecttype-checkcomponent"></a> CheckerComponent
1657
1658 The checker component is responsible for scheduling active checks. There are no configurable options.
1659
1660 Example:
1661
1662     library "checker"
1663
1664     object CheckerComponent "checker" { }
1665
1666 Can be enabled/disabled using
1667
1668     # icinga2 feature enable checker
1669
1670
1671 ### <a id="objecttype-notificationcomponent"></a> NotificationComponent
1672
1673 The notification component is responsible for sending notifications. There are no configurable options.
1674
1675 Example:
1676
1677     library "notification"
1678
1679     object NotificationComponent "notification" { }
1680
1681 Attributes:
1682
1683   Name            |Description
1684   ----------------|----------------
1685   enable_ha       |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability). Defaults to "true".
1686
1687
1688 Can be enabled/disabled using
1689
1690     # icinga2 feature enable notification
1691
1692
1693 ### <a id="objecttype-filelogger"></a> FileLogger
1694
1695 Specifies Icinga 2 logging to a file.
1696
1697 Example:
1698
1699     object FileLogger "debug-file" {
1700       severity = "debug"
1701       path = "/var/log/icinga2/debug.log"
1702     }
1703
1704 Attributes:
1705
1706   Name            |Description
1707   ----------------|----------------
1708   path            |**Required.** The log path.
1709   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "warning" or "critical". Defaults to "information".
1710
1711
1712 ### <a id="objecttype-sysloglogger"></a> SyslogLogger
1713
1714 Specifies Icinga 2 logging to syslog.
1715
1716 Example:
1717
1718     object SyslogLogger "crit-syslog" {
1719       severity = "critical"
1720     }
1721
1722 Attributes:
1723
1724   Name            |Description
1725   ----------------|----------------
1726   severity        |**Optional.** The minimum severity for this log. Can be "debug", "notice", "information", "notice", "warning" or "critical". Defaults to "warning".
1727
1728
1729
1730 ### <a id="objecttype-icingastatuswriter"></a> IcingaStatusWriter
1731
1732 The IcingaStatusWriter feature periodically dumps the current status
1733 and performance data from Icinga 2 and all registered features into
1734 a defined JSON file.
1735
1736 Example:
1737
1738     object IcingaStatusWriter "status" {
1739       status_path = LocalStateDir + "/cache/icinga2/status.json"
1740       update_interval = 15s
1741     }
1742
1743 Attributes:
1744
1745   Name                      |Description
1746   --------------------------|--------------------------
1747   status\_path              |**Optional.** Path to cluster status file. Defaults to LocalStateDir + "/cache/icinga2/status.json"
1748   update\_interval          |**Optional.** The interval in which the status files are updated. Defaults to 15 seconds.
1749
1750
1751 ### <a id="objecttype-apilistener"></a> ApiListener
1752
1753 ApiListener objects are used for distributed monitoring setups
1754 specifying the certificate files used for ssl authorization.
1755
1756 The `NodeName` constant must be defined in [constants.conf](#constants-conf).
1757
1758 Example:
1759
1760     object ApiListener "api" {
1761       cert_path = SysconfDir + "/icinga2/pki/" + NodeName + ".crt"
1762       key_path = SysconfDir + "/icinga2/pki/" + NodeName + ".key"
1763       ca_path = SysconfDir + "/icinga2/pki/ca.crt"
1764     }
1765
1766
1767 Attributes:
1768
1769   Name                      |Description
1770   --------------------------|--------------------------
1771   cert\_path                |**Required.** Path to the public key.
1772   key\_path                 |**Required.** Path to the private key.
1773   ca\_path                  |**Required.** Path to the CA certificate file.
1774   crl\_path                 |**Optional.** Path to the CRL file.
1775   bind\_host                |**Optional.** The IP address the api listener should be bound to. Defaults to `0.0.0.0`.
1776   bind\_port                |**Optional.** The port the api listener should be bound to. Defaults to `5665`.
1777   accept\_config            |**Optional.** Accept zone configuration. Defaults to `false`.
1778
1779
1780 ### <a id="objecttype-endpoint"></a> Endpoint
1781
1782 Endpoint objects are used to specify connection information for remote
1783 Icinga 2 instances.
1784
1785 Example:
1786
1787     object Endpoint "icinga2b" {
1788       host = "192.168.5.46"
1789       port = 5665
1790     }
1791
1792 Attributes:
1793
1794   Name            |Description
1795   ----------------|----------------
1796   host            |**Required.** The hostname/IP address of the remote Icinga 2 instance.
1797   port            |**Optional.** The service name/port of the remote Icinga 2 instance. Defaults to `5665`.
1798   log_duration    |**Optional.** Duration for keeping replay logs on connection loss. Defaults to `1d`.
1799
1800
1801 ### <a id="objecttype-zone"></a> Zone
1802
1803 Zone objects are used to specify which Icinga 2 instances are located in a zone.
1804 All zone endpoints elect one active master instance among them (required for High-Availability setups).
1805
1806 Example:
1807
1808     object Zone "config-ha-master" {
1809       endpoints = [ "icinga2a", "icinga2b" ]
1810
1811     }
1812
1813     object Zone "check-satellite" {
1814       endpoints = [ "icinga2c" ]
1815       parent = "config-ha-master"
1816     }
1817
1818 Attributes:
1819
1820   Name            |Description
1821   ----------------|----------------
1822   endpoints       |**Optional.** Dictionary with endpoints located in this zone.
1823   parent          |**Optional.** Parent zone.
1824
1825
1826
1827 ## <a id="icinga-template-library"></a> Icinga Template Library
1828
1829 ### <a id="itl-overview"></a> Overview
1830
1831 The Icinga Template Library (ITL) implements standard templates and object
1832 definitions for commonly used services.
1833
1834 You can include the ITL by using the `include` directive in your configuration
1835 file:
1836
1837     include <itl>
1838
1839 ### <a id="itl-generic-templates"></a> Generic Templates
1840
1841 These templates are imported by the provided example configuration.
1842
1843 #### <a id="itl-plugin-check-command"></a> plugin-check-command
1844
1845 Command template for check plugins executed by Icinga 2.
1846
1847 The `plugin-check-command` command does not support any vars.
1848
1849 #### <a id="itl-plugin-notification-command"></a> plugin-notification-command
1850
1851 Command template for notification scripts executed by Icinga 2.
1852
1853 The `plugin-notification-command` command does not support any vars.
1854
1855 #### <a id="itl-plugin-event-command"></a> plugin-event-command
1856
1857 Command template for event handler scripts executed by Icinga 2.
1858
1859 The `plugin-event-command` command does not support any vars.
1860
1861 ### <a id="itl-check-commands"></a> Check Commands
1862
1863 These check commands are embedded into Icinga 2 and do not require any external
1864 plugin scripts.
1865
1866 #### <a id="itl-icinga"></a> icinga
1867
1868 Check command for the built-in `icinga` check. This check returns performance
1869 data for the current Icinga instance.
1870
1871 The `icinga` check command does not support any vars.
1872
1873 #### <a id="itl-icinga-cluster"></a> cluster
1874
1875 Check command for the built-in `cluster` check. This check returns performance
1876 data for the current Icinga instance and connected endpoints.
1877
1878 The `cluster` check command does not support any vars.
1879
1880 #### <a id="itl-icinga-cluster-zone"></a> cluster-zone
1881
1882 Check command for the built-in `cluster-zone` check.
1883
1884 Cluster Attributes:
1885
1886 Name         | Description
1887 -------------|---------------
1888 cluster_zone | **Optional.** The zone name. Defaults to "$host.name$".
1889
1890 ## <a id="plugin-check-commands"></a> Plugin Check Commands
1891
1892 ### <a id="plugin-check-command-overview"></a> Overview
1893
1894 The Plugin Check Commands provides example configuration for plugin check commands
1895 provided by the Monitoring Plugins project.
1896
1897 You can include the plugin check command definitions by using the `include`
1898 directive in your configuration file:
1899
1900     include <plugins>
1901
1902 The plugin check commands assume that there's a global constant named `PluginDir`
1903 which contains the path of the plugins from the Monitoring Plugins project.
1904
1905
1906 #### <a id="plugin-check-command-ping4"></a> ping4
1907
1908 Check command object for the `check_ping` plugin.
1909
1910 Custom Attributes:
1911
1912 Name            | Description
1913 ----------------|--------------
1914 ping_address    | **Optional.** The host's IPv4 address. Defaults to "$address$".
1915 ping_wrta       | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
1916 ping_wpl        | **Optional.** The packet loss warning threshold in %. Defaults to 5.
1917 ping_crta       | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
1918 ping_cpl        | **Optional.** The packet loss critical threshold in %. Defaults to 15.
1919 ping_packets    | **Optional.** The number of packets to send. Defaults to 5.
1920 ping_timeout    | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
1921
1922 #### <a id="plugin-check-command-ping6"></a> ping6
1923
1924 Check command object for the `check_ping` plugin.
1925
1926 Custom Attributes:
1927
1928 Name            | Description
1929 ----------------|--------------
1930 ping_address    | **Optional.** The host's IPv6 address. Defaults to "$address6$".
1931 ping_wrta       | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
1932 ping_wpl        | **Optional.** The packet loss warning threshold in %. Defaults to 5.
1933 ping_crta       | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
1934 ping_cpl        | **Optional.** The packet loss critical threshold in %. Defaults to 15.
1935 ping_packets    | **Optional.** The number of packets to send. Defaults to 5.
1936 ping_timeout    | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
1937
1938 #### <a id="plugin-check-command-hostalive"></a> hostalive
1939
1940 Check command object for the `check_ping` plugin with host check default values.
1941
1942 Custom Attributes:
1943
1944 Name            | Description
1945 ----------------|--------------
1946 ping_address    | **Optional.** The host's IPv4 address. Defaults to "$address$".
1947 ping_wrta       | **Optional.** The RTA warning threshold in milliseconds. Defaults to 3000.
1948 ping_wpl        | **Optional.** The packet loss warning threshold in %. Defaults to 80.
1949 ping_crta       | **Optional.** The RTA critical threshold in milliseconds. Defaults to 5000.
1950 ping_cpl        | **Optional.** The packet loss critical threshold in %. Defaults to 100.
1951 ping_packets    | **Optional.** The number of packets to send. Defaults to 5.
1952 ping_timeout    | **Optional.** The plugin timeout in seconds. Defaults to 0 (no timeout).
1953
1954 #### <a id="plugin-check-command-fping4"></a> fping4
1955
1956 Check command object for the `check_fping` plugin.
1957
1958 Custom Attributes:
1959
1960 Name            | Description
1961 ----------------|--------------
1962 fping_address   | **Optional.** The host's IPv4 address. Defaults to "$address$".
1963 fping_wrta      | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
1964 fping_wpl       | **Optional.** The packet loss warning threshold in %. Defaults to 5.
1965 fping_crta      | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
1966 fping_cpl       | **Optional.** The packet loss critical threshold in %. Defaults to 15.
1967 fping_number    | **Optional.** The number of packets to send. Defaults to 5.
1968 fping_interval  | **Optional.** The interval between packets in milli-seconds. Defaults to 500.
1969 fping_bytes     | **Optional.** The size of ICMP packet.
1970 fping_target_timeout | **Optional.** The target timeout in milli-seconds.
1971 fping_source_ip | **Optional.** The name or ip address of the source ip.
1972 fping_source_interface | **Optional.** The source interface name.
1973
1974 #### <a id="plugin-check-command-fping6"></a> fping6
1975
1976 Check command object for the `check_fping` plugin.
1977
1978 Custom Attributes:
1979
1980 Name            | Description
1981 ----------------|--------------
1982 fping_address   | **Optional.** The host's IPv6 address. Defaults to "$address6$".
1983 fping_wrta      | **Optional.** The RTA warning threshold in milliseconds. Defaults to 100.
1984 fping_wpl       | **Optional.** The packet loss warning threshold in %. Defaults to 5.
1985 fping_crta      | **Optional.** The RTA critical threshold in milliseconds. Defaults to 200.
1986 fping_cpl       | **Optional.** The packet loss critical threshold in %. Defaults to 15.
1987 fping_number    | **Optional.** The number of packets to send. Defaults to 5.
1988 fping_interval  | **Optional.** The interval between packets in milli-seconds. Defaults to 500.
1989 fping_bytes     | **Optional.** The size of ICMP packet.
1990 fping_target_timeout | **Optional.** The target timeout in milli-seconds.
1991 fping_source_ip | **Optional.** The name or ip address of the source ip.
1992 fping_source_interface | **Optional.** The source interface name.
1993
1994
1995 #### <a id="plugin-check-command-dummy"></a> dummy
1996
1997 Check command object for the `check_dummy` plugin.
1998
1999 Custom Attributes:
2000
2001 Name            | Description
2002 ----------------|--------------
2003 dummy_state     | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 0.
2004 dummy_text      | **Optional.** Plugin output. Defaults to "Check was successful.".
2005
2006 #### <a id="plugin-check-command-passive"></a> passive
2007
2008 Specialised check command object for passive checks executing the `check_dummy` plugin with appropriate default values.
2009
2010 Custom Attributes:
2011
2012 Name            | Description
2013 ----------------|--------------
2014 dummy_state     | **Optional.** The state. Can be one of 0 (ok), 1 (warning), 2 (critical) and 3 (unknown). Defaults to 3.
2015 dummy_text      | **Optional.** Plugin output. Defaults to "No Passive Check Result Received.".
2016
2017 #### <a id="plugin-check-command-tcp"></a> tcp
2018
2019 Check command object for the `check_tcp` plugin.
2020
2021 Custom Attributes:
2022
2023 Name            | Description
2024 ----------------|--------------
2025 tcp_address     | **Optional.** The host's address. Defaults to "$address$".
2026 tcp_port        | **Required.** The port that should be checked.
2027
2028 #### <a id="plugin-check-command-ssl"></a> ssl
2029
2030 Check command object for the `check_tcp` plugin, using ssl-related options.
2031
2032 Custom Attributes:
2033
2034 Name                          | Description
2035 ------------------------------|--------------
2036 ssl_address                   | **Optional.** The host's address. Defaults to "$address$".
2037 ssl_port                      | **Required.** The port that should be checked.
2038 ssl_timeout                   | **Optional.** Timeout in seconds for the connect and handshake. The plugin default is 10 seconds.
2039 ssl_cert_valid_days_warn      | **Optional.** Warning threshold for days before the certificate will expire. When used, ssl_cert_valid_days_critical must also be set.
2040 ssl_cert_valid_days_critical  | **Optional.** Critical threshold for days before the certificate will expire. When used, ssl_cert_valid_days_warn must also be set.
2041
2042 #### <a id="plugin-check-command-udp"></a> udp
2043
2044 Check command object for the `check_udp` plugin.
2045
2046 Custom Attributes:
2047
2048 Name            | Description
2049 ----------------|--------------
2050 udp_address     | **Optional.** The host's address. Defaults to "$address$".
2051 udp_port        | **Required.** The port that should be checked.
2052
2053 #### <a id="plugin-check-command-http"></a> http
2054
2055 Check command object for the `check_http` plugin.
2056
2057 Custom Attributes:
2058
2059 Name                     | Description
2060 -------------------------|--------------
2061 http_address             | **Optional.** The host's address. Defaults to "$address".
2062 http_vhost               | **Optional.** The virtual host that should be sent in the "Host" header.
2063 http_uri                 | **Optional.** The request URI.
2064 http_port                | **Optional.** The TCP port. Defaults to 80 when not using SSL, 443 otherwise.
2065 http_ssl                 | **Optional.** Whether to use SSL. Defaults to false.
2066 http_sni                 | **Optional.** Whether to use SNI. Defaults to false.
2067 http_auth_pair           | **Optional.** Add 'username:password' authorization pair.
2068 http_proxy_auth_pair     | **Optional.** Add 'username:password' authorization pair for proxy.
2069 http_ignore_body         | **Optional.** Don't download the body, just the headers.
2070 http_linespan            | **Optional.** Allow regex to span newline.
2071 http_expect_body_regex   | **Optional.** A regular expression which the body must match against. Incompatible with http_ignore_body.
2072 http_expect_body_eregi   | **Optional.** A case-insensitive expression which the body must match against. Incompatible with http_ignore_body.
2073 http_invertregex         | **Optional.** Changes behaviour of http_expect_body_regex and http_expect_body_eregi to return CRITICAL if found, OK if not.
2074 http_warn_time           | **Optional.** The warning threshold.
2075 http_critical_time       | **Optional.** The critical threshold.
2076 http_expect              | **Optional.** Comma-delimited list of strings, at least one of them is expected in the first (status) line of the server response. Default: HTTP/1.
2077 http_certificate         | **Optional.** Minimum number of days a certificate has to be valid. Port defaults to 443.
2078 http_clientcert          | **Optional.** Name of file contains the client certificate (PEM format).
2079 http_privatekey          | **Optional.** Name of file contains the private key (PEM format).
2080 http_headerstring        | **Optional.** String to expect in the response headers.
2081 http_string              | **Optional.** String to expect in the content.
2082 http_post                | **Optional.** URL encoded http POST data.
2083 http_method              | **Optional.** Set http method (for example: HEAD, OPTIONS, TRACE, PUT, DELETE).
2084 http_maxage              | **Optional.** Warn if document is more than seconds old.
2085 http_contenttype         | **Optional.** Specify Content-Type header when POSTing.
2086 http_useragent           | **Optional.** String to be sent in http header as User Agent.
2087 http_header              | **Optional.** Any other tags to be sent in http header.
2088 http_extendedperfdata    | **Optional.** Print additional perfdata. Defaults to "false".
2089 http_onredirect          | **Optional.** How to handle redirect pages. Possible values: "ok" (default), "warning", "critical", "follow", "sticky" (like follow but stick to address), "stickyport" (like sticky but also to port)
2090 http_pagesize            | **Optional.** Minimum page size required:Maximum page size required.
2091 http_timeout             | **Optional.** Seconds before connection times out.
2092
2093
2094 #### <a id="plugin-check-command-ftp"></a> ftp
2095
2096 Check command object for the `check_ftp` plugin.
2097
2098 Custom Attributes:
2099
2100 Name               | Description
2101 -------------------|--------------
2102 ftp_address        | **Optional.** The host's address. Defaults to "$address".
2103
2104 #### <a id="plugin-check-command-smtp"></a> smtp
2105
2106 Check command object for the `check_smtp` plugin.
2107
2108 Custom Attributes:
2109
2110 Name                 | Description
2111 ---------------------|--------------
2112 smtp_address         | **Optional.** The host's address. Defaults to "$address$".
2113 smtp_port            | **Optional.** The port that should be checked. Defaults to 25.
2114 smtp_mail_from       | **Optional.** Test a MAIL FROM command with the given email address.
2115
2116 #### <a id="plugin-check-command-ssmtp"></a> ssmtp
2117
2118 Check command object for the `check_ssmtp` plugin.
2119
2120 Custom Attributes:
2121
2122 Name            | Description
2123 ----------------|--------------
2124 ssmtp_address   | **Required.** The host's address. Defaults to "$address$".
2125 ssmtp_port      | **Optional.** The port that should be checked. Defaults to 465.
2126 ssmtp_mail_from | **Optional.** Test a MAIL FROM command with the given email address.
2127
2128 #### <a id="plugin-check-command-imap"></a> imap
2129
2130 Check command object for the `check_imap` plugin.
2131
2132 Custom Attributes:
2133
2134 Name            | Description
2135 ----------------|--------------
2136 imap_address    | **Optional.** The host's address. Defaults to "$address$".
2137 imap_port       | **Optional.** The port that should be checked. Defaults to 143.
2138
2139 #### <a id="plugin-check-command-simap"></a> simap
2140
2141 Check command object for the `check_simap` plugin.
2142
2143 Custom Attributes:
2144
2145 Name            | Description
2146 ----------------|--------------
2147 simap_address   | **Optional.** The host's address. Defaults to "$address$".
2148 simap_port      | **Optional.** The host's port.
2149
2150 #### <a id="plugin-check-command-pop"></a> pop
2151
2152 Check command object for the `check_pop` plugin.
2153
2154 Custom Attributes:
2155
2156 Name            | Description
2157 ----------------|--------------
2158 pop_address     | **Optional.** The host's address. Defaults to "$address$".
2159 pop_port        | **Optional.** The port that should be checked. Defaults to 110.
2160
2161 #### <a id="plugin-check-command-spop"></a> spop
2162
2163 Check command object for the `check_spop` plugin.
2164
2165 Custom Attributes:
2166
2167 Name            | Description
2168 ----------------|--------------
2169 spop_address    | **Optional.** The host's address. Defaults to "$address$".
2170 spop_port       | **Optional.** The host's port.
2171
2172 #### <a id="plugin-check-command-ntp-time"></a> ntp_time
2173
2174 Check command object for the `check_ntp_time` plugin.
2175
2176 Custom Attributes:
2177
2178 Name            | Description
2179 ----------------|--------------
2180 ntp_address     | **Optional.** The host's address. Defaults to "$address$".
2181
2182 #### <a id="plugin-check-command-ssh"></a> ssh
2183
2184 Check command object for the `check_ssh` plugin.
2185
2186 Custom Attributes:
2187
2188 Name            | Description
2189 ----------------|--------------
2190 ssh_address     | **Optional.** The host's address. Defaults to "$address$".
2191 ssh_port        | **Optional.** The port that should be checked. Defaults to 22.
2192 ssh_timeout     | **Optional.** Seconds before connection times out. Defaults to 10.
2193
2194 #### <a id="plugin-check-command-disk"></a> disk
2195
2196 Check command object for the `check_disk` plugin.
2197
2198 Custom Attributes:
2199
2200 Name                    | Description
2201 ------------------------|------------------------
2202 disk_wfree              | **Optional.** The free space warning threshold in %. Defaults to 20.
2203 disk_cfree              | **Optional.** The free space critical threshold in %. Defaults to 10.
2204 disk_inode_wfree        | **Optional.** The free inode warning threshold.
2205 disk_inode_cfree        | **Optional.** The free inode critical threshold.
2206 disk_partition          | **Optional.** The partition.
2207 disk_partition_excluded | **Optional.** The excluded partition.
2208
2209 #### <a id="plugin-check-command-users"></a> users
2210
2211 Check command object for the `check_users` plugin.
2212
2213 Custom Attributes:
2214
2215 Name            | Description
2216 ----------------|--------------
2217 users_wgreater  | **Optional.** The user count warning threshold. Defaults to 20.
2218 users_cgreater  | **Optional.** The user count critical threshold. Defaults to 50.
2219
2220 #### <a id="plugin-check-command-processes"></a> procs
2221
2222 Check command object for the `check_procs` plugin.
2223
2224 Custom Attributes:
2225
2226 Name                 | Description
2227 ---------------------|--------------
2228 procs_warning        | **Optional.** The process count warning threshold. Defaults to 250.
2229 procs_critical       | **Optional.** The process count critical threshold. Defaults to 400.
2230 procs_metric         | **Optional.** Check thresholds against metric.
2231 procs_timeout        | **Optional.** Seconds before plugin times out.
2232 procs_traditional    | **Optional.** Filter own process the traditional way by PID instead of /proc/pid/exe. Defaults to "false".
2233 procs_state          | **Optional.** Only scan for processes that have one or more of the status flags you specify.
2234 procs_ppid           | **Optional.** Only scan for children of the parent process ID indicated.
2235 procs_vsz            | **Optional.** Only scan for processes with VSZ higher than indicated.
2236 procs_rss            | **Optional.** Only scan for processes with RSS higher than indicated.
2237 procs_pcpu           | **Optional.** Only scan for processes with PCPU higher than indicated.
2238 procs_user           | **Optional.** Only scan for processes with user name or ID indicated.
2239 procs_argument       | **Optional.** Only scan for processes with args that contain STRING.
2240 procs_argument_regex | **Optional.** Only scan for processes with args that contain the regex STRING.
2241 procs_command        | **Optional.** Only scan for exact matches of COMMAND (without path).
2242 procs_nokthreads     | **Optional.** Only scan for non kernel threads. Defaults to "false".
2243
2244 #### <a id="plugin-check-command-swap"></a> swap
2245
2246 Check command object for the `check_swap` plugin.
2247
2248 Custom Attributes:
2249
2250 Name            | Description
2251 ----------------|--------------
2252 swap_wfree      | **Optional.** The free swap space warning threshold in %. Defaults to 50.
2253 swap_cfree      | **Optional.** The free swap space critical threshold in %. Defaults to 25.
2254
2255 #### <a id="plugin-check-command-load"></a> load
2256
2257 Check command object for the `check_load` plugin.
2258
2259 Custom Attributes:
2260
2261 Name            | Description
2262 ----------------|--------------
2263 load_wload1     | **Optional.** The 1-minute warning threshold. Defaults to 5.
2264 load_wload5     | **Optional.** The 5-minute warning threshold. Defaults to 4.
2265 load_wload15    | **Optional.** The 15-minute warning threshold. Defaults to 3.
2266 load_cload1     | **Optional.** The 1-minute critical threshold. Defaults to 10.
2267 load_cload5     | **Optional.** The 5-minute critical threshold. Defaults to 6.
2268 load_cload15    | **Optional.** The 15-minute critical threshold. Defaults to 4.
2269
2270 #### <a id="plugin-check-command-snmp"></a> snmp
2271
2272 Check command object for the `check_snmp` plugin.
2273
2274 Custom Attributes:
2275
2276 Name                | Description
2277 --------------------|--------------
2278 snmp_address        | **Optional.** The host's address. Defaults to "$address$".
2279 snmp_oid            | **Required.** The SNMP OID.
2280 snmp_community      | **Optional.** The SNMP community. Defaults to "public".
2281 snmp_warn           | **Optional.** The warning threshold.
2282 snmp_crit           | **Optional.** The critical threshold.
2283 snmp_string         | **Optional.** Return OK state if the string matches exactly with the output value
2284 snmp_ereg           | **Optional.** Return OK state if extended regular expression REGEX matches with the output value
2285 snmp_eregi          | **Optional.** Return OK state if case-insensitive extended REGEX matches with the output value
2286 snmp_label          | **Optional.** Prefix label for output value
2287 snmp_invert_search  | **Optional.** Invert search result and return CRITICAL state if found
2288 snmp_units          | **Optional.** Units label(s) for output value (e.g., 'sec.').
2289
2290 #### <a id="plugin-check-command-snmp"></a> snmpv3
2291
2292 Check command object for the `check_snmp` plugin, using SNMPv3 authentication and encryption options.
2293
2294 Custom Attributes:
2295
2296 Name              | Description
2297 ------------------|--------------
2298 snmpv3_address    | **Optional.** The host's address. Defaults to "$address$".
2299 snmpv3_user       | **Required.** The username to log in with.
2300 snmpv3_auth_alg   | **Optional.** The authentication algorithm. Defaults to SHA.
2301 snmpv3_auth_key   | **Required.** The authentication key.
2302 snmpv3_priv_alg   | **Optional.** The encryption algorithm. Defaults to AES.
2303 snmpv3_priv_key   | **Required.** The encryption key.
2304 snmpv3_oid        | **Required.** The SNMP OID.
2305 snmpv3_warn       | **Optional.** The warning threshold.
2306 snmpv3_crit       | **Optional.** The critical threshold.
2307
2308 #### <a id="plugin-check-command-snmp-uptime"></a> snmp-uptime
2309
2310 Check command object for the `check_snmp` plugin.
2311
2312 Custom Attributes:
2313
2314 Name            | Description
2315 ----------------|--------------
2316 snmp_address    | **Optional.** The host's address. Defaults to "$address$".
2317 snmp_oid        | **Optional.** The SNMP OID. Defaults to "1.3.6.1.2.1.1.3.0".
2318 snmp_community  | **Optional.** The SNMP community. Defaults to "public".
2319
2320 #### <a id="plugin-check-command-dns"></a> dns
2321
2322 Check command object for the `check_dns` plugin.
2323
2324 Custom Attributes:
2325
2326 Name                 | Description
2327 ---------------------|--------------
2328 dns_lookup           | **Optional.** The hostname or IP to query the DNS for. Defaults to $host_name$.
2329 dns_server           | **Optional.** The DNS server to query. Defaults to the server configured in the OS.
2330 dns_expected_answer  | **Optional.** The answer to look for. A hostname must end with a dot.
2331 dns_authoritative    | **Optional.** Expect the server to send an authoritative answer.
2332
2333 #### <a id="plugin-check-command-dig"></a> dig
2334
2335 Check command object for the `check_dig` plugin.
2336
2337 Custom Attributes:
2338
2339 Name                 | Description
2340 ---------------------|--------------
2341 dig_server           | **Optional.** The DNS server to query. Defaults to "127.0.0.1".
2342 dig_lookup           | **Optional.** The address that should be looked up.
2343
2344 #### <a id="plugin-check-command-dhcp"></a> dhcp
2345
2346 Check command object for the `check_dhcp` plugin.
2347
2348 Custom Attributes:
2349
2350 Name            | Description
2351 ----------------|--------------
2352 dhcp_serverip   | **Optional.** The IP address of the DHCP server which we should get a response from.
2353 dhcp_requestedip| **Optional.** The IP address which we should be offered by a DHCP server.
2354 dhcp_timeout    | **Optional.** The timeout in seconds.
2355 dhcp_interface  | **Optional.** The interface to use.
2356 dhcp_mac        | **Optional.** The MAC address to use in the DHCP request.
2357 dhcp_unicast    | **Optional.** Whether to use unicast requests. Defaults to false.
2358
2359 #### <a id="plugin-check-command-nscp"></a> nscp
2360
2361 Check command object for the `check_nt` plugin.
2362
2363 Custom Attributes:
2364
2365 Name            | Description
2366 ----------------|--------------
2367 nscp_address    | **Optional.** The host's address. Defaults to "$address$".
2368 nscp_port       | **Optional.** The NSClient++ port. Defaults to 12489.
2369 nscp_password   | **Optional.** The NSClient++ password.
2370 nscp_variable   | **Required.** The variable that should be checked.
2371 nscp_params     | **Optional.** Parameters for the query.
2372 nscp_warn       | **Optional.** The warning threshold.
2373 nscp_crit       | **Optional.** The critical threshold.
2374 nscp_timeout    | **Optional.** The query timeout in seconds.
2375
2376 #### <a id="plugin-check-command-by-ssh"></a> by_ssh
2377
2378 Check command object for the `check_by_ssh` plugin.
2379
2380 Custom Attributes:
2381
2382 Name            | Description
2383 ----------------|--------------
2384 by_ssh_address  | **Optional.** The host's address. Defaults to "$address$".
2385 by_ssh_port     | **Optional.** The SSH port. Defaults to 22.
2386 by_ssh_command  | **Optional.** The command that should be executed.
2387 by_ssh_logname  | **Optional.** The SSH username.
2388 by_ssh_identity | **Optional.** The SSH identity.
2389 by_ssh_quiet    | **Optional.** Whether to suppress SSH warnings. Defaults to false.
2390 by_ssh_warn     | **Optional.** The warning threshold.
2391 by_ssh_crit     | **Optional.** The critical threshold.
2392 by_ssh_timeout  | **Optional.** The timeout in seconds.
2393
2394 #### <a id="plugin-check-command-ups"></a> ups
2395
2396 Check command object for the `check_ups` plugin.
2397
2398 Custom Attributes:
2399
2400 Name            | Description
2401 ----------------|--------------
2402 ups_address     | **Optional.** The host's address. Defaults to "$address$".
2403 ups_name        | **Optional.** The UPS name. Defaults to `ups`.
2404
2405
2406 #### <a id="plugin-check-command-nrpe"></a> nrpe
2407
2408 Check command object for the `check_nrpe` plugin.
2409
2410 Custom Attributes:
2411
2412 Name            | Description
2413 ----------------|--------------
2414 nrpe_address    | **Optional.** The host's address. Defaults to "$address$".
2415 nrpe_port       | **Optional.** The NRPE port. Defaults to 5668.
2416 nrpe_command    | **Optional.** The command that should be executed.
2417 nrpe_no_ssl     | **Optional.** Whether to disable SSL or not. Defaults to `false`.
2418 nrpe_timeout_unknown | **Optional.** Whether to set timeouts to unknown instead of critical state. Defaults to `false`.
2419 nrpe_timeout    | **Optional.** The timeout in seconds.
2420
2421 #### <a id="plugin-check-command-apt"></a> apt
2422
2423 Check command for the `check_apt` plugin.
2424
2425 The `apt` check command does not support any vars.
2426
2427
2428 #### <a id="plugin-check-command-running-kernel"></a> running_kernel
2429
2430 Check command object for the `check_running_kernel` plugin
2431 provided by the `nagios-plugins-contrib` package on Debian.
2432
2433 The `running_kernel` check command does not support any vars.
2434
2435
2436 ## <a id="snmp-manubulon-plugin-check-commands"></a> SNMP Manubulon Plugin Check Commands
2437
2438 ### <a id="snmp-manubulon-plugin-check-commands-overview"></a> Overview
2439
2440 The `SNMP Manubulon Plugin Check Commands` provide example configuration for plugin check
2441 commands provided by the [SNMP Manubulon project](http://nagios.manubulon.com/index_snmp.html).
2442
2443 The SNMP manubulon plugin check commands assume that the global constant named `ManubulonPluginDir`
2444 is set to the path where the Manubublon SNMP plugins are installed.
2445
2446 You can enable these plugin check commands by adding the following the include directive in your
2447 configuration [icinga2.conf](#icinga2-conf) file:
2448
2449     include <manubulon>
2450
2451 ### Checks by Host Type
2452
2453 **N/A**      : Not available for this type.
2454
2455 **SNMP**     : Available for simple SNMP query.
2456
2457 **??**       : Untested.
2458
2459 **Specific** : Script name for platform specific checks.
2460
2461
2462   Host type               | Interface  | storage  | load/cpu  | mem | process  | env | specific
2463   ------------------------|------------|----------|-----------|-----|----------|-----|-------------------------
2464   Linux                   |   Yes      |   Yes    |   Yes     | Yes |   Yes    | No  |
2465   Windows                 |   Yes      |   Yes    |   Yes     | Yes |   Yes    | No  | check_snmp_win.pl
2466   Cisco router/switch     |   Yes      |   N/A    |   Yes     | Yes |   N/A    | Yes |
2467   HP router/switch        |   Yes      |   N/A    |   Yes     | Yes |   N/A    | No  |
2468   Bluecoat proxy          |   Yes      |   SNMP   |   Yes     | SNMP|   No     | Yes |
2469   CheckPoint on SPLAT     |   Yes      |   Yes    |   Yes     | Yes |   Yes    | No  | check_snmp_cpfw.pl
2470   CheckPoint on Nokia IP  |   Yes      |   Yes    |   Yes     | No  |   ??     | No  | check_snmp_vrrp.pl
2471   Boostedge               |   Yes      |   Yes    |   Yes     | Yes |   ??     | No  | check_snmp_boostedge.pl
2472   AS400                   |   Yes      |   Yes    |   Yes     | Yes |   No     | No  |
2473   NetsecureOne Netbox     |   Yes      |   Yes    |   Yes     | ??  |   Yes    | No  |
2474   Radware Linkproof       |   Yes      |   N/A    |   SNMP    | SNMP|   No     | No  | check_snmp_linkproof_nhr <br> check_snmp_vrrp.pl
2475   IronPort                |   Yes      |   SNMP   |   SNMP    | SNMP|   No     | Yes |
2476   Cisco CSS               |   Yes      |   ??     |   Yes     | Yes |   No     | ??  | check_snmp_css.pl
2477
2478
2479 #### <a id="plugin-check-command-snmp-load"></a> snmp-load
2480
2481 Check command object for the [check_snmp_load.pl](http://nagios.manubulon.com/snmp_load.html) plugin.
2482
2483 Custom Attributes:
2484
2485
2486 Name                    | Description
2487 ------------------------|--------------
2488 snmp_address            | **Optional.** The host's address. Defaults to "$address$".
2489 snmp_nocrypt            | **Optional.** Define SNMP encryption. If set **snmp_v3** needs to be set. Defaults to "false".
2490 snmp_community          | **Optional.** The SNMP community. Defaults to "public".
2491 snmp_port               | **Optional.** The SNMP port connection.
2492 snmp_v2                 | **Optional.** SNMP version to 2c. Defaults to "false".
2493 snmp_v3                 | **Optional.** SNMP version to 3. Defaults to "false".
2494 snmp_login              | **Optional.** SNMP version 3 username. Defaults to "snmpuser".
2495 snmp_password           | **Required.** SNMP version 3 password. No value defined as default.
2496 snmp_v3_use_privpass    | **Optional.** Define to use SNMP version 3 priv password. Defaults to "false".
2497 snmp_authprotocol       | **Optional.** SNMP version 3 authentication protocol. Defaults to "md5,des".
2498 snmp_privpass           | **Required.** SNMP version 3 priv password. No value defined as default.
2499 snmp_warn               | **Optional.** The warning threshold. Change the `snmp_load_type` var to "netsl" for using 3 values.
2500 snmp_crit               | **Optional.** The critical threshold. Change the `snmp_load_type` var to "netsl" for using 3 values.
2501 snmp_load_type          | **Optional.** Load type. Defaults to "stand". Check all available types in the [snmp load](http://nagios.manubulon.com/snmp_load.html) documentation.
2502 snmp_perf               | **Optional.** Enable perfdata values. Defaults to "true".
2503
2504 #### <a id="plugin-check-command-snmp-memory"></a> snmp-memory
2505
2506 Check command object for the [check_snmp_mem.pl](http://nagios.manubulon.com/snmp_mem.html) plugin.
2507
2508 Custom Attributes:
2509
2510 Name                    | Description
2511 ------------------------|--------------
2512 snmp_address            | **Optional.** The host's address. Defaults to "$address$".
2513 snmp_nocrypt            | **Optional.** Define SNMP encryption. If set **snmp_v3** needs to be set. Defaults to "false".
2514 snmp_community          | **Optional.** The SNMP community. Defaults to "public".
2515 snmp_port               | **Optional.** The SNMP port connection.
2516 snmp_v2                 | **Optional.** SNMP version to 2c. Defaults to "false".
2517 snmp_v3                 | **Optional.** SNMP version to 3. Defaults to "false".
2518 snmp_login              | **Optional.** SNMP version 3 username. Defaults to "snmpuser".
2519 snmp_password           | **Required.** SNMP version 3 password. No value defined as default.
2520 snmp_v3_use_privpass    | **Optional.** Define to use SNMP version 3 priv password. Defaults to "false".
2521 snmp_authprotocol       | **Optional.** SNMP version 3 authentication protocol. Defaults to "md5,des".
2522 snmp_privpass           | **Required.** SNMP version 3 priv password. No value defined as default.
2523 snmp_warn               | **Optional.** The warning threshold.
2524 snmp_crit               | **Optional.** The critical threshold.
2525 snmp_perf               | **Optional.** Enable perfdata values. Defaults to "true".
2526
2527 #### <a id="plugin-check-command-snmp-storage"></a> snmp-storage
2528
2529 Check command object for the [check_snmp_storage.pl](http://nagios.manubulon.com/snmp_storage.html) plugin.
2530
2531 Custom Attributes:
2532
2533 Name                    | Description
2534 ------------------------|--------------
2535 snmp_address            | **Optional.** The host's address. Defaults to "$address$".
2536 snmp_nocrypt            | **Optional.** Define SNMP encryption. If set **snmp_v3** needs to be set. Defaults to "false".
2537 snmp_community          | **Optional.** The SNMP community. Defaults to "public".
2538 snmp_port               | **Optional.** The SNMP port connection.
2539 snmp_v2                 | **Optional.** SNMP version to 2c. Defaults to "false".
2540 snmp_v3                 | **Optional.** SNMP version to 3. Defaults to "false".
2541 snmp_login              | **Optional.** SNMP version 3 username. Defaults to "snmpuser".
2542 snmp_password           | **Required.** SNMP version 3 password. No value defined as default.
2543 snmp_v3_use_privpass    | **Optional.** Define to use SNMP version 3 priv password. Defaults to "false".
2544 snmp_authprotocol       | **Optional.** SNMP version 3 authentication protocol. Defaults to "md5,des".
2545 snmp_privpass           | **Required.** SNMP version 3 priv password. No value defined as default.
2546 snmp_warn               | **Optional.** The warning threshold.
2547 snmp_crit               | **Optional.** The critical threshold.
2548 snmp_storage_name       | **Optional.** Storage name. Default to regex "^/$$". More options available in the [snmp storage](http://nagios.manubulon.com/snmp_storage.html) documentation.
2549 snmp_perf               | **Optional.** Enable perfdata values. Defaults to "true".
2550
2551 #### <a id="plugin-check-command-snmp-interface"></a> snmp-interface
2552
2553 Check command object for the [check_snmp_int.pl](http://nagios.manubulon.com/snmp_int.html) plugin.
2554
2555 Custom Attributes:
2556
2557 Name                    | Description
2558 ------------------------|--------------
2559 snmp_address            | **Optional.** The host's address. Defaults to "$address$".
2560 snmp_nocrypt            | **Optional.** Define SNMP encryption. If set **snmp_v3** needs to be set. Defaults to "false".
2561 snmp_community          | **Optional.** The SNMP community. Defaults to "public".
2562 snmp_port               | **Optional.** The SNMP port connection.
2563 snmp_v2                 | **Optional.** SNMP version to 2c. Defaults to "false".
2564 snmp_v3                 | **Optional.** SNMP version to 3. Defaults to "false".
2565 snmp_login              | **Optional.** SNMP version 3 username. Defaults to "snmpuser".
2566 snmp_password           | **Required.** SNMP version 3 password. No value defined as default.
2567 snmp_v3_use_privpass    | **Optional.** Define to use SNMP version 3 priv password. Defaults to "false".
2568 snmp_authprotocol       | **Optional.** SNMP version 3 authentication protocol. Defaults to "md5,des".
2569 snmp_privpass           | **Required.** SNMP version 3 priv password. No value defined as default..
2570 snmp_warn               | **Optional.** The warning threshold.
2571 snmp_crit               | **Optional.** The critical threshold.
2572 snmp_interface          | **Optional.** Network interface name. Default to regex "eth0".
2573 snmp_interface_perf     | **Optional.** Check the input/ouput bandwidth of the interface. Defaults to "true".
2574 snmp_interface_bits     | **Optional.** Make the warning and critical levels in KBits/s. Defaults to "true".
2575 snmp_interface_64bit    | **Optional.** Use 64 bits counters instead of the standard counters when checking bandwidth & performance data for interface >= 1Gbps. Defaults to "false".
2576 snmp_perf               | **Optional.** Enable perfdata values. Defaults to "true".
2577
2578 #### <a id="plugin-check-command-snmp-process"></a> snmp-process
2579
2580 Check command object for the [check_snmp_process.pl](http://nagios.manubulon.com/snmp_process.html) plugin.
2581
2582 Custom Attributes:
2583
2584 Name                    | Description
2585 ------------------------|--------------
2586 snmp_address            | **Optional.** The host's address. Defaults to "$address$".
2587 snmp_nocrypt            | **Optional.** Define SNMP encryption. If set **snmp_v3** needs to be set. Defaults to "false".
2588 snmp_community          | **Optional.** The SNMP community. Defaults to "public".
2589 snmp_port               | **Optional.** The SNMP port connection.
2590 snmp_v2                 | **Optional.** SNMP version to 2c. Defaults to "false".
2591 snmp_v3                 | **Optional.** SNMP version to 3. Defaults to "false".
2592 snmp_login              | **Optional.** SNMP version 3 username. Defaults to "snmpuser".
2593 snmp_password           | **Required.** SNMP version 3 password. No value defined as default.
2594 snmp_v3_use_privpass    | **Optional.** Define to use SNMP version 3 priv password. Defaults to "false".
2595 snmp_authprotocol       | **Optional.** SNMP version 3 authentication protocol. Defaults to "md5,des".
2596 snmp_privpass           | **Required.** SNMP version 3 priv password. No value defined as default..
2597 snmp_warn               | **Optional.** The warning threshold.
2598 snmp_crit               | **Optional.** The critical threshold.
2599 snmp_process_name       | **Optional.** Name of the process (regexp). No trailing slash!. Defaults to ".*".
2600 snmp_perf               | **Optional.** Enable perfdata values. Defaults to "true".