Update documentation

README.md

@@ -12,155 +12,12 @@ Icingabeat is an [Elastic Beat](https://www.elastic.co/products/beats) that
 fetches data from the Icinga 2 API and sends it either directly to Elasticsearch
 or Logstash.
 
-![icingabeat-checkresult-dashboard](screenshots/icingabeat-checkresults-dashboard.png)
+![icingabeat-checkresult-dashboard](screenshots/checkresults.png)
 
-## Eventstream
+## Documentation
-
+Please read the documentation on
-Receive an eventstream from the Icinga 2 API. This stream includes events such
+[icinga.com/docs/icingabeat/latest](https://www.icinga.com/docs/icingabeat/latest/)
-as checkresults, notifications, downtimes, acknowledgemts and many other types.
+for more information
-See below for details. There is no polling involved when receiving an
-eventstream.
-
-Example use cases:
-* Correlate monitoring data with logging information
-* Monitor notifications sent by Icinga 2
-
-## Statuspoller
-
-The Icinga 2 API exports a lot of information about the state of the Icinga
-daemon. Icingabeat can poll these information periodically.
-
-Example use cases:
-* Visualize metrics of the Icinga 2 daemon
-* Get insights how each enable Icinga 2 feature performs
-* Information about zones and endpoints
-
-
-### Installation
-Download and install your package from the
-[latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
-
-### Configuration
-Configuration of Icingabeat is split into 3 sections: General, Evenstream and
-Statuspoller. On Linux configuration files are located at `/etc/icingabeat`
-
-#### General
-Settings in this section apply to both modes.
-
-##### `host`
-Hostname of Icinga 2 API. This can be either an IP address or domain.
-Defaults to `localhost`
-
-##### `port`
-Defaults to `5665`
-
-##### `user`
-Username to be used for the API connection. You need to create this user in your Icinga 2 configuration. Make sure that it has sufficient permissions to read the
-data you want to collect.
-
-Here is an example of an API user in your Icinga 2 configuration:
-
-```c++
-object ApiUser "icinga" {
-  password = "icinga"
-  permissions = ["events/*", "status/query"]
-}
-```
-
-
-Learn more about the `ApiUser` and its permissions in the
-[Icinga 2 docs](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-permissions).
-
-##### `password`
-Defaults to `icinga`
-
-##### `skip_ssl_verify`
-Skip verification of SSL certificates. Defaults to `false`
-
-#### Eventstream
-Settings in this section apply to the eventstream mode. To disable the
-eventstream completely, comment out the section.
-
-##### `types`
-You can select which particular Icinga 2 events you want to receive and store.
-The following types are available, you must set at least one:
-
-* `CheckResult`
-* `StateChange`
-* `Notification`
-* `AcknowledgementSet`
-* `AcknowledgementCleared`
-* `CommentAdded`
-* `CommentRemoved`
-* `DowntimeAdded`
-* `DowntimeRemoved`
-* `DowntimeStarted`
-* `DowntimeTriggered`
-
-To set multiple types, do the following:
-
-```yaml
-  types:
-    - CheckResult
-    - StateChange
-    - Notification
-    - AcknowledgementSet
-    - AcknowledgementCleared
-```
-
-##### `filter`
-In addition to selecting the types of events, you can filter them by
-attributes using the prefix `event.`. By default no filter is set.
-
-###### Examples
-
-Only check results with the exit code 2:
-```yaml
-  filter: "event.check_result.exit_status==2"
-```
-
-Only check results of services that match `mysql*`:
-```yaml
-  filter: 'match("mysql*", event.service)'
-```
-
-##### `retry_interval`
-On a connection loss Icingabeat will try to reconnect to the API periodically.
-This setting defines the interval for connection retries. Defaults to `10s`
-
-#### Statuspoller
-Settings of this section apply to the statuspoller mode.
-
-##### `interval`
-Interval at which the status API is called. Set to `0` to disable polling.
-Defaults to `60s`
-
-### Run
-
-On Linux systems, use one of the following commands to start Icingabeat:
-
-* `service icingabeat start` or
-* `systemctl icingabeat start` or
-* `/etc/init.d/icingabeat start`
-
-## Dashboards
-We have dashboards prepared that you can use when getting started with
-Icingabeat. They are meant to give you some inspiration before you start
-exploring the data by yourself. Download the dashboards from the
-[latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
-
-**Note:** The dashboards require Kibana >= 5.2.0
-
-The tool to import dashboards with is already included in the Icingabeat package.
-
-```
-unzip icingabeat-dashboards-5.6.6.zip -d /tmp
-/usr/share/icingabeat/scripts/import_dashboards -dir /tmp/icingabeat-dashboards-5.6.6 -es http://127.0.0.1:9200
-```
-
-## Fields
-Icingabeat exports a bunch of fields. Have a look to the
-[fields.asciidoc](docs/fields.asciidoc) for details.
 
 ## Development
 
@@ -168,7 +25,7 @@ Icingabeat exports a bunch of fields. Have a look to the
 
 #### Requirements
 
-* [Golang](https://golang.org/dl/) 1.7
+* [Golang](https://golang.org/dl/) 1.9
 
 #### Clone
 

data/meta.json

@@ -0,0 +1 @@
+{"uuid":"0409fabd-956a-4000-9090-22c9c0b438af"}

docs/01-about.md

@@ -0,0 +1,38 @@
+# Icingabeat
+
+Icingabeat is an [Elastic Beat](https://www.elastic.co/products/beats) that
+fetches data from the Icinga 2 API and sends it either directly to Elasticsearch
+or Logstash.
+
+> The Beats are lightweight data shippers, written in Go, that you install on
+> your servers to capture all sorts of operational data (think of logs,
+> metrics, or network packet data). The Beats send the operational data to
+> Elasticsearch, either directly or via Logstash, so it can be visualized with
+> Kibana.
+
+![CheckResults](../screenshots/checkresults.png) | ![Status](../screenshots/status.png)
+-------------------------------------------------|-------------------------------------
+
+## Eventstream
+
+Icingabeat listens to an eventstream published by the Icinga 2 API. This stream
+includes detailed information about events, such as checkresults, notifications,
+downtimes, acknowledgemts and many other event types. There is no polling
+involved in this mode. The configuration section describes how to limit the
+amount of data you receive by setting types and filters.
+
+Example use cases:
+* Correlate monitoring data with logging information
+* Retrace notifications sent by Icinga 2
+* Find bottlenecks in execution time and latency of service checks
+
+## Statuspoller
+
+The Icinga 2 API exports a lot of information about the state of the Icinga 2
+daemon. Icingabeat can poll these information periodically.
+
+Example use cases:
+* Visualize metrics of the Icinga 2 daemon
+* Get insights how each Icinga 2 feature performs
+* Information about zones and endpoints
+* Compare Icinga servers with each other

docs/02-installation.md

@@ -0,0 +1,101 @@
+# Installation
+
+## Packages
+Packages are available on [packages.icinga.com](https://packages.icinga.com).
+
+Depending on your distribution and version you need to run one of the following
+commands:
+
+#### Debian
+
+``` shell
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+echo 'deb http://packages.icinga.com/debian icinga-stretch main' > etc/apt/sources.list.d/icinga.list
+```
+
+``` shell
+apt-get update
+apt-get install icingabeat
+```
+
+#### Ubuntu
+
+``` shell
+wget -O - https://packages.icinga.com/icinga.key | apt-key add -
+echo 'deb http://packages.icinga.com/ubuntu icinga-xenial main' > etc/apt/sources.list.d/icinga.list
+```
+
+``` shell
+apt-get update
+apt-get install icingabeat
+```
+
+#### CentOS
+
+``` shell
+yum install epel-release
+rpm --import https://packages.icinga.com/icinga.key
+yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
+```
+
+``` shell
+yum install icingabeat
+```
+
+#### RHEL
+
+``` shell
+yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
+rpm --import https://packages.icinga.com/icinga.key
+yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
+```
+
+``` shell
+yum install icingabeat
+```
+
+#### SLES
+
+``` shell
+rpm --import https://packages.icinga.com/icinga.key
+zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
+zypper ref
+```
+
+``` shell
+zypper install icingabeat
+```
+
+### Run
+Make sure you have configured Icingabeat properly before starting it. Use one
+of the following commands to start Icingabeat:
+
+* `service icingabeat start` or
+* `systemctl icingabeat start` or
+* `/etc/init.d/icingabeat start`
+
+## Dashboards
+We have dashboards prepared that you can use when getting started with
+Icingabeat. They are meant to give you some inspiration before you start
+exploring the data by yourself.
+
+**Note:** The dashboards require Kibana >= 6.0
+
+Import dashboards and index pattern:
+``` shell
+./icingabeat setup
+```
+
+Set Kibana host, user and password if necessary:
+``` shell
+./metricbeat setup -E setup.kibana.host=127.0.0.1:5601 -E setup.kibana.username=elastic -E setup.kibana.password=secret
+```
+
+## Manual Installation
+
+Download and install a package or tarball from the
+[latest release](https://github.com/Icinga/icingabeat/releases/latest) page.
+
+## Development
+Please follow [README.md](https://github.com/icinga/icingabeat/README.md) for
+instructions about how to build icingabeat.

docs/03-configuration.md

@@ -0,0 +1,109 @@
+# Configuration
+Configuration of Icingabeat is split into 3 sections: Connection, Evenstream and
+Statuspoller. On Linux configuration files are located at `/etc/icingabeat`
+
+## Connection
+Settings in this section apply to both modes.
+
+### `host`
+Hostname of Icinga 2 API. This can be either an IP address or domain.
+Defaults to `localhost`
+
+### `port`
+Defaults to `5665`
+
+### `user`
+Username to be used for the API connection. You need to create this user in your Icinga 2 configuration. Make sure that it has sufficient permissions to read the
+data you want to collect.
+
+Here is an example of an API user in your Icinga 2 configuration:
+
+``` c++
+object ApiUser "icinga" {
+  password = "icinga"
+  permissions = ["events/*", "status/query"]
+}
+```
+
+Learn more about the `ApiUser` and its permissions in the
+[Icinga 2 docs](https://docs.icinga.com/icinga2/latest/doc/module/icinga2/chapter/icinga2-api#icinga2-api-permissions).
+
+### `password`
+Defaults to `icinga`
+
+
+### `ssl.verify`
+Configure SSL verification. If `false` is configured, all server hosts and
+certificates will be accepted. In this mode, SSL based connections are
+susceptible to man-in-the-middle attacks. Use only for testing. Default is
+`true`.
+
+### `ssl.certificate_authorities`
+List of root certificates for HTTPS server verifications
+
+Example:
+```
+ssl.certificate_authorities: ["/etc/pki/root/ca.pem"]
+```
+
+## Eventstream
+Settings in this section apply to the eventstream mode. To disable the
+eventstream completely, comment out the section.
+
+### `eventstream.types`
+You can select which particular Icinga 2 events you want to receive and store.
+The following types are available, you must set at least one:
+
+* `CheckResult`
+* `StateChange`
+* `Notification`
+* `AcknowledgementSet`
+* `AcknowledgementCleared`
+* `CommentAdded`
+* `CommentRemoved`
+* `DowntimeAdded`
+* `DowntimeRemoved`
+* `DowntimeStarted`
+* `DowntimeTriggered`
+
+To set multiple types, do the following:
+
+```yaml
+  eventstream.types:
+    - CheckResult
+    - StateChange
+    - Notification
+    - AcknowledgementSet
+    - AcknowledgementCleared
+```
+
+### `eventstream.filter`
+In addition to selecting the types of events, you can filter them by
+attributes using the prefix `event.`. By default no filter is set.
+
+###### Examples
+
+Only check results with the exit code 2:
+```yaml
+  eventstream.filter: "event.check_result.exit_status==2"
+```
+
+Only check results of services that match `mysql*`:
+```yaml
+  eventstream.filter: 'match("mysql*", event.service)'
+```
+
+### `eventstream.retry_interval`
+On a connection loss Icingabeat will try to reconnect to the API periodically.
+This setting defines the interval for connection retries. Defaults to `10s`
+
+## Statuspoller
+Settings of this section apply to the statuspoller mode.
+
+### `statuspoller.interval`
+Interval at which the status API is called. Set to `0` to disable polling.
+Defaults to `60s`
+
+## Fields
+Icingabeat exports a bunch of fields. Have a look to the
+[fields.asciidoc](https://github.com/Icinga/icingabeat/blob/master/docs/fields.asciidoc) for details.