icinga-rest 0.1.0

data/Gemfile

@@ -0,0 +1,8 @@
+source :rubygems
+gem "json"
+group :development do
+  gem "ruby-debug"
+  gem "rdoc"
+  gem "rspec"
+  gem "gem-this"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    columnize (0.3.2)
+    diff-lcs (1.1.3)
+    gem-this (0.3.7)
+    json (1.6.1)
+    linecache (0.43)
+    rdoc (3.9.4)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    ruby-debug (0.10.4)
+      columnize (>= 0.1)
+      ruby-debug-base (~> 0.10.4.0)
+    ruby-debug-base (0.10.4)
+      linecache (>= 0.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  gem-this
+  json
+  rdoc
+  rspec
+  ruby-debug

data/Rakefile

@@ -0,0 +1,91 @@
+require 'rake'
+require "rubygems"
+require "rubygems/package_task"
+require "rdoc/task"
+
+require "rspec"
+require "rspec/core/rake_task"
+
+$stdout.sync = true
+
+desc "Run all specs whenever anything changes"
+task :stakeout do
+  system "rake spec"
+  system "stakeout rake spec/*.rb spec/*/*_spec.rb lib/*.rb lib/*/*.rb"
+end
+
+RSpec::Core::RakeTask.new do |t|
+  t.rspec_opts = %w(--format documentation --colour)
+end
+
+task :default => ["spec"]
+
+# This builds the actual gem. For details of what all these options
+# mean, and other ones you can add, check the documentation here:
+#
+#   http://rubygems.org/read/chapter/20
+#
+spec = Gem::Specification.new do |s|
+
+  # Change these as appropriate
+  s.name              = "icinga-rest"
+  s.version           = "0.1.0"
+  s.summary           = "Simple, basic access to the Icinga REST API"
+  s.author            = "David Salgado"
+  s.email             = "david@digitalronin.com"
+  s.homepage          = "http://roninonrails.wordpress.com/2011/10/08/icinga-rest-ruby-gem"
+
+  s.has_rdoc          = true
+  # You should probably have a README of some kind. Change the filename
+  # as appropriate
+  s.extra_rdoc_files  = %w(Readme.markdown)
+  # s.rdoc_options      = %w(--main README)
+  s.description       = "Use the Icinga REST API to count hosts with services in a given state"
+
+  # Add any extra files to include in the gem (like your README)
+  s.files             = %w(Gemfile Gemfile.lock Rakefile) + Dir.glob("{spec,lib}/**/*")
+  s.require_paths     = ["lib"]
+
+  # If you want to depend on other gems, add them here, along with any
+  # relevant versions
+  s.add_dependency("json")
+
+  # If your tests use any gems, include them here
+  s.add_development_dependency("rspec")
+  s.add_development_dependency("ruby-debug")
+end
+
+# This task actually builds the gem. We also regenerate a static
+# .gemspec file, which is useful if something (i.e. GitHub) will
+# be automatically building a gem for this project. If you're not
+# using GitHub, edit as appropriate.
+#
+# To publish your gem online, install the 'gemcutter' gem; Read more 
+# about that here: http://gemcutter.org/pages/gem_docs
+Gem::PackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+end
+
+desc "Build the gemspec file #{spec.name}.gemspec"
+task :gemspec do
+  file = File.dirname(__FILE__) + "/#{spec.name}.gemspec"
+  File.open(file, "w") {|f| f << spec.to_ruby }
+end
+
+# If you don't want to generate the .gemspec file, just remove this line. Reasons
+# why you might want to generate a gemspec:
+#  - using bundler with a git source
+#  - building the gem without rake (i.e. gem build blah.gemspec)
+#  - maybe others?
+task :package => :gemspec
+
+# Generate documentation
+RDoc::Task.new do |rd|
+  rd.rdoc_files.include("lib/**/*.rb")
+  rd.rdoc_dir = "rdoc"
+end
+
+desc 'Clear out RDoc and generated packages'
+task :clean => [:clobber_rdoc, :clobber_package] do
+  rm "#{spec.name}.gemspec"
+end

data/Readme.markdown

@@ -0,0 +1,56 @@
+Icinga REST Gem
+===============
+
+A gem to simplify the use of the Icinga REST API.
+
+Currently, the only function that this gem will perform is a count of hosts where a specific service is in a given state. 
+
+e.g. To get a count of all hosts whose names begin with 'web' and whose 'Load' service is critical, you would do this;
+
+    #!/usr/bin/env ruby
+
+    require 'rubygems'
+    require 'icinga_rest'
+
+    check = IcingaRest::ServiceCheck.new(
+      :host    => 'my.icinga.host',
+      :authkey => 'mysecretapikey',
+      :filter  => [
+        {:host_name    => 'web*'},
+        {:service_name => 'Load', :state => :critical}
+      ]
+    )
+
+    puts check.count
+
+Requirements
+------------
+
+You must have enabled the REST API on your Icinga server (and configured the hosts and services to be monitored, of course)
+
+Any box that runs this check will need the wget program in /usr/bin/wget
+
+wget is used instead of a nice ruby http library because the URLs to access the Icinga REST API are not valid http URLs, so all the libraries I tried barf on them. wget is more forgiving.
+
+MIT License
+===========
+
+(c) David Salgado 2011, or whenever
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/lib/icinga_rest.rb

@@ -0,0 +1,12 @@
+# Gem to simplify the use of the Icinga REST API
+class IcingaRest
+end
+
+require 'rubygems'
+require 'json'
+
+libdir = File.join(File.dirname(__FILE__), 'icinga_rest')
+
+require "#{libdir}/request"
+require "#{libdir}/service_check"
+

data/lib/icinga_rest/request.rb

@@ -0,0 +1,50 @@
+# Wrapper to simplify constructing the http GET request
+# to access the Icinga REST API
+class IcingaRest::Request
+  attr_accessor :host,         # The Icinga server
+                :authkey,      # API key
+                :target,       # host|service
+                :filter,       # filter string to use. e.g. 'AND(SERVICE_NAME|=|Foobar;AND(SERVICE_CURRENT_STATE|!=|0))'
+                :count_column, # count this column to produce the total
+                :output        # json|xml
+
+  WGET = '/usr/bin/wget'
+
+  def initialize(params)
+    @host         = params[:host]
+    @target       = params[:target]
+    @filter       = params[:filter]
+    @count_column = params[:count_column]
+    @authkey      = params[:authkey]
+    @output       = params[:output]
+  end
+
+  # It would be nicer to use Net::HTTP, or something, but the 
+  # URLs required by the Icinga API are not well-formed, and 
+  # the URI library, used by most of the ruby http libs, barfs.
+  # So, we shell out to wget, which is more tolerant.
+  # Fugly, but functional.
+  def get
+    `#{WGET} -q -O - '#{to_url}'`
+  end
+
+  def to_url
+    "http://%s/icinga-web/web/api/%s/%s/authkey=%s/%s" % [host, target, url_options, authkey, output]
+  end
+
+  private
+
+  # The optional components of the API request path
+  def url_options
+    [filter_url, count_column_url].compact.join('/')
+  end
+
+  def filter_url
+    self.filter ? "filter[%s]" % filter : nil
+  end
+
+  def count_column_url
+    self.count_column ? "countColumn=%s"% count_column : nil
+  end
+
+end

data/lib/icinga_rest/service_check.rb

@@ -0,0 +1,107 @@
+# Class to count services in a given state, optionally filtered by host name, either as
+# a pattern ('foo*', or '*foo*'), or as an exact match ('foobar')
+class IcingaRest::ServiceCheck
+  attr_accessor :host,    # The Icinga server
+                :authkey, # API key
+                :filter   # List of tuples
+
+  SERVICE_STATES = {
+    :ok       => 0,
+    :warn     => 1,
+    :critical => 2
+  }
+
+  # Define a service check to be carried out.
+  #
+  # Currently, only counting services in a given state is possible,
+  # where the service name and state are provided as literals, with
+  # optional filtering on host name, either as an exact match or 
+  # with wildcards in the host name.
+  #
+  # Arguments:
+  # * :host - The Icinga host. The REST API must be available at the default location
+  #   http://[host]/icinga-web/web/api/
+  # * :authkey - Your API key to access the REST API
+  # * :filter - a list of tuples to filter the count
+  #   e.g.
+  #     [ {:host_name => 'web*'}, {:service_name => 'Load', :state => :critical} ]
+  #
+  #   The :host_name and :service_name should match hosts and services you have configured
+  #   in Icinga (otherwise your count will always be zero).
+  #
+  #   :state should be one of :ok, :warn, :critical
+  #
+  # Example:
+  #
+  #     check = IcingaRest::ServiceCheck.new(
+  #       :host    => 'my.icinga.host',
+  #       :authkey => 'mysecretapikey',
+  #       :filter  => [
+  #         {:host_name    => 'web*'},
+  #         {:service_name => 'Load', :state => :critical}
+  #       ]
+  #     )
+  #
+  #     puts check.count
+  #
+  def initialize(params)
+    @host    = params[:host]
+    @authkey = params[:authkey]
+    @filter  = params[:filter]
+  end
+
+  def count
+    json = request.get
+    result = JSON.load json
+    if result['success'] == 'true'
+      result['total']
+    else
+      raise "API call failed"
+    end
+  end
+
+  private
+
+  def request
+    IcingaRest::Request.new(
+      :host         => host,
+      :target       => 'service',
+      :filter       => filters,
+      :count_column => 'SERVICE_ID',
+      :authkey      => authkey,
+      :output       => 'json'
+    )
+  end
+
+  def filters
+    clauses = filter.inject([]) {|list, tuple| list << filter_clause(tuple)}
+    "AND(%s)" % clauses.map {|c| "(#{c})"}.join(';AND')
+  end
+
+  def filter_clause(tuple)
+    if tuple[:host_name]
+      host_clause tuple
+    elsif tuple[:service_name]
+      service_clause tuple
+    else
+      raise "Bad filter clause #{tuple.inspect}"
+    end
+  end
+
+
+  # {:service_name => 'Foobar', :state => :critical} => '(SERVICE_NAME|=|Foobar);AND(SERVICE_CURRENT_STATE|=|2)'
+  def service_clause(tuple)
+    name = tuple[:service_name]
+    state = SERVICE_STATES[tuple[:state]]
+    "(SERVICE_NAME|=|%s);AND(SERVICE_CURRENT_STATE|=|%d)" % [name, state]
+  end
+
+  # {:host_name => '*foobar*'} => 'HOST_NAME|like|*foobar*'
+  # {:host_name => 'foobar'}   => 'HOST_NAME|=|foobar'
+  def host_clause(tuple)
+    name = tuple[:host_name]
+    operator = name.index('*').nil? ? '=' : 'like'
+    ['HOST_NAME', operator, name].join('|')
+  end
+
+end

data/spec/icinga_rest/request_spec.rb

@@ -0,0 +1,21 @@
+require 'spec/spec_helper'
+
+describe IcingaRest::Request do
+  before(:each) do
+    @request = IcingaRest::Request.new(
+      :host         => 'my.icinga.host',
+      :target       => 'service',
+      :filter       => 'AND(SERVICE_NAME|=|Foobar;AND(SERVICE_CURRENT_STATE|!=|0))',
+      :count_column => 'SERVICE_ID',
+      :authkey      => 'itsasekrit',
+      :output       => 'json'
+    )
+  end
+
+  context "requesting" do
+    it "composes a URI" do
+      url = 'http://my.icinga.host/icinga-web/web/api/service/filter[AND(SERVICE_NAME|=|Foobar;AND(SERVICE_CURRENT_STATE|!=|0))]/countColumn=SERVICE_ID/authkey=itsasekrit/json'
+      @request.to_url.should == url
+    end
+  end
+end

data/spec/icinga_rest/service_check_spec.rb

@@ -0,0 +1,87 @@
+require 'spec/spec_helper'
+
+describe IcingaRest::ServiceCheck do
+  before(:each) do
+    @check = IcingaRest::ServiceCheck.new(
+      :host         => 'my.icinga.host',
+      :authkey      => 'itsasekrit',
+      :filter       => [
+        {:service_name => 'Foobar', :state => :critical}
+      ]
+    )
+  end
+
+  context "filtering" do
+
+    it "filters on hostname like whatever*" do
+      @check.filter << {:host_name => 'foobar*'} 
+      request = mock IcingaRest::Request, :get => '{"success":"true"}'
+      request_params = {
+        :host         => 'my.icinga.host',
+        :target       => 'service',
+        :filter       => 'AND(((SERVICE_NAME|=|Foobar);AND(SERVICE_CURRENT_STATE|=|2));AND(HOST_NAME|like|foobar*))',
+        :count_column => 'SERVICE_ID',
+        :authkey      => 'itsasekrit',
+        :output       => 'json'
+      }
+      IcingaRest::Request.should_receive(:new).with(request_params).and_return(request)
+      @check.count
+    end
+
+    it "filters on hostname is whatever" do
+      @check.filter << {:host_name => 'foobar'} 
+      request = mock IcingaRest::Request, :get => '{"success":"true"}'
+      request_params = {
+        :host         => 'my.icinga.host',
+        :target       => 'service',
+        :filter       => 'AND(((SERVICE_NAME|=|Foobar);AND(SERVICE_CURRENT_STATE|=|2));AND(HOST_NAME|=|foobar))',
+        :count_column => 'SERVICE_ID',
+        :authkey      => 'itsasekrit',
+        :output       => 'json'
+      }
+      IcingaRest::Request.should_receive(:new).with(request_params).and_return(request)
+      @check.count
+    end
+
+    it "creates a request" do
+      request = mock IcingaRest::Request, :get => '{"success":"true"}'
+      request_params = {
+        :host         => 'my.icinga.host',
+        :target       => 'service',
+        :filter       => 'AND(((SERVICE_NAME|=|Foobar);AND(SERVICE_CURRENT_STATE|=|2)))',
+        :count_column => 'SERVICE_ID',
+        :authkey      => 'itsasekrit',
+        :output       => 'json'
+      }
+      IcingaRest::Request.should_receive(:new).with(request_params).and_return(request)
+      @check.count
+    end
+  end
+
+  context "counting" do
+    it "throws an exception if request unsuccessful" do
+      json = '{"success":"false"}'
+      request = mock IcingaRest::Request, :get => json
+      IcingaRest::Request.stub!(:new).and_return(request)
+      expect {
+        @check.count
+      }.to raise_error("API call failed")
+    end
+
+    it "parses json response" do
+      json = '{"result":[{"SERVICE_ID":"16649","SERVICE_OBJECT_ID":"4546","SERVICE_IS_ACTIVE":"1","SERVICE_INSTANCE_ID":"1","SERVICE_NAME":"Foobar","SERVICE_DISPLAY_NAME":"Foobar","SERVICE_OUTPUT":"CRITICAL: Foobar is broken","SERVICE_PERFDATA":"in_service=0"},{"SERVICE_ID":"14083","SERVICE_OBJECT_ID":"1972","SERVICE_IS_ACTIVE":"1","SERVICE_INSTANCE_ID":"1","SERVICE_NAME":"Foobar","SERVICE_DISPLAY_NAME":"Foobar","SERVICE_OUTPUT":"CRITICAL: Foobar is broken","SERVICE_PERFDATA":"in_service=0"},{"SERVICE_ID":"12688","SERVICE_OBJECT_ID":"548","SERVICE_IS_ACTIVE":"1","SERVICE_INSTANCE_ID":"1","SERVICE_NAME":"Foobar","SERVICE_DISPLAY_NAME":"Foobar","SERVICE_OUTPUT":"CHECK_NRPE: Socket timeout after 10 seconds.","SERVICE_PERFDATA":""},{"SERVICE_ID":"13138","SERVICE_OBJECT_ID":"1013","SERVICE_IS_ACTIVE":"1","SERVICE_INSTANCE_ID":"1","SERVICE_NAME":"Foobar","SERVICE_DISPLAY_NAME":"Foobar","SERVICE_OUTPUT":"CHECK_NRPE: Socket timeout after 10 seconds.","SERVICE_PERFDATA":""},{"SERVICE_ID":"12763","SERVICE_OBJECT_ID":"638","SERVICE_IS_ACTIVE":"1","SERVICE_INSTANCE_ID":"1","SERVICE_NAME":"Foobar","SERVICE_DISPLAY_NAME":"Foobar","SERVICE_OUTPUT":"CRITICAL: Foobar is broken","SERVICE_PERFDATA":"in_service=0"}],"success":"true","total":5}'
+      request = mock IcingaRest::Request, :get => json
+      IcingaRest::Request.stub!(:new).and_return(request)
+
+      @check.count.should == 5
+    end
+
+    it "sends request" do
+      request = mock IcingaRest::Request
+      IcingaRest::Request.stub!(:new).and_return(request)
+      request.should_receive(:get).and_return('{"success":"true","total":5}')
+      @check.count
+    end
+
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,5 @@
+require 'ruby-debug'
+Debugger.start
+
+require 'lib/icinga_rest'
+

metadata

@@ -0,0 +1,115 @@
+--- !ruby/object:Gem::Specification 
+name: icinga-rest
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- David Salgado
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-10-08 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: json
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: ruby-debug
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Use the Icinga REST API to count hosts with services in a given state
+email: david@digitalronin.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- Readme.markdown
+files: 
+- Gemfile
+- Gemfile.lock
+- Rakefile
+- spec/icinga_rest/request_spec.rb
+- spec/icinga_rest/service_check_spec.rb
+- spec/spec_helper.rb
+- lib/icinga_rest/request.rb
+- lib/icinga_rest/service_check.rb
+- lib/icinga_rest.rb
+- Readme.markdown
+homepage: http://roninonrails.wordpress.com/2011/10/08/icinga-rest-ruby-gem
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Simple, basic access to the Icinga REST API
+test_files: []
+