rubyipmi 0.3.0

data/.document

@@ -0,0 +1,5 @@
+lib/**/*.rb
+bin/*
+- 
+features/**/*.feature
+LICENSE.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

@@ -0,0 +1,14 @@
+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 "rdoc", "~> 3.12"
+  gem "bundler", "~> 1.1.5"
+  gem "jeweler", "~> 1.8.4"
+  gem "rcov", ">= 0"
+end

data/Gemfile.lock

@@ -0,0 +1,33 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    git (1.2.5)
+    jeweler (1.8.4)
+      bundler (~> 1.0)
+      git (>= 1.2.5)
+      rake
+      rdoc
+    json (1.7.4)
+    rake (0.9.2.2)
+    rcov (1.0.0)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.8.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.1.5)
+  jeweler (~> 1.8.4)
+  rcov
+  rdoc (~> 3.12)
+  rspec (~> 2.8.0)

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Corey Osman
+
+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.md

@@ -0,0 +1,267 @@
+# 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.
+
+## Using the library in your code
+
+### Install
+
+
+   1. Install the freeipmi from source (http://www.gnu.org/software/freeipmi/) or ipmitool
+   2. gem install rubyipmi
+
+### General Usage
+
+   ` require 'rubyipmi' `
+
+#### Create a connection object
+   `conn = Rubyipmi.connect("username", "password", "hostname", "providertype) `
+
+   Providertype: optional (ipmitool or freeipmi)
+
+   If you don't specify the provider type, Rubyipmi will detect if freeipmi or ipmitool
+   is installed and load the first tool found.  If you specify the provider type rubyipmi will only use that specific
+   provider.
+
+
+#### Use power functions (not all listed)
+   <pre>
+   conn.chassis.power.on
+   conn.chassis.power.off
+   conn.chassis.power.on?
+   conn.chassis.power.off?
+   conn.chassis.power.cycle
+   </pre>
+
+#### Boot to specific device
+   <pre>
+   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
+
+   </pre>
+
+## Testing
+There are a series of automated rspec tests that test the functionality of this library with the ipmi device.
+In order to perform use the following steps.
+
+DO NOT PERFORM THESE TEST ON ANY PRODUCTION SYSTEM.  THESE TESTS WILL TURN OFF THE DEVICE!
+
+
+1.  Install gem via source
+2.  bundle install
+3.  rake ipmiuser=ipmiuser ipmipass=ipmiuserpass ipmihost=192.168.1.22 ipmiprovider=freeipmi   (fill in your your details)
+4.  report any failures with your make/model/firmware revision to corey@logicminds.biz
+
+ ## Security
+ Currently security is not enforced in the development process.  Furthermore, the rubyipmi library uses the same methods
+ currently provided by the C based freeipmi command line tools.  This includes the use of freeipmi.conf file.  You can easily
+ store credentials in this file which will be included automatically via the command line.
+
+
+## How the library works
+Since this library is based off of running a suite of command line tools I have created a base class called baseCommand
+that performs the actual execution of the command.  The baseCommand only executes the command with the supplied
+arguments and options and returns the exit status.  Additionally the result of the executed command is stored in
+the result variable should we need to retrieve the output of the command. To further extend the baseCommand class.
+
+
+### Creating a new command
+Creating a new command is actually quite simple.  Follow these steps to wrap a freeipmi or ipmitool command.
+
+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.
+
+    ```
+    def initialize(opts = {})
+      @options = opts
+      super("bmc-info", opts)
+    end
+
+    ```
+
+     ```
+        def initialize(opts = {})
+          @options = opts
+          super("ipmitool", opts)
+        end
+
+     ```
+3.  Thats it.  The rest of the class is related to running the command and interperting the results
+
+### Writing a function for running a command
+The freeipmi command line tools have two different ways to run the commands.
+
+1.  ``` ipmipower --hostname=host --password=pass --username=user --off ```  (single action, multiple arguments)
+2.  ``` ipmi-chassis --hostname=host --password=pass --username=user --chassis-identify=FORCE ```  (multiple arguments, one main action with different qualifers)
+
+Because of the varying ways to run a command I have simplified them so it makes it easy to call the command line tools.
+
+1. Each subclassed baseCommand class inherits runcmd, result, cmd, and runcmd_with_args.
+2. The cmd executable gets set when instantiating a baseCommand class, where the class also finds the path of the executable.
+3. The options variable gets set when instantiating a subclass of the baseCommand class.
+
+### Running the cmd
+
+1.  To run the cmd, just call ``` runcmd ```  (which will automatically set all the options specified in the options hash)
+2.  To run the cmd, with arguments and options call ``` runcmd([]) ``` and pass in a array of the arguments.  (Arguments are actions only and look like --off, --on, --action)
+3.  To run the cmd, with just arguments ``` runcmd_with_args([]) ```  and pass in a array of the arguments.  (Example: 192.168.1.1)
+
+### The Options hash
+The options hash can be considered a global hash that is passed in through the connection object.
+Most of the options will be set at the connection level.  However, most commands require additional options
+that should be set at the subclassed BaseCommand level.  You must not forget to unset the option after calling
+the runcmd command.  Failure to do so will add previous options to subsequent run options.
+
+Example:
+
+```
+def ledlight(status=false, delay=300)
+      if status
+        if delay <= 0
+          options["chassis-identify"] = "FORCE"
+        else
+          options["chassis-identify"] = delay
+        end
+      else
+        options["chassis-identify"] = "TURN-OFF"
+      end
+      # Run the command
+      run
+      # unset the option by deleting from hash
+      options.delete("chassis-identify")
+end
+
+```
+
+### How to get the results of the command
+After running a command it may be desirable to get the results for further processing.  To get the results, follow the example below:
+
+Example:
+
+```
+    def status
+      command("--stat")
+      @result.split(":").last.chomp.trim
+    end
+
+    def command(opt)
+      status = run([opt])
+      return status
+    end
+
+    def on?
+      status == "on"
+    end
+
+```
+
+### The command function
+Although its not necessary to implement the command function it may be desirable if your code starts to repeat itself.
+  In this example the command function is just a wrapper command that calls run.  Your implementation will vary,
+  but be sure to always call it the "command" function, so its easily identified.
+  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.
+
+```
+ def command(opt)
+      status = runcmd([opt])
+      return status
+ end
+
+ def on
+      command("--on")
+ end
+
+```
+
+## The following are tools bundled with freeipmi
+
+* ipmi-chassis
+* ipmi-oem
+* ipmi-chassis-config
+* ipmiping
+* ipmiconsole
+* ipmipower
+* ipmidetect
+* ipmi-raw
+* ipmi-fru
+* ipmi-sel
+* ipmi-locate
+* ipmi-sensors
+* ipmimonitoring
+* ipmi-sensors-config
+* bmc-config
+* bmc-device
+* bmc-info
+
+## To contrast ipmitool has one command with many options
+* ipmitool
+
+
+
+## Auto Detect workarounds
+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
+
+
+
+## Contributing to rubyipmi
+
+* Check out the latest code to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2012 Corey Osman. See LICENSE.txt for
+further details.
+
+
+## Freeipmi Documented Workarounds
+
+
+One of my design goals is to raise exceptions and have the library try workarounds before ultimately failing since there is a whole list of workarounds that can be attempted.However, it would be nice to know the make and model of the server up front to decrease workaround attempts.
+
+So essentially I need to figure out how to save a command call and then retry if it doesn't work.
+
+With so many different vendors implementing their own IPMI solutions, different vendors may implement their IPMI protocols incorrectly. The following describes a number of workarounds currently available to handle discovered compliance issues. When possible, workarounds have been implemented so they will be transparent to the user. However, some will require the user to specify a workaround be used via the -W option.
+The hardware listed below may only indicate the hardware that a problem was discovered on. Newer versions of hardware may fix the problems indicated below. Similar machines from vendors may or may not exhibit the same problems. Different vendors may license their firmware from the same IPMI firmware developer, so it may be worthwhile to try workarounds listed below even if your motherboard is not listed.
+
+If you believe your hardware has an additional compliance issue that needs a workaround to be implemented, please contact the FreeIPMI maintainers on <freeipmi-users@gnu.org> or <freeipmi-devel@gnu.org>.
+
+assumeio - This workaround flag will assume inband interfaces communicate with system I/O rather than being memory-mapped. This will work around systems that report invalid base addresses. Those hitting this issue may see "device not supported" or "could not find inband device" errors. Issue observed on HP ProLiant DL145 G1.
+
+spinpoll - This workaround flag will inform some inband drivers (most notably the KCS driver) to spin while polling rather than putting the process to sleep. This may significantly improve the wall clock running time of tools because an operating system scheduler's granularity may be much larger than the time it takes to perform a single IPMI message transaction. However, by spinning, your system may be performing less useful work by not contexting out the tool for a more useful task.
+
+authcap - This workaround flag will skip early checks for username capabilities, authentication capabilities, and K_g support and allow IPMI authentication to succeed. It works around multiple issues in which the remote system does not properly report username capabilities, authentication capabilities, or K_g status. Those hitting this issue may see "username invalid", "authentication type unavailable for attempted privilege level", or "k_g invalid" errors. Issue observed on Asus P5M2/P5MT-R/RS162-E4/RX4, Intel SR1520ML/X38ML, and Sun Fire 2200/4150/4450 with ELOM.
+
+idzero - This workaround flag will allow empty session IDs to be accepted by the client. It works around IPMI sessions that report empty session IDs to the client. Those hitting this issue may see "session timeout" errors. Issue observed on Tyan S2882 with M3289 BMC.
+
+unexpectedauth - This workaround flag will allow unexpected non-null authcodes to be checked as though they were expected. It works around an issue when packets contain non-null authentication data when they should be null due to disabled per-message authentication. Those hitting this issue may see "session timeout" errors. Issue observed on Dell PowerEdge 2850,SC1425. Confirmed fixed on newer firmware.
+
+forcepermsg - This workaround flag will force per-message authentication to be used no matter what is advertised by the remote system. It works around an issue when per-message authentication is advertised as disabled on the remote system, but it is actually required for the protocol. Those hitting this issue may see "session timeout" errors. Issue observed on IBM eServer 325.
+
+endianseq - This workaround flag will flip the endian of the session sequence numbers to allow the session to continue properly. It works around IPMI 1.5 session sequence numbers that are the wrong endian. Those hitting this issue may see "session timeout" errors. Issue observed on some Sun ILOM 1.0/2.0 (depends on service processor endian).
+
+intel20 - This workaround flag will work around several Intel IPMI 2.0 authentication issues. The issues covered include padding of usernames, and password truncation if the authentication algorithm is HMAC-MD5-128. Those hitting this issue may see "username invalid", "password invalid", or "k_g invalid" errors. Issue observed on Intel SE7520AF2 with Intel Server Management Module (Professional Edition).
+
+supermicro20 - This workaround flag will work around several Supermicro IPMI 2.0 authentication issues on motherboards w/ Peppercon IPMI firmware. The issues covered include handling invalid length authentication codes. Those hitting this issue may see "password invalid" errors. Issue observed on Supermicro H8QME with SIMSO daughter card. Confirmed fixed on newerver firmware.
+
+sun20 - This workaround flag will work work around several Sun IPMI 2.0 authentication issues. The issues covered include invalid lengthed hash keys, improperly hashed keys, and invalid cipher suite records. Those hitting this issue may see "password invalid" or "bmc error" errors. Issue observed on Sun Fire 4100/4200/4500 with ILOM. This workaround automatically includes the "opensesspriv" workaround.
+
+opensesspriv - This workaround flag will slightly alter FreeIPMI's IPMI 2.0 connection protocol to workaround an invalid hashing algorithm used by the remote system. The privilege level sent during the Open Session stage of an IPMI 2.0 connection is used for hashing keys instead of the privilege level sent during the RAKP1 connection stage. Those hitting this issue may see "password invalid", "k_g invalid", or "bad rmcpplus status code" errors. Issue observed on Sun Fire 4100/4200/4500 with ILOM, Inventec 5441/Dell Xanadu II, Supermicro X8DTH, Supermicro X8DTG, Intel S5500WBV/Penguin Relion 700, Intel S2600JF/Appro 512X, and Quanta QSSC-S4R//Appro GB812X-CN. This workaround is automatically triggered with the "sun20" workaround.
+
+integritycheckvalue - This workaround flag will work around an invalid integrity check value during an IPMI 2.0 session establishment when using Cipher Suite ID 0. The integrity check value should be 0 length, however the remote motherboard responds with a non-empty field. Those hitting this issue may see "k_g invalid" errors. Issue observed on Supermicro X8DTG, Supermicro X8DTU, and Intel S5500WBV/Penguin Relion 700, and Intel S2600JF/Appro 512X.
+
+No IPMI 1.5 Support - Some motherboards that support IPMI 2.0 have been found to not support IPMI 1.5. Those hitting this issue may see "ipmi 2.0 unavailable" or "connection timeout" errors. This issue can be worked around by using IPMI 2.0 instead of IPMI 1.5 by specifying --driver-address=LAN_2_0. Issue observed on HP Proliant DL 145.
+
+slowcommit - This workaround will slow down commits to the BMC by sleeping one second between the commit of sections. It works around motherboards that have BMCs that can be overwhelmed by commits. Those hitting this issue may see commit errors or commits not being written to the BMC. Issue observed on Supermicro H8QME.
+
+veryslowcommit - This workaround will slow down commits to the BMC by sleeping one second between the commit of every key. It works around motherboards that have BMCs that can be overwhelmed by commits. Those hitting this issue may see commit errors or commits not being written to the BMC. Issue observed on Quanta S99Q/Dell FS12-TY.
+
+
+

data/README.rdoc

@@ -0,0 +1,18 @@
+= rubyipmi
+
+
+== Contributing to rubyipmi
+ 
+* Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet.
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it.
+* Fork the project.
+* Start a feature/bugfix branch.
+* Commit and push until you are happy with your contribution.
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+== Copyright
+
+Copyright (c) 2012 Corey Osman. See LICENSE.txt for
+further details.
+

data/Rakefile

@@ -0,0 +1,49 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+
+require 'jeweler'
+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.summary = %Q{A ruby wrapper for ipmi command line tools that supports ipmitool and freeipmi}
+  gem.description = %Q{A ruby wrapper for ipmi command line tools that supports ipmitool and freeipmi}
+  gem.email = "corey@logicminds.biz"
+  gem.authors = ["Corey Osman"]
+  # dependencies defined in Gemfile
+end
+Jeweler::RubygemsDotOrgTasks.new
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec) do |spec|
+  spec.pattern = FileList['spec/**/*_spec.rb']
+end
+
+RSpec::Core::RakeTask.new(:rcov) do |spec|
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :default => :spec
+
+require 'rdoc/task'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rubyipmi #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.3.0

data/lib/rubyipmi.rb

@@ -0,0 +1,80 @@
+require 'rubyipmi/ipmitool/connection'
+require 'rubyipmi/freeipmi/connection'
+
+module Rubyipmi
+
+
+  # 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")
+
+      # use this variable to reduce cmd calls
+      installed = false
+
+      # use the first available provider
+      if provider == "any"
+        if is_provider_installed?("freeipmi")
+          provider = "freeipmi"
+          installed = true
+        elsif is_provider_installed?("ipmitool")
+          provider = "ipmitool"
+          installed = true
+        else
+          raise "No IPMI provider is installed, please install freeipmi or ipmitool"
+        end
+      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)
+        elsif provider == "ipmitool"
+          @conn = Rubyipmi::Ipmitool::Connection.new(user,pass,host)
+        else
+          raise "Incorrect provider given, must use freeipmi or ipmitool"
+        end
+      else
+        # Can't find the provider command line tool, maybe try other provider?
+        raise "The IPMI provider: #{provider} is not installed"
+
+      end
+    end
+
+    def self.connection
+      return @conn if @conn
+      raise "No Connection available, please use the connect method"
+    end
+
+    # Return true or false if the provider is available
+    def self.is_provider_installed?(provider)
+      case provider
+        when "freeipmi"
+          cmdpath = `which ipmipower`.strip
+        when "ipmitool"
+          cmdpath = `which ipmitool`.strip
+        else
+          raise "Invalid BMC provider type"
+      end
+      return $?.success?
+    end
+
+    def self.providers
+      ["freeipmi", "ipmitool"]
+    end
+
+    # returns true if any of the providers are installed
+    def self.provider_installed?
+      providers_installed?.length > 0
+    end
+
+    def self.providers_installed?
+      available = []
+      providers.each do |prov|
+        if is_provider_installed?(prov)
+          available << prov
+        end
+      end
+      return available
+    end
+  end