icinga2 0.6.1 → 0.6.2

data/lib/icinga2/downtimes.rb

@@ -3,13 +3,34 @@
 
 module Icinga2
 
-  #
-  #
-  #
+  # namespace for downtimes handling
   module Downtimes
 
+    # add downtime
     #
+    # @param [Hash] params
+    # @option params [String] :name
+    # @option params [String] :host
+    # @option params [String] :host_group
+    # @option params [Integer] :start_time (Time.new.to_i)
+    # @option params [Integer] :end_time
+    # @option params [String] :author
+    # @option params [String] :comment
+    # @option params [String] :type 'host' or 'service' downtime
     #
+    # @example
+    #    param = {
+    #      name: 'test',
+    #      type: 'service',
+    #      host: 'icinga2',
+    #      comment: 'test downtime',
+    #      author: 'icingaadmin',
+    #      start_time: Time.now.to_i,
+    #      end_time: Time.now.to_i + 20
+    #    }
+    #    @icinga.add_downtime(param)
+    #
+    # @return [Hash]
     #
     def add_downtime( params = {} )
 
@@ -84,7 +105,6 @@ module Icinga2
         }
       end
 
-
       if( end_time.nil? )
         return {
           status: 404,
@@ -97,9 +117,6 @@ module Icinga2
         }
       end
 
-#       logger.debug( Time.at( start_time ).strftime( '%Y-%m-%d %H:%M:%S' ) )
-#       logger.debug( Time.at( end_time ).strftime( '%Y-%m-%d %H:%M:%S' ) )
-
       payload = {
         'type'        => type,
         'start_time'  => start_time,
@@ -111,8 +128,6 @@ module Icinga2
         'filter'      => filter
       }
 
-#       logger.debug( JSON.pretty_generate( payload ) )
-
       result = Network.post(         host: name,
         url: format( '%s/v1/actions/schedule-downtime', @icinga_api_url_base ),
         headers: @headers,
@@ -131,19 +146,24 @@ module Icinga2
 
       #  --data '{ "type": "Service", "filter": "\"api_dummy_hostgroup\" in host.groups)", ... }'
 
-      JSON.pretty_generate( result )
-
     end
 
+    # return downtimes
+    #
+    # @param [Hash] params
+    # @option params [String] :host
     #
+    # @example
+    #    @icinga.downtimes
     #
+    # @return [Hash]
     #
     def downtimes( params = {} )
 
-      name = params.dig(:name)
+      host = params.dig(:host)
 
-      result = Network.get(         host: name,
-        url: format( '%s/v1/objects/downtimes/%s', @icinga_api_url_base, name ),
+      result = Network.get(         host: host,
+        url: format( '%s/v1/objects/downtimes/%s', @icinga_api_url_base, host ),
         headers: @headers,
         options: @options )
 

data/lib/icinga2/hostgroups.rb

@@ -3,71 +3,105 @@
 
 module Icinga2
 
-  #
-  #
-  #
+  # namespace for hostgroup handling
   module Hostgroups
 
+    # add a hostgroup
     #
+    # @param [Hash] params
+    # @option params [String] :host_group hostgroup to create
+    # @option params [String] :display_name the displayed name
     #
+    # @example
+    #   @icinga.add_hostgroup(host_group: 'foo', display_name: 'FOO')
+    #
+    # @return [Hash] result
     #
     def add_hostgroup(params = {})
-      name = params.dig(:name)
+
+      host_group = params.dig(:host_group)
       display_name = params.dig(:display_name)
-      if name.nil?
+
+      if host_group.nil?
         return {
           status: 404,
           message: 'no name for the hostgroup'
         }
       end
-      result = Network.put(url: format('%s/v1/objects/hostgroups/%s', @icinga_api_url_base, name),
+
+      Network.put(url: format('%s/v1/objects/hostgroups/%s', @icinga_api_url_base, host_group),
         headers: @headers,
         options: @options,
         payload: { 'attrs' => { 'display_name' => display_name } })
-      JSON.pretty_generate(result)
+
     end
 
+    # delete a hostgroup
+    #
+    # @param [Hash] params
+    # @option params [String] :name hostgroup to delete
     #
+    # @example
+    #   @icinga.delete_hostgroup(host_group: 'foo')
     #
+    # @return [Hash] result
     #
     def delete_hostgroup(params = {})
-      name = params.dig(:name)
-      if name.nil?
+
+      host_group = params.dig(:host_group)
+
+      if host_group.nil?
         return {
           status: 404,
           message: 'no name for the hostgroup'
         }
       end
-      result = Network.delete(host: name,
-        url: format('%s/v1/objects/hostgroups/%s?cascade=1', @icinga_api_url_base, name),
+
+      Network.delete(host: host_group,
+        url: format('%s/v1/objects/hostgroups/%s?cascade=1', @icinga_api_url_base, host_group),
         headers: @headers,
         options: @options)
-      JSON.pretty_generate(result)
     end
 
+    # returns all usersgroups
+    #
+    # @param [Hash] params
+    # @option params [String] :host_group ('') optional for a single hostgroup
     #
+    # @example to get all users
+    #    @icinga.hostgroups
     #
+    # @example to get one user
+    #    @icinga.hostgroups(name: 'linux-servers')
+    #
+    # @return [Hash] returns a hash with all hostgroups
     #
     def hostgroups(params = {})
-      name = params.dig(:name) || ''
-      result = Network.get(host: name,
-        url: format('%s/v1/objects/hostgroups/%s', @icinga_api_url_base, name),
+
+      host_group = params.dig(:host_group)
+
+      Network.get(host: host_group,
+        url: format('%s/v1/objects/hostgroups/%s', @icinga_api_url_base, host_group),
         headers: @headers,
         options: @options)
-      result = JSON.pretty_generate(result) unless result.nil?
-      result
+
     end
 
+    # returns true if the hostgroup exists
     #
+    # @param [String] name the name of the hostgroup
     #
+    # @example
+    #    @icinga.exists_hostgroup?('linux-servers')
+    #
+    # @return [Bool] returns true if the hostgroup exists
     #
     def exists_hostgroup?(name)
-      result = hostgroups(name: name)
+      result = hostgroups(host_group: name)
       result = JSON.parse(result) if result.is_a?(String)
-      status = result.dig('status')
+      status = result.dig(:status)
 
       return true if  !status.nil? && status == 200
-
       false
     end
 

data/lib/icinga2/hosts.rb

@@ -2,30 +2,51 @@
 # frozen_string_literal: true
 module Icinga2
 
-  #
-  #
-  #
+  # namespace for host handling
   module Hosts
 
+    # add host
     #
+    # @param [Hash] params
+    # @option params [String] :host
+    # @option params [String] :fqdn
+    # @option params [String] :display_name
+    # @option params [Bool] :enable_notifications (false)
+    # @option params [Integer] :max_check_attempts (3)
+    # @option params [Integer] :check_interval (60)
+    # @option params [Integer] :retry_interval (45)
+    # @option params [String] :notes
+    # @option params [String] :notes_url
+    # @option params [String] :action_url
+    # @option params [Hash] :vars ({})
     #
+    # @example
+    #    param = {
+    #      host: 'foo',
+    #      fqdn: 'foo.bar.com',
+    #      display_name: 'test node',
+    #      max_check_attempts: 5,
+    #      notes: 'test node'
+    #    }
+    #    @icinga.add_host(param)
+    #
+    # @return [Hash]
     #
     def add_host( params = {} )
 
-      name             = params.dig(:name)
-      fqdn             = params.dig(:fqdn)
-      display_name      = params.dig(:display_name) || name
-      notifications    = params.dig(:enable_notifications) || false
+      host               = params.dig(:host)
+      fqdn               = params.dig(:fqdn)
+      display_name       = params.dig(:display_name) || host
+      notifications      = params.dig(:enable_notifications) || false
       max_check_attempts = params.dig(:max_check_attempts) || 3
-      check_interval    = params.dig(:check_interval) || 60
-      retry_interval    = params.dig(:retry_interval) || 45
-      notes            = params.dig(:notes)
-      notes_url         = params.dig(:notes_url)
-      action_url        = params.dig(:action_url)
-      vars             = params.dig(:vars) || {}
-
-      if( name.nil? )
-
+      check_interval     = params.dig(:check_interval) || 60
+      retry_interval     = params.dig(:retry_interval) || 45
+      notes              = params.dig(:notes)
+      notes_url          = params.dig(:notes_url)
+      action_url         = params.dig(:action_url)
+      vars               = params.dig(:vars) || {}
+
+      if( host.nil? )
         return {
           status: 404,
           message: 'missing host name'
@@ -34,7 +55,7 @@ module Icinga2
 
       if( fqdn.nil? )
         # build FQDN
-        fqdn = Socket.gethostbyname( name ).first
+        fqdn = Socket.gethostbyname( host ).first
       end
 
       payload = {
@@ -60,24 +81,29 @@ module Icinga2
 
       logger.debug( JSON.pretty_generate( payload ) )
 
-      result = Network.put(         host: name,
-        url: format( '%s/v1/objects/hosts/%s', @icinga_api_url_base, name ),
+      Network.put(         host: host,
+        url: format( '%s/v1/objects/hosts/%s', @icinga_api_url_base, host ),
         headers: @headers,
         options: @options,
         payload: payload )
 
-      JSON.pretty_generate( result )
-
     end
 
+    # delete a host
     #
+    # @param [Hash] params
+    # @option params [String] :host host to delete
     #
+    # @example
+    #   @icinga.delete_host(host: 'foo')
+    #
+    # @return [Hash] result
     #
     def delete_host( params = {} )
 
-      name = params.dig(:name)
+      host = params.dig(:host)
 
-      if( name.nil? )
+      if( host.nil? )
 
         return {
           status: 404,
@@ -85,21 +111,32 @@ module Icinga2
         }
       end
 
-      result = Network.delete(         host: name,
-        url: format( '%s/v1/objects/hosts/%s?cascade=1', @icinga_api_url_base, name ),
+      Network.delete(         host: host,
+        url: format( '%s/v1/objects/hosts/%s?cascade=1', @icinga_api_url_base, host ),
         headers: @headers,
         options: @options )
 
-      JSON.pretty_generate( result )
-
     end
 
+    # return hosts
+    #
+    # @param [Hash] params
+    # @option params [String] :host
+    # @option params [String] :attrs
+    # @option params [String] :filter
+    # @option params [String] :joins
+    #
+    # @example to get all hosts
+    #    @icinga.hosts
     #
+    # @example to get one host
+    #    @icinga.host(host: 'icinga2')
     #
+    # @return [Hash]
     #
     def hosts( params = {} )
 
-      name   = params.dig(:name)
+      host   = params.dig(:host)
       attrs  = params.dig(:attrs)
       filter = params.dig(:filter)
       joins  = params.dig(:joins)
@@ -108,34 +145,46 @@ module Icinga2
       payload['filter'] = filter unless  filter.nil?
       payload['joins'] = joins unless  joins.nil?
 
-      result = Network.get(         host: name,
-        url: format( '%s/v1/objects/hosts/%s', @icinga_api_url_base, name ),
+      Network.get(         host: host,
+        url: format( '%s/v1/objects/hosts/%s', @icinga_api_url_base, host ),
         headers: @headers,
         options: @options )
 
-      JSON.pretty_generate( result )
-
     end
 
+    # returns true if the host exists
+    #
+    # @param [String] name
     #
+    # @example
+    #    @icinga.exists_host?('icinga2')
     #
+    # @return [Bool]
     #
     def exists_host?( name )
 
       result = hosts( name: name )
-
       result = JSON.parse( result ) if  result.is_a?( String )
-
-      status = result.dig('status')
+      status = result.dig(:status)
 
       return true if  !status.nil? && status == 200
-
       false
-
     end
 
+    # returns host objects
+    #
+    # @param [Hash] params
+    # @option params [Array] :attrs (['name', 'state', 'acknowledgement', 'downtime_depth', 'last_check'])
+    # @option params [Array] :filter ([])
+    # @option params [Array] :joins ([])
+    #
+    # @example with default attrs and joins
+    #    @icinga.host_objects
     #
+    # @example
+    #    @icinga.host_objects(attrs: ['name', 'state'])
     #
+    # @return [Hash]
     #
     def host_objects( params = {} )
 
@@ -149,23 +198,23 @@ module Icinga2
       end
 
       payload['attrs'] = attrs unless  attrs.nil?
-
       payload['filter'] = filter unless  filter.nil?
-
       payload['joins'] = joins unless  joins.nil?
 
-      result = Network.get(         host: nil,
+      Network.get(         host: nil,
         url: format( '%s/v1/objects/hosts', @icinga_api_url_base ),
         headers: @headers,
         options: @options,
         payload: payload )
 
-      JSON.pretty_generate( result )
-
     end
 
+    # return count of hosts with problems
     #
+    # @example
+    #    @icinga.host_problems
     #
+    # @return [Integer]
     #
     def host_problems
 
@@ -173,29 +222,34 @@ module Icinga2
       problems = 0
 
       data = JSON.parse(data) if  data.is_a?(String)
+      nodes = data.dig(:nodes)
 
-      nodes = data.dig('nodes')
+      unless !nodes
 
-      nodes.each do |n|
+        nodes.each do |n|
 
-        attrs           = n.last.dig('attrs')
+          attrs           = n.last.dig('attrs')
+          state           = attrs.dig('state')           || 0
+          downtime_depth  = attrs.dig('downtime_depth')  || 0
+          acknowledgement = attrs.dig('acknowledgement') || 0
 
-        state           = attrs.dig('state')           || 0
-        downtime_depth   = attrs.dig('downtime_depth')  || 0
-        acknowledgement = attrs.dig('acknowledgement') || 0
+          if( state != 0 && downtime_depth.zero? && acknowledgement.zero? )
+            problems += 1
+          end
 
-        if( state != 0 && downtime_depth.zero? && acknowledgement.zero? )
-          problems += 1
         end
-
       end
-
       problems
-
     end
 
+    # return a list of host with problems
+    #
+    # @param [Integer] max_items numbers of list entries
     #
+    # @example
+    #    @icinga.problem_hosts
     #
+    # @return [Hash]
     #
     def problem_hosts( max_items = 5 )
 
@@ -205,32 +259,39 @@ module Icinga2
       host_data = host_objects
 
       host_data = JSON.parse( host_data ) if  host_data.is_a?(String)
+      host_data = host_data.dig(:nodes)
 
-#       logger.debug( host_data )
+      unless !host_data
 
-      host_data = host_data.dig('nodes')
+        host_data.each do |_host,v|
 
-      host_data.each do |_host,v|
+          name  = v.dig('name')
+          state = v.dig('attrs','state')
 
-        name  = v.dig('name')
-        state = v.dig('attrs','state')
+          next if  state.zero?
 
-        next if  state.zero?
+          @host_problems[name] = host_severity(v)
+        end
 
-        @host_problems[name] = host_severity(v)
+        # get the count of problems
+        #
+        @host_problems.keys[1..max_items].each { |k,_v| @host_problems_severity[k] = @host_problems[k] }
       end
-
-      # get the count of problems
-      #
-      @host_problems.keys[1..max_items].each { |k,_v| @host_problems_severity[k] = @host_problems[k] }
-
       @host_problems_severity
 
     end
 
+    # calculate a host severity
+    #
     # stolen from Icinga Web 2
     # ./modules/monitoring/library/Monitoring/Backend/Ido/Query/ServicestatusQuery.php
     #
+    # @param [Hash] host
+    #
+    # @private
+    #
+    # @return [Hash]
+    #
     def host_severity( host )
 
       attrs           = host.dig('attrs')