Zabby¶ ↑

Zabby is a Ruby library and client for Zabbix. It provides a simple and clean interface to the Zabbix Web Services.

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.

• 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.

See the [ChangeLog.rdoc] file.

All the settings can be used interactively or written in a configuration file. The file ~/.zabbyrc is read on startup unless the option “--no-rcfile” is used.

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

The following settings can be configured with the ‘set’ command:

server

Zabbix webservice URL. If the URL does not end with .php then /api_jsonrpc.php 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

This is a configuration .zabbyrc 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

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.

Provided you created a ~/.zabbyrc 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

Type help to get a brief description of available commands.

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 “#!/usr/bin/env zabbysh” on the first line of the script and make it executable with “chmod +x my_zabby_commands.zby”.

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’).

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 course 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 proxy_* settings are optionnal.

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…

• Ruby 1.8.5. IT BASICALLY RUNS ANYWHERE!

• JSON library: ‘json’ or ‘json_pure’

• OptionParser

• Readline (optionnal, used by the interactive shell)

• Main web site: zabby.org

• GitHub projet: github.com/Pragmatic-Source/zabby

• RubyGems.org homepage: rubygems.org/gems/zabby

• Author’s company: www.pragmatic-source.com

All contributions are welcome. You can either open a ticket on Github, send a pull request with a patch or send an email to the author.

Farzad FARID ffarid@pragmatic-source.com

• 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.

• Adam Wiggins’s Rush for the interactive shell.

• Other Zabbix Ruby libraries (only the good parts ;) ):

zabcon

Zabcon is a command line interface for Zabbix written in Ruby

rzabbix

Zabbix API client for Ruby

rubix

Rubix is a Ruby client for Zabbix

This software is release under the Simplified BSD license. See the LICENSE file.