nagios_mklivestatus 0.0.3 → 0.0.9

data/README.rdoc

@@ -0,0 +1,221 @@
+= Description
+
+This gem provides support to \Nagios MkLiveStatus through an API.
+The library have the following functionality :
+
+* check query validity
+* parse query from string
+* create query
+* request mklivestatus with query
+
+See this {link}[http://mathias-kettner.de/checkmk_livestatus.html] for more detail about the MkLiveStatus.
+
+---
+
+= Installation
+
+In order to use the gem, you have to install it into your rubygem environment.
+
+ gem install nagios_maklivestatus
+
+To integrate it in your applications, it can be done just by adding the two following lines :
+
+ require 'rubygems'
+ require 'nagios_mklivestatus'
+
+Your reading to use the library
+
+---
+
+= User Guide
+
+== Configuration
+
+The configuration is made through the following command:
+ nagmk-ruby-config
+
+This command is defined like this:
+
+ nagmk-ruby-config [-h|--help] [-p|--path PATH] [-r|--remove] [-o|--options NAME=VALUE] [-u|--unset NAME][-s|--show]
+
+ arguments : -h|--help                help 
+             -p|--path PATH           path to the nagios mklivestatus socket by default
+             -r|--remove              remove the path from the config file
+             -o|--options NAME=VALUE  add option to the configuration
+             -u|--unset NAME          remove option from the configuration file.
+             -s|--show                show configuration
+
+== Client
+
+The client is the executable file that use the gem in order to execute the query.
+ nagmk-ruby <query>
+ 
+The client can take the query from 3 sources:
+
+from argument :: simply puts your query as argument into the command line "<query>" and with \n for new line
+from file     :: with the -f option you can define a path to the file containing the query
+from pipe     :: echo -e "<query>" | nagmk-ruby
+ 
+The client command is defined like this:
+
+ nagmk-ruby [-h|--help] -p|--path PATH [-o|--options NAME=VALUE] {[-f|--file FILE]|query}
+
+ arguments : -h|--help                help 
+             -p|--path PATH           redefine path to the nagios mklivestatus socket
+             -o|--options NAME=VALUE  add or override option to the request 
+             -f|--file FILE           file containing the query
+             query                    the nagios query to execute 
+
+---
+
+= Developper Guide
+
+== Logging System
+
+The logger use the default logger class of ruby : Logger.
+The logger can be initiate and changed through the same way:
+
+ require 'nagios_mklivestatus'
+ 
+ ## changing nagios logging
+ # options
+ log_opts = { #logger options used to override default options
+   :name => STDOUT, # name of the logger like in Logger.new(name)
+   :level => Logger::ERROR, # logger level  logger.level = Logger::ERROR
+   
+   # used if defined or not nil
+   :shift_age => nil, # shift age of the logger like in Logger.new(name, shift_age)
+   
+   # used if defined or not nil and if shift_age is defined
+   :shift_size => nil # shift size of the logger like in Logger.new(name, shift_age, shift_size)
+ }
+ # change log setting
+ Nagios::MkLiveStatus.init({:log=>log_opts})
+
+== Creating Query
+
+Creating a query can be made in multiples ways using :
+* API
+* Helper
+* Parser
+
+Next, we will show you how to use those methods to create query.
+
+=== API
+
+===== Query
+
+Look at the following code :
+
+ require 'nagios_mklivestatus'
+ 
+ ##
+ # create the query
+ #
+ query = Nagios::MkLiveStatus::Query.new 
+ 
+ # add GET hosts
+ query.get "hosts"
+ 
+ # add Columns: host_name groups
+ query.addColumn "host_name"
+ query.addColumn "groups"
+ 
+ # add Filter: (see below)
+ query.addFilter "<filter_expr>"
+ 
+ # add Stats: (see below)
+ query.addStats "<stat_expr>"
+ 
+Only the two first are required in order to create a correct MkLiveStatus Query.
+
+===== Filter
+ 
+The filter expression which can be added to query are defined like this :
+
+ require 'nagios_mklivestatus'
+  
+ #both line are equals
+ filter1 = Nagios::MkLiveStatus::Filter::Attr.new("host_name", Nagios::MkLiveStatus::Filter::Attr::EQUAL, "<name>")
+ filter2 = Nagios::MkLiveStatus::Filter::Attr.new("host_name", "=", "<name>")
+ 
+ #filter and, or and negate
+ filter_and = Nagios::MkLiveStatus::Filter::And.new(filter1, filter2)
+ filter_or = Nagios::MkLiveStatus::Filter::Or.new(filter1, filter2)
+ filter_neg = Nagios::MkLiveStatus::Filter::Negate.new(filter2)
+ 
+===== Stats
+ 
+The stats expression which can be added to the query are defined like this:
+
+ require 'nagios_mklivestatus'
+ 
+ #both line are equals: host_name = <name>
+ stats1 = Nagios::MkLiveStatus::Stats::Attr.new("host_name", Nagios::MkLiveStatus::Stats::Attr::EQUAL, "<name>")
+ stats2 = Nagios::MkLiveStatus::Stats::Attr.new("host_name", "=", "<name>")
+ 
+ #both line are equals Stats: sum host_name
+ stats1 = Nagios::MkLiveStatus::Stats::Attr.new("host_name", nil, nil, Nagios::MkLiveStatus::Stats::Attr::SUM)
+ stats2 = Nagios::MkLiveStatus::Stats::Attr.new("host_name", nil, nil,"sum")
+ 
+ #stats and, or
+ stats_and = Nagios::MkLiveStatus::Stats::And.new(stats1, stats2)
+ stats_or = Nagios::MkLiveStatus::Stats::Or.new(stats1, stats2)
+ 
+Please refer to the corresponding class for more details on expressions.
+
+=== Helper
+
+An helper exists containing the query, filter and stats creation. This helper also contains comparator operator and deviation in sub modules.
+
+ require 'nagios_mklivestatus'
+ include Nagios::MkLiveStatus::QueryHelper
+ 
+ # query helper : create a query
+ query = nagmk_query
+ 
+ query.get "host"
+ query.addColumn "host_name"
+ 
+ # query helper : create filter
+ filter = nagmk_filter("host_name", Comparator::EQUAL, "<name>")
+ query.addFilter filter
+ 
+ # query helper : create filter from string
+ filter = nagmk_filter_from_str("host_name = <name>")
+ 
+See the Nagios::MkLiveStatus::QueryHelper for more methods.
+
+=== Parser
+
+The Nagios::MkLiveStatus::Parser is a module that provides a string parser in order to create the query:
+
+ require 'nagios_mklivestatus'
+ include Nagios::MkLiveStatus::Parser
+
+ query_str = <nagios_query>
+ query = nagmk_parse(query_str)
+ 
+== Making Request
+
+Once you have the query you can send it to the Nagios MkLiveStatus Server using the Request Object
+
+ require 'nagios_mklivestatus'
+ 
+ ##
+ # creating request
+ # path can be tcp://<host>:<port> or <path>
+ mklive_req = Nagios::MkLiveStatus::Request.new(path)
+ 
+ ##
+ # common options:
+ # :limit : limit the number of results
+ # :output : output format
+ # :user : authenticated user
+ #
+ # see the class for more
+ results = mklive_req.query(query, options)
+
+=TODO:
+* advanced management for exceptions throws by the socket
+* adding support to http

data/RELEASE.rdoc

@@ -0,0 +1,20 @@
+= nagios_mklivestatus version 0.0.9
+
+== 0.0.1
+
+* Creation initial release of the gem
+
+== 0.0.4
+
+* include user authentification for query.
+* include advanced query filtering
+* include advanced count/group (stats)
+* include exception management
+* include query parser
+
+== 0.0.9
+* include query helper
+* include logging management
+* preparing release v1.0.0
+* include wait query manager
+* include binaries for library

data/bin/nagmk-conf.yml

@@ -0,0 +1,2 @@
+---
+:options: {}

data/bin/nagmk-ruby

@@ -0,0 +1,146 @@
+#!/usr/bin/env ruby
+# Use the nagios_mklivestatus gem in order to create and execute the query in parameters.
+#
+# nagmk-ruby [-h|--help] -p|--path PATH [-o|--options NAME=VALUE] {[-f|--file FILE]|query}
+#
+# arguments : -h|--help                help 
+#             -p|--path PATH           path to the nagios mklivestatus socket
+#             -o|--options NAME=VALUE  add option to the request 
+#             -f|--file FILE           file containing the query
+#             query                    the nagios query to execute
+require 'rubygems'
+require 'optparse'
+require 'nagios_mklivestatus'
+require 'logger'
+require 'yaml'
+
+#default logging
+log_opts = {
+  :name  => '/var/logs/nagios_mklivestatus_ruby.log',
+  :level => Logger::INFO
+}
+
+# loading configuration
+mk_conf_file = File.join(File.absolute_path(File.dirname(__FILE__)), "nagmk-conf.yml")
+mk_conf_opts = YAML::load_file(mk_conf_file)
+
+
+mk_file=nil
+mk_opts=Hash.new
+mk_path=nil
+#loading conf path if sets
+mk_path=mk_conf_opts[:path] if mk_conf_opts.has_key? :path
+#loading conf options if sets
+mk_opts=mk_conf_opts[:options] if mk_conf_opts.has_key? :options
+optparser = OptionParser.new do |opts|
+  
+  # set help banner
+  opts.banner = "nagmk-ruby [-h|--help] -p|--path PATH [-o|--options NAME=VALUE] {[-f|--file FILE]|query}\n\nExecute the query or the file to the request.\n\n"
+  
+  # add help option
+  opts.on( '-h', '--help', 'Display this screen' ) do
+    # show help
+    puts opts
+    # exit command 
+    exit
+  end
+  
+  # add verbose option : default to false
+  opts.on( '-v', '--verbose', "Show logs. Multiple time (-vv or -v -v)makes it appears like this :\n\t-v => log on the screen\n\t-vv => log warn\n\t-vvv => log info\n\t-vvvv => log debug\n ") do
+    # if option found set verbose option
+    if log_opts[:name] != STDOUT
+      log_opts[:name] = STDOUT
+    elsif log_opts[:level] != Logger::DEBUG
+      log_opts[:level] = log_opts[:level]-1
+    end
+    
+  end
+  
+  opts.on( '-p', '--path PATH', "Path to the Nagios MkLiveStatus socket according to specification :\n\ttcp://<host>:<port> for TCP or <path> for unix socket\n ") do |path|
+    mk_path = path
+  end
+  
+  opts.on( '-o', '--options NAME=VALUE', "Options to add to make the request.\n\tcolumn_headers : show column header\n\tlimit          : limit output lines\n\toutput         : \'json\' or \'python\' output formating\n\tlocal_time     : local time settings\n\tuser           : authenticated user\n ") do |opt|
+    
+    if opt.match(/^([\w_]+)=(true|false)$/)
+      name,value = opt.split("=")
+      if value == "true"
+        mk_opts[name.to_sym] = true
+      elsif value == "false"
+        mk_opts[name.to_sym] = false
+      end
+    elsif opt.match(/^([\w_]+)=(\d)$/) 
+      name,value = opt.split("=")
+      mk_opts[name.to_sym] = value.to_i
+    elsif opt.match(/^([\w_]+)=(\w)$/)
+      name,value = opt.split("=")
+      mk_opts[name.to_sym] = value
+    end
+  end
+  
+  opts.on( '-f', '--file FILE', "The file containing the query.") do |file|
+    mk_file = file
+  end
+  
+end
+
+optparser.parse!
+
+#set logging options
+Nagios::MkLiveStatus.init(:log=>log_opts)
+
+begin
+  
+  if not mk_path or mk_path.empty?
+    raise ArgumentError.new("Path must be specified in the command line.")
+  end
+  
+  if not STDIN.tty?
+    tty_in = true
+  else
+    tty_in = false
+  end
+
+  # only file  
+  file_ok = mk_file != nil and (not tty_in or ARGV.length == 0)
+  # only gets
+  gets_ok = tty_in and (not mk_file or ARGV.length == 0)
+  # only argv
+  argv_ok = ARGV.length == 1 and (not tty_in or mk_file == nil)
+  
+  if (file_ok and gets_ok or gets_ok and argv_ok or argv_ok and file_ok) or (not argv_ok and not gets_ok and not file_ok)
+    raise ArgumentError.new("Wrong number of arguments. Please look at the help (-h).")
+  end
+  
+  mk_query_str=""
+  if mk_file != nil and not File.exists? mk_file
+    raise ArgumentError.new("The file containing the query doesn't exists.")
+  elsif mk_file != nil
+    File.open(mk_file) do |file|
+      while (line = file.gets)
+        mk_query_str << line
+      end
+    end
+  elsif not STDIN.tty?
+    while (line = STDIN.gets)
+      mk_query_str << line
+    end
+  else
+    mk_query_str = ARGV[0].gsub(/\\n/,"\n")
+  end  
+  
+  mk_request = Nagios::MkLiveStatus::Request.new(mk_path)
+
+  include Nagios::MkLiveStatus::Parser
+  mk_query = nagmk_parse(mk_query_str)
+  
+  mk_results = mk_request.query(mk_query, mk_opts)
+  
+  if log_opts[:name] != STDOUT or log_opts[:level] > Logger::INFO
+    puts mk_results
+  end
+rescue Exception => ex
+  if log_opts[:name] != STDOUT
+    puts ex.message
+  end
+end

data/bin/nagmk-ruby-config

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# Set default configuration for the nagmk-ruby
+#
+# nagmk-ruby-config [-h|--help] [-p|--path PATH] [-r|--remove] [-o|--options NAME=VALUE] [-u|--unset NAME][-s|--show]
+#
+# arguments : -h|--help                help 
+#             -p|--path PATH           path to the nagios mklivestatus socket by default
+#             -r|--remove              remove the path from the config file
+#             -o|--options NAME=VALUE  add option to the configuration
+#             -u|--unset NAME          remove option from the configuration file.
+#             -s|--show                show configuration
+require 'rubygems'
+require 'optparse'
+require 'yaml'
+
+mk_show = false
+
+#loading options
+mk_conf_file = File.join(File.absolute_path(File.dirname(__FILE__)), "nagmk-conf.yml")
+mk_opts = YAML::load_file(mk_conf_file)
+
+optparser = OptionParser.new do |opts|
+  
+  # set help banner
+  opts.banner = "nagmk-ruby [-h|--help] -p|--path PATH [-o|--options NAME=VALUE] {[-f|--file FILE]|query}\n\nExecute the query or the file to the request.\n\n"
+  
+  # add help option
+  opts.on( '-h', '--help', 'Display this screen' ) do
+    # show help
+    puts opts
+    # exit command 
+    exit
+  end
+  
+  # add show list
+  opts.on( '-s', '--show', 'show options' ) do
+    #set to show
+    mk_show=true
+    
+  end
+  
+  opts.on( '-p', '--path PATH', "Path to the Nagios MkLiveStatus socket according to specification :\n\ttcp://<host>:<port> for TCP or <path> for unix socket\n ") do |path|
+    mk_opts[:path] = path
+  end
+  
+  opts.on( '-r', '--remove', "Remove the path from the configuration file") do
+    mk_opts.delete(:path)
+  end
+  
+  opts.on( '-o', '--options NAME=VALUE', "Options to add to make the request.\n\tcolumn_headers : show column header\n\tlimit          : limit output lines\n\toutput         : \'json\' or \'python\' output formating\n\tlocal_time     : local time settings\n\tuser           : authenticated user\n ") do |opt|
+    if opt.match(/^([\w_]+)=(true|false)$/)
+      name,value = opt.split("=")
+      if value == "true"
+        mk_opts[:options][name.to_sym] = true
+      elsif value == "false"
+        mk_opts[:options][name.to_sym] = false
+      end
+    elsif opt.match(/^([\w_]+)=(\d)$/) 
+      name,value = opt.split("=")
+      mk_opts[:options][name.to_sym] = value.to_i
+    elsif opt.match(/^([\w_]+)=(\w)$/)
+      name,value = opt.split("=")
+      mk_opts[:options][name.to_sym] = value
+    end
+  end
+  
+  opts.on( '-u', '--unset NAME', "Remove option from the configuration file.") do |opt|
+    if mk_opts[:options].has_key? opt.to_sym
+      mk_opts[:options].delete(opt.to_sym)
+    end
+  end
+  
+end
+
+optparser.parse!
+
+begin
+  
+  if mk_show
+    #re loading options
+    mk_opts = YAML::load_file(mk_conf_file)
+    puts mk_opts.to_yaml
+  else
+    # write options
+    File.open(mk_conf_file, "w") do |io|
+      io.write(mk_opts.to_yaml)
+      io.close
+    end
+  end
+  
+rescue Exception => ex
+  puts ex.message
+end

data/lib/nagios_mklivestatus/exception/query_exception.rb

@@ -0,0 +1,9 @@
+##
+# Exception for nagios query manipulation : creation of predicat Filter, Stats, Wait 
+# or converting query to string
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::QueryException <  Nagios::MkLiveStatus::Exception
+end

data/lib/nagios_mklivestatus/exception/request_exception.rb

@@ -0,0 +1,8 @@
+##
+# Exception for nagios request error 
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::RequestException < Nagios::MkLiveStatus::Exception
+end

data/lib/nagios_mklivestatus/exception.rb

@@ -0,0 +1,19 @@
+##
+# General Exception for nagios.
+# Add logging error when raised
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::Exception < Exception
+  
+  include Nagios::MkLiveStatus
+  
+  def initialize(msg=nil)
+    super(msg)
+    logger.error(msg)
+  end
+  
+  require File.join(File.dirname(__FILE__), File.basename(__FILE__, ".rb"), "query_exception")
+  require File.join(File.dirname(__FILE__), File.basename(__FILE__, ".rb"), "request_exception")
+end

data/lib/nagios_mklivestatus/filter/and.rb

@@ -0,0 +1,64 @@
+# This class is used to make a logical "AND" operator between two filter expressions.
+#
+# If one of the filter expression is also an "AND", 
+# it takes all the expressions of the operator as its own.
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::Filter::And < Nagios::MkLiveStatus::Filter
+  
+  include Nagios::MkLiveStatus
+  
+  #
+  # Create a new "AND" operator between left and right expressions.
+  #
+  # Those expressions must be of type Nagios::MkLiveStatus::Filter
+  #
+  def initialize(left_expr, right_expr)
+    if not left_expr.is_a? Nagios::MkLiveStatus::Filter or not right_expr.is_a? Nagios::MkLiveStatus::Filter
+      raise QueryException.new("The left and the right operand for an AND expression must be filter expressions.")
+    end
+    
+    @expressions = Array.new
+    if left_expr.is_a? Nagios::MkLiveStatus::Filter::And
+      left_expr.get_expressions.each do |expr|
+        @expressions.push expr
+      end
+    else
+      @expressions.push left_expr
+    end
+    
+    if right_expr.is_a? Nagios::MkLiveStatus::Filter::And
+      right_expr.get_expressions.each do |expr|
+        @expressions.push expr
+      end
+    else
+      @expressions.push right_expr
+    end
+
+  end
+  
+  #
+  # Return all the expressions under the "AND". It's used by 
+  # the new method in order to get all "AND" expressions into the same object.  
+  #
+  def get_expressions
+    return @expressions
+  end
+  
+  #
+  # Convert the current "AND" expression into a nagios query string
+  #  Filter: ...
+  #  Filter: ...
+  #  And: 2
+  #
+  def to_s
+    and_arr = []
+    @expressions.each do |expr|
+      and_arr.push expr.to_s
+    end
+    and_arr.push "And: #{@expressions.length}"
+    return and_arr.join("\n")
+  end
+end

data/lib/nagios_mklivestatus/filter/attr.rb

@@ -0,0 +1,57 @@
+# This class symbolise a filter unit. This unit represents a small filter predicate like, in the nagios query, this : 
+#  Filter: host_name = name
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::Filter::Attr < Nagios::MkLiveStatus::Filter
+  
+  include Nagios::MkLiveStatus
+  include Nagios::MkLiveStatus::QueryHelper::Comparator
+  
+  #
+  # Create the unit predicate with the column name, the operator use to compare, and the value
+  # [attr_name] name of the column
+  # [attr_comp] operator, one of the constant of the class
+  # [attr_value] the value to compare to
+  #
+  def initialize (attr_name, attr_comp, attr_value)
+    
+    list_comparator = get_all_comparators
+    
+    if attr_name == nil or attr_name.empty?
+      raise QueryException.new("The name of the attribute must be set in order to create the filter")
+    else
+      @attr_name = attr_name
+    end
+    
+    if list_comparator.index(attr_comp) == nil
+      raise QueryException.new("The comparator \"#{attr_comp}\" is not recognized.\n Please use one of : #{list_comparator.join(", ")}")
+    else
+      @attr_comp = attr_comp
+    end
+    
+    @attr_value = attr_value
+  end
+  
+  #
+  # Convert the class into the nagios query string:
+  #  Filter: name comp value
+  #
+  def to_s
+    if @attr_name == nil or @attr_name.empty?
+      raise QueryException.new("The filter cannot be converted into string because the name of the attribute is not set.")
+    end
+    
+    if @attr_comp == nil or @attr_comp.empty?
+      raise QueryException.new("The filter cannot be converted into string because the comparator of the attribute is not set.")
+    end
+    
+    if @attr_value == nil or @attr_value.empty?
+      return "Filter: "+@attr_name+" "+@attr_comp 
+    end
+    
+    return "Filter: "+@attr_name+" "+@attr_comp+" "+@attr_value;
+  end
+  
+end

data/lib/nagios_mklivestatus/filter/negate.rb

@@ -0,0 +1,49 @@
+# This class is used to make a logical "NOT" operator for the filter expression.
+#
+# Author::    Esco-lan Team  (mailto:team@esco-lan.org)
+# Copyright:: Copyright (c) 2012 GIP RECIA
+# License::   General Public Licence
+class Nagios::MkLiveStatus::Filter::Negate < Nagios::MkLiveStatus::Filter
+  
+  include Nagios::MkLiveStatus
+  
+  #
+  # Create a new "Not" operator for the expression.
+  #
+  # Those expressions must be of type Nagios::MkLiveStatus::Filter
+  #
+  def initialize(expr)
+    if not expr.is_a? Nagios::MkLiveStatus::Filter
+      raise QueryException.new("The operand for a NEGATE expression must be a filter expression.")
+    end
+    
+    @expression = expr
+    
+  end
+  
+  #
+  # Return the expression under the "Negate". It's used by 
+  # the to_s method in order to remove the overflow of Negate expression.  
+  #
+  def get_expression
+    return @expression
+  end
+  
+  #
+  # Convert the current "Negate" expression into a nagios query string.
+  #  Filter: ...
+  #  Negate:
+  #
+  # If the sub expression is also a Negate, it returns the sub-sub expression without negating it.
+  #
+  def to_s
+    if @expression.is_a? Nagios::MkLiveStatus::Filter::Negate
+      return @expression.get_expression.to_s
+    else
+      negate_arr = []
+      negate_arr.push @expression.to_s
+      negate_arr.push "Negate: "
+      return negate_arr.join("\n")
+    end
+  end
+end