icinga2 0.9.0.1 → 0.9.2.1

data/doc/statistics.md

@@ -1,19 +1,26 @@
 # Icinga2 - Statistics
 
 
-## <a name="stats-avg"></a>statistic data for latency and execution_time
-    average_statistics
+## <a name="stats-avg"></a>*average_statistics*
+
+statistic data for latency and execution_time
+
+The result are an `Hash`
 
 ### Example
     @icinga.cib_data
     latency, execution_time = @icinga.average_statistics.values
 
 or
+
     h = @icinga.average_statistics
     latency = h.dig(:latency)
 
-## <a name="stats-interval"></a>statistic data for intervall data
-    interval_statistics
+## <a name="stats-interval"></a>*interval_statistics*
+
+statistic data for intervall data
+
+The result are an `Hash`
 
 ### Example
     @icinga.cib_data
@@ -24,8 +31,11 @@ or
     hosts_active_checks = i.dig(:hosts_active_checks)
 
 
-## <a name="stats-services"></a>statistic data for services
-    service_statistics
+## <a name="stats-services"></a>*service_statistics*
+
+statistic data for services
+
+The result are an `Hash`
 
 ### Example
     @icinga.cib_data
@@ -35,19 +45,27 @@ or
     s = @icinga.service_statistics
     critical = s.dig(:critical)
 
-## <a name="stats-hosts"></a>statistic data for hosts
-    host_statistics
+## <a name="stats-hosts"></a>*host_statistics*
+
+statistic data for hosts
+
+The result are an `Hash`
 
 ### Example
     @icinga.cib_data
     up, down, pending, unreachable, in_downtime, ack = @icinga.host_statistics.values
 
 or
+
     h = @icinga.host_statistics
     pending = h.dig(:pending)
 
-## <a name="stats-work-queue"></a>queue statistics from the api
-    work_queue_statistics
+
+## <a name="stats-work-queue"></a>work_queue_statistics
+
+queue statistics from the api
+
+The result are an `Hash`
 
 ### Example
     @icinga.work_queue_statistics

data/doc/usergroups.md

@@ -1,27 +1,51 @@
 # Icinga2 - Usergroups
 
 
-## <a name="add-usergroup"></a>add a usergroup
-    add_usergroup( params )
+## <a name="add-usergroup"></a>*add_usergroup( params )*
+
+Creates an Icinga2 Usergroup.
+
+`params` are an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example    | Description
+| :--------------------  | :-----: | :-----     | :-----------
+| `user_group`           | String  | `foo`      | Usergroup they will be created
+| `display_name`         | String  | `User Foo` | the displayed Name
+
+The result are an `Hash`
 
 ### Example
     @icinga.add_usergroup(user_group: 'foo', display_name: 'FOO')
 
 
-## <a name="delete-usergroup"></a>delete a usergroup
-    delete_usergroup( params )
+## <a name="delete-usergroup"></a>*delete_usergroup( params )*
+
+Delete a Usergroup.
+
+`params` are an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `user_group`           | String  | `foo`   | Usergroup they will be deleted
+
+The result are an `Hash`
 
 ### Example
     @icinga.delete_usergroup(user_group: 'foo')
 
 
-## <a name="list-usergroups"></a>list usergroups
+## <a name="list-usergroups"></a>*usergroups* or *usergroups( params )*
 
-### list named usergroup
-    usergroups( params )
+returns all or a named usergroup.
+
+the optional `params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `user_group`           | String  | `foo`   | Usergroup they will be listed
+
+The result are an `Hash`
 
-#### Example
-    @icinga.usergroups(user_group: 'icingaadmins')
 
 ### list all usergroups
     usergroups
@@ -30,8 +54,22 @@
     @icinga.usergroups
 
 
-## <a name="usergroup-exists"></a>check if the usergroup exists
-    exists_usergroup?( user_group )
+### list named usergroup
+    usergroups( params )
+
+#### Example
+    @icinga.usergroups(user_group: 'icingaadmins')
+
+
+
+## <a name="usergroup-exists"></a>*exists_usergroup?( user_group )*
+
+check if the Usergroup exists
+
+`params` is an `String` with the Usergroupname.
+
+The result are an `Boolean`
 
 ### Example
+
     @icinga.exists_usergroup?('icingaadmins')

data/doc/users.md

@@ -1,9 +1,24 @@
 # Icinga2 - Users
 
-## <a name="add-user"></a>add a user
-    add_user( params )
+## <a name="add-user"></a>*add_user( params )*
+
+creates an Icinga2 User.
+
+`params` are an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example                  | Description
+| :--------------------  | :-----: | :-----                   | :-----------
+| `user_name`            | String  | `foo`                    | User they will be created
+| `display_name`         | String  | `User Foo`               | the displayed Name
+| `email`                | String  | `foo@bar.tld`            | the Email for this Users
+| `pager`                | String  | `+49 000 000000`         | an optional Pager Number
+| `enable_notifications` | Bool    | `true`                   | enable notifications for this user (default: **false**)
+| `groups`               | Array   | `['icingaadmins','dba']` | a hash with (existing!) groups
+
+The result are an `Hash`
 
 ### Example
+
     params =  {
       user_name: 'foo',
       display_name: 'FOO',
@@ -11,29 +26,65 @@
       pager: '0000',
       groups: ['icingaadmins']
     }
-    @icinga.add_user( params )
+    puts @icinga.add_user( params )
+    {"code"=>200, "name"=>nil, "status"=>"Object was created"}
+
+
+## <a name="delete-user"></a>*delete_user( params )*
 
+delete an Icinga2 User.
 
-## <a name="delete-user"></a>delete a user
-    delete_user( params )
+`params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `user_name`            | String  | `foo`   | User they will be deleted
+
+The result are an `Hash`
 
 ### Example
-    @icinga.delete_user(user_name: 'foo')
 
+    puts @icinga.delete_user(user_name: 'foo')
+    {"code"=>200, "name"=>"foo", "status"=>"Object was deleted."}
 
-## <a name="list-users"></a>list users
-### list named user
-    users( params )
-#### Example
-    @icinga.users(user_name: 'icingaadmin')
+
+## <a name="list-users"></a>*users* or *users( params )*
+
+returns all or a named user.
+
+the optional `params` is an `Hash` with following Parameters:
+
+| Parameter              | Type    | Example | Description
+| :--------------------  | :-----: | :-----  | :-----------
+| `user_name`            | String  | `foo`   | User they will be listed
+
+The result are an `Hash`
 
 ### list all users
     users
+
 #### Example
     @icinga.users
+    {"attrs"=>{"__name"=>"icingaadmin", "active"=>true, "display_name"=>"Icinga 2 Admin", "email"=>"icinga@localhost", "enable_notifications"=>true, "groups"=>["icingaadmins"], "ha_mode"=>0.0, "last_notification"=>0.0, "name"=>"icingaadmin", "original_attributes"=>nil, "package"=>"_etc", "pager"=>"", "paused"=>false, "period"=>"", "source_location"=>{"first_column"=>1.0, "first_line"=>6.0, "last_column"=>25.0, "last_line"=>6.0, "path"=>"/etc/icinga2/conf.d/users.conf"}, "states"=>nil, "templates"=>["icingaadmin", "generic-user"], "type"=>"User", "types"=>nil, "vars"=>nil, "version"=>0.0, "zone"=>""}, "joins"=>{}, "meta"=>{}, "name"=>"icingaadmin", "type"=>"User"}
+
+### list named user
+    users( params )
 
+#### Example
+    @icinga.users(user_name: 'foo')
+    {"attrs"=>{"__name"=>"foo", "active"=>true, "display_name"=>"FOO", "email"=>"foo@bar.com", "enable_notifications"=>false, "groups"=>["icingaadmins"], "ha_mode"=>0.0, "last_notification"=>0.0, "name"=>"foo", "original_attributes"=>nil, "package"=>"_api", "pager"=>"0000", "paused"=>false, "period"=>"", "source_location"=>{"first_column"=>0.0, "first_line"=>1.0, "last_column"=>16.0, "last_line"=>1.0, "path"=>"/var/lib/icinga2/api/packages/_api/icinga2-master.matrix.lan-1507365860-1/conf.d/users/foo.conf"}, "states"=>nil, "templates"=>["foo"], "type"=>"User", "types"=>nil, "vars"=>nil, "version"=>1507609817.587105, "zone"=>"icinga2-master.matrix.lan"}, "joins"=>{}, "meta"=>{}, "name"=>"foo", "type"=>"User"}
+
+
+
+## <a name="user-exists"></a>*exists_user?( params )*
 
-## <a name="user-exists"></a>checks if the user exists
+check if an User exists.
+
+`params` is an `String` with the Username.
+
+The result are an `Boolean`
 
 ### Example
-    @icinga.exists_user?('icingaadmin')
+
+    puts @icinga.exists_user?('icingaadmin')
+    true

data/examples/_blank.rb

@@ -0,0 +1,72 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 07.10.2017 - Bodo Schulz
+#
+#
+# Examples for Hostgroups
+
+# -----------------------------------------------------------------------------
+
+require_relative '../lib/icinga2'
+
+# -----------------------------------------------------------------------------
+
+icinga_host          = ENV.fetch( 'ICINGA_HOST'             , 'icinga2' )
+icinga_api_port      = ENV.fetch( 'ICINGA_API_PORT'         , 5665 )
+icinga_api_user      = ENV.fetch( 'ICINGA_API_USER'         , 'admin' )
+icinga_api_pass      = ENV.fetch( 'ICINGA_API_PASSWORD'     , nil )
+icinga_api_pki_path  = ENV.fetch( 'ICINGA_API_PKI_PATH'     , '/etc/icinga2' )
+icinga_api_node_name = ENV.fetch( 'ICINGA_API_NODE_NAME'    , nil )
+icinga_cluster       = ENV.fetch( 'ICINGA_CLUSTER'          , false )
+icinga_satellite     = ENV.fetch( 'ICINGA_CLUSTER_SATELLITE', nil )
+
+
+# convert string to bool
+icinga_cluster   = icinga_cluster.to_s.eql?('true') ? true : false
+
+config = {
+  icinga: {
+    host: icinga_host,
+    api: {
+      port: icinga_api_port,
+      user: icinga_api_user,
+      password: icinga_api_pass,
+      pki_path: icinga_api_pki_path,
+      node_name: icinga_api_node_name
+    },
+    cluster: icinga_cluster,
+    satellite: icinga_satellite
+  }
+}
+
+# ---------------------------------------------------------------------------------------
+
+i = Icinga2::Client.new( config )
+
+unless( i.nil? )
+
+  # run tests ...
+  #
+  #
+
+  begin
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+    rescue => e
+      $stderr.puts( e )
+      $stderr.puts( e.backtrace.join("\n") )
+    end
+end
+
+
+# -----------------------------------------------------------------------------
+
+# EOF

data/examples/downtimes.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 07.10.2017 - Bodo Schulz
+#
+#
+# Examples for Hostgroups
+
+# -----------------------------------------------------------------------------
+
+require_relative '../lib/icinga2'
+
+# -----------------------------------------------------------------------------
+
+icinga_host          = ENV.fetch( 'ICINGA_HOST'             , 'icinga2' )
+icinga_api_port      = ENV.fetch( 'ICINGA_API_PORT'         , 5665 )
+icinga_api_user      = ENV.fetch( 'ICINGA_API_USER'         , 'admin' )
+icinga_api_pass      = ENV.fetch( 'ICINGA_API_PASSWORD'     , nil )
+icinga_api_pki_path  = ENV.fetch( 'ICINGA_API_PKI_PATH'     , '/etc/icinga2' )
+icinga_api_node_name = ENV.fetch( 'ICINGA_API_NODE_NAME'    , nil )
+icinga_cluster       = ENV.fetch( 'ICINGA_CLUSTER'          , false )
+icinga_satellite     = ENV.fetch( 'ICINGA_CLUSTER_SATELLITE', nil )
+
+
+# convert string to bool
+icinga_cluster   = icinga_cluster.to_s.eql?('true') ? true : false
+
+config = {
+  icinga: {
+    host: icinga_host,
+    api: {
+      port: icinga_api_port,
+      user: icinga_api_user,
+      password: icinga_api_pass,
+      pki_path: icinga_api_pki_path,
+      node_name: icinga_api_node_name
+    },
+    cluster: icinga_cluster,
+    satellite: icinga_satellite
+  }
+}
+
+# ---------------------------------------------------------------------------------------
+
+i = Icinga2::Client.new( config )
+
+unless( i.nil? )
+
+  # run tests ...
+  #
+  #
+
+  begin
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+#   puts ' ==> DOWNTIMES'
+#   puts ''
+#   puts 'add Downtime \'test\''
+#   puts i.add_downtime( name: 'test', type: 'service', host: 'foo', comment: 'test downtime', author: 'icingaadmin', start_time: Time.now.to_i, end_time: Time.now.to_i + 20 )
+#   puts ''
+#   puts 'list all Downtimes'
+#   puts i.downtimes
+#   puts ''
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+    rescue => e
+      $stderr.puts( e )
+      $stderr.puts( e.backtrace.join("\n") )
+    end
+end
+
+
+# -----------------------------------------------------------------------------
+
+# EOF

data/examples/hostgroups.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+#
+# 07.10.2017 - Bodo Schulz
+#
+#
+# Examples for Hostgroups
+
+# -----------------------------------------------------------------------------
+
+require_relative '../lib/icinga2'
+
+# -----------------------------------------------------------------------------
+
+icinga_host          = ENV.fetch( 'ICINGA_HOST'             , 'icinga2' )
+icinga_api_port      = ENV.fetch( 'ICINGA_API_PORT'         , 5665 )
+icinga_api_user      = ENV.fetch( 'ICINGA_API_USER'         , 'admin' )
+icinga_api_pass      = ENV.fetch( 'ICINGA_API_PASSWORD'     , nil )
+icinga_api_pki_path  = ENV.fetch( 'ICINGA_API_PKI_PATH'     , '/etc/icinga2' )
+icinga_api_node_name = ENV.fetch( 'ICINGA_API_NODE_NAME'    , nil )
+icinga_cluster       = ENV.fetch( 'ICINGA_CLUSTER'          , false )
+icinga_satellite     = ENV.fetch( 'ICINGA_CLUSTER_SATELLITE', nil )
+
+
+# convert string to bool
+icinga_cluster   = icinga_cluster.to_s.eql?('true') ? true : false
+
+config = {
+  icinga: {
+    host: icinga_host,
+    api: {
+      port: icinga_api_port,
+      user: icinga_api_user,
+      password: icinga_api_pass,
+      pki_path: icinga_api_pki_path,
+      node_name: icinga_api_node_name
+    },
+    cluster: icinga_cluster,
+    satellite: icinga_satellite
+  }
+}
+
+# ---------------------------------------------------------------------------------------
+
+i = Icinga2::Client.new( config )
+
+unless( i.nil? )
+
+  # run tests ...
+  #
+  #
+
+  begin
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+    puts '= check if Hostgroup \'linux-servers\' exists'
+    puts i.exists_hostgroup?( 'linux-servers' ) ? 'true' : 'false'
+    puts ''
+    puts '= check if Hostgroup \'docker\' exists'
+    puts i.exists_hostgroup?( 'docker' ) ? 'true' : 'false'
+    puts ''
+    puts '= list named Hostgroup \'linux-servers\''
+    puts i.hostgroups( host_group: 'linux-servers' )
+    puts ''
+    puts '= list named Hostgroup \'foo\''
+    puts i.hostgroups( host_group: 'foo' )
+    puts ''
+    puts '= list all Hostgroups'
+    puts i.hostgroups
+    puts ''
+    puts '= add hostgroup \'foo\''
+    puts i.add_hostgroup( host_group: 'foo', display_name: 'FOO' )
+    puts ''
+    puts '= delete Hostgroup \'foo\''
+    puts i.delete_hostgroup( host_group: 'foo' )
+
+    puts ' ------------------------------------------------------------- '
+    puts ''
+
+    rescue => e
+      $stderr.puts( e )
+      $stderr.puts( e.backtrace.join("\n") )
+    end
+end
+
+
+# -----------------------------------------------------------------------------
+
+# EOF