Zabby

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

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 ~/.zabbyrc is read on startup unless the option “--no-rcfile” 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 .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

Sample “.zabbyrc”

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

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 ~/.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

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 “#!/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’).

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 proxy_* 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. IT BASICALLY RUNS ANYWHERE!
JSON library: ‘json’ or ‘json_pure’
OptionParser
Readline (optionnal, used by the interactive shell)

References

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

Contributing

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.

Author

Farzad FARID [email protected]

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

License

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