Pyghmi: Python General Hardware Management Initiative

Common errors

• Error: Session is logged out

  cause The IPMI session was idle for too long and the BMC automatically terminated it.
  fix Implement a background thread to run `ipmi_cmd.eventloop()` to prevent session timeouts. For example: `import threading; house_keeper_thread = threading.Thread(target=ipmi_cmd.eventloop, daemon=True); house_keeper_thread.start()`

• No module named 'pyghmi.ipmi'

  cause The `pyghmi` package is either not installed, or there's a typo in the import statement.
  fix Ensure `pyghmi` is correctly installed via `pip install pyghmi`. Verify the import statement is `from pyghmi.ipmi import ...`.

• Unable to establish IPMI v2 / RMCP+ session

  cause Common causes include incorrect BMC IP, username, password, network firewall blocking UDP port 623, or the BMC not supporting IPMI v2.0/RMCP+.
  fix Verify all connection parameters (IP, user, pass). Check firewall rules on both client and BMC. Use `ipmitool` from the command line to confirm basic connectivity if possible (e.g., `ipmitool -H <bmc_ip> -U <user> -P <pass> chassis power status`).

Warnings

• gotcha IPMI sessions can time out if idle for too long (e.g., 30 seconds), leading to 'Session is logged out' errors or deadlocks on subsequent commands.
  Fix: To maintain an active session for long-running scripts or applications, explicitly call `ipmi_cmd.eventloop()` in a separate thread after creating the `Command` object. This method is responsible for housekeeping and keeping the session alive.
• breaking The library was originally named 'ipmi' and later renamed to 'pyghmi'. Attempting to import or use older 'ipmi' references will result in `ModuleNotFoundError` or similar issues.
  Fix: Always use the `pyghmi` package name and its corresponding import paths (e.g., `from pyghmi.ipmi import command`). Ensure your `pip install` command specifies `pyghmi`.
• gotcha When trying to establish an IPMI v2 / RMCP+ session, errors can occur due to network issues, incorrect credentials, or unsupported IPMI versions/configurations on the BMC itself.
  Fix: Double-check the BMC IP address, username, and password. Verify network connectivity to the BMC on UDP port 623 (default IPMI port). Ensure the BMC firmware supports IPMI v2.0/RMCP+ if that is the desired protocol version.

Install

• pip install pyghmi Install latest version

Imports

• command
  wrong:

  import pyghmi.ipmi.command

  correct:

  from pyghmi.ipmi import command

  Directly importing `command` from `pyghmi.ipmi` is the standard way to access IPMI command functionality.
• bmc
  wrong:

  from pyghmi import bmc

  correct:

  from pyghmi.ipmi import bmc

  `bmc` related functionalities are typically found within the `pyghmi.ipmi` submodule.

Quickstart

This quickstart demonstrates how to establish a connection to an IPMI BMC and retrieve its current power state using `pyghmi`. It relies on environment variables for BMC IP address, username, and password for secure configuration. The `command.Command` object manages the IPMI session lifecycle automatically.

import os
from pyghmi.ipmi import command

# Environment variables for BMC connection
BMC_IP = os.environ.get('PYGHMI_BMC_IP', '192.168.1.100')
BMC_USER = os.environ.get('PYGHMI_BMC_USER', 'admin')
BMC_PASS = os.environ.get('PYGHMI_BMC_PASSWORD', 'password')

try:
    # Establish an IPMI command session
    # The `command.Command` object automatically manages session lifecycle.
    ipmi_cmd = command.Command(
        bmc=BMC_IP,
        userid=BMC_USER,
        password=BMC_PASS
    )

    print(f"Connected to BMC at {BMC_IP}...")

    # Get power state
    power_state = ipmi_cmd.get_power_state()
    print(f"Power State: {power_state['powerstate']}")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Ensure PYGHMI_BMC_IP, PYGHMI_BMC_USER, and PYGHMI_BMC_PASSWORD environment variables are set correctly.")
    print("Also verify network connectivity to the BMC and correct IPMI port (default 623).")