rnagios 0.0.1

data/README.md

@@ -0,0 +1,34 @@
+rnagios
+=======
+
+Ruby gem to make creating Nagios plugins easier
+
+There are two types of checks you can perform that Nagios will process:
+active and NSCA checks.  Active checks are run on the Nagios
+monitoring host and actively check services.  NSCA checks are run
+by remote hosts and their output is sent back to the ` host
+for processing by the NSCA daemon.  Active checks are "actively" run
+by Nagios; NSCA checks are "passively" run by other servers.
+
+To create an active check, create logic that measures a service
+(such as a database, a web service, or a custom application) and
+returns a fully-populated ActiveStatus object.  By the same token,
+to create an NSCA check, create logic that measures a service and
+returns a fully-populated NscaHostStatus or NscaServiceStatus object.
+(There are many gems available that can help you connect to services
+and parse their output; this class does not attempt to be everything
+to everyone.)
+  
+RNagios handles the formatting, and provides the appropriate
+exit code so Nagios will process it correctly.  When running on
+UNIX/Linux, Nagios will check the exit codes along with the string
+in the status message to determine how to handle it.  Under Windows,
+Nagios only cares about the strings in the status message.
+
+RNagios allows you to use an optional configuration file in case your
+plugin requires access to multiple configuration parameters.  If
+you supply a configuration file, it should be a YAML file, and it will
+be parsed in the check method before the measure method is called.
+measure() can then use the @config attribute to access configuration
+parameters.  The configuration file is expected to be in the same
+directory as the plugin.

data/lib/rnagios/active_status.rb

@@ -0,0 +1,75 @@
+# Represents the status of an active check.  Valid status strings for
+# Nagios are OK, WARNING, CRITICAL, and UNKNOWN.  UNIX/Linux exit codes
+# are set automatically when you set the status attribute.
+class ActiveStatus < Status
+
+  # Indicates everything is good with the service
+  OK = 'OK'
+  # Indicates a status of concern; not necessarily catastrophic
+  WARNING = 'WARNING'
+  # Indicates a serious failure or error
+  CRITICAL = 'CRITICAL'
+  # Indicates that the status is unknown or can not be determined
+  UNKNOWN = 'UNKNOWN'
+
+  # UNIX/Linux exit code for Nagios OK
+  OK_EXIT_CODE = 0
+  # UNIX/Linux exit code for Nagios WARNING
+  WARNING_EXIT_CODE = 1
+  # UNIX/Linux exit code for Nagios CRITICAL
+  CRITICAL_EXIT_CODE = 2
+  # UNIX/Linux exit code for Nagios UNKNOWN
+  UNKNOWN_EXIT_CODE = 3
+
+  # If status is not given, it will default to UNKNOWN.  If message
+  # is not given, it will default to <EMPTY>.  UNIX/Linux exit codes
+  # are assigned automatically.
+  def initialize(status=nil, message=nil)
+    if status.nil? || (status != OK && status != WARNING && status != CRITICAL && status != UNKNOWN)
+      @status = UNKNOWN
+    else
+      @status = status if !status.nil?
+    end
+
+    if message.nil?
+      @message = '<EMPTY>'
+    else
+      @message = message
+    end
+
+    case @status
+    when OK
+      @exit_code = OK_EXIT_CODE
+    when WARNING
+      @exit_code = WARNING_EXIT_CODE
+    when CRITICAL
+      @exit_code = CRITICAL_EXIT_CODE
+    when UNKNOWN
+      @exit_code = UNKNOWN_EXIT_CODE
+    end
+  end
+
+  def status=(value)
+    if value.nil? || (value != OK && value != WARNING && value != CRITICAL && value != UNKNOWN)
+      @status = UNKNOWN
+    else
+      @status = value
+    end
+
+    case @status
+    when OK
+      @exit_code = OK_EXIT_CODE
+    when WARNING
+      @exit_code = WARNING_EXIT_CODE
+    when CRITICAL
+      @exit_code = CRITICAL_EXIT_CODE
+    when UNKNOWN
+      @exit_code = UNKNOWN_EXIT_CODE
+    end
+  end
+
+  def empty?
+    @status == UNKNOWN && (@message.nil? || @message.empty? || @message == '<EMPTY>')
+  end
+
+end

data/lib/rnagios/nagios_error.rb

@@ -0,0 +1,7 @@
+class NagiosError < StandardError
+
+  def initialize(message=nil)
+    super(message) if !message.nil? && !message.empty?
+  end
+
+end

data/lib/rnagios/nsca_host_status.rb

@@ -0,0 +1,78 @@
+# NscaHostStatus has a different set of statuses from ActiveStatus.
+# Instead of OK, WARNING, UNKNOWN, and CRITICAL, NscaHostStatus
+# uses UP, DOWN, and UNREACHABLE.  These statuses are all meant to apply
+# only to hosts and not services.  Also, passive checks do not need to
+# concern themselves with exit codes, as their output will be sent via
+# the send_nsca program to a Nagios server for processing.  It just so
+# happens that the 'host status' is exactly the same as the UNIX/Linux
+# exit codes, but we use the @passive_code attribute anyway for clarity.
+class NscaHostStatus < Status
+
+  # Stand-in for host status
+  attr_reader :passive_code
+
+  # Host is up and available
+  UP = 'UP'
+  # Host is down and unavailable
+  DOWN = 'DOWN'
+  # Host is unreachable (e.g. behind a router or host that is down)
+  UNREACHABLE = 'UNREACHABLE'
+
+  # Host status code for UP
+  UP_CODE = 0
+  # Host status code for DOWN
+  DOWN_CODE = 1
+  # Host status code for UNREACHABLE
+  UNREACHABLE_CODE = 2
+
+  # If status is not given, it will default to UNREACHABLE.  If message
+  # is not given, it will default to <EMPTY>.  UNIX/Linux exit codes
+  # are assigned automatically.
+  def initialize(status=nil, message=nil)
+    if status.nil? || (status != UP && status != DOWN && status != UNREACHABLE)
+      @status = UNREACHABLE
+    else
+      @status = status
+    end
+
+    if message.nil?
+      @message = '<EMPTY>'
+    else
+      @message = message
+    end
+
+    case @status
+    when UP
+      @passive_code = UP_CODE
+    when DOWN
+      @passive_code = DOWN_CODE
+    when UNREACHABLE
+      @passive_code = UNREACHABLE_CODE
+    end
+  end
+
+  # If status is not given, it will default to UNREACHABLE.  Changing
+  # the status will change the passive_code accordingly
+  def status=(value)
+    if value.nil? || (value != UP && value != DOWN && value != UNREACHABLE)
+      @status = UNREACHABLE
+    else
+      @status = value
+    end
+
+    case @status
+    when UP
+      @passive_code = UP_CODE
+    when DOWN
+      @passive_code = DOWN_CODE
+    when UNREACHABLE
+      @passive_code = UNREACHABLE_CODE
+    end
+  end
+
+  def empty?
+    @status == UNREACHABLE && (@message.nil? || @message.empty? || @message == '<EMPTY>')
+  end
+
+end
+  

data/lib/rnagios/nsca_service_status.rb

@@ -0,0 +1,62 @@
+# NscaServiceStatus is essentially an ActiveStatus object with
+# only an extra :passive_code attribute.
+class NscaServiceStatus < ActiveStatus
+
+  # Stand-in for return code
+  attr_reader :passive_code
+
+  # We call super.initialize to setup the ActiveStatus object then
+  # we set @passive_code to @exit_code.  The values are exactly the
+  # same
+  def initialize(status=nil, message=nil)
+    if status.nil? || (status != OK && status != WARNING && status != CRITICAL && status != UNKNOWN)
+      @status = UNKNOWN
+    else
+      @status = status
+    end
+
+    if message.nil?
+      @message = '<EMPTY>'
+    else
+      @message = message
+    end
+
+    case @status
+    when OK
+      @passive_code = OK_EXIT_CODE
+    when WARNING
+      @passive_code = WARNING_EXIT_CODE
+    when CRITICAL
+      @passive_code = CRITICAL_EXIT_CODE
+    when UNKNOWN
+      @passive_code = UNKNOWN_EXIT_CODE
+    end
+  end
+
+  # We call super.status to setup the ActiveStatus object then
+  # we set @passive_code to @exit_code.  The values are exactly the
+  # same
+  def status=(value)
+    if value.nil? || (value != OK && value != WARNING && value != CRITICAL && value != UNKNOWN)
+      @status = UNKNOWN
+    else
+      @status = value
+    end
+
+    case @status
+    when OK
+      @passive_code = OK_EXIT_CODE
+    when WARNING
+      @passive_code = WARNING_EXIT_CODE
+    when CRITICAL
+      @passive_code = CRITICAL_EXIT_CODE
+    when UNKNOWN
+      @passive_code = UNKNOWN_EXIT_CODE
+    end
+  end
+
+  def empty?
+    @status == UNKNOWN && (@message.nil? || @message.empty? || @message == '<EMPTY>')
+  end
+
+end

data/lib/rnagios/plugin.rb

@@ -0,0 +1,369 @@
+# There are two types of checks you can perform that Nagios will process:
+# active and NSCA checks.  Active checks are run on the Nagios
+# monitoring host and actively check services.  NSCA checks are run
+# by remote hosts and their output is sent back to the ` host
+# for processing by the NSCA daemon.  Active checks are "actively" run
+# by Nagios; NSCA checks are "passively" run by other servers.
+#
+# To create an active check, create logic that measures a service
+# (such as a database, a web service, or a custom application) and
+# returns a fully-populated ActiveStatus object.  By the same token,
+# to create an NSCA check, create logic that measures a service and
+# returns a fully-populated NscaHostStatus or NscaServiceStatus object.
+# (There are many gems available that can help you connect to services
+# and parse their output; this class does not attempt to be everything
+# to everyone.)
+#
+# Plugin handles the formatting, and provides the appropriate
+# exit code so Nagios will process it correctly.  When running on
+# UNIX/Linux, Nagios will check the exit codes along with the string
+# in the status message to determine how to handle it.  Under Windows,
+# Nagios only cares about the strings in the status message.
+#
+# Plugin allows you to use an optional configuration file in case your
+# plugin requires access to multiple configuration parameters.  If
+# you supply a configuration file, it should be a YAML file, and it will
+# be parsed in the check method before the measure method is called.
+# measure() can then use the @config attribute to access configuration
+# parameters.  The configuration file is expected to be in the same
+# directory as the plugin.
+class Plugin
+
+  # Internal configuration access attribute
+  attr_reader :config
+  # Name of the plugin (e.g. check_service)
+  attr_reader :name
+
+  # Warning level
+  attr_accessor :w
+  # Critical level
+  attr_accessor :c
+  # Path to the configuration file
+  attr_accessor :config_file
+  # Name of host to check
+  attr_accessor :host
+  # Port of host to check (defaults to 80)
+  attr_accessor :port
+  # Set to true to use SSL
+  attr_accessor :use_ssl
+  # Whether we verify the host if using SSL to connect
+  attr_accessor :verify_ssl
+
+  # Plugin expects a hash with the following symbols:
+  #   :host         # The hostname or IP address to check (required)
+  #   :port         # The port on :host to check (default: 80)
+  #   :name         # The name of the service, usually starting with 'check_' (default: <UNDEFINED>)
+  #   :config_file  # Path to YAML configuration file (optional)
+  #   :w            # Warning level (optional, usually numeric)
+  #   :c            # Critical level (optional, usually numeric)
+  #   :use_ssl      # True to use SSL, false otherwise (default: false)
+  #   :verify_ssl   # If using SSL, set to true to verify the server (default: false)
+  # :host must be provided, otherwise a NagiosError will be thrown.
+  def initialize(params={})
+    if !blank?(params)
+      if params[:host].nil?
+        raise NagiosError.new('Hostname must be provided')
+      else
+        @host = params[:host]
+      end
+      if params[:port].nil?
+        @port = 80
+      elsif params[:port].is_a?(String)
+        begin
+          @port = params[:port].to_i
+        rescue
+          raise NagiosError.new('Port number must be numeric')
+        end
+      else
+        @port = params[:port]
+      end
+      @name = default(params[:name])
+      @config_file = params[:config_file] if !params[:config_file].nil?
+      @w = params[:w] if !params[:w].nil?
+      @c = params[:c] if !params[:c].nil?
+      if !params[:use_ssl].nil?
+        @use_ssl = params[:use_ssl]
+      else
+        @use_ssl = false
+      end
+      if !params[:verify_ssl].nil?
+        @verify_ssl = params[:verify_ssl]
+      else
+        @verify_ssl = false
+      end
+    else
+      raise NagiosError.new('At least hostname must be provided')
+    end
+  end
+
+  # The name of the Plugin.  This should conform to the Nagios
+  # convention of "check_<service>" as the name of the script to
+  # run.  The name can have extensions such as ".py" or ".rb";
+  # they will be stripped off.  This name will show up in capital
+  # letters as the service name in Nagios status information columns
+  def name=(value)
+    @name = default(value)
+  end
+
+  # Returns a Status with the message to print to STDOUT
+  # and an exit code to return if running under UNIX/Linux.  If
+  # the operating system is not UNIX/Linux, the exit_code will be
+  # zero (0).  If the measure method throws an exception or the
+  # status object is not a properly-populated Status object,
+  # then this method will throw a NagiosError.
+  #
+  # This method will run the user-overloaded measure() method.  If
+  # measure() should return an uncaught exception, the exception
+  # message will be returned to Nagios as an UNKNOWN status, so
+  # make sure to handle all known error conditions within measure()
+  # to make the output of your script meaningful.
+  #
+  # Scripts should call this method at the very end.  The general
+  # flow of a script running on UNIX/Linux should be as follows:
+  # 
+  #   class MyCheck < Nagios::Plugin
+  #     def measure
+  #       stat = Nagios::ActiveStatus.new
+  #       stat.status = <...service check code goes here, returns Nagios::Status::<constant> status...>
+  #       stat.message = <...service message state construction goes here...>
+  #       # UNIX/Linux exit codes are taken core of for you
+  #     end
+  #   end
+  #
+  #   plugin = MyCheck.new( { :name => 'check_service', :host = '<my_host>', :w => 15, :c => 5 })
+  #   status = plugin.check
+  #   $stdout.puts status.message  # status.message needs to be output to STDOUT
+  #   exit status.exit_code  # For UNIX/Linux
+  #
+  # It is up to the developer to handle command-line arguments.
+  # (See the gem trollop for a good example of command-line parameter
+  # hadling.)  Nagios plugins usually accept "w" as a warning level and "c"
+  # as a critical level, but it is up to the plugin developer if
+  # these values are used in the measure method.
+  def check
+    start_time = Time.now
+    end_time = -1
+    status = nil
+
+    # If there is a config file, load it
+    if !blank? @config_file
+      @config = YAML.load_file(@config_file)
+    end
+
+    # measure() is where the magic happens.  measure() should
+    # return a Status object.  Any exceptions thrown
+    # in measure() drop right out, so make sure you handle all
+    # error conditions appropriately before using your plugin
+    # with Nagios
+    status = measure
+
+    # Mark the end time for Nagios performance stats
+    end_time = Time.now        
+
+    # Since we can't effectively check for exceptions, we make
+    # sure we get a good Status
+    if !valid?(status)
+      raise NagiosError.new('Returned status must be an instance or subclass of Status')
+    elsif !valid_status?(status)
+      raise NagiosError.new('Status must have be a valid status constant')
+    elsif status.is_a?(NscaHostStatus) && !valid_passive_code?(status)
+      raise NagiosError.new('Status passive code is invalid')
+    elsif status.is_a? ActiveStatus
+      if status.is_a? NscaServiceStatus
+        if !valid_passive_code? status 
+          raise NagiosError.new('Status passive code is invalid')
+        end
+      elsif !valid_exit_code? status
+        raise NagiosError.new('Status exit code is invalid')
+      end
+    elsif blank?(status.message)
+      raise NagiosError.new('Status message must not be nil or empty')
+    end
+
+    # Status checks out as valid -- we now format the output based on
+    # the type of Status received
+    if status.is_a? NscaHostStatus
+      status.message = format_passive_host_check(status)
+    elsif status.is_a? NscaServiceStatus
+      status.message = format_passive_service_check(status)
+    else
+      status.message = format_active_service_check(status, start_time, end_time)
+    end
+
+    status
+  end
+
+  # This method should be overloaded by classes that subclass
+  # Plugin.  For active checks, measure() should return an
+  # ActiveStatus object.  For passive checks, measure()
+  # should return a NscaHostStatus or NscaServiceStatus
+  # object.
+  #
+  # The developer of must determine how to best check the
+  # service in question.  Below is an example of how measure()
+  # should be structured.
+  #
+  #   status = ''
+  #   message = ''
+  #   begin
+  #     random_measure = 1 + rand(4) # Bad real-world event simulator
+  #     if random_measure == 1
+  #       status = ActiveStatus::OK
+  #       message = 'Everything looks good'
+  #     elsif random_measure == 2
+  #       status = ActiveStatus::WARNING
+  #       message = 'Keep an eye on this service' 
+  #     elsif random_measure == 3
+  #       status = ActiveStatus::CRITICAL
+  #       message = 'There''s a problem'
+  #     else
+  #       status = ActiveStatus::UNKNOWN
+  #       message = 'Can''t figure out what''s going on'
+  #     end
+  #   rescue StandardError => e
+  #     # You should decide what kind of status to return in case
+  #     # of an error.  You should not let errors go unhandled in
+  #     # a Nagios plugin, otherwise Nagios will handle it as a
+  #     # failure and you may be spammed with unnecessary notifications
+  #     # for something that should only merit a warning
+  #     status = ActiveStatus::WARNING
+  #     message = 'Possibly recoverable error occurred'
+  #   rescue Exception => e
+  #     # It is wise to account for exceptions you don't anticipate
+  #     # and create a status that is more meaningful for your service.
+  #     # For your situation, unanticipated errors may be critical, or
+  #     # they may be worth only a warning; you decide
+  #     status = ActiveStatus::CRITICAL
+  #     message = 'Something we didn''t anticipate occurred'
+  #   ensure
+  #     # Make sure the returned status has something in it if all else fails
+  #     status = ActiveStatus::UNKNOWN
+  #     message = 'Don''t know what happened'
+  #   end
+  #   ActiveStatus.new(status, message)
+  def measure
+    # Overload this method to populate the status object
+    raise NagiosError.new('Call to measure should not invoke base class measure method; measure method should be overridden')
+  end
+
+private
+    # This method uses the value of @name to create a default.
+    # As long as the name sticks to the Nagios convention of
+    # "check_<service>", this method can make a good guess as
+    # to the default it should create
+    def default(value=nil)
+      if !blank? value
+        if value.downcase.include? 'check_'
+          value.downcase.gsub('check_', '').upcase
+        else
+          value.upcase
+        end
+      elsif blank?(value) && !blank?(@name)
+        @name.downcase.gsub('check_', '').upcase
+      else
+        '<UNDEFINED>'
+      end
+    end
+
+    def format_active_service_check(status, start_time, end_time)
+      @name + ' ' + status.to_s + ' | time=' + (end_time - start_time).to_s + ';;;' + @w.to_s + ';' + @c.to_s
+    end
+
+    # NSCA check results are different from active check results
+    # [<timestamp>] PROCESS_SERVICE_CHECK_RESULT;<host_name>;<svc_description>;<return_code>;<plugin_output>
+    def format_passive_service_check(status)
+      '[' + Time.now.to_i.to_s + '] PROCESS_SERVICE_CHECK_RESULT;' + @host + ';' + @name + ';' + status.passive_code.to_s + ';' + status.message
+    end
+
+    # NSCA check results are different from active check results
+    # [<timestamp>] PROCESS_HOST_CHECK_RESULT;<host_name>;<host_status>;<plugin_output>
+    def format_passive_host_check(status)
+      '[' + Time.now.to_i.to_s + '] PROCESS_HOST_CHECK_RESULT;' + @host + ';' + status.passive_code.to_s + ';' + status.message
+    end
+
+    def valid?(status)
+      blank?(status) || !status.is_a?(Status) ? false : true
+    end
+
+    def valid_status?(status)
+      if blank?(status) || blank?(status.status) || !status.status.is_a?(String)
+        false
+      elsif status.is_a?(ActiveStatus) || status.is_a?(NscaServiceStatus)
+        case status.status
+        when ActiveStatus::OK
+          true
+        when ActiveStatus::WARNING
+          true
+        when ActiveStatus::UNKNOWN
+          true
+        when ActiveStatus::CRITICAL
+          true
+        else
+          false
+        end
+      elsif status.is_a? NscaHostStatus
+        case status.status
+        when NscaHostStatus::UP
+          true
+        when NscaHostStatus::DOWN
+          true
+        when NscaHostStatus::UNREACHABLE
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def valid_exit_code?(status)
+      if blank?(status) || !status.exit_code.is_a?(Integer) || !status.is_a?(ActiveStatus)
+        false
+      else
+        case status.exit_code
+        when ActiveStatus::OK_EXIT_CODE
+          true
+        when ActiveStatus::WARNING_EXIT_CODE
+          true
+        when ActiveStatus::UNKNOWN_EXIT_CODE
+          true
+        when ActiveStatus::CRITICAL_EXIT_CODE
+          true
+        else
+          false
+        end
+      end
+    end
+
+    def valid_passive_code?(status)
+      if blank?(status) || !status.passive_code.is_a?(Integer)
+        false
+      elsif status.is_a?(NscaServiceStatus)
+        case status.passive_code
+        when ActiveStatus::OK_EXIT_CODE
+          true
+        when ActiveStatus::WARNING_EXIT_CODE
+          true
+        when ActiveStatus::UNKNOWN_EXIT_CODE
+          true
+        when ActiveStatus::CRITICAL_EXIT_CODE
+          true
+        else
+          false
+        end
+      elsif status.is_a?(NscaHostStatus)
+        case status.passive_code
+        when NscaHostStatus::UP_CODE
+          true
+        when NscaHostStatus::DOWN_CODE
+          true
+        when NscaHostStatus::UNREACHABLE_CODE
+          true
+        else
+          false
+        end
+      else
+        false
+      end
+    end
+
+end

data/lib/rnagios/status.rb

@@ -0,0 +1,28 @@
+# Superclass for ActiveStatus, NscaHostStatus, and NscaServiceStatus
+class Status
+
+  # A Nagios::Status constant
+  attr_accessor :status
+  # UNIX/Linux exit code
+  attr_reader :exit_code
+  # The status output from the measure() method
+  attr_accessor :message
+
+  def initialize(status=nil, message=nil)
+    @status = status if !status.nil? && !status.empty?
+    @message = message if !message.nil? && !message.empty?
+    @exit_code = 0
+  end
+
+  # Formats the given message for output to Nagios
+  def to_s
+    @status = '' if @status.nil?
+    @message = '' if @message.nil?
+    @status + ': ' + @message
+  end
+
+  def empty?
+    (@status.nil? && @message.nil?) || (@status.empty? && @message.empty?)
+  end
+
+end

data/lib/rnagios.rb

@@ -0,0 +1,30 @@
+require 'rnagios/status'
+require 'rnagios/active_status'
+require 'rnagios/nsca_host_status'
+require 'rnagios/nsca_service_status'
+require 'rnagios/nagios_error'
+require 'rnagios/plugin'
+
+def blank?(value)
+  value.nil? || value.empty?
+end
+
+# Check for Windows OS
+def windows?
+  (/cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM) != nil
+end
+
+# Check for Mac OS
+def mac?
+ (/darwin/ =~ RUBY_PLATFORM) != nil
+end
+
+# Check for UNIX or UNIX-like OS
+def unix?
+  !OS.windows?
+end
+
+# Check for Linux
+def linux?
+  OS.unix? and not OS.mac?
+end