Class: IDRAC::Firmware

Inherits:

Object

• Object
• IDRAC::Firmware

Defined in:

lib/idrac/firmware.rb

Constant Summary

CATALOG_URL =

"https://downloads.dell.com/catalog/Catalog.xml.gz"

TERMINAL_JOB_STATES =

An iDRAC holds ONE staged package and refuses another while any update job is outstanding ("503: A deployment operation is already in progress"). Retrying cannot clear it, because the staged package IS the operation -- the caller has to wait for the slot. Anyone updating several components in sequence needs this: a straight loop over one R6525's 15 packages submitted 6 and lost 9 to 503.

Every rule here is a Dell fact rather than a caller's policy, which is why it belongs in the gem. Each was a silent stall on real hardware:

* "Available-" is a PREFIX, not a substring. The TPM ships an installed entry whose
version is the literal string "NotAvailable"
(Installed-12345-NotAvailable__TPM.Integrated.1-1); a substring test matches it and the
slot then never reads free on that machine.
* RebootCompleted is TERMINAL, as is anything at PercentComplete 100. Counting a finished
reboot as active made a drained queue look busy for 67 minutes.
* Jobs matter, not just the staging slot: triggering an install consumes the staged
package into a job, so Available empties while the install is still pending.

%w[Completed Failed CompletedWithErrors RebootCompleted RebootFailed].freeze

Instance Attribute Summary

• #client ⇒ Object readonly

  Returns the value of attribute client.

Instance Method Summary

• #check_updates(catalog_path = nil) ⇒ Object
• #download_catalog(output_dir = nil) ⇒ Object
• #download_firmware(update) ⇒ Object
• #get_system_inventory ⇒ Object
• #initialize(client) ⇒ Firmware constructor

  A new instance of Firmware.

• #interactive_update(catalog_path = nil, selected_updates = nil) ⇒ Object
• #update(firmware_path, options = {}) ⇒ Object
• #update_slot_free? ⇒ Boolean
• #wait_for_update_slot!(timeout: 2700, interval: 30, probe_timeout: 90) ⇒ Object

  Block until the iDRAC can accept an update.

Constructor Details

#initialize(client) ⇒ Firmware

Returns a new instance of Firmware.

# File 'lib/idrac/firmware.rb', line 22

def initialize(client)
  @client = client
end

Instance Attribute Details

#client ⇒ Object (readonly)

Returns the value of attribute client.

# File 'lib/idrac/firmware.rb', line 18

def client
  @client
end

Instance Method Details

#check_updates(catalog_path = nil) ⇒ Object

Raises:

• (Error)

# File 'lib/idrac/firmware.rb', line 140

def check_updates(catalog_path = nil)
  # Ensure we have a client for system inventory
  raise Error, "Client is required for checking updates" unless client
  
  # Download catalog if not provided
  catalog_path ||= download_catalog
  
  # Get system inventory
  inventory = get_system_inventory
  
  # Create a FirmwareCatalog instance
  catalog = FirmwareCatalog.new(catalog_path)
  
  # Extract system information
  system_model = inventory[:system][:model]
  service_tag = inventory[:system][:service_tag]
  
  puts "Checking updates for system with service tag: #{service_tag}".light_cyan
  puts "Searching for updates for model: #{system_model}".light_cyan
  
  # Find system models in the catalog
  models = catalog.find_system_models(system_model)
  
  if models.empty?
    puts "No matching system model found in catalog".yellow
    return []
  end
  
  # Use the first matching model
  model = models.first
  puts "Found system IDs for #{model[:name]}: #{model[:id]}".green
  
  # Find updates for this system
  catalog_updates = catalog.find_updates_for_system(model[:id])
  puts "Found #{catalog_updates.size} firmware updates for #{model[:name]}".green
  
  # Compare current firmware with available updates
  updates = []
  
  # Print header for firmware comparison table
  puts "\nFirmware Version Comparison:".green.bold
  puts "=" * 100
  puts "%-30s %-20s %-20s %-10s %-15s %s" % ["Component", "Current Version", "Available Version", "Updateable", "Category", "Status"]
  puts "-" * 100
  
  # Track components we've already displayed to avoid duplicates
  displayed_components = Set.new
  
  # First show current firmware with available updates
  inventory[:firmware].each do |fw|
    # Make sure firmware name is not nil
    firmware_name = fw[:name] || ""
    
    # Skip if we've already displayed this component
    next if displayed_components.include?(firmware_name.downcase)
    displayed_components.add(firmware_name.downcase)
    
    # Match the installed component to catalog DUPs. Prefer the Dell
    # componentID (reliable) — only fall back to the legacy name heuristic
    # when the inventory doesn't expose one.
    matching_updates = catalog.updates_for_component(catalog_updates, fw)

    if matching_updates.any?
      # Among matches, take the newest available version (the catalog can
      # list several revisions for one component).
      update = matching_updates.max_by { |u| catalog.version_key(u[:version]) }

      # Check if version is newer
      needs_update = catalog.compare_versions(fw[:version], update[:version])
      
      # Add to updates list if needed
      if needs_update && fw[:updateable]
        updates << {
          name: fw[:name],
          current_version: fw[:version],
          available_version: update[:version],
          path: update[:path],
          component_type: update[:component_type],
          category: update[:category],
          download_url: update[:download_url]
        }
        
        # Print row with update available
        puts "%-30s %-20s %-20s %-10s %-15s %s" % [
          fw[:name].to_s[0..29],
          fw[:version],
          update[:version],
          fw[:updateable] ? "Yes".light_green : "No".light_red,
          update[:category] || "N/A",
          "UPDATE AVAILABLE".light_green.bold
        ]
      else
        # Print row with no update needed
        status = if !needs_update
                   "Current".light_blue
                 elsif !fw[:updateable]
                   "Not updateable".light_red
                 else
                   "No update needed".light_yellow
                 end
        
        puts "%-30s %-20s %-20s %-10s %-15s %s" % [
          fw[:name].to_s[0..29],
          fw[:version],
          update[:version] || "N/A",
          fw[:updateable] ? "Yes".light_green : "No".light_red,
          update[:category] || "N/A",
          status
        ]
      end
    else
      # No matching update found
      puts "%-30s %-20s %-20s %-10s %-15s %s" % [
        fw[:name].to_s[0..29],
        fw[:version],
        "N/A",
        fw[:updateable] ? "Yes".light_green : "No".light_red,
        "N/A",
        "No update available".light_yellow
      ]
    end
  end
  
  # Then show available updates that don't match any current firmware
  catalog_updates.each do |update|
    update_name = update[:name] || ""
    
    # Skip if we've already displayed this component
    next if displayed_components.include?(update_name.downcase)
    displayed_components.add(update_name.downcase)
    
    # Skip if this update was already matched to a current firmware
    next if inventory[:firmware].any? do |fw|
      catalog.updates_for_component([update], fw).any?
    end
    
    puts "%-30s %-20s %-20s %-10s %-15s %s" % [
      update_name.to_s[0..29],
      "Not Installed".light_red,
      update[:version] || "Unknown",
      "N/A",
      update[:category] || "N/A",
      "NEW COMPONENT".light_blue
    ]
  end
  
  puts "=" * 100
  
  updates
end

#download_catalog(output_dir = nil) ⇒ Object

# File 'lib/idrac/firmware.rb', line 48

def download_catalog(output_dir = nil)
  # Use the new FirmwareCatalog class
  catalog = FirmwareCatalog.new
  catalog.download(output_dir)
end

#download_firmware(update) ⇒ Object

# File 'lib/idrac/firmware.rb', line 401

def download_firmware(update)
  return false unless update && update[:download_url]
  
  begin
    # Create a temporary directory for the download
    temp_dir = Dir.mktmpdir
    
    # Extract the filename from the path
    filename = File.basename(update[:path])
    local_path = File.join(temp_dir, filename)
    
    puts "Downloading firmware from #{update[:download_url]}".light_cyan
    puts "Saving to #{local_path}".light_cyan
    
    # Download the file
    uri = URI.parse(update[:download_url])
    
    Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https', verify_mode: OpenSSL::SSL::VERIFY_NONE) do |http|
      request = Net::HTTP::Get.new(uri)
      
      http.request(request) do |response|
        if response.code == "200"
          File.open(local_path, 'wb') do |file|
            response.read_body do |chunk|
              file.write(chunk)
            end
          end
          
          puts "Download completed successfully".green
          return local_path
        else
          puts "Failed to download firmware: #{response.code} #{response.message}".red
          return false
        end
      end
    end
  rescue => e
    puts "Error downloading firmware: #{e.message}".red.bold
    return false
  end
end

#get_system_inventory ⇒ Object

Raises:

• (Error)

# File 'lib/idrac/firmware.rb', line 54

def get_system_inventory
  # Ensure we have a client
  raise Error, "Client is required for system inventory" unless client
  
  puts "Retrieving system inventory..."
  
  # Get basic system information
  # system_uri = URI.parse("#{client.base_url}/redfish/v1/Systems/System.Embedded.1")  # Not used, kept for reference
  system_response = client.authenticated_request(:get, "/redfish/v1/Systems/System.Embedded.1")
  
  if system_response.status != 200
    raise Error, "Failed to get system information: #{system_response.status}"
  end
  
  system_data = JSON.parse(system_response.body)
  
  # Get firmware inventory
  # firmware_uri = URI.parse("#{client.base_url}/redfish/v1/UpdateService/FirmwareInventory")  # Not used, kept for reference
  firmware_response = client.authenticated_request(:get, "/redfish/v1/UpdateService/FirmwareInventory")
  
  if firmware_response.status != 200
    raise Error, "Failed to get firmware inventory: #{firmware_response.status}"
  end
  
  firmware_data = JSON.parse(firmware_response.body)
  
  # Get detailed firmware information for each component
  firmware_inventory = []
  
  if firmware_data['Members'] && firmware_data['Members'].is_a?(Array)
    firmware_data['Members'].each do |member|
      if member['@odata.id']
        component_uri = member['@odata.id']
        component_response = client.authenticated_request(:get, component_uri)
        
        if component_response.status == 200
          component_data = JSON.parse(component_response.body)
          # Dell componentID — prefer the Oem field, else parse the inventory
          # Id ("Installed-<componentID>-<version>"). Used to match DUPs by
          # componentID rather than by ambiguous display name.
          fw_id = component_data['Id'].to_s
          oem = component_data.dig('Oem', 'Dell', 'DellSoftwareInventory') || {}
          component_id = oem['ComponentID']
          component_id ||= fw_id[/\A(?:Installed|Current|Previous|Available)-(\d+)-/, 1]
          # The same Oem block carries the device's PCI IDs, and it carries
          # them exactly where the componentID is missing. The iDRAC reports
          # componentID "0" for firmware it did not install itself, so
          # factory-flashed hardware is unmatchable by componentID: on an
          # R6525, 13 of 23 entries report "0" (both LOMs, both ConnectX-6,
          # the PERC, all 8 NVMe drives) and each publishes all four PCI
          # IDs, while the 10 with a real componentID publish none. An
          # entry gains its componentID once a DUP is applied — a LOM went
          # from "Installed-0-22.91.5" to "Installed-108255-23.61.3" — so
          # the unmatchable set is first-touch hardware, not an edge case.
          # No PCIeDevices/PCIeFunctions lookup is needed to identify what
          # the componentID cannot; see #updates_for_component.
          firmware_inventory << {
            name: component_data['Name'],
            id: component_data['Id'],
            component_id: component_id,
            vendor_id: oem['VendorID'],
            device_id: oem['DeviceID'],
            sub_vendor_id: oem['SubVendorID'],
            sub_device_id: oem['SubDeviceID'],
            version: component_data['Version'],
            updateable: component_data['Updateable'] || false,
            status: component_data['Status'] ? component_data['Status']['State'] : 'Unknown'
          }
        end
      end
    end
  end
  
  {
    system: {
      model: system_data['Model'],
      manufacturer: system_data['Manufacturer'],
      serial_number: system_data['SerialNumber'],
      part_number: system_data['PartNumber'],
      bios_version: system_data['BiosVersion'],
      service_tag: system_data['SKU']
    },
    firmware: firmware_inventory
  }
end

#interactive_update(catalog_path = nil, selected_updates = nil) ⇒ Object

# File 'lib/idrac/firmware.rb', line 291

def interactive_update(catalog_path = nil, selected_updates = nil)
  # Check if updates are available
  updates = selected_updates || check_updates(catalog_path)
  
  if updates.empty?
    puts "No updates available for your system.".yellow
    return
  end
  
  # Display available updates
  puts "\nAvailable Updates:".green.bold
  updates.each_with_index do |update, index|
    puts "#{index + 1}. #{update[:name]}: #{update[:current_version]} -> #{update[:available_version]}".light_cyan
  end
  
  # If no specific updates were selected, ask the user which ones to install
  if selected_updates.nil?
    puts "\nEnter the number of the update to install (or 'all' for all updates, 'q' to quit):".light_yellow
    input = STDIN.gets.chomp
    
    if input.downcase == 'q'
      puts "Update cancelled.".yellow
      return
    elsif input.downcase == 'all'
      selected_updates = updates
    else
      begin
        index = input.to_i - 1
        if index >= 0 && index < updates.length
          selected_updates = [updates[index]]
        else
          puts "Invalid selection. Please enter a number between 1 and #{updates.length}.".red
          return
        end
      rescue
        puts "Invalid input. Please enter a number, 'all', or 'q'.".red
        return
      end
    end
  end
  
  # Process each selected update
  selected_updates.each do |update|
    puts "\nDownloading #{update[:name]} version #{update[:available_version]}...".light_cyan
    
    begin
      # Download the firmware
      firmware_file = download_firmware(update)
      
      if firmware_file
        puts "Installing #{update[:name]} version #{update[:available_version]}...".light_cyan
        
        begin
          # Upload and install the firmware
          job_id = upload_firmware(firmware_file)
          
          if job_id
            puts "Firmware update job created with ID: #{job_id}".green
            
            # Wait for the job to complete
            success = wait_for_job_completion(job_id, 1800) # 30 minutes timeout
            
            if success
              puts "Successfully updated #{update[:name]} to version #{update[:available_version]}".green.bold
            else
              puts "Failed to update #{update[:name]}. Check the iDRAC web interface for more details.".red
              puts "You may need to wait for any existing jobs to complete before trying again.".yellow
            end
          else
            puts "Failed to create update job for #{update[:name]}".red
          end
        rescue IDRAC::Error => e
          if e.message.include?("already in progress")
            puts "Error: A firmware update is already in progress.".red.bold
            puts "Please wait for the current update to complete before starting another.".yellow
            puts "You can check the status in the iDRAC web interface under Maintenance > System Update.".light_cyan
          elsif e.message.include?("job ID not found") || e.message.include?("Failed to get job status")
            puts "Error: Could not monitor the update job.".red.bold
            puts "The update may still be in progress. Check the iDRAC web interface for status.".yellow
            puts "This can happen if the iDRAC is busy processing the update request.".light_cyan
          else
            puts "Error during firmware update: #{e.message}".red.bold
          end
          
          # If we encounter an error with one update, ask if the user wants to continue with others
          if selected_updates.length > 1 && update != selected_updates.last
            puts "\nDo you want to continue with the remaining updates? (y/n)".light_yellow
            continue = STDIN.gets.chomp.downcase
            break unless continue == 'y'
          end
        end
      else
        puts "Failed to download firmware for #{update[:name]}".red
      end
    rescue => e
      puts "Error processing update for #{update[:name]}: #{e.message}".red.bold
      
      # If we encounter an error with one update, ask if the user wants to continue with others
      if selected_updates.length > 1 && update != selected_updates.last
        puts "\nDo you want to continue with the remaining updates? (y/n)".light_yellow
        continue = STDIN.gets.chomp.downcase
        break unless continue == 'y'
      end
    ensure
      # Clean up temporary files
      FileUtils.rm_f(firmware_file) if firmware_file && File.exist?(firmware_file)
    end
  end
end

#update(firmware_path, options = {}) ⇒ Object

Raises:

• (Error)

# File 'lib/idrac/firmware.rb', line 26

def update(firmware_path, options = {})
  # Validate firmware file exists
  unless File.exist?(firmware_path)
    raise Error, "Firmware file not found: #{firmware_path}"
  end

  # Ensure we have a client
  raise Error, "Client is required for firmware update" unless client

  client.ensure_authenticated!

  # Upload firmware file
  job_id = upload_firmware(firmware_path)
  
  # Check if we should wait for the update to complete
  if options[:wait]
    wait_for_job_completion(job_id, options[:timeout] || 3600)
  end

  job_id
end

#update_slot_free? ⇒ Boolean

Returns:

• (Boolean)

# File 'lib/idrac/firmware.rb', line 464

def update_slot_free?
  staged = JSON.parse(client.authenticated_request(:get, "/redfish/v1/UpdateService/FirmwareInventory").body)["Members"]
               .map { |m| m["@odata.id"].to_s.split("/").last }
               .count { |id| id.start_with?("Available-") }
  busy = JSON.parse(client.authenticated_request(:get, "/redfish/v1/Managers/iDRAC.Embedded.1/Oem/Dell/Jobs?$expand=*($levels=1)").body)["Members"]
             .count { |job| !(TERMINAL_JOB_STATES.include?(job["JobState"]) || job["PercentComplete"].to_i == 100) }
  staged.zero? && busy.zero?
end

#wait_for_update_slot!(timeout: 2700, interval: 30, probe_timeout: 90) ⇒ Object

Block until the iDRAC can accept an update. Probes are bounded because a hung transport blocks without raising, so a bare rescue never fires and the wait wedges silently.

# File 'lib/idrac/firmware.rb', line 475

def wait_for_update_slot!(timeout: 2700, interval: 30, probe_timeout: 90)
  deadline = Time.now + timeout
  loop do
    begin
      return true if Timeout.timeout(probe_timeout) { update_slot_free? }
    rescue StandardError => e
      # Report rather than counting a probe failure as "busy": an unreachable BMC is
      # otherwise indistinguishable from a working one, and the caller waits out the timeout.
      puts "Update slot probe failed (#{e.class}); retrying".yellow
    end
    raise Error, "iDRAC update slot never freed within #{timeout}s" if Time.now > deadline
    sleep interval
  end
end