rubyipmi 0.8.1 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e4d19bb30d3eeb5fd8777b9bb46b6e6e9b4bfa2c
-  data.tar.gz: 4c200d37a6b4764a6e6c5eac32fea5b2abb6f01d
+  metadata.gz: d461e3d295c4e31dfe971e6c9283158abe3cb9ac
+  data.tar.gz: 685a0f016ab45c40be2de1ded13da863bdba4cfb
 SHA512:
-  metadata.gz: 4fddc56cd48d76ece1d6daa4a137c05c99122d8605fea92a0253ae20cfddbccafeef504aef6964454daa6b870e35ec703598a5aa893d8926c8fdf680051e9698
-  data.tar.gz: ded7e2190931753455dd40a7814f40f619c06da4dcaa2550971b218f92ac3375401120fe620cd6e21bdb3961672aa47ddd440c1f3296869f9f13617cebce66f9
+  metadata.gz: 9dd16183f0bb968cee9043a5323a29215d1d5a0b317ac9531e859a7f68729aa647cd2016f5424fcee33b17bf3a346ef048d09a7e5e029cf63d7831117093551b
+  data.tar.gz: ab8ea8f08702fcda75e79bb02dfd7970f0ce717aa51839bfeeab478df4a6c7e49bab5cfb7d63778d5e0a7eb7d12b42057f290f35c245e500c6d97d6ba5c84ce0

data/Gemfile

@@ -1,16 +1,13 @@
 source "http://rubygems.org"
-# Add dependencies required to use your gem here.
-# Example:
-#   gem "activesupport", ">= 2.3.5"
 
-# Add dependencies to develop your gem here.
-# Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rspec", "<= 2.8.0"
+  gem "rspec", "~> 3.1"
   gem "rdoc", "~> 3.12"
   gem "bundler", ">= 1.1.5"
-  gem "jeweler", "~> 1.8.4"
-#  gem "rcov", "< 1.0.0"
+  gem "jeweler", "~> 2.0.1"
   gem "highline"
   gem "rake"
+  gem 'coveralls', require: false
+  gem 'pry'
+  gem 'pry-rescue'
 end

data/README.md

@@ -1,29 +1,29 @@
-# rubyipmi
+# Rubyipmi
 This gem is a ruby wrapper for the freeipmi and ipmitool command line tools.
 It provides a ruby implementation of ipmi commands that will make it simple to connect to BMC devices from ruby.
 
 [![Build Status](https://travis-ci.org/logicminds/rubyipmi.png)](https://travis-ci.org/logicminds/rubyipmi)
 [![Gem Version](https://badge.fury.io/rb/rubyipmi.png)](http://badge.fury.io/rb/rubyipmi)
-## Using the library in your code
-
-### Install
+[![Coverage Status](https://coveralls.io/repos/logicminds/rubyipmi/badge.png)](https://coveralls.io/r/logicminds/rubyipmi)
 
+## Projects that use Rubyipmi
+* https://github.com/sensu/sensu-community-plugins/blob/master/plugins/ipmi/check-sensor.rb
+* https://github.com/theforeman/smart-proxy
+* https://github.com/logicminds/ipmispec
 
-   1. Install the freeipmi from source (http://www.gnu.org/software/freeipmi/) or ipmitool
-   2. gem install rubyipmi
+Don't see your project listed? Create a PR with your project listed here.
+## Using the library in your code
 
-### General Usage
+### Requirements
 
-   ```Ruby
 
-   require 'rubyipmi'
-
-   ```
+   1. Install the freeipmi from source (http://www.gnu.org/software/freeipmi/) or ipmitool
+   2. `gem install rubyipmi`
 
 #### Create a connection object
 
-   ```Ruby
-
+   ```ruby
+   require 'rubyipmi'
    conn = Rubyipmi.connect("username", "password", "hostname", "providertype")
 
    ```
@@ -34,11 +34,29 @@ It provides a ruby implementation of ipmi commands that will make it simple to c
    is installed and load the first tool found.  If you specify the provider type rubyipmi will only use that specific
    provider.
 
+   Additionally, if your using [openipmi](http://openipmi.sourceforge.net) and will be using rubyipmi to connect to the
+   localhost you can utilize the openipmi driver and not have to pass in any connection parameters. Openipmi works
+   by installing a driver and makes it available to the host.  Freeipmi/Ipmitool will then try to use this driver to
+   automatically use the openipmi if no host is given.  The one caveat here is that you cannot control remote hosts using
+   openipmi.  The rubyipmi code must be executed on the host you want to control.  The upside is that you don't need
+   any credentials.  Some commands may require root privileges to run when using openipmi.
 
-#### Use power functions (not all listed)
+   ```ruby
+      conn = Rubyipmi.connect
+      conn.power.status
+   ```
+
+   Should you need to specify some additional options or the provider type
+   ```ruby
+      conn = Rubyipmi.connect(nil,nil,nil, 'freeipmi', {:privilege  =>'USER'})
+   ```
 
-   ```Ruby
 
+#### Use power functions (not all listed)
+
+   ```ruby
+   require 'rubyipmi'
+   conn = Rubyipmi.connect("username", "password", "hostname")
    conn.chassis.power.on
    conn.chassis.power.off
    conn.chassis.power.on?
@@ -49,8 +67,9 @@ It provides a ruby implementation of ipmi commands that will make it simple to c
 
 #### Boot to specific device
 
-  ```Ruby
-
+  ```ruby
+   require 'rubyipmi'
+   conn = Rubyipmi.connect("username", "password", "hostname")
    conn.chassis.bootpxe(true, false) # reboot after setting, one time boot only - non persistent
    conn.chassis.bootdisk(false, false) # boot to disk on next reboot, don't reboot automatically
 
@@ -59,8 +78,9 @@ It provides a ruby implementation of ipmi commands that will make it simple to c
 
 #### Sensors
 
-  ```Ruby
-
+  ```ruby
+    require 'rubyipmi'
+    conn = Rubyipmi.connect("username", "password", "hostname")
     conn.sensors.names
     conn.sensors.list
     conn.sensors.<sensor name>
@@ -69,8 +89,9 @@ It provides a ruby implementation of ipmi commands that will make it simple to c
 
 #### Fru
 
-  ```Ruby
-
+  ```ruby
+    require 'rubyipmi'
+    conn = Rubyipmi.connect("username", "password", "hostname")
     conn.fru.list
     conn.fru.serial
     conn.fru.manufacturer
@@ -113,7 +134,7 @@ Creating a new command is actually quite simple.  Follow these steps to wrap a f
 1.  Create a new subclass of BaseCommand
 2.  define the initialize function like so, and pass in the name of the command line tool to the super constructor.
 
-    ```Ruby
+    ```ruby
     def initialize(opts = {})
       @options = opts
       super("bmc-info", opts)
@@ -121,7 +142,7 @@ Creating a new command is actually quite simple.  Follow these steps to wrap a f
 
     ```
 
-    ```Ruby
+    ```ruby
     def initialize(opts = {})
       @options = opts
       super("ipmitool", opts)
@@ -156,7 +177,7 @@ the runcmd command.  Failure to do so will add previous options to subsequent ru
 
 Example:
 
-```Ruby
+```ruby
 def ledlight(status=false, delay=300)
       if status
         if delay <= 0
@@ -185,7 +206,7 @@ To get the results:
 
 Example:
 
-```Ruby
+```ruby
 
     def status
       value = command("--stat")
@@ -212,7 +233,7 @@ Although its not necessary to implement the command function it may be desirable
   Additionally, should this gem ever become out of date one could call the command function and pass in any
   arguments that have not already been implemented in the rest of the class.
 
-```Ruby
+```ruby
 
  def command(opt)
       status = runcmd([opt])
@@ -254,7 +275,51 @@ Although its not necessary to implement the command function it may be desirable
 IPMI is great for a vendor neutral management interface.  However, not all servers are 100% compatible with the specifications.
 In order to overcome ipmi non-compliance there will be some workarounds built into this library
 
+## Troubleshooting
 
+### Log files
+Rubyipmi has a built in logging system for debugging purposes.  By default logging is disabled.  The logger is a class instance
+variable and will stay in memory for as long as your program or interpreter is loaded. In order to enable logging
+you need to do the following.
+
+```ruby
+    require 'rubyipmi'
+    require 'logger'
+    Rubyipmi.log_level = Logger::DEBUG
+```
+This will create a log file in /tmp/rubyipmi.log which you can use to trace the commands Rubyipmi generates and runs.
+
+If you want to setup a custom logger (not required) you can also pass in a logger instance as well.
+
+```ruby
+   require 'rubyipmi'
+   require 'logger'
+   custom_logger = Logger.new('/var/log/rubyipmi_custom.log')
+   custom_logger.progname = 'Rubyipmi'
+   custom_logger.level = Logger::DEBUG
+   Rubyipmi.logger = custom_logger
+```
+
+### Diagnostics Function
+Running IPMI commands can be frustrating sometimes and with the addition of this library you are bound to find edge
+cases.  If you do find an edge case there is a easy function that will generate a diagnostics file that you can
+review and optionally create an issue with for us to work.  Without this information its really hard to help because
+every server is different. The following code will generate a file in /tmp/rubyipmi_diag_data.txt that we can use to
+as test cases.  Please look over the file for any sensitive data you don't want to share like ip/mac address.
+
+```ruby
+   require 'rubyipmi'
+   Rubyipmi.get_diag(user, pass, host)
+```
+
+You can couple this with the logger and also generate a log file of all the commands get_diag uses as well.
+
+```ruby
+   require 'rubyipmi'
+   require 'logger'
+   Rubyipmi.log_level = Logger::DEBUG
+   Rubyipmi.get_diag(user, pass, host)
+```
 
 ## Contributing to rubyipmi
 
@@ -268,7 +333,7 @@ In order to overcome ipmi non-compliance there will be some workarounds built in
 
 ## Copyright
 
-Copyright (c) 2012 Corey Osman. See LICENSE.txt for
+Copyright (c) 2015 Corey Osman. See LICENSE.txt for
 further details.
 
 

data/Rakefile

@@ -19,7 +19,7 @@ Jeweler::Tasks.new do |gem|
   # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
   gem.name = "rubyipmi"
   gem.homepage = "http://github.com/logicminds/rubyipmi"
-  gem.license = "GPLv3"
+  gem.license = "LGPLv2.1"
   gem.summary = %Q{A ruby wrapper for ipmi command line tools that supports ipmitool and freeipmi}
   gem.description = %Q{Provides a library for controlling IPMI devices using pure ruby code}
   gem.email = "corey@logicminds.biz"
@@ -66,11 +66,6 @@ RSpec::Core::RakeTask.new :integration do |spec|
   end
 end
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
-end
-
 task :default => :unit
 
 require 'rdoc/task'

data/VERSION

@@ -1 +1 @@
-0.8.1
+0.9.0

data/lib/rubyipmi.rb

@@ -19,38 +19,79 @@
 
 require 'rubyipmi/ipmitool/connection'
 require 'rubyipmi/freeipmi/connection'
+require 'logger'
 
+class NullLogger < Logger
+  def initialize(*args)
+  end
+
+  def add(*args, &block)
+  end
+end
 
 module Rubyipmi
   PRIV_TYPES = ['CALLBACK', 'USER', 'OPERATOR', 'ADMINISTRATOR']
+  attr_accessor :logger, :log_level
+
+  # set a logger instance yourself to customize where the logs should go
+  # you will need to set the log level yourself
+  def self.logger=(log)
+    @logger = log
+  end
+
+  # sets the log level, this should be called first if logging to a file is desired
+  # if you wish to customize the logging options, set the logger yourself with logger=
+  # valid levels are of the type Logger::INFO, Logger::DEBUG, Logger::ERROR, ...
+  def self.log_level=(level)
+    @log_level = level
+  end
+
+  # this is an read only method that only creates a real logger if the log_level is set
+  # if the log_level is not setup it creates a null logger which logs nothing
+  def self.logger
+    # by default the log will be set to info
+    unless @logger
+      if @log_level and @log_level >= 0
+        @logger = Logger.new('/tmp/rubyipmi.log')
+        @logger.progname = 'Rubyipmi'
+        @logger.level = @log_level
+      else
+        @logger = NullLogger.new
+      end
+    end
+    @logger
+  end
 
   def self.valid_drivers
     ['auto', "lan15", "lan20", "open"]
   end
 
+  def self.valid_providers
+    ['auto', 'ipmitool', 'freeipmi']
+  end
   # The connect method will create a connection object based the provider type passed in
   # If provider is left blank the function will use the first available provider
-
-  def self.connect(user, pass, host, provider='any', opts={:driver => 'auto',
-                                                           :timeout => 'default', :debug => false})
-
+  # When the driver is set to auto, rubyipmi will try and figure out which driver to use by common error messages.  We will most likely be using
+  # the lan20 driver, but in order to support a wide use case we default to auto.
+  def self.connect(user, pass, host, provider='any', opts={:driver => 'auto', :timeout => 'default'})
     # use this variable to reduce cmd calls
     installed = false
 
+    # allow the user to specify an options hash instead of the provider
+    # in the future I would stop using the provider and use the opts hash instead to get the provider
+    # This allows us to be a little more flexible if the user is doesn't supply us what we need.
     if provider.is_a?(Hash)
       opts = provider
-      provider = 'any'
+      provider = opts[:provider] ||= 'any'
     end
 
     # Verify options just in case user passed in a incomplete hash
     opts[:driver]  ||= 'auto'
     opts[:timeout] ||= 'default'
-    opts[:debug]   = false if opts[:debug] != true
 
-    if ! opts[:privilege].nil?
-      if ! supported_privilege_type?(opts[:privilege])
-        raise "Invalid privilege type :#{opts[:privilege]}, must be one of: #{PRIV_TYPES.join("\n")}"
-      end
+    if opts[:privilege] and not supported_privilege_type?(opts[:privilege])
+      logger.error("Invalid privilege type :#{opts[:privilege]}, must be one of: #{PRIV_TYPES.join("\n")}") if logger
+      raise "Invalid privilege type :#{opts[:privilege]}, must be one of: #{PRIV_TYPES.join("\n")}"
     end
 
     # use the first available provider
@@ -62,6 +103,7 @@ module Rubyipmi
         provider = "ipmitool"
         installed = true
       else
+        logger.error("No IPMI provider is installed, please install freeipmi or ipmitool")
         raise "No IPMI provider is installed, please install freeipmi or ipmitool"
       end
     end
@@ -69,22 +111,24 @@ module Rubyipmi
     # Support multiple drivers
     # Note: these are just generic names of drivers that need to be specified for each provider
     unless valid_drivers.include?(opts[:driver])
+      logger.debug("You must specify a valid driver: #{valid_drivers.join(',')}") if logger
       raise "You must specify a valid driver: #{valid_drivers.join(',')}"
     end
 
     # If the provider is available create a connection object
     if installed or is_provider_installed?(provider)
       if provider == "freeipmi"
-        @conn = Rubyipmi::Freeipmi::Connection.new(user, pass, host, opts)
+        Rubyipmi::Freeipmi::Connection.new(user, pass, host, opts)
       elsif provider == "ipmitool"
-        @conn = Rubyipmi::Ipmitool::Connection.new(user,pass,host, opts)
+        Rubyipmi::Ipmitool::Connection.new(user,pass,host, opts)
       else
-        raise "Incorrect provider given, must use freeipmi or ipmitool"
+        logger.error("Incorrect provider given, must use one of #{valid_providers.join(', ')}") if logger
+        raise "Incorrect provider given, must use one of #{valid_providers.join(', ')}"
       end
     else
       # Can't find the provider command line tool, maybe try other provider?
+      logger.error("The IPMI provider: #{provider} is not installed") if logger
       raise "The IPMI provider: #{provider} is not installed"
-
     end
   end
 
@@ -93,18 +137,13 @@ module Rubyipmi
      PRIV_TYPES.include?(type)
   end
 
-  def self.connection
-    return @conn if @conn
-    raise "No Connection available, please use the connect method"
-  end
-
   # method used to find the command which also makes it easier to mock with
   def self.locate_command(commandname)
     location = `which #{commandname}`.strip
     if not $?.success?
       location = nil
     end
-    return location
+    location
   end
 
   # Return true or false if the provider is available
@@ -115,6 +154,7 @@ module Rubyipmi
       when "ipmitool"
         cmdpath = locate_command('ipmitool')
       else
+        logger.error("Invalid BMC provider type") if logger
         raise "Invalid BMC provider type"
     end
     # return false if command was not found
@@ -141,24 +181,23 @@ module Rubyipmi
   end
 
   # gets data from the bmc device and puts in a hash for diagnostics
-  def self.get_diag(user, pass, host)
+  def self.get_diag(user, pass, host, opts={:driver => 'auto', :timeout => 'default'})
     data = {}
-
     if Rubyipmi.is_provider_installed?('freeipmi')
-      @freeconn = Rubyipmi::connect(user, pass, host, 'freeipmi')
-      if @freeconn
+      freeconn = Rubyipmi.connect(user, pass, host, 'freeipmi', opts)
+      if freeconn
         puts "Retrieving freeipmi data"
-        data['freeipmi'] = @freeconn.get_diag
+        data[:freeipmi] = freeconn.get_diag
       end
     end
     if Rubyipmi.is_provider_installed?('ipmitool')
-      @ipmiconn = Rubyipmi::connect(user, pass, host, 'ipmitool')
-      if @ipmiconn
+      ipmiconn = Rubyipmi.connect(user, pass, host, 'ipmitool', opts)
+      if ipmiconn
         puts "Retrieving ipmitool data"
-        data['ipmitool'] = @ipmiconn.get_diag
+        data[:ipmitool] = ipmiconn.get_diag
       end
     end
-    return data
+    File.open('/tmp/rubyipmi_diag_data.txt', 'w') {|f| f.write(data)}
+    puts "Created file /tmp/rubyipmi_diag_data.txt"
   end
-
 end