rbZabbix 0.1.4 → 0.1.5

data/.gitignore

@@ -0,0 +1,7 @@
+*.gem
+.bundle
+Gemfile.lock
+pkg/*
+.idea
+.yardoc
+/doc

data/.yardopts

@@ -0,0 +1 @@
+lib/**/*.rb - LICENSE TODO.rdoc ChangeLog.rdoc

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+
+# Specify your gem's dependencies in zabby.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,49 @@
+Copyright 2011-2012 Farzad FARID / Pragmatic Source. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided that the following conditions are met:
+
+   1. Redistributions of source code must retain the above copyright notice, this list of
+      conditions and the following disclaimer.
+
+   2. Redistributions in binary form must reproduce the above copyright notice, this list
+      of conditions and the following disclaimer in the documentation and/or other materials
+      provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY PRAGMATIC SOURCE ''AS IS'' AND ANY EXPRESS OR IMPLIED
+WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL PRAGMATIC SOURCE OR
+CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+The views and conclusions contained in the software and documentation are those of the
+authors and should not be interpreted as representing official policies, either expressed
+or implied, of Pragmatic Source.
+
+OTHER LICENSES COVERING PORTIONS OF CODE
+========================================
+
+Portions of code in "Zabbix::Running" were inspired by Rush (https://github.com/adamwiggins/rush):
+
+Copyright (c) 2010 Adam Wiggins
+
+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/README.rdoc

@@ -0,0 +1,246 @@
+= Zabby
+
+Zabby[http://zabby.org] is a Ruby library and client for Zabbix[http://www.zabbix.com/]. It provides a simple and
+clean interface to the {Zabbix Web Services}[http://www.zabbix.com/documentation/1.8/api].
+
+== Goals
+
+Zabby has the following caracteristics:
+- Works both as a Ruby API and a command line tool.
+- Uses an internal Ruby DSL (Domain Specific Langage) that give access to the full power of
+  Ruby scripting in your configurarion files. No need for a specific configuration language.
+- Simple design: avoids spaghetti code, WTF and facepalm, unlike some other
+  Ruby Zabbix libraries.
+
+There already are Ruby Zabbix libraries but some of them are unfinished (and apparently
+abandonned) and some other's code is too complicated or poorly designed. This is why I decided
+to write this tool for which my primary goal is to keep the code design the user interaction
+and application interface clean and simple.
+
+== Features
+
+- Low level Ruby API that maps every Zabbix API (JSON RPC) to Ruby hashes.
+- Higher level Ruby DSL, both available in pure Ruby and for writing configuration files.
+- Supports SSL and authenticated HTTP proxies.
+- Full featured IRB like shell included with Readline support. You can mix Zabbix instructions
+  with Ruby calls transparently.
+- Reads a configuration file on startup.
+
+== Changes
+
+See the [ChangeLog.rdoc] file.
+
+== Configuration
+
+All the settings can be used interactively or written in a configuration file. The file
+<tt>~/.zabbyrc</tt> is read on startup unless the option "<tt>--no-rcfile</tt>" is
+used.
+
+=== Command line
+
+The main configuration parameters are:
+
+  --[no-]rcfile [CONFIG FILE]:  Configuration file to load on startup. Default is '~/.zabbyrc'. With the 'no' prefix no configuration file will be loaded.
+  -f, --extra-file COMMAND_FILE:    Execute the instructions in COMMAND_FILE
+
+=== Zabby configuration
+
+The following settings can be configured with the '+set+' command:
+[server]  Zabbix webservice URL. If the URL does not end with <tt>.php</tt> then
+          <tt>/api_jsonrpc.php</tt> is appended automatically.
+[user]    User login with +API+ rights on the Zabbix Server. If the account does not have
+          +API+ access the connection will be refused by Zabbix.
+[password] User password.
+[proxy_host] HTTP proxy.SSL is supported and the certificate validity is not checked. *Optional*
+[proxy_user] User authentication on the proxy. *Optional*
+[proxy_password] User password on the proxy. *Optional*
+
+=== Sample ".zabbyrc"
+
+This is a configuration <tt>.zabbyrc</tt> file example, it will be loaded at startup:
+
+    # Zabby configuration
+    set :server => "https://monitoring.example.com"
+    set :user => "api_user"
+    set :password => "s3cr3t"
+    set :proxy_host => "http://10.10.10.10"
+    set :proxy_user => "john"
+    set :proxy_password => "D0e"
+    login
+
+== Examples
+
+=== Zabby on the Command Line
+
+*zabbysh* is an simple Zabbix Shell. It runs either interactively or
+can be used to execute a command file with the "-f CMD_FILE" option.
+
+If the command file does not end with "exit" then the program drops into
+the shell after executing the file.
+
+*zabbysh* provides Readline support but does no support advanced IRB features likes
+multi-lines instructions.
+
+*Note*: *zabbyrb* is another Zabbix Shell based on *IRB*. It provides the whole power of IRB
+but may be less stable than zabbysh because the IRB API is poorly documented and hard
+to use.
+
+==== Interactive shell
+
+Provided you created a <tt>~/.zabbyrc</tt> configuration file with authentication settings
+you can launch the interactive shell and start talking to the Zabbix server:
+
+    # zabbysh
+    Zabby Shell 0.1.0
+
+    ** This is a simple irb like Zabbix Shell. Multiline commands do not work for e.g. **
+    Type "help" for online documentation.
+    zabby> logged_in?
+    => true
+    zabby> Host.get "filter" => { "host" => "monitor.example.com" }, "output" => "extend"
+    => [{"snmp_errors_from"=>"0", "ipmi_port"=>"623", "outbytes"=>"0", "proxy_hostid"=>"0",
+     "maintenance_status"=>"0", "ipmi_password"=>"", "ipmi_privilege"=>"2",
+     "ipmi_disable_until"=>"0", "available"=>"1", "maintenances"=>[{"maintenanceid"=>"0"}],
+     "ipmi_error"=>"", "maintenanceid"=>"0", "useipmi"=>"0", "port"=>"10050", "useip"=>"1",
+     "ipmi_errors_from"=>"0", "maintenance_from"=>"0", "ipmi_ip"=>"", "hostid"=>"10017",
+     "ipmi_available"=>"0", "disable_until"=>"0", "ip"=>"127.0.0.1", "maintenance_type"=>"0",
+     "ipmi_authtype"=>"0", "inbytes"=>"0", "lastaccess"=>"0",
+     "host"=>"monitor.example.com", "snmp_error"=>"", "ipmi_username"=>"", "status"=>"0",
+     "dns"=>"monitor.example.com", "snmp_available"=>"0", "snmp_disable_until"=>"0",
+     "errors_from"=>"0", "error"=>""}]
+    zabby> Item.get "host" => "monitor.example.com", "output" => "refer"
+    => [{"itemid"=>"18435", "host"=>"monitor.example.com"},
+    {"itemid"=>"18436", "host"=>"monitor.example.com"},
+    {"itemid"=>"18438", "host"=>"monitor.example.com"},
+    {"itemid"=>"18439",....]
+    zabby> [...]
+    zabby> logout
+    => nil
+    zabby> exit
+
+To execute a script file before dropping into the shell type:
+
+    # zabbysh --extra-file some_zabbix_cmds.zby
+
+===== Online help
+
+Type *help* to get a brief description of available commands.
+
+==== Execute a command script
+
+To execute a script non interactively create a file and put the same
+instructions as above in it then execute *zabbysh*:
+
+    # zabbysh my_zabbix_commands.zby
+
+You can even create auto-executable scripts! Just add "<tt>#!/usr/bin/env zabbysh</tt>"
+on the first line of the script and make it executable with "<tt>chmod +x my_zabby_commands.zby</tt>".
+
+For example create the script "my_zabbix_command.zby":
+
+    #!/usr/bin/env zabbysh
+    #
+    # Zabby configuration
+    set :server => "https://monitoring.example.com"
+    set :user => "api_user"
+    set :password => "s3cr3t"
+    set :proxy_host => "http://10.10.10.10"
+    set :proxy_user => "john"
+    set :proxy_password => "D0e"
+    login
+
+    hosts = Host.get "filter" => { "host" => "monitor.example.com" }, "output" => "extend"
+    h = hosts.first
+    puts "Host #{h['host']} has IP address #{h['ip']}"
+
+    exit 0
+
+Now to execute the script you just have to type:
+
+    # ./my_zabbix_commands.zby
+
+Zabbysh script can have their own command line parameters (with libs like 'optparse').
+
+=== API use
+
+The barebone API can be used in Ruby like this:
+
+    require "rubygems"
+    require "zabby"
+    require "pp"
+
+    z = Zabby.init do
+      set :server => "https://monitoring.example.com"
+      set :user => "api_user"
+      set :password => "s3cr3t"
+      # The proxy settings are of coure optional
+      set :proxy_host => "http://10.10.10.10"
+      set :proxy_user => "john"
+      set :proxy_password => "D0e"
+      login
+    end
+
+    pp z.run { Zabby::Host.get "filter" => { "host" => "master.example.com" } }
+    pp z.run { Zabby::Item.get "host" => "master.example.com", "output" => "shorten" }
+
+
+- The _server_, _user_ and _passord_ are necessary.
+- If you don't provide the path to the JSON-RPC script "/api_jsonrpc.php" is appended
+  to the URI automatically.
+- The <em>proxy_*</em> settings are optionnal.
+
+==== Note
+
+When using the barebone API you have to prefix the Zabbix classes (Host, Item, Trigger, etc.) with the "Zabby::"
+namespace, otherwise Ruby won't find the classes. This is apparently the way Ruby 1.8.x looks up constants, the
+problem should not happen with Ruby 1.9.x...
+
+== Requirements
+
+- Ruby 1.8.5. <b>IT BASICALLY RUNS ANYWHERE!</b>
+- JSON library: 'json' or 'json_pure'
+- OptionParser
+- Readline (optionnal, used by the interactive shell)
+
+== References
+
+- Main web site: http://zabby.org
+- GitHub projet: https://github.com/Pragmatic-Source/zabby
+- RubyGems.org homepage: https://rubygems.org/gems/zabby
+- Author's company: http://www.pragmatic-source.com
+
+== Contributing
+
+All contributions are welcome. You can either
+{open a ticket on Github}[https://github.com/Pragmatic-Source/zabby/issues], send a pull request
+with a patch or send an email to the author.
+
+== Author
+
+Farzad FARID mailto:ffarid@pragmatic-source.com
+
+=== Thanks to
+
+- Jean-Hadrien Chabran (jhchabran): Advices on code design.
+- Nicolas Blanco (slainer68): Advices on code design and Triple Facepalming after reading other Ruby/Zabbix code.
+- Renaud Chaput (renchap): For suggesting the "zabby" name.
+- Folks on the irc channel #rubyonrails.fr@Freenode
+- Beta testers: A-Kaser, gaetronik.
+
+=== Sources of inspiration
+
+- Adam Wiggins's Rush[https://github.com/adamwiggins/rush] for the interactive shell.
+- Other Zabbix Ruby libraries (only the good parts ;) ):
+
+zabcon[http://trac.red-tux.net/]::
+  Zabcon is a command line interface for Zabbix written in Ruby
+
+rzabbix[http://github.com/neerfri/rzabbix]::
+  Zabbix API client for Ruby
+
+rubix[https://github.com/dhruvbansal/rubix]::
+  Rubix is a Ruby client for Zabbix
+
+== License
+
+This software is release under the <b>Simplified BSD license</b>. See the LICENSE file.

data/Rakefile

@@ -0,0 +1,11 @@
+require 'bundler'
+require 'yard'
+Bundler::GemHelper.install_tasks
+
+YARD::Rake::YardocTask.new do |t|
+  # File list is defined in '.yardopts'
+  #t.files   = ['lib/**/*.rb', '-', 'LICENSE', 'TODO.rdoc', 'ChangeLog.rdoc']
+  #t.options = ['--any', '--extra', '--opts'] # optional
+end
+
+task :default => [ :yard, :install ]

data/bin/zabbyrb

@@ -0,0 +1,86 @@
+#!/usr/bin/env ruby
+# -*- encoding: utf-8 -*-
+# Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
+# License:: Simplified BSD License
+
+# This is an experimental Zabby Shell based on IRB. It is still buggy and the code
+# is very nasty because IRB is poorly documented and hard to use as a library. Use
+# with care.
+#
+# Ugly IRB initialisation inspired by Shef (Chef's CLI) and a article on
+# StackOverflow : http://stackoverflow.com/questions/4189818/how-to-run-irb-start-in-context-of-current-class
+
+ZABBY_ROOT = File.expand_path('../../lib', __FILE__)
+$: << ZABBY_ROOT unless $:.include?(ZABBY_ROOT)
+
+require 'rbZabbix'
+require 'optparse'
+require 'ostruct'
+require 'irb'
+require 'irb/completion'
+
+
+module ZabbyRB
+  def self.irb_conf
+    @irb_conf || IRB.conf
+  end
+
+  def self.configure_irb
+    irb_conf[:MAIN_CONTEXT] = IRB::Irb.new.context
+    irb_conf[:HISTORY_FILE] = "~/.zabby_history"
+    irb_conf[:SAVE_HISTORY] = 1000
+
+    irb_conf[:IRB_RC] = lambda do |conf|
+      m = conf.main
+      leader = "(#{m.class.to_s})"
+
+      def m.help
+        puts "Help??"
+      end
+
+      # Hack without which "exit" brings us back to the main IRB context instead
+      # of exiting.
+      def m.exit
+        Kernel.exit
+      end
+
+      conf.prompt_c       = "Zabby#{leader} > "
+      conf.return_format  = " => %s \n"
+      conf.prompt_i       = "Zabby#{leader} > "
+      conf.prompt_n       = "Zabby#{leader} ?> "
+      conf.prompt_s       = "Zabby#{leader}%l> "
+    end
+  end
+
+  def self.init
+    configure_irb
+
+    puts <<EOT
+Zabby Shell #{Zabby::VERSION}, irb based shell.
+
+run `help' for help, `exit' or ^D to quit.
+
+** THIS IS AN EXPERIMENTAL SHELL, IT MAY BE UNSTABLE. USE WITH CARE. **
+Please use 'zabbysh' instead and report a bug if 'zabbyrb' does not
+work correctly.
+EOT
+  end
+end
+
+module IRB
+  class << self
+    alias :run_original_config :run_config
+
+    def run_config
+      run_original_config
+      ZabbyRB.init
+    end
+  end
+end
+
+IRB.setup nil
+#IRB.conf[:MAIN_CONTEXT] = IRB::Irb.new.context
+require 'irb/ext/multi-irb'
+IRB.irb nil, Zabby.init
+IRB.start

data/bin/zabbysh

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# -*- encoding: utf-8 -*-
+# Author:: Farzad FARID (<ffarid@pragmatic-source.com>)
+# Copyright:: Copyright (c) 2011-2012 Farzad FARID
+# License:: Simplified BSD License
+
+
+ZABBY_ROOT = File.expand_path('../../lib', __FILE__)
+$: << ZABBY_ROOT unless $:.include?(ZABBY_ROOT)
+
+require 'rbZabbix'
+require 'optparse'
+require 'ostruct'
+
+options = OpenStruct.new
+options.rcfile = File.expand_path('~/.zabbyrc')
+options.extra_file = nil
+
+opts = OptionParser.new do |opts|
+  opts.banner = <<'EOT'
+Usage: zabbysh [zabbysh options] [script [script options]]
+
+  if no 'script' file is provided an interactive shell is started.
+  Otherwise the script file is executed. To load and execute a
+  supplementary script file before the shell use the '--extra-file'
+  option.
+
+  HOW TO PASS ARGUMENTS TO THE SCRIPT
+  -----------------------------------
+
+  The Zabbysh script can have its own command line arguments. Just prepend
+  '--' before the arguments to separate them from Zabbysh's own arguments.
+EOT
+  opts.separator ""
+  opts.separator "Zabbysh specific options:"
+
+  opts.on("--[no-]rcfile [CONFIG FILE]",
+          "Configuration file to load on startup.\n\tDefault is '~/.zabbyrc'." +
+              " With the 'no' prefix no configuration file will be loaded.") do |file|
+    options.rcfile = file || nil
+  end
+  opts.on("-f", "--extra-file CMD_FILE",
+                "Execute the instructions in CMD_FILE") do |file|
+          options.extra_file = file
+  end
+
+  opts.on_tail("-h", "--help", "Show this message") do
+    puts opts
+    exit
+  end
+
+  opts.on_tail("--version", "Show version") do
+    puts <<EOT
+Zabby #{Zabby::VERSION}
+Copyright (c) 2011-2012-2012 Farzad FARID / Pragmatic Source
+Home page: http://www.zabby.org/
+License: Simplified BSD
+EOT
+    exit
+  end
+end
+
+# Parse options, extract optional script to execute and initialize Zabby.
+# Do not reorder commandline argument otherwise zabbysh's arguments will
+# get mixed up with the script's argument.
+begin
+  ENV['POSIXLY_CORRECT'] = '1'
+  opts.parse!(ARGV)
+rescue OptionParser::ParseError => e
+  STDERR.puts("ERROR: #{e.message}.")
+  STDERR.puts opts
+  exit 1
+ensure
+  ENV['POSIXLY_CORRECT'] = nil
+end
+
+# Now ARGV only contains the script's optional arguments.
+script = ARGV.shift
+z = Zabby.init
+
+# Read & execute startup file and/or command file. The true/false indicates if
+# we should fail in case the file does not exist.
+[ [ options.rcfile, false ], [ options.extra_file, true ], [ script, true ] ].each do |file, fail_on_missing|
+  if file.nil?
+    # Do nothing
+  elsif File.exist?(file)
+    begin
+      z.run(file)
+    rescue SystemExit
+      exit 0
+    rescue Exception => e
+      puts "Exception #{e.class} -> #{e.message}"
+      e.backtrace.each do |t|
+        puts "   #{::File.expand_path(t)}"
+      end
+      exit 1
+    end
+  elsif fail_on_missing # File is missing but do not fail for '.zabbyrc'
+    raise RuntimeError, "Missing Zabby script '#{file}'."
+  end
+end
+
+
+# We start the shell if a command file is not provided
+if script.nil?
+  z.shell
+end
+
+exit 0