icinga2 0.9.0.1 → 0.9.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 72d12c2bfb82c51e11f6b302d524212f24923994
-  data.tar.gz: 0996b07dfcbc324711f2c6b1d036476c4dbe9551
+  metadata.gz: db0fe25ebd8e946d7c604572bf519a42d07a9d82
+  data.tar.gz: a903a6ec90465f9c77eaa435fd87fce351aa6993
 SHA512:
-  metadata.gz: d43124defda6f6b95bc37f98cdf101c08cf28d219f746fbaeccbe896a89e867de7eeb11392c01b0f9b1a56d9a78666f33e9b2c378e37071974d78c8f4e971077
-  data.tar.gz: fcb769550f203d42d9511f6567a408dc7e05f11a48b50f72548ed91430a17cfdaa76320b6f31e0591ff5f88b018e56fc251436debfcb2a490711854eed4b66a4
+  metadata.gz: bae9836345523dcf3756967d14d54d19bd8b0b266f0883e01397bdaca52b05671e09266bbbbc3d384c903a6bc33f9177bc7ad76d8489ac9c88b44a7de75ed6ed
+  data.tar.gz: f956ffb022e2fa3857646d8e1b1a2f366276c2945a478e4d5faac64b6747d86c653ede0202e358635a530405a55226659c58f10f28065cd9ef6efcafdaf82d68

data/README.md

@@ -1,12 +1,11 @@
 # ruby-icinga2
 
-Ruby Class for the Icinga2 API
+An enhanced ruby gem to communicate with Icinga2 API
 
 [![Gem Version](https://badge.fury.io/rb/icinga2.svg)](https://badge.fury.io/rb/icinga2)
 
-[![Build Status](https://travis-ci.org/bodsch/ruby-icinga2.svg?branch=v0.8.1.2)][travis]
-[![Build Status](https://travis-ci.org/bodsch/ruby-icinga2.svg?branch=master)][travis]
-[![Gem Downloads](http://ruby-gem-downloads-badge.herokuapp.com/icinga2?0.8.1.2)][gem-downloads]
+[![Build Status](https://travis-ci.org/bodsch/ruby-icinga2.svg)][travis]
+[![Gem Downloads](http://ruby-gem-downloads-badge.herokuapp.com/icinga2)][gem-downloads]
 [![total Downloads](http://ruby-gem-downloads-badge.herokuapp.com/icinga2?type=total&metric=true&label=downloads-total)][gem-downloads]
 [![Dependency Status](https://gemnasium.com/badges/github.com/bodsch/ruby-icinga2.svg)][gemnasium]
 
@@ -17,16 +16,17 @@ Ruby Class for the Icinga2 API
 
 ## Requirements
 
-* ruby version  => 2.1
+* ruby version  => 2.0
 * rest-client ~> 2.0
-* openssl ~> 2.0 (only with ruby 2.3)
 * json  ~> 2.1
+* openssl ~> 2.0 (only with ruby >= 2.3)
+* ruby_dig (only with ruby < 2.3)
 
-## install
+## Install
 
     gem install icinga2
 
-## usage
+## Usage
 
 create an instance
 
@@ -37,14 +37,53 @@ create an instance
           :port => icingaApiPort,
           :user => icingaApiUser,
           :pass => icingaApiPass
-        },
-        :cluster   => icingaCluster,
-        :satellite => icingaSatellite,
+        }
       }
     }
 
     @icinga = Icinga::Client.new( config )
 
+### Use the examples
+
+You can use the [Icinga Vagrant-Box](https://github.com/Icinga/icinga-vagrant) from the Icinga Team or
+my own [Docker Container](https://hub.docker.com/r/bodsch/docker-icinga2/) as Datasource.
+
+**Remember** Change the exported Environment Variables to your choosed Datasource!
+
+you can find many examples under the directory `examples`:
+
+    #$ export ICINGA_HOST=localhost ; export ICINGA_API_USER=root ; export ICINGA_API_PASSWORD=icinga
+    #$ ruby examples/informations.rb
+    #$ ruby examples/statistics.rb
+    #$ ruby examples/users.rb
+
+and so on.
+
+### Test via CLI
+
+    #$ irb
+    2.3.0 :001 > require 'icinga2'
+     => true
+    2.3.0 :002 > config = { :icinga => { :host => 'localhost', :api => { :user => 'root', :pass => 'icinga' } } }
+     => {:icinga=>{:host=>"localhost", :api=>{:user=>"root", :pass=>"icinga"}}}
+    2.3.0 :003 > i = Icinga2::Client.new( config )
+
+
+## Create a own gem file
+
+    #$ gem build icinga2.gemspec
+    Successfully built RubyGem
+    Name: icinga2
+    Version: 0.9.0
+    File: icinga2-0.9.0.gem
+
+## Install local gem
+
+    #$ gem install icinga2
+    Successfully installed icinga2-0.9.0
+    1 gem installed
+
+
 ## Status
 
 supports the following API Calls:
@@ -64,10 +103,10 @@ supports the following API Calls:
   - [Hosts](doc/hosts.md)
     * [add host](doc/hosts.md#add-host)
     * [delete host](doc/hosts.md#delete-host)
+    * [modify host](doc/hosts.md#modify-host)
     * [list hosts](doc/hosts.md#list-hosts)
     * [check if host exists](doc/hosts.md#host-exists)
     * [list host objects](doc/hosts.md#list-host-objects)
-    * [adjusted hosts state](doc/hosts.md#hosts-adjusted)
     * [count of hosts with problems](doc/hosts.md#count-hosts-with-problems)
     * [list of hosts with problems](doc/hosts.md#list-hosts-with-problems)
     * [count of all hosts](doc/hosts.md#count-all-hosts)
@@ -87,7 +126,6 @@ supports the following API Calls:
     * [list services](doc/services.md#list-services)
     * [check if service exists](doc/services.md#service-exists)
     * [list service objects](doc/services.md#list-service-objects)
-    * [adjusted service state](doc/services.md#services-adjusted)
     * [count services with problems](doc/services.md#count-services-with-problems)
     * [list of services with problems](doc/services.md#list-services-with-problems)
     * [count of all services](doc/services.md#count-all-services)
@@ -125,34 +163,6 @@ supports the following API Calls:
     * [queue statistics from the api](doc/statistics.md#stats-work-queue)
 
 
-## create a own gem File
-
-    #$ gem build icinga2.gemspec
-    Successfully built RubyGem
-    Name: icinga2
-    Version: 0.6.0
-    File: icinga2-0.6.0.gem
-
-## install gem
-
-    #$ gem install icinga2
-    Successfully installed icinga2-0.6.0
-    1 gem installed
-
-## test via CLI
-
-    #$ irb
-    2.3.0 :001 > require 'icinga2'
-     => true
-    2.3.0 :002 > config = { :icinga => { :host => 'localhost', :api => { :user => 'root', :pass => 'icinga' } } }
-     => {:icinga=>{:host=>"localhost", :api=>{:user=>"root", :pass=>"icinga"}}}
-    2.3.0 :003 > i = Icinga2::Client.new( config )
-
-## test via example
-    #$ export ICINGA_HOST=localhost ; export ICINGA_API_USER=root ; export ICINGA_API_PASSWORD=icinga
-    #$ ruby examples/test.rb
-
-
 
 ## Contributing
 
@@ -161,7 +171,3 @@ supports the following API Calls:
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
-
-
-
-

data/doc/hosts.md

@@ -5,11 +5,21 @@
 
 ### Example
     param = {
-      host: 'foo',
-      fqdn: 'foo.bar.com',
+      name: 'foo',
+      address: 'foo.bar.com',
       display_name: 'test node',
       max_check_attempts: 5,
-      notes: 'test node'
+      notes: 'test node',
+      vars: {
+        description: 'host foo',
+        os: 'Linux',
+        partitions: {
+          '/' => {
+            crit: '95%',
+            warn: '90%'
+          }
+        }
+      }
     }
     @icinga.add_host(param)
 
@@ -18,7 +28,52 @@
     delete_host( params )
 
 ### Example
-    @icinga.delete_host(host: 'foo')
+    @icinga.delete_host(name: 'foo')
+
+
+## <a name="modify-host"></a>modify a host
+    modify-host( params )
+
+### Example
+
+
+    param = {
+      name: 'foo',
+      address: 'foo.bar.com',
+      display_name: 'Host for an example Problem',
+      max_check_attempts: 10,
+    }
+
+or
+
+    param = {
+      name: 'foo',
+      address: 'foo.bar.com',
+      notes: 'an demonstration object',
+      vars: {
+        description: 'schould be delete ASAP',
+        os: 'Linux',
+        partitions: {
+          '/' => {
+            crit: '98%',
+            warn: '95%'
+          }
+        }
+      },
+      merge_vars: true
+    }
+
+or
+
+    param = {
+      name: 'foo',
+      address: 'foo.bar.com',
+      vars: {
+        description: 'removed all other custom vars',
+      }
+    }
+
+    @icinga.modify-host( name: 'foo')
 
 
 ## <a name="list-hosts"></a>list hosts
@@ -27,7 +82,7 @@
     hosts( params )
 
 #### Example
-    @icinga.host(host: 'icinga2')
+    @icinga.host(name: 'icinga2')
 
 ### list all hosts
     hosts
@@ -50,19 +105,6 @@
     @icinga.host_objects(attrs: ['name', 'state'])
 
 
-## <a name="hosts-adjusted"></a>adjusted hosts state
-    hosts_adjusted
-
-### Example
-    @icinga.cib_data
-    @icinga.host_objects
-    warning, critical, unknown = @icinga.hosts_adjusted.values
-
-or
-    h = @icinga.hosts_adjusted
-    down = h.dig(:down_adjusted)
-
-
 ## <a name="count-hosts-with-problems"></a>count of hosts with problems
     count_hosts_with_problems
 
@@ -82,7 +124,6 @@ or
     hosts_all
 
 ### Example
-    @icinga.host_objects
     @icinga.hosts_all
 
 
@@ -90,10 +131,10 @@ or
     host_problems
 
 ### Example
-    @icinga.host_objects
-    all, down, critical, unknown = @icinga.host_problems.values
+    all, down, critical, unknown, handled, adjusted = @icinga.host_problems.values
 
 or
+
     p = @icinga.host_problems
     down = h.dig(:down)
 

data/doc/services.md

@@ -1,22 +1,40 @@
 # Icinga2 - Services
 
 
-## <a name="add-service"></a>add services
-    add_services( params )
+## <a name="add-service"></a>*add_services( params )*
 
-### Example
-    services = {
-      vars: {
-        display_name: 'Tomcat - Heap Memory',
-        check_command: 'tomcat-heap-memory'
-      }
-    }
+Add a Service to Icinga2
+
+`params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example           | Description
+| :--------------------  | :-----: | :-----            | :-----------
+| `host_name`            | String  | `foo`             | existing Host for these Service
+| `name`                 | String  | `ping4`           | Service Name they will be create
+| `templates`            | Array   | `['own-service']` | (optional) a Array of templates (default: `['generic-service']`)
+| `vars`                 | Hash    | (see below)       | Hash with custom options
+
+Under the `vars` Hash is the structure very strict.
+They hold only a `attrs` Hash with all others variable.
 
-    @icinga.add_services( host: 'icinga2', service_name: 'ping4', vars: services )
+**Importand** The the `attrs` Hash has mandatory fields!
+
+| Parameter              | Type    | Example           | Description
+| :--------------------  | :-----: | :------------     | :-----------
+| `check_command`        | String  | `ping4`           | The Check Command to execute (**Importand** This Check-Comand must be exists! Otherwise an error will occur)
+| `check_interval`       | Integer | `10`              | The check Interval
+| `retry_interval`       | Integer | `30`              | The retry Interval
+| `vars`                 | Hash    | (see below)       | optional config params for the `check_command`
+
+For more custom fields, add an `vars` Hash with the config parameters of the `check_command` (see below in the examples)
+
+The result are an `Hash`
+
+### Example
 
     @icinga.add_services(
-      host: 'icinga2',
-      service_name: 'ping4',
+      host_name: 'foo',
+      name: 'ping4',
       vars: {
         attrs: {
           check_command: 'ping4',
@@ -26,14 +44,109 @@
       }
     )
 
+or
+
+    @icinga.add_service(
+      host_name: 'foo',
+      name: 'http',
+      vars: {
+        attrs: {
+          check_command: 'http',
+          check_interval: 10,
+          retry_interval: 30,
+          vars: {
+            http_address: '127.0.0.1',
+            http_url: '/access/index',
+            http_port: 80
+          }
+        }
+      }
+    )
+
 
-## <a name="list-services"></a>list services
 
-### list named service
-    services( params )
+## <a name="delete-service"></a>*delete_service( params )*
+
+Delete an Service From Icinga2
+
+`params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example           | Description
+| :--------------------  | :-----: | :-----            | :-----------
+| `host`                 | String  | `foo`             | existing Host for these Service
+| `name`                 | String  | `ping4`           | Service Name they will be deleted
+| `cascade`              | Bool    | `true`            | delete service also when other objects depend on it (default: `false`)
+
+
+The result are an `Hash`
+
+#### Example
+
+    @icinga.delete_service(host_name: 'foo', name: 'ping4')
+
+or
+
+    @icinga.delete_service(host_name: 'foo', name: 'new_ping4', cascade: true)
+
+
+## <a name="modify-service"></a>*modify_service( params )*
+
+Modify an Service.
+
+`params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example           | Description
+| :--------------------  | :-----: | :-----            | :-----------
+| `name`         | String  | `ping4`           | Service Name they will be deleted
+| `templates`            | Array   | `['own-service']` | (optional) a Array of templates (default: `['generic-service']`)
+| `vars`                 | Hash    | (see below)       | Hash with custom options
+
+Under the `vars` Hash is the structure very strict.
+They hold only a `attrs` Hash with all others variable. (similar to `add_service`)
+
+For more custom fields, add an `vars` Hash with the config parameters of the `check_command` (see below in the examples)
+
+The result are an `Hash`
+
+#### Example
+
+    @icinga.modify_service(
+      name: 'http2',
+      vars: {
+        attrs: {
+          check_interval: 60,
+          retry_interval: 10,
+          vars: {
+            http_url: '/access/login'     ,
+            http_address: '10.41.80.63'
+          }
+        }
+      }
+    )
+
+
+## <a name="unhandled-services"></a>*unhandled_services*
+
+return all unhandled services
+
+The result are an `Hash`
 
 #### Example
-    @icinga.services( host: 'icinga2', service: 'ping4' )
+    @icinga.unhandled_services
+
+
+## <a name="list-services"></a>*services* or *services( params )*
+
+returns all or a named service
+
+the optional `params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `host`                 | String  | `foo`   | Hostname
+| `service`              | String  | `ping4` | service to list
+
+The result are an `Hash`
 
 ### list all services
     services
@@ -42,96 +155,144 @@
     @icinga.services
 
 
-## <a name="delete-service"></a>delete
-    delete_service( params )
+### list named service
+    services( params )
 
 #### Example
-    @icinga.delete_service(host: 'foo', service_name: 'ping4')
+    @icinga.services( host_name: 'icinga2', service: 'ping4' )
 
-    @icinga.delete_service(host: 'foo', service_name: 'new_ping4', cascade: true)
 
+## <a name="service-exists"></a>*exists_service?( params )*
 
-## <a name="unhandled-services"></a>list unhandled_services
-    unhandled_services
+check if the service exists
 
-#### Example
-    @icinga.unhandled_services
+the optional `params` is an `Hash` with following Parameters:
 
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `host`                 | String  | `foo`   | Hostname
+| `service`              | String  | `ping4` | servicename
 
-## <a name="service-exists"></a>check if the service exists
-    exists_service?( params )
+The result are an `Hash`
 
 ### Example
-    @icinga.exists_service?(host: 'icinga2', service: 'users' )
+    @icinga.exists_service?( host_name: 'icinga2', service: 'users' )
+
+
+## <a name="list-service-objects"></a>*service_objects( params )*
 
+list service objects
 
-## <a name="list-service-objects"></a>list service objects
-    service_objects( params )
+the optional `params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `attrs`                | Array   | `[]`    | Array of `attrs`
+| `filter`               | Array   | `[]`    | Array of `filter`
+| `joins`                | Array   | `[]`    | Array of `joins`
+
+For more Examples for Quering Objects read the [Icinga2 Documentation](https://www.icinga.com/docs/icinga2/latest/doc/12-icinga2-api/#querying-objects)
+
+ - defaults for `attrs` are `['name', 'state', 'acknowledgement', 'downtime_depth', 'last_check']`
+ - defaults for `filter` are `[]`
+ - defaults for `joins` are `['host.name','host.state','host.acknowledgement','host.downtime_depth','host.last_check']`
+
+The result are an `Array`
 
 ### Example
-    @icinga.service_objects(attrs: ['name', 'state'], joins: ['host.name','host.state'])
+    @icinga.service_objects(
+      attrs: ['name', 'state'],
+      joins: ['host.name','host.state']
+    )
+
 
+## <a name="services-adjusted"></a>*services_adjusted*
 
-## <a name="services-adjusted"></a>adjusted service state
-    services_adjusted
+returns adjusted service state
+
+The result are an `Hash`
 
 ### Example
-    @icinga.cib_data
-    @icinga.service_objects
+
     warning, critical, unknown = @icinga.services_adjusted.values
 
 or
+
     s = @icinga.services_adjusted
     unknown = s.dig(:unknown)
 
 
-## <a name="count-services-with-problems"></a>count services with problems
-    count_services_with_problems
+## <a name="count-services-with-problems"></a>*count_services_with_problems*
+
+count services with problems
+
+The result are an `Integer`
 
 ### Example
     @icinga.count_services_with_problems
 
 
-## <a name="list-services-with-problems"></a>list of services with problems
-    list_services_with_problems( max_items )
+## <a name="list-services-with-problems"></a>*list_services_with_problems( max_items )*
+
+list of services with problems
+
+The result are an `Hash`
 
 ### Example
-    @icinga.list_services_with_problems
-    @icinga.list_services_with_problems(10)
+
     problems, problems_and_severity = @icinga.list_services_with_problems(10).values
 
+or
+
+    l = @icinga.list_services_with_problems(10)
+    problems_and_severity = l.dig(:services_with_problems_and_severity)
+
+
+## <a name="services-all"></a>*services_all*
 
-## <a name="count-all-services"></a>count all services
-    services_all
+count all services
+
+The result are an `Integer`
 
 ### Example
-    @icinga.service_objects
+
     @icinga.services_all
 
 
-## <a name="count-all-services-handled"></a>count all services with handled problems
-    service_problems_handled
+## <a name="service-problems"></a>*service_problems*
+
+returns data with service problems
+
+The result are an `Hash`
 
 ### Example
-    @icinga.cib_data
-    @icinga.service_objects
-    all, critical, warning, unknown = @icinga.service_problems_handled.values
+
+    all, warning, critical, unknown, pending, in_downtime, acknowledged, adjusted_warning, adjusted_critical, adjusted_unknown = @icinga.service_problems.values
 
 or
-    p = @icinga.service_problems_handled
+
+    p = @icinga.service_problems
     warning = p.dig(:warning)
 
 
-## <a name=""></a>(protected) calculate a service severity
-    service_severity( params )
+## <a name=""></a>*service_severity( params )* (protected)
+
+calculate a service severity
+(taken from the IcingaWeb2 Code)
+
+The result are an `Integer`
 
 ### Example
     service_severity( {'attrs' => { 'state' => 0.0, 'acknowledgement' => 0.0, 'downtime_depth' => 0.0 } } )
 
 
 
-## <a name=""></a>(private) update host
-    update_host( hash, host )
+## <a name=""></a>*update_host( hash, host )* (private)
+
+update host
+
+The result are an `Hash`
 
 ### Example
-    update_host( v, host_name )
+    service_severity( {'attrs' => { 'state' => 0.0, 'acknowledgement' => 0.0, 'downtime_depth' => 0.0 } } )
+