From: Gunnar Beutner Date: Thu, 26 Sep 2013 12:01:29 +0000 (+0200) Subject: Update documentation. X-Git-Tag: v0.0.3~391 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=6fa861b7313dfa1254ea7bce54f83fec18c32030;p=icinga2 Update documentation. --- diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..dcaf71693 --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +index.html diff --git a/doc/1-about.md b/doc/1-about.md index 591b6704c..37e8d71f1 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -4,8 +4,19 @@ ### What is Icinga? +Icinga 2 is a network monitoring application. + ### Licensing +Icinga 2 and the Icinga 2 documentation are licensed under the terms of the GNU +General Public License Version 2, you will find a copy of this license in the +LICENSE file included in the package. + ### Support -## What's New in Version 0.0.3 \ No newline at end of file +Support for Icinga 2 is available in a number of ways. Please have a look at +the support overview page at https://www.icinga.org/support/. + +## What's New in Version 0.0.3 + +* Lots of things. \ No newline at end of file diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index 9e35bb544..83af1feca 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -1,3 +1,218 @@ # Getting Started ## Installation + +This tutorial is a step-by-step introduction to installing Icinga 2 and +the standalone version of the Icinga 1.x classic web interface. It assumes +that you are familiar with the system you're installing Icinga 2 on. + +### Installing Icinga 2 + +In order to get started with Icinga 2 you will have to install it. The +preferred way of doing this is to use the official Debian or RPM +package repositories depending on which Linux distribution you are +running. + + Distribution |Repository URL + ------------------------|--------------------------- + Debian |http://packages.icinga.org/debian/ + RHEL/CentOS 5 |http://packages.icinga.org/epel/5/release/ + RHEL/CentOS 6 |http://packages.icinga.org/epel/6/release/ + +Packages for distributions other than the ones listed above may also be +available. Please check http://packages.icinga.org/ to see if packages +are available for your favorite distribution. + +In case you're running a distribution for which Icinga 2 packages are +not yet available you will have to check out the Icinga 2 Git repository +from git://git.icinga.org/icinga2 and read the *INSTALL* file. + +By default Icinga 2 uses the following files and directories: + + Path |Description + ------------------------------------|------------------------------------ + /etc/icinga2 |Contains Icinga 2 configuration files. + /etc/init.d/icinga2 |The Icinga 2 init script. + /usr/share/doc/icinga2 |Documentation files that come with Icinga 2. + /usr/share/icinga2/itl |The Icinga Template Library. + /var/run/icinga2 |Command pipe and PID file. + /var/cache/icinga2 |Performance data files and status.dat/objects.cache. + /var/lib/icinga2 |The Icinga 2 state file. + +An example configuration file is installed for you in /etc/icinga2/icinga2.conf. + +Here's a brief description of the concepts the example configuration file +introduces: + + /** + * Icinga 2 configuration file + * - this is where you define settings for the Icinga application including + * which hosts/services to check. + * + * The docs/icinga2-config.adoc file in the source tarball has a detailed + * description of what configuration options are available. + */ + +Icinga 2 supports C- and C++-style comments. + + include + include + +The *include* directive can be used to include other files. The *itl/itl.conf* +file defines a number of useful templates and constants you can use to +configure your services. + + /** + * Global macros + */ + set IcingaMacros = { + plugindir = "/usr/local/icinga/libexec" + } + +Icinga 2 lets you define free-form macros. The IcingaMacros variable can be used +to define global macros which are available in all command definitions. + + /** + * The compat library periodically updates the status.dat and objects.cache + * files. These are used by the Icinga 1.x CGIs to display the state of + * hosts and services. CompatLog writeis the Icinga 1.x icinga.log and archives. + */ + library "compat" + +Some of Icinga 2's functionality is available in separate libraries. These +libraries usually implement their own object types that can be used to configure +what you want the library to do. + + object StatusDataWriter "status" { } + object ExternalCommandListener "command" { } + object CompatLogger "compat-log" { } + +Those three object types are provided by the *compat* library. The *StatusDataWriter* + + Type | Description + StatusDataWriter | Is responsible for writing the status.dat and objects.cache files. + ExternalCommandListener | Implements the command pipe which is used by the CGIs to send commands to Icinga 2. + CompatLogger | Writes log files in a format that is compatible with Icinga 1.x. + + /** + * And finally we define some host that should be checked. + */ + object Host "localhost" { + services["ping4"] = { + templates = [ "ping4" ] + }, + + services["ping6"] = { + templates = [ "ping6" ] + }, + + services["http"] = { + templates = [ "http_ip" ] + }, + + services["ssh"] = { + templates = [ "ssh" ] + }, + + services["load"] = { + templates = [ "load" ] + }, + + services["processes"] = { + templates = [ "processes" ] + }, + + services["users"] = { + templates = [ "users" ] + }, + + services["disk"] = { + templates = [ "disk" ] + }, + + macros = { + address = "127.0.0.1", + address6 = "::1", + }, + + check = "ping4", + } + +This defines a host named "localhost" which has a couple of services. Services +may inherit from one or more service templates. + +The templates *ping4*, *ping6*, *http_ip*, *ssh*, *load*, *processes*, *users* +and *disk* are all provided by the Icinga Template Library (short ITL) which +we enabled earlier by including the itl/itl.conf configuration file. + +The *macros* attribute can be used to define macros that are available for all +services which belong to this host. Most of the templates in the Icinga Template +Library require an *address* macro. + +### Installing the Icinga 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. It also supports writing Icinga 1.x +log files which are required for the reporting functionality in the Classic UI. + +These features are implemented as part of the "compat" library and are enabled +by default in the example configuration file. + +You should be able to find the status.dat and objects.cache files in +/var/cache/icinga2. The log files can be found in /var/log/icinga2/compat. +The command pipe can be found in /var/run/icinga2. + +You can install the Icinga 1.x Classic UI in standalone mode using the +following commands: + + $ wget http://downloads.sourceforge.net/project/icinga/icinga/1.9.3/icinga-1.9.3.tar.gz + $ tar xzf icinga-1.9.3.tar.gz ; cd icinga-1.9.3 + $ ./configure --enable-classicui-standalone --prefix=/usr/local/icinga2-classicui + $ make classicui-standalone + $ sudo make install classicui-standalone install-webconf-auth + $ sudo service apache2 restart + +> **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](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 in the "STANDALONE (ICINGA 2) +OPTIONS" section: + + 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 + ------------------------------------ ------------------------------------ + +> **Note** +> +> Depending on how you installed Icinga 2 some of those paths and options +> might be different. + +In order for commands to work you will need to grant the web server +write permissions for the command pipe: + + # chgrp www-data /var/run/icinga2/icinga2.cmd + # chmod 660 /var/run/icinga2/icinga2.cmd + +> **Note** +> +> Change "www-data" to the group the Apache HTTP daemon is running as. + +Verify that your Icinga 1.x Classic UI works by browsing to your Classic +UI installation URL, e.g. +[http://localhost/icinga](http://localhost/icinga) \ No newline at end of file diff --git a/doc/3.1-configuration-syntax.md b/doc/3.1-configuration-syntax.md index 2d0f88ab0..52a8a4f22 100644 --- a/doc/3.1-configuration-syntax.md +++ b/doc/3.1-configuration-syntax.md @@ -146,10 +146,10 @@ Operators --------- In addition to the *=* operator shown above a number of other operators -to manipulate configuration objects are supported. Here’s a list of all +to manipulate configuration objects are supported. Here's a list of all available operators: -### Operator *=* +### Operator = Sets a dictionary element to the specified value. @@ -162,7 +162,7 @@ Example: In this example a has the value 7 after both instructions are executed. -### Operator *+=* +### Operator += Modifies a dictionary or array by adding new elements to it. @@ -177,6 +177,7 @@ In this example a contains both *"hello"* and *"world"*. This currently only works for dictionaries and arrays. Attribute Shortcuts @@ -273,7 +275,7 @@ templates though in general they are. > The final macros dictionary contains all 3 macros and the macro > *color* has the value *"blue"*. -Parent objects are resolved in the order they’re specified using the +Parent objects are resolved in the order they're specified using the *inherits* keyword. Variables @@ -375,6 +377,7 @@ Example: > The *icinga* library is automatically loaded at startup. \ No newline at end of file + +--> diff --git a/doc/3.3-object-types.md b/doc/3.3-object-types.md index 8550065a2..f25794336 100644 --- a/doc/3.3-object-types.md +++ b/doc/3.3-object-types.md @@ -14,9 +14,9 @@ Example: Attributes: + Name |Description ----------------|---------------- severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information". - ----------------|---------------- FileLogger ---------- @@ -32,6 +32,7 @@ Example: 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". @@ -49,6 +50,7 @@ Example: Attributes: + Name |Description ----------------|---------------- severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information". @@ -149,6 +151,7 @@ Example: 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). @@ -180,6 +183,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |**Optional.** A short description of the service group. @@ -194,6 +198,7 @@ Example: Attributes: + Name |Description ----------------|---------------- host |TODO service |TODO @@ -218,6 +223,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |TODO macros |TODO @@ -238,6 +244,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |TODO @@ -252,6 +259,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |TODO methods |TODO @@ -268,6 +276,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |TODO @@ -282,6 +291,7 @@ Example: Attributes: + Name |Description ----------------|---------------- acl |TODO @@ -325,13 +335,14 @@ Example: 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.** An array of host names which this host depends on. These dependencies are used to determine whether the host is unreachable. service_dependencies|**Optional.** An array of service names 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. + 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 @@ -347,6 +358,7 @@ Example: Attributes: + Name |Description ----------------|---------------- display_name |**Optional.** A short description of the host group. @@ -368,6 +380,7 @@ Example 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. @@ -400,11 +413,12 @@ Example: 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". + 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". @@ -432,6 +446,7 @@ Example: 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". @@ -453,6 +468,7 @@ Example: Attributes: + Name |Description ----------------|---------------- status\_path |TODO objects\_path |TODO @@ -468,6 +484,7 @@ Example: Attributes: + Name |Description ----------------|---------------- command\_path |TODO @@ -482,6 +499,7 @@ Example: Attributes: + Name |Description ----------------|---------------- log\_dir |TODO rotation\_method|TODO @@ -497,6 +515,7 @@ Example: Attributes: + Name |Description ----------------|---------------- spool\_dir |TODO @@ -533,6 +552,7 @@ Example: Attributes: + Name |Description ----------------|---------------- cert\_path |TODO ca\_path |TODO @@ -557,6 +577,7 @@ Example: 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. diff --git a/doc/jquery.toc.min.js b/doc/jquery.toc.min.js new file mode 100644 index 000000000..53a2c621c --- /dev/null +++ b/doc/jquery.toc.min.js @@ -0,0 +1,8 @@ +/*! + * toc - jQuery Table of Contents Plugin + * v0.1.2 + * http://projects.jga.me/toc/ + * copyright Greg Allen 2013 + * MIT License +*/ +(function(t){t.fn.toc=function(e){var n,i=this,r=t.extend({},jQuery.fn.toc.defaults,e),o=t(r.container),a=t(r.selectors,o),l=[],h=r.prefix+"-active",s=function(e){if(r.smoothScrolling){e.preventDefault();var n=t(e.target).attr("href"),o=t(n);t("body,html").animate({scrollTop:o.offset().top},400,"swing",function(){location.hash=n})}t("li",i).removeClass(h),t(e.target).parent().addClass(h)},c=function(){n&&clearTimeout(n),n=setTimeout(function(){for(var e,n=t(window).scrollTop(),o=0,a=l.length;a>o;o++)if(l[o]>=n){t("li",i).removeClass(h),e=t("li:eq("+(o-1)+")",i).addClass(h),r.onHighlight(e);break}},50)};return r.highlightOnScroll&&(t(window).bind("scroll",c),c()),this.each(function(){var e=t(this),n=t("