icinga2/doc/3.3-object-types.md

Object Types

Host

A host.

Note

Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2.

Example:

object Host "localhost" {
  display_name = "The best host there is",

  groups = [ "all-hosts" ],

  check = "ping",

  host_dependencies = [ "router" ],

  service_dependencies = [
    { host = "db-server", service = "mysql" }
  ],

  services["ping"] = {
    templates = [ "ping" ]
  },

  services["http"] = {
    templates = [ "my-http" ],

    macros = {
      vhost = "test1.example.org",
      port = 81
    }
  }
}

Attributes:

Name	Description
display_name	Optional. A short description of the host.
check	Optional. A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
groups	Optional. A list of host groups this host belongs to.
host_dependencies	Optional. A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
service_dependencies	Optional. A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
services	Optional. Inline definition of services. Each dictionary item specifies a service. The templates attribute can be used to specify an array of templates that should be inherited by the service. The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary. The dictionary key is used as the service's short name.
macros	TODO

HostGroup

A group of hosts.

Example:

object HostGroup "my-hosts" {
  display_name = "My hosts",
}

Attributes:

Name	Description
display_name	Optional. A short description of the host group.

Service

Service objects describe network services and how they should be checked by Icinga 2.

Best Practice

Rather than creating a Service object for a specific host it is usually easier to just create a Service template and using the services attribute in the Host object to associate these templates with a host.

Example:

object Service "localhost-uptime" {
  host = "localhost",
  short_name = "uptime",

  display_name = "localhost Uptime",

  check_command = "check_snmp",

  macros = {
    community = "public",
    oid = "DISMAN-EVENT-MIB::sysUpTimeInstance"
  }

  check_interval = 60s,
  retry_interval = 15s,

  servicegroups = [ "all-services", "snmp" ],
}

Attributes:

Name	Description
host	Required. The host this service belongs to. There must be a Host object with that name.
short_name	Required. The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
display_name	Optional. A short description of the service.
macros	Optional.
check_command	Required. The name of the check command.
max_check_attempts	TODO
check_period	Optional. The name of a time period which determines when this service should be checked. Not set by default.
check_interval	Optional. The check interval (in seconds).
retry_interval	Optional. The retry interval (in seconds). This is used when the service is in a soft state. Defaults to 1/5th of the check interval if not specified.
event_command	Optional. The name of an event command that should be executed every time the service's state changes.
flapping_threshold	TODO
volatile	TODO
host_dependencies	TODO
service_dependencies	TODO
groups	Optional. The service groups this service belongs to.
notifications	TODO

ServiceGroup

A group of services.

Example:

object ServiceGroup "snmp" {
  display_name = "SNMP services",
}

Attributes:

Name	Description
display_name	Optional. A short description of the service group.

Notification

TODO

Example:

TODO

Attributes:

Name	Description
host	Required. The name of the host this notification belongs to.
service	Required. The short name of the service this notification belongs to.
macros	TODO
users	Optional. A list of user names who should be notified.
user_groups	Optional. A list of user group names who should be notified.
times	TODO
notification_command	TODO
notification_interval	TODO
notification_period	TODO
notification_type_filter	TODO
notification_state_filter	TODO

User

A user.

Example:

TODO

Attributes:

Name	Description
display_name	Optional. A short description of the user.
macros	TODO
groups	TODO
enable_notifications	TODO
notification_period	TODO
notification_type_filter	TODO
notification_state_filter	TODO

UserGroup

A user group.

Example:

object UserGroup "noc-staff" {
    display_name = "NOC Staff"
}

Attributes:

Name	Description
display_name	Optional. A short description of the user group.

TimePeriod

Time periods can be used to specify when services should be checked or to limit when notifications should be sent out.

Example:

TODO

Attributes:

Name	Description
display_name	Optional. A short description of the time period.
methods	TODO
ranges	TODO

ConsoleLogger

Specifies Icinga 2 logging to the console.

Example:

object ConsoleLogger "my-debug-console" {
  severity = "debug"
}

Attributes:

Name	Description
severity	Optional. The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

FileLogger

Specifies Icinga 2 logging to a file.

Example:

object FileLogger "my-debug-file" {
  severity = "debug",
  path = "/var/log/icinga2/icinga2-debug.log"
}

Attributes:

Name	Description
path	Required. The log path.
severity	Optional. The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

SyslogLogger

Specifies Icinga 2 logging to syslog.

Example:

object SyslogLogger "my-crit-syslog" {
  severity = "critical"
}

Attributes:

Name	Description
severity	Optional. The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".

CheckCommand

A check command definition. Additional default command macros can be defined here.

Example:

object CheckCommand "check_snmp" inherits "plugin-check-command" {
  command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",

  macros = {
    address = "127.0.0.1",
    community = "public",
  }
}

Attributes:

Name	Description
methods	TODO
command	TODO
export_macros	TODO
escape_macros	TODO
macros	TODO
timeout	TODO

NotificationCommand

A notification command definition.

Example:

object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
  command = [
    "/opt/bin/send-mail-notification",
    "$CONTACTEMAIL$",
    "$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$",
    {{{***** Icinga  *****

Notification Type: $NOTIFICATIONTYPE$

Service: $SERVICEDESC$
Host: $HOSTALIAS$
Address: $HOSTADDRESS$
State: $SERVICESTATE$

Date/Time: $LONGDATETIME$

Additional Info: $SERVICEOUTPUT$

Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$}}}
  ]
}

Attributes:

Name	Description
methods	TODO
command	TODO
export_macros	TODO
escape_macros	TODO
macros	TODO
timeout	TODO

EventCommand

An event command definition.

Note

Similar to Icinga 1.x event handlers.

Example:

object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
  command = "/opt/bin/restart-httpd.sh",
}

Attributes:

Name	Description
methods	TODO
command	TODO
export_macros	TODO
escape_macros	TODO
macros	TODO
timeout	TODO

PerfdataWriter

Writes check result performance data to a defined path using macro pattern.

Example

object PerfdataWriter "pnp" {
  perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata",

  format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$",

  rotation_interval = 15s,
}

Attributes:

Name	Description
perfdata_path	Optional. Path to the service perfdata file. Defaults to IcingaLocalStateDir + "/cache/icinga2/perfdata/perfdata".
format_template	Optional. Format template for the perfdata file. Defaults to a template that's suitable for use with PNP4Nagios.
rotation_interval	Optional. Rotation interval for the file specified in perfdata_path. Defaults to 30 seconds.

Note

When rotating the perfdata file the current UNIX timestamp is appended to the path specified in perfdata_path to generate a unique filename.

IdoMySqlConnection

IDO DB schema compatible output into MySQL database.

Example:

library "db_ido_mysql"

object IdoMysqlConnection "mysql-ido" {
  host = "127.0.0.1",
  port = 3306,
  user = "icinga",
  password = "icinga",
  database = "icinga",
  table_prefix = "icinga_",
  instance_name = "icinga2",
  instance_description = "icinga2 dev instance"
  cleanup = {
    downtimehistory_age = 48h,
logentries_age = 31d,
  }
}

Attributes:

Name	Description
host	Optional. MySQL database host address. Defaults to "localhost".
port	Optional. MySQL database port. Defaults to 3306.
user	Optional. MySQL database user with read/write permission to the icinga database. Defaults to "icinga".
password	Optional. MySQL database user's password. Defaults to "icinga".
database	Optional. MySQL database name. Defaults to "icinga".
table_prefix	Optional. MySQL database table prefix. Defaults to "icinga_".
instance_name	Optional. Unique identifier for the local Icinga 2 instance. Defaults to "default".
instance_description	Optional. Description for the Icinga 2 instance.
cleanup	Optional. Dictionary with items for historical table cleanup.

Cleanup Items:

----------------|---------------- acknowledgement_age |Optional. Max age for acknowledgement table rows (entry_time) commenthistory_age |Optional. Max age for commenthistory table rows (entry_time) contactnotifications_age |Optional. Max age for contactnotifications table rows (start_time) contactnotificationmethods_age |Optional. Max age for contactnotificationmethods table rows (start_time) downtimehistory_age |Optional. Max age for downtimehistory table rows (entry_time) eventhandlers_age |Optional. Max age for eventhandlers table rows (start_time) externalcommands_age |Optional. Max age for externalcommands table rows (entry_time) flappinghistory_age |Optional. Max age for flappinghistory table rows (event_time) hostchecks_age |Optional. Max age for hostchecks table rows (start_time) logentries_age |Optional. Max age for logentries table rows (logentry_time) notifications_age |Optional. Max age for notifications table rows (start_time) processevents_age |Optional. Max age for processevents table rows (event_time) statehistory_age |Optional. Max age for statehistory table rows (state_time) servicechecks_age |Optional. Max age for servicechecks table rows (start_time) systemcommands_age |Optional. Max age for systemcommands table rows (start_time)

LiveStatusListener

Livestatus API interface available as TCP or UNIX socket.

Example:

library "livestatus"

object LivestatusListener "livestatus-tcp" {
  socket_type = "tcp",
  bind_host = "127.0.0.1",
  bind_port = "6558"
}

object LivestatusListener "livestatus-unix" {
  socket_type = "unix",
  socket_path = "/var/run/icinga2/livestatus"
}

Attributes:

Name	Description
socket_type	Optional. Specifies the socket type. Can be either "tcp" or "unix". Defaults to "unix".
bind_host	Optional. Only valid when socket_type is "tcp". Host address to listen on for connections. Defaults to "127.0.0.1".
bind_port	Optional. Only valid when socket_type is "tcp". Port to listen on for connections. Defaults to 6558.
socket_path	Optional. Only valid when socket_type is "unix". Specifies the path to the UNIX socket file. Defaults to IcingaLocalStateDir + "/run/icinga2/livestatus".

Note

UNIX sockets are not supported on Windows.

StatusDataWriter

Periodically writes status data files which are used by the Classic UI and other third-party tools.

Example:

library "compat"

object StatusDataWriter "status" {
    status\_path = "/var/cache/icinga2/status.dat",
    objects\_path = "/var/cache/icinga2/objects.path"
}

Attributes:

Name	Description
status_path	Optional. Path to the status.dat file. Defaults to IcingaLocalStateDir + "/cache/icinga2/status.dat".
objects_path	Optional. Path to the objects.cache file. Defaults to IcingaLocalStateDir + "/cache/icinga2/objects.cache".

ExternalCommandListener

Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.

Example:

library "compat"

object ExternalCommandListener "external" {
    command\_path = "/var/run/icinga2/cmd/icinga2.cmd"
}

Attributes:

Name	Description
command_path	Optional. Path to the command pipe. Defaults to IcingaLocalStateDir + "/run/icinga2/cmd/icinga2.cmd".

CompatLogger

Writes log files in a format that's compatible with Icinga 1.x.

Example:

library "compat"

object CompatLogger "my-log" {
  log\_dir = "/var/log/icinga2/compat/compat-log",
  rotation\_method = "HOURLY"
}

Attributes:

Name	Description
log_dir	Optional. Path to the compat log directory. Defaults to IcingaLocalStateDir + "/log/icinga2/compat".
rotation_method	Optional. Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".

CheckResultReader

TODO

Example:

TODO

Attributes:

Name	Description
spool_dir	TODO

CheckerComponent

TODO

Example:

library "checker"

object CheckerComponent "checker" { }

NotificationComponent

TODO

Example:

library "notification"

object NotificationComponent "notification" { }

ClusterListener

TODO

Example:

TODO

Attributes:

Name	Description
cert_path	TODO
ca_path	TODO
bind_host	TODO
bind_port	TODO
peers	TODO

Endpoint

Endpoint objects are used to specify connection information for remote Icinga 2 instances.

Example:

library "cluster"

object Endpoint "icinga-c2" {
  node = "192.168.5.46",
  service = 7777,
}

Attributes:

Name	Description
node	Required. The hostname/IP address of the remote Icinga 2 instance.
service	Required. The service name/port of the remote Icinga 2 instance.
config_files	TODO
accept_config	Optional. A list of endpoint names from which this endpoint accepts configuration files.

Domain

TODO

Example:

TODO

Attributes:

Name	Description
acl	TODO