zenoss_client 0.1.0 → 0.5.0

data/README.textile

@@ -0,0 +1,67 @@
+h1. zenoss_client: A Ruby library for JSON/REST access to Zenoss
+
+This is a work-in-progress to create an easy to use client JSON/REST API for
+Zenoss (http://www.zenoss.com) written in Ruby.  I love Zenoss as a product,
+but I am much more efficient in Ruby than Python so I decided to start
+hacking this library together.  It is very incomplete and I am just adding
+functionality as I need it or it is requested.
+
+Cheers,
+
+Dan Wanek
+
+h2. CHANGES SINCE THE 0.1.x BRANCH
+
+Starting with 0.5.0 I am trying to incorporate as much of the new JSON API
+into this library as possible because the type conversion hackery that was
+present in the REST code is largely unnecessary. Please note that the
+initialization is much different because we are using the sign-in form auth
+instead of the Basic auth of the previous version. This is because the JSON
+calls do not support Basic authentication.
+
+There is still much work that needs to be done in order to fully implement
+all of the JSON methods. For now many of the older features fall back to
+REST and some of those will always rely on REST because they are not
+currently supported in the JSON API.
+
+
+h2. REQUIREMENTS:
+Gems:
+
+* tzinfo: For Python DateTime to Ruby DateTime conversion
+
+
+h2. UNSUPPORTED REST METHODS:
+Some methods within Zope are unsupported due to type conversion issues.
+I have created a work-around but you must add a custom Python script
+to Zope in order to do this.  Please see this blog post for information
+on how add the custom script:
+
+http://distributed-frostbite.blogspot.com/2010/04/using-ruby-with-zenoss-part-1.html
+
+UPDATE: The script itself is now part of the source tree and can be found here: tools/callZenossMethod.py
+It should still be installed in the same fashion as the blog post steps through.
+
+== TO USE:
+A gem is now available.  'gem install zenoss_client'
+
+	require 'zenoss'
+  require 'date'
+
+  server = 'https://zenhost:port/zport/dmd'
+  user, pass = 'zuser', 'zpass'
+  @zen = Zenoss.connect server, user, pass
+  dev = (@zen.find_devices_by_name 'myservername').first
+
+  # Get RRD data for this device
+  rrdpts = dev.get_rrd_data_points
+  datapoints = dev.fetch_rrd_value rrdpts.first.name, (DateTime.now - 1)
+
+	# Get the uptime of the device
+	dev.sys_uptime
+
+  # Get a list of events for this system
+  dev.get_events
+
+
+Have fun and let me know what needs to be fixed / added.

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.5.0

data/lib/{events/zevent.rb → ext/ipaddr.rb}

@@ -17,13 +17,16 @@
 # You should have received a copy of the GNU General Public License along
 # with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
 #############################################################################
+require 'ipaddr'
+
+class IPAddr
+
+  # This is an extension to the base IPAddr that adds the ability to convert
+  # an IP Address from it's network form to a string in the standard dotted
+  # decimal format
+  def self.inet_ntoa(addr)
+    [addr].pack("N").unpack("C*").join "."
+  end
+end
 
-module Zenoss
-  module Event
-    class ZEvent < Event
-      include Zenoss
-      include Zenoss::Event
 
-    end # ZEvent
-  end # Event
-end # Zenoss

data/lib/zenoss.rb

@@ -21,94 +21,18 @@ require 'rubygems'
 require 'date'
 require 'tzinfo'
 require 'uri'
+require 'httpclient'
+require 'json'
 
-module Zenoss
-
-  # Set the Base URI of the Zenoss server
-  #
-  # @param [URI, String] uri is the URL we use to connect to the Zenoss server
-  # @return [URI] the URI that was parsed and used as our base connection
-  def Zenoss.uri(uri)
-    if(uri.kind_of?(URI))
-      uri.path << '/' unless(uri.path.index /\/$/)
-      const_set(:BASE_URI, uri)
-    else
-      uri << '/' unless(uri.index /\/$/)
-      const_set(:BASE_URI, URI.parse(uri))
-    end
-  end
-
-  # @param [String] user
-  # @param [String] pass
-  # @return [Boolean]
-  def Zenoss.set_auth(user, pass)
-    const_set(:USER, user)
-    const_set(:PASS, pass)
-    true
-  end
-
-  # @return [Model::DeviceClass] the base DeviceClass /zport/dmd/Devices
-  def Zenoss.devices
-    Model::DeviceClass.new('/zport/dmd/Devices')
-  end
-
-  # @return [Model::ServiceOrganizer] the base ServiceOrganizer /zport/dmd/Services
-  def Zenoss.services
-    Model::ServiceOrganizer.new('/zport/dmd/Services')
-  end
+# An extension to IPAddr for address conversion
+require 'ext/ipaddr'
 
-  # @return [Model::System] the base System /zport/dmd/Systems
-  def Zenoss.systems
-    Model::System.new('/zport/dmd/Systems')
-  end
-
-
-
-  private
-
-  # Prepend the appropriate path and call the REST method on the URL set with Zenoss#uri
-  #
-  # @param [String] req_path the request path of the REST method
-  # @return [String] the response body of the REST call
-  def rest(req_path)
-    Net::HTTP.start(Zenoss::BASE_URI.host,Zenoss::BASE_URI.port) {|http|
-      req = Net::HTTP::Get.new("#{BASE_URI.path}#{req_path}")
-      puts "Request: #{BASE_URI.path}#{req_path}"
-      req.basic_auth USER, PASS if USER
-      response = http.request(req)
-      response.body.chomp! unless response.body.nil?
-      return(response.body)
-    }
-  end
+module Zenoss
 
-  # Call a custom Zope method to work around some issues of unsupported or bad behaving
-  # REST methods.
-  # @see http://gist.github.com/343627 for more info.
-  #
-  # @param [String] req_path the request path of the REST method ( as if it wasn't misbehaving )
-  #   @example req_path
-  #     getRRDValues?dsnames=['ProcessorTotalUserTime_ProcessorTotalUserTime','MemoryPagesOutputSec_MemoryPagesOutputSec']
-  # @param [String] callback_func the name of the function to be called on the returned object before giving it back to Ruby
-  # @param [String] callback_attr the name of the attribute to fetch on the returned object before giving it back to Ruby
-  # @return [String] the response body of the REST call
-  def custom_rest(req_path,callback_func = nil, callback_attr=nil)
-    meth,args = req_path.split('?')
-    meth = "callZenossMethod?methodName=#{meth}"
-    unless args.nil?
-      meth << '&args=['
-      # Remove the named parameters because we can't dynamically call named parameters in Python.
-      # This method uses positional parameters via the passed Array (Python List).
-      args.split('&').inject(nil) do |delim,arg|
-        arg.gsub!(/'/, "'''") # This may cause problems if the passed argument is already triple quoted.
-        meth << "#{delim}#{arg.split('=').last}"
-        delim = '===' if delim.nil?
-      end
-      meth << ']'
-    end
-    meth << "&filterFunc=#{callback_func}" unless callback_func.nil?
-    meth << "&filterAttr=#{callback_attr}" unless callback_attr.nil?
-    puts "METHOD: #{meth}"
-    rest(meth)
+  # initialize a connection to a Zenoss server. This is the same as doing
+  #   Zenoss::Connection.new(server,user,pass)
+  def Zenoss.connect(server, user, pass)
+    Connection.new(server,user,pass)
   end
 
   # Some of the REST methods return Strings that are formated like a Python list.
@@ -172,9 +96,7 @@ module Zenoss
   # @return [Hash,nil] a Ruby Hash
   def pdict_to_hash(dict)
     return nil if dict.nil?
-    puts "Dict: #{dict}"
     dict = sanitize_str(dict)
-    puts "New Dict: #{dict}"
     dict = dict.sub(/^\{(.*)\}$/,'\1').split(/[,:]/).map do |str|
       str.strip
     end
@@ -214,5 +136,7 @@ module Zenoss
 
 end # Zenoss
 
-require 'model/model'
-require 'events/event'
+require 'zenoss/connection'
+require 'zenoss/exceptions'
+require 'zenoss/model'
+require 'zenoss/events'

data/lib/zenoss/connection.rb

@@ -0,0 +1,62 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dwanek@nd.gov>
+#
+#
+# This file is part of zenoss_client.
+# 
+# zenoss_client is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# zenoss_client is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+require 'zenoss/jsonapi'
+require 'zenoss/restapi'
+
+module Zenoss
+
+  # This class represents a connection into a Zenoss server.
+  class Connection
+    include Zenoss
+    include Zenoss::JSONAPI
+    include Zenoss::JSONAPI::DeviceRouter
+    include Zenoss::JSONAPI::EventsRouter
+    include Zenoss::JSONAPI::ReportRouter
+    include Zenoss::RESTAPI
+
+    def initialize(url, user, pass)
+      @zenoss_uri = (url.is_a?(URI) ? url : URI.parse(url))
+      @request_number = 1
+      @httpcli = HTTPClient.new
+      sign_in(user,pass)
+    end
+
+    private
+
+    # Sign-in to this Zenoss instance.
+    def sign_in(user,pass)
+      login_parms = {
+        :__ac_name     => user,
+        :__ac_password => pass,
+        :submitted     => true,
+        :came_from     => "#{@zenoss_uri}/zport/dmd",
+      }
+      login_path = "#{@zenoss_uri}/zport/acl_users/cookieAuthHelper/login"
+      resp = @httpcli.post login_path, login_parms
+      if(resp.status == 302)
+        login_path = resp.header['Location'].first
+        resp = @httpcli.post login_path, login_parms 
+        raise ZenossError, "(HTTP Response #{resp.status}) Could not authenticate to #{@zenoss_uri}" unless resp.status == 200
+      end
+      true
+    end
+
+  end # Connection
+end # Zenoss

data/lib/{model/events/event_class.rb → zenoss/events.rb}

@@ -17,3 +17,5 @@
 # You should have received a copy of the GNU General Public License along
 # with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
 #############################################################################
+require 'zenoss/events/event'
+require 'zenoss/events/zevent'

data/lib/{model/rrd_view.rb → zenoss/events/event.rb}

@@ -17,30 +17,36 @@
 # You should have received a copy of the GNU General Public License along
 # with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
 #############################################################################
+
 module Zenoss
-  module Model
-    module RRDView
-      include Zenoss::Model
+  module Events
+    class Event < OpenStruct
+
+      # Initialize this object from a Hash returned via the JSON api
+      # @param[Zenoss] zenoss the current instance we are connecting with
+      # @param[Hash] zhash a hash of values used to create this Event instance
+      def initialize(zenoss,zhash)
+        @zenoss = zenoss
+        super zhash
+        self.firstTime = DateTime.parse(self.firstTime) if self.firstTime
+        self.lastTime  = DateTime.parse(self.lastTime) if self.lastTime
+      end
 
-      # @return [Array] of datapoints
-      def get_rrd_data_points
-        (plist_to_array( custom_rest('getRRDDataPoints') )).map do |dstr|
-          dp = dstr.sub(/^<([\w]+)\s+at\s+(.*)>$/,'\2')
-          RRDDataPoint.new(dp)
+      def detail(history = false)
+        data = {
+          :evid => self.evid,
+          :history => history,
+        }
+        resp = @zenoss.json_request('EventsRouter', 'detail', [data])
+        resp['event'].first.each_pair do |k,v|
+          self.new_ostruct_member(k)
+          @table[k.to_sym] = v
         end
       end
 
-      # Get key/value pairs of RRD Values for the passed data source names.
-      #
-      # @param [Array <String>] dsnames data source names from RRDDataPoint#name
-      # @return [Hash] key/value pairs of data source name and data source values
-      def get_rrd_values(dsnames)
-        pdict_to_hash(custom_rest("getRRDValues?dsnames=[#{dsnames.join(',')}]"))
+      def acknowledge
       end
 
-    end # RRDView
-  end # Model
+    end # Event
+  end # Events
 end # Zenoss
-
-# Load the RRD related files
-require 'model/rrd/rrd_data_point'

data/lib/zenoss/events/zevent.rb

@@ -0,0 +1,25 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dwanek@nd.gov>
+#
+#
+# This file is part of zenoss_client.
+# 
+# zenoss_client is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# zenoss_client is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+module Zenoss
+  module Events
+    class ZEvent < Event; end
+  end # Events
+end # Zenoss

data/lib/zenoss/exceptions.rb

@@ -0,0 +1,25 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dwanek@nd.gov>
+#
+#
+# This file is part of zenoss_client.
+# 
+# zenoss_client is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# zenoss_client is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+module Zenoss
+
+  class ZenossError < StandardError; end
+
+end

data/lib/zenoss/jsonapi.rb

@@ -0,0 +1,84 @@
+#############################################################################
+# Copyright © 2010 Dan Wanek <dwanek@nd.gov>
+#
+#
+# This file is part of zenoss_client.
+# 
+# zenoss_client is free software: you can redistribute it and/or
+# modify it under the terms of the GNU General Public License as published
+# by the Free Software Foundation, either version 3 of the License, or (at
+# your option) any later version.
+# 
+# zenoss_client is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License along
+# with zenoss_client.  If not, see <http://www.gnu.org/licenses/>.
+#############################################################################
+
+module Zenoss
+  module JSONAPI
+    ROUTERS = {
+      'MessagingRouter' => 'messaging',
+      'EventsRouter'    => 'evconsole',
+      'ProcessRouter'   => 'process',
+      'ServiceRouter'   => 'service',
+      'DeviceRouter'    => 'device',
+      'NetworkRouter'   => 'network',
+      'TemplateRouter'  => 'template',
+      'DetailNavRouter' => 'detailnav',
+      'ReportRouter'    => 'report',
+      'MibRouter'       => 'mib',
+      'ZenPackRouter'   => 'zenpack',
+    }
+
+    def json_request(router, method, data={})
+      raise ZenossError, "Router (#{router}) not found" unless ROUTERS.has_key?(router)
+
+      req_url = "#{@zenoss_uri}/zport/dmd/#{ROUTERS[router]}_router"
+      req_headers = {'Content-type' => 'application/json; charset=utf-8'}
+      req_body = [{
+        :action => router,
+        :method => method,
+        :data   => data,
+        :type   => 'rpc',
+        :tid    => @request_number,
+      }].to_json
+
+      @request_number += 1
+
+      resp = @httpcli.post req_url, req_body, req_headers
+      parse_json(resp)
+    end
+
+    private
+
+    # Check the HTTP and JSON response for errors and return JSON response
+    def parse_json(resp)
+      begin
+        if(resp.status != 200)
+          raise ZenossError, "Bad HTTP Response #{resp.status}: Cound not make JSON call"
+        end
+
+        json = JSON.load(resp.body.content)
+        # Check for JSON success. There are some exceptions where this doesn't make sense:
+        #   1. Sometimes the 'success' key does not exist like in EventsRouter#query
+        #   2. When json['result'] is not a Hash like a return from ReportRouter#get_tree
+        if(json['result'].is_a?(Hash) && json['result'].has_key?('success') && !json['result']['success'])
+          raise ZenossError, "JSON request '#{json['method']}' on '#{json['action']}' was unsuccessful"
+        end
+
+        json['result']
+      rescue JSON::ParserError => e
+        raise ZenossError, "Invalid JSON response: #{e.message}"
+      end
+    end
+
+  end
+end
+
+require 'zenoss/jsonapi/device_router'
+require 'zenoss/jsonapi/events_router'
+require 'zenoss/jsonapi/report_router'