IDRAC

A Ruby client for the Dell iDRAC API. This gem provides a command-line interface and a Ruby API for interacting with Dell iDRAC servers.

Features

  • Take screenshots of the iDRAC console
  • Update firmware using Dell’s catalog
  • Check for firmware updates
  • Interactive firmware update process

Installation

Add this line to your application’s Gemfile:

gem 'idrac'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install idrac

Usage

Command Line Interface

The gem provides a command-line interface for interacting with iDRAC servers:

# Take a screenshot of the iDRAC console
idrac screenshot --host=192.168.1.100 --username=root --password=calvin
# Specify a custom output filename
idrac screenshot --host=192.168.1.100 --username=root --password=calvin --output=my_screenshot.png

# Download the Dell firmware catalog (no host required)
idrac catalog download
# or
idrac firmware:catalog

# Check firmware status and available updates
idrac firmware:status --host=192.168.1.100 --username=root --password=calvin

# Update firmware using a specific file
idrac firmware:update /path/to/firmware.exe --host=192.168.1.100 --username=root --password=calvin

# Interactive firmware update
idrac firmware:interactive --host=192.168.1.100 --username=root --password=calvin

All commands automatically handle session expiration by re-authenticating when necessary, ensuring that long-running operations like firmware updates complete successfully even if the iDRAC session times out.

Session Management Options

By default, the client will automatically delete existing sessions when the maximum session limit is reached. You can control this behavior with the --auto-delete-sessions option:

# Disable automatic session deletion (use direct mode instead when max sessions reached)
idrac firmware:status --host=192.168.1.100 --no-auto-delete-sessions

# Explicitly enable automatic session deletion (this is the default)
idrac firmware:status --host=192.168.1.100 --auto-delete-sessions

When --auto-delete-sessions is enabled (the default), the client will attempt to delete existing sessions when it encounters a “maximum number of user sessions” error. When disabled, it will switch to direct mode (using Basic Authentication) instead of trying to clear sessions.

Ruby API

require 'idrac'

# Create a client
client = IDRAC.new(
  host: '192.168.1.100',
  username: 'root',
  password: 'calvin'
)

# The client automatically handles session expiration (401 errors)
# by re-authenticating and retrying the request

# Take a screenshot (using the client convenience method)
filename = client.screenshot
puts "Screenshot saved to: #{filename}"

# Or use the Screenshot class directly for more control
screenshot = IDRAC::Screenshot.new(client)
filename = screenshot.capture
puts "Screenshot saved to: #{filename}"

# Firmware operations
firmware = IDRAC::Firmware.new(client)

# Download catalog (no client required)
catalog = IDRAC::FirmwareCatalog.new
catalog_path = catalog.download

# Get system inventory
inventory = firmware.get_system_inventory
puts "Service Tag: #{inventory[:system][:service_tag]}"

# Check for updates
updates = firmware.check_updates(catalog_path)
updates.each do |update|
  puts "#{update[:name]}: #{update[:current_version]} -> #{update[:available_version]}"
end

# Update firmware
job_id = firmware.update('/path/to/firmware.exe', wait: true)
puts "Update completed with job ID: #{job_id}"

# Create a client with auto_delete_sessions disabled
client = IDRAC.new(
  host: '192.168.1.100',
  username: 'root',
  password: 'calvin',
  auto_delete_sessions: false
)

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Changelog

Version 0.1.28

  • Improved Firmware Update Checking: Completely redesigned the firmware update checking process
  • Added a dedicated FirmwareCatalog class for better separation of concerns
  • Improved component matching with more accurate detection of available updates
  • Enhanced output format with a tabular display showing component details, versions, and update status
  • Added system model detection for more accurate firmware matching
  • Improved version comparison logic for different version formats (numeric, Dell A00 format, etc.)
  • Better handling of network adapters and other component types

Version 0.1.27

  • Removed Host Requirement for Catalog Download: The catalog download and firmware:catalog commands no longer require the --host parameter
  • Added a dedicated catalog command that can be used directly: idrac catalog download
  • The catalog download functionality can now be used without an iDRAC connection
  • Updated the Ruby API to support catalog downloads without a client

Version 0.1.26

  • Improved Redfish Session Creation: Fixed issues with the Redfish session creation process
  • Added multiple fallback methods for creating sessions with different iDRAC versions
  • Fixed 415 Unsupported Media Type error by trying different content types
  • Added support for form-urlencoded requests when JSON requests fail
  • Enhanced error handling and logging during session creation

Version 0.1.25

  • Enhanced Component Matching: Improved firmware component matching with catalog entries
  • Added extraction of model numbers and identifiers from component names (X520, H730, etc.)
  • Implemented multiple matching strategies for better accuracy
  • Added special handling for different component types (NIC, PERC, BIOS, iDRAC, etc.)
  • Improved matching for components with different naming conventions

Version 0.1.24

  • Improved Firmware Update Check: Fixed issues with firmware version comparison
  • Eliminated duplicate entries in firmware update results
  • Improved matching logic between installed firmware and catalog entries
  • Added proper handling of BIOS updates
  • Fixed missing version information in update output
  • Enhanced name comparison with case-insensitive matching

Version 0.1.23

  • Fixed Duplicate Messages: Removed duplicate “Retrieving system inventory…” message in firmware:status command
  • The message was appearing twice because it was being printed by both the CLI class and the Firmware class
  • Improved user experience by eliminating redundant output

Version 0.1.22

  • Session Management Control: Added --auto-delete-sessions CLI option (default: true)
  • When enabled, the client automatically deletes existing sessions when maximum session limit is reached
  • When disabled, the client switches to direct mode instead of trying to clear sessions
  • Added detailed logging for session management decisions
  • Updated documentation with examples of how to use the new option

Version 0.1.21

  • Improved Authentication Flow: Completely restructured the login process
  • Renamed legacy_login to webui_login and limited its use to screenshot functionality only
  • Implemented proper Redfish authentication flow: start with direct login to get a session
  • Enhanced session management: when max sessions are encountered, delete sessions using direct login
  • Simplified code by removing redundant authentication methods and focusing on Redfish standards
  • Improved error handling and logging for better troubleshooting

Version 0.1.20

  • Simplified CLI Interface: Removed the direct-mode CLI option
  • Maintained internal direct mode functionality as an automatic fallback mechanism
  • The client will still automatically switch to direct mode when session management fails
  • This change simplifies the user interface while preserving the robust session handling

Version 0.1.19

  • Basic Auth Session Clearing: Implemented direct session management using Basic Authentication
  • Added ability to list and delete all active sessions without requiring a session
  • Improved session clearing by directly accessing the Redfish Sessions API with Basic Auth
  • Enhanced force_clear_sessions to first try the direct Basic Auth approach before falling back to login/logout cycles
  • Added detailed logging of session clearing operations

Version 0.1.18

  • Direct Mode Implementation: Added a fallback mechanism for environments with persistent session issues
  • Implemented automatic switching to direct mode (Basic Auth) when session creation repeatedly fails
  • Added detection of maximum sessions condition to avoid unnecessary session creation attempts
  • Improved handling of authentication failures with graceful degradation to direct mode
  • Added Basic Auth support for all request types when in direct mode
  • Enhanced logging for better visibility into authentication mode changes

Version 0.1.17

  • Enhanced Session Clearing: Added aggressive session clearing functionality
  • Implemented a force_clear_sessions method that attempts multiple login/logout cycles with both authentication methods
  • Added automatic session clearing when maximum sessions error is encountered
  • Improved retry logic after session clearing
  • Added detailed logging during session clearing process for better troubleshooting

Version 0.1.16

  • Implemented Redfish API Session Management: Completely redesigned session handling to use the proper Redfish API
  • Added support for X-Auth-Token authentication (the standard Redfish approach)
  • Maintained backward compatibility with legacy session management for screenshot functionality
  • Improved session creation and deletion with proper error handling
  • Added fallback mechanism to legacy authentication if Redfish session creation fails
  • Enhanced logging for better troubleshooting of session-related issues

Version 0.1.15

  • Aggressive Session Management: Implemented a more robust approach to handle persistent session issues
  • Added retry counters with limits to prevent infinite loops
  • Increased delays between logout and login operations (5 seconds)
  • Added multiple logout attempts to ensure sessions are properly cleared
  • Added pre-emptive logout before login to help clear existing sessions
  • Improved error messages with attempt counters for better debugging

Version 0.1.14

  • Enhanced Session Management: Improved handling of “maximum number of user sessions” errors
  • Added detection and handling of session limits during initial login
  • Added retry mechanism with proper session cleanup
  • Added delays between logout and login operations to allow server to process session changes
  • Made logout operation more robust by handling potential errors

Version 0.1.13

  • Fixed Maximum Sessions Error: Added handling for “maximum number of user sessions” errors
  • The client now properly logs out before attempting to create a new session
  • Improved session management to prevent session buildup on the iDRAC server

Version 0.1.12

  • Improved Session Handling: Added automatic re-authentication when sessions expire (401 errors)
  • The client now automatically re-logs in and retries the request when it encounters a 401 Unauthorized error
  • This prevents interruptions during long-running operations when the iDRAC session times out

Version 0.1.11

  • Added support for Ruby 3.2.x (previously required Ruby 3.3.0+)
  • Fixed SSL verification warnings by making SSL verification optional
  • Improved error handling and reporting

Version 0.1.10

  • Added base64 gem as a dependency to address Ruby 3.4.0 compatibility warnings
  • Updated dependency versions with bounded requirements
  • Added proper license specification in gemspec

Version 0.1.9

  • Added screenshot functionality with custom output filename support
  • Improved firmware update process with better progress reporting
  • Enhanced error handling for network connectivity issues
  • Added default credentials (root/calvin) to simplify command usage

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/usiegj00/idrac.