From: Michael Friedrich Date: Thu, 27 Jun 2013 12:53:26 +0000 (+0200) Subject: docs: update latest changes X-Git-Tag: v0.0.2~38 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=db07e19ae892c3b144b210e9fe3af879e2ee09f3;p=icinga2 docs: update latest changes fixes #4338 --- diff --git a/docs/icinga2-config-types.adoc b/docs/icinga2-config-types.adoc index aca5220f1..a391d18a9 100644 --- a/docs/icinga2-config-types.adoc +++ b/docs/icinga2-config-types.adoc @@ -511,31 +511,46 @@ Specifies where Icinga 2 Compat component will put the objects.cache file, which be read by Icinga 1.x Classic UI and other addons. If not set, it defaults to the localstatedir location. -Type: Logger -~~~~~~~~~~~~ +Type: ConsoleLogger +~~~~~~~~~~~~~~~~~~~ -Specifies where Icinga 2 should be logging. Objects of this type must have the +Specifies Icinga 2 logging to the console. Objects of this type must have the "local" specifier. Example: ------------------------------------------------------------------------------- -local object Logger "my-debug-log" { - type = "file", - path = "./var/log/icinga2/icinga2.log", +local object ConsoleLogger "my-debug-console" { severity = "debug" } ------------------------------------------------------------------------------- -Attribute: type -^^^^^^^^^^^^^^^ +Attribute: severity +^^^^^^^^^^^^^^^^^^^ + +The minimum severity for this log. Can be "debug", "information", "warning" or +"critical". Defaults to "information". + +Type: FileLogger +~~~~~~~~~~~~~~~~ + +Specifies Icinga 2 logging to a file. Objects of this type must have the "local" +specifier. + +Example: + +------------------------------------------------------------------------------- +local object FileLogger "my-debug-file" { + severity = "debug", + path = "/var/log/icinga2/icinga2-debug.log" +} +------------------------------------------------------------------------------- -The type of the log. Can be "console", "syslog" or "file". Attribute: path ^^^^^^^^^^^^^^^ -The log path. Ignored if the log type is not "file". +The log path. Attribute: severity ^^^^^^^^^^^^^^^^^^^ @@ -543,6 +558,27 @@ Attribute: severity The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information". +Type: SyslogLogger +~~~~~~~~~~~~~~~~~~ + +Specifies Icinga 2 logging to syslog. Objects of this type must have the "local" +specifier. + +Example: + +------------------------------------------------------------------------------- +local object SyslogLogger "my-crit-syslog" { + severity = "critical" +} +------------------------------------------------------------------------------- + +Attribute: severity +^^^^^^^^^^^^^^^^^^^ + +The minimum severity for this log. Can be "debug", "information", "warning" or +"critical". Defaults to "information". + + Type: Endpoint ~~~~~~~~~~~~~~ @@ -566,12 +602,63 @@ Attribute: service The service name/port of the remote Icinga 2 instance. +Type: 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 = {2yy + plugindir = "/usr/lib/nagios/plugins", + address = "127.0.0.1", + community = "public", + } +} +------------------------------------------------------------------------------- + +Type: NotificationCommand +~~~~~~~~~~~~~~~~~~~~~~~~~ + +A notification command definition. + +Example: + +------------------------------------------------------------------------------- +object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" { + command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$", +} +------------------------------------------------------------------------------- + +Type: NotificationCommand +~~~~~~~~~~~~~~~~~~~~~~~~~ + +An event command definition. + +NOTE: Similar to Icinga 1.x event handlers. + +Example: + +------------------------------------------------------------------------------- +object EventCommand "restart-httpd-event" inherits "plugin-event-command" { + command = "/usr/local/icinga/libexec/restart-httpd.sh", +} +------------------------------------------------------------------------------- + + Type: Service ~~~~~~~~~~~~~ Service objects describe network services and how they should be checked by Icinga 2. +NOTE: Better create a service template and use that reference on the host +definition as shown below. + Example: ------------------------------------------------------------------------------- @@ -584,17 +671,17 @@ object Service "localhost-uptime" { check = "PluginCheck" }, - check_command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$", + check_command = "check_snmp", macros = { plugindir = "/usr/lib/nagios/plugins", address = "127.0.0.1", - community = "public" ,A hos + community = "public", oid = "DISMAN-EVENT-MIB::sysUpTimeInstance" } - check_interval = 60, - retry_interval = 15, + check_interval = 60s, + retry_interval = 15s, servicegroups = { "all-services", "snmp" }, @@ -657,8 +744,10 @@ Example: object ServiceGroup "snmp" { alias = "SNMP services", - notes_url = "http://www.example.org/", - action_url = "http://www.example.org/", + custom = { + notes_url = "http://www.example.org/", + action_url = "http://www.example.org/", + } } ------------------------------------------------------------------------------- @@ -688,27 +777,24 @@ Example: object Host "localhost" { alias = "The best host there is", - hostgroups = { "all-hosts" }, + hostgroups = [ "all-hosts" ], hostcheck = "ping", - dependencies = { "router-ping" } - - services = { - "ping", - "my-http" { - service = "http", - - macros = { - vhost = "test1.example.org", - port = 81 - } + dependencies = [ "router-ping" ] + + services["ping"] = { templates = "ping" } + services["http"] = { + templates = "my-http", + macros = { + vhost = "test1.example.org", + port = 81 } } - check_interval = 60, - retry_interval = 15, + check_interval = 60m, + retry_interval = 15m, - servicegroups = { "all-services" }, + servicegroups = [ "all-services" ], checkers = { "*" }, } @@ -744,15 +830,14 @@ unreachable. Attribute: services ^^^^^^^^^^^^^^^^^^^ -Inline definition of services. Each property in this dictionary specifies a -service. If the value of a property is a string it is interpreted as the name -of a service template and is used as a parent object for the new service. If it -is a dictionary its service property is used to determine the parent object and -all other service-related properties are additively copied into the new service +Inline definition of services. Each service name is defined in square brackets +and got its own dictionary with attribute properties, such as the template service +being used. +All other service-related properties are additively copied into the new service object. The new service's name is "hostname-service" - where "service" is the -dictionary key in the services dictionary. +array key in the services array. The priority for service properties is (from highest to lowest): @@ -821,6 +906,9 @@ Configuration Examples Non-networked minimal example ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +NOTE: Icinga 2 ITL provides itl/standalone.conf which loads all required components, as well +as itl/itl.conf includes many object templates already for an easy start with Icinga 2. + ------------------------------------------------------------------------------- local object IcingaApplication "icinga" { @@ -834,7 +922,11 @@ local object Component "delegation" { } -abstract object Service "icinga-service" { +object CheckCommand "ping" { + command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%", +} + +template Service "icinga-service" { methods = { check = "PluginCheck" }, @@ -844,9 +936,8 @@ abstract object Service "icinga-service" { } } -abstract object Service "ping" inherits "icinga-service" { - check_command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%", - +template Service "ping-tmpl" inherits "icinga-service" { + check_command = "ping", macros += { wrta = 50, wpl = 5, @@ -856,13 +947,13 @@ abstract object Service "ping" inherits "icinga-service" { } object Host "localhost" { - services = { "ping" }, + services["ping"] = { templates = "ping-tmpl" }, macros = { address = "127.0.0.1" }, - check_interval = 10 + check_interval = 10m } ------------------------------------------------------------------------------- diff --git a/docs/icinga2-tutorial.adoc b/docs/icinga2-tutorial.adoc index 39f46ced5..17a888637 100644 --- a/docs/icinga2-tutorial.adoc +++ b/docs/icinga2-tutorial.adoc @@ -193,6 +193,8 @@ Setting up the Icinga 1.x Classic UI Icinga 2 can write status.dat and objects.cache files in the format that is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the "command pipe") are also supported. +If you require the icinga.log for history views and/or reporting in Classic UI, this can be +added seperately to the CompatComponent object definition by adding a CompatLog object. In order to enable this feature you will need to load the library 'compat' by adding the following lines to your configuration file: @@ -219,19 +221,30 @@ $ sudo make install classicui-standalone install-webconf-auth $ sudo service apache2 restart ---- -After installing the Classic UI you will need to update the following settings in your cgi.cfg configuration file: +NOTE: A detailed guide on installing Icinga 1.x Classic UI Standalone can be found on the Icinga Wiki +here: https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone + +After installing the Classic UI you will need to update the following settings in your cgi.cfg +configuration file at the bottom (section "STANDALONE (ICINGA 2) OPTIONS"): |=== -|Configuration Setting | Value -|object_cache_file | /var/cache/icinga2/objects.cache -|status_file | /var/cache/icinga2/status.dat -|command_file | /var/run/icinga2/icinga2.cmd -|log_file | /var/log/icinga2/compat/icinga.log +|Configuration Setting | Value +|object_cache_file | /var/cache/icinga2/objects.cache +|status_file | /var/cache/icinga2/status.dat +|resource_file | - +|command_file | /var/run/icinga2/icinga2.cmd +|check_external_commands | 1 +|interval_length | 60 +|status_update_interval | 10 +|log_file | /var/log/icinga2/compat/icinga.log +|log_rotation_method | h +|log_archive_path | /var/log/icinga2/compat/archives +|date_format | us |=== -Depending on how you installed Icinga 2 some of those paths might be different. +Depending on how you installed Icinga 2 some of those paths and options might be different. -Verify that your Icinga 1.x Classic UI work by browsing to your Classic UI installation URL e.g. http://localhost/icinga +Verify that your Icinga 1.x Classic UI works by browsing to your Classic UI installation URL e.g. http://localhost/icinga Some More Templates ------------------- @@ -289,7 +302,8 @@ object CheckCommand "my-ping" inherits "plugin-check-command" { ---- We have replaced our hard-coded timeout values with macros and we're providing default -values for these same macros right in the template definition. +values for these same macros right in the template definition. The object inherits the +basic check command attributes from the ITL provided template 'plugin-check-command'. In order to oderride some of these macros for a specific host we need to update our 'icinga.org' host definition like this: @@ -319,7 +333,8 @@ object Host "icinga.org" { The '+=' operator allows us to selectively add new key-value pairs to an existing dictionary. If we were to use the '=' operator instead we would have to provide -values for all the macros that are used in the 'my-ping' template. +values for all the macros that are used in the 'my-ping' template overriding all +values there. Icinga Template Library ----------------------- @@ -519,6 +534,9 @@ In addition to defining notifications for individual services it is also possibl to assign notification templates to all services of a host. You can find more information about how to do that in the documentation. +NOTE: Escalations in Icinga 2 are just a notification, only added a defined begin and end time. +Check the documentation for details. + Time Periods ------------ @@ -574,14 +592,124 @@ The 'notification_period' attribute is also valid in 'User' and 'Notification' o Dependencies ------------ -TODO +If you are familiar with Icinga 1.x Host/Service Dependencies and the Parent-Child logic on hosts, +you might want to look at the conversion script converting your existing configuration. There are +no extry dependency objects anymore, and no extra parent attribute either. + +Using Icinga 2, we can directly define a dependency in the current host or service object to any other +host or service object. If we want other objects to inherit those dependency attributes, we may just +define them in a template. + +Looking at the following example, we've added a cluster host with the service 'ping' on which we want +to depend on when defining checks for our client host. + +---- +template Service "my-cluster-ping" { + check_command = "my-ping", +} + +object Host "my-cluster" { + ... + services["ping"] = { + templates = [ "my-cluster-ping" ], + } + ... +} +---- + +We can now define a service dependency as new service template (or directly on the service definition): + +---- +template Service "my-cluster-dependency" { + servicedependencies = [ + { host = "my-cluster", service = "ping" }, + ], +} +---- + +Now use that template for the 'ping' service we've defined previously and assign the servicedependencies +to that service. + +---- + ... + services["ping"] = { + templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ], + }, + ... +---- + + Performance Data ---------------- -TODO +Due to the reason that there is no host check in Icinga 2, the PerfdataWriter object will only write service +performance data files. Loading the object will allow you to set the perfdata_path, format_template and rotation_interval. +The format template is similar to existing Icinga 1.x configuration for PNP or inGraph using macro formatted strings. -Compat Log Files ----------------- +Details on the common Icinga 1.x macros can be found on http://docs.icinga.org/latest/en/macrolist.html + +NOTE: You can define multiple PerfdataWriter objects with different configuration settings, i.e. one for PNP, one for inGraph +or your preferred graphite collector. + +Let's create a new PNP PerfdataWriter object: + +---- +local object PerfdataWriter "pnp" { + perfdata_path = "/var/lib/icinga2/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, +} +---- + +Now tell your NPCD daemon where to look for new performance data in the PNP provided npcd.cfg + +---- +perfdata_spool_dir = /var/lib/icinga2/ +---- + + +Custom Attributes +----------------- + +In Icinga 1.x there were so-called "Custom Variables" available prefixed with an underscore, as well +as plenty of other attributes such as action_url, notes_url, icon_image, etc. To overcome the limitations +of hardcoded custom attributes, Icinga 2 ships with the 'custom' attribute as dictionary. + +Having PNP for graphing installed, we should add a reference url to Icinga Classic UI by using the classic +method of defining an action_url. + +---- +template Service "my-pnp-svc" { + custom = { + action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$", + } +} +---- + +And add that template again to our service definition: + +---- + ... + services["ping"] = { + templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], + }, + ... +---- + +While at it, our configuration tool will add its ldap dn and a snmp community to the service too, using += for +additive attributes: + +---- + ... + services["ping"] = { + templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], + custom += { + DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org", + SNMPCOMMUNITY = "public" + } + }, + ... + +---- -TODO