Quick start

Importing the library

After you successfully installed the python-ipmi library, import it in your python environment:

import pyipmi
import pyipmi.interfaces

Creating the session

Authenticated IPMI communication to the BMC is accomplished by establishing a session. Once established, a session is identified by a Session ID. The Session ID identifies a connection between a given remote user and BMC, using either the LAN or Serial/Modem connection.

Before establishing the session the interface type shall be defined. There are 4 interface types included in this library:

• ‘rmcp’ - using native RMCP encapsulation over LAN (so called IPMI over LAN). This interface requires only common python libraries.
• ‘ipmitool’ - so called legacy RMCP, still an IPMI over LAN, but requires IPMITOOL as backend. This interface requires ipmitool compiled and installed, and each time an ipmitool command is issued a new session is established with the Target (left for legacy purpuses; used before native rmcp was not implemented yet).
• ‘aardvark’ - IPMB interface (using the Total Phase Aardvark)
• ‘mock’ - This interface uses the ipmitool raw command to “emulate” an RMCP session. It uses the session information to assemble the correct ipmitool parameters. Therefore, a session must be established before any request can be sent.

Then you create an instance of the pyipmi.Ipmi object using the interface instance just created, and set also the required parameteres of the interface type. You should also set the IPMI Target, otherwise different runtime errors shall be expected later on when invoking methods of this library. Finally, you can try to establish a session. If there is a connection problem (no response), then you get the following error during session establishment:

Error

timeout: timed out

This runtime error occurs anytime with any method in case of no response.

Native RMCP interface

Here is an example to create a native RMCP interface:

interface = pyipmi.interfaces.create_interface(interface='rmcp',
                                             slave_address=0x81,
                                             host_target_address=0x20,
                                             keep_alive_interval=1)
ipmi = pyipmi.create_connection(interface)
ipmi.session.set_session_type_rmcp(host='10.0.114.199', port=623)
ipmi.session.set_auth_type_user(username='admin', password='admin')

ipmi.target = pyipmi.Target(ipmb_address=0x20)

ipmi.session.establish()
device_id = ipmi.get_device_id()

# Below code used only to print out the device ID information
print('''
Device ID:          %(device_id)s
Device Revision:    %(revision)s
Firmware Revision:  %(fw_revision)s
IPMI Version:       %(ipmi_version)s
Manufacturer ID:    %(manufacturer_id)d (0x%(manufacturer_id)04x)
Product ID:         %(product_id)d (0x%(product_id)04x)
Device Available:   %(available)d
Provides SDRs:      %(provides_sdrs)d
Additional Device Support:
'''[1:-1] % device_id.__dict__)
functions = (
        ('SENSOR', 'Sensor Device'),
        ('SDR_REPOSITORY', 'SDR Repository Device'),
        ('SEL', 'SEL Device'),
        ('FRU_INVENTORY', 'FRU Inventory Device'),
        ('IPMB_EVENT_RECEIVER', 'IPMB Event Receiver'),
        ('IPMB_EVENT_GENERATOR', 'IPMB Event Generator'),
        ('BRIDGE', 'Bridge'),
        ('CHASSIS', 'Chassis Device')
)
for n, s in functions:
    if device_id.supports_function(n):
        print('  %s' % s)
if device_id.aux is not None:
    print('Aux Firmware Rev Info:  [%s]' % (
            ' '.join('0x%02x' % d for d in device_id.aux)))

For create_interface method the first argument tells that a native RMCP interface shall be created, while for the rest of the arguments the default values are shown. After creating an instance of the interface object the interface parameters shall be set with set_session_type_rmcp and set_auth_type_user methods of the session as shown above. If authentication fails during session establishment an error of the following form shall be expected:

Error

CompletionCodeError: CompletionCodeError cc=0x81 desc=Unknown error description

Legacy RMCP interface with IPMITOOL as backend

An example showing how to setup the interface and the connection using the ipmitool as backend with network interface:

interface = pyipmi.interfaces.create_interface(interface='ipmitool',
                                               interface_type='lan')
ipmi = pyipmi.create_connection(interface)
ipmi.session.set_session_type_rmcp('10.0.0.1', port=623)
ipmi.session.set_auth_type_user('admin', 'admin')

ipmi.target = pyipmi.Target(ipmb_address=0x82, routing=[(0x81,0x20,0),(0x20,0x82,7)])

ipmi.session.establish()
ipmi.get_device_id()

where in the create_interface method the supported interface types for ipmitool are ‘lan’ , ‘lanplus’, and ‘serial-terminal’. When setting the Target, the ipmb_address argument represents the IPMI target address, and routing argument represents the bridging information over which a target is reachable. The path is given as a list of tuples in the form (address, bridge_channel). Here are three examples to have a better understanding about the format of the routing:

• Example #1: access to an ATCA blade in a chassis
  • slave = 0x81, target = 0x82
  • routing = [(0x81,0x20,0),(0x20,0x82,None)]

• Example #2: access to an MMC of an AMC plugged into a CM in a uTCA-MCH chassis with ShMC
  • slave = 0x81, target = 0x72
  • routing = [(0x81,0x20,0),(0x20,0x82,7),(0x20,0x72,None)]

• Example #3: access to an MMC of an AMC plugged into ATCA AMC carrier
  • slave = 0x81, target = 0x72
  • routing = [(0x81,0x20,0),(0x20,0x8e,7),(0x20,0x80,None)]

ipmitool command:

ipmitool -I lan -H 10.0.0.1 -p 623 -U "admin" -P "admin" -t 0x82 -b 0 -l 0 raw 0x06 0x01

An example that shows how to setup the interface and the connection using the ipmitool as backend with serial interfaces:

interface = pyipmi.interfaces.create_interface(interface='ipmitool',
                                               interface_type='serial-terminal')
ipmi = pyipmi.create_connection(interface)
ipmi.session.set_session_type_serial('/dev/tty2', 115200)

ipmi.target = pyipmi.Target(0xb2)

ipmi.session.establish()
ipmi.get_device_id()

ipmitool command:

ipmitool -I serial-terminal -D /dev/tty2:115200 -t 0xb2 -l 0 raw 0x06 0x01

IPMB with Aardvark

For IPMB interface with Aardvark tool you should use the followig code:

interface = pyipmi.interfaces.create_interface('aardvark',
                                             slave_address=0x20,
                                             serial_number='2237-523145')
ipmi = pyipmi.create_connection(interface)
ipmi.target = pyipmi.Target(ipmb_address=0xb4)
device_id = ipmi.get_device_id()

# Below code used only to print out the device ID information
print('''
Device ID:          %(device_id)s
Device Revision:    %(revision)s
Firmware Revision:  %(fw_revision)s
IPMI Version:       %(ipmi_version)s
Manufacturer ID:    %(manufacturer_id)d (0x%(manufacturer_id)04x)
Product ID:         %(product_id)d (0x%(product_id)04x)
Device Available:   %(available)d
Provides SDRs:      %(provides_sdrs)d
Additional Device Support:
'''[1:-1] % device_id.__dict__)

functions = (
        ('SENSOR', 'Sensor Device'),
        ('SDR_REPOSITORY', 'SDR Repository Device'),
        ('SEL', 'SEL Device'),
        ('FRU_INVENTORY', 'FRU Inventory Device'),
        ('IPMB_EVENT_RECEIVER', 'IPMB Event Receiver'),
        ('IPMB_EVENT_GENERATOR', 'IPMB Event Generator'),
        ('BRIDGE', 'Bridge'),
        ('CHASSIS', 'Chassis Device')
)
for n, s in functions:
    if device_id.supports_function(n):
        print('  %s' % s)

if device_id.aux is not None:
    print('Aux Firmware Rev Info:  [%s]' % (
            ' '.join('0x%02x' % d for d in device_id.aux)))

Sending IPMI commands

You can send an IPMI message using the predefined command name

send_message_with_name(name, *args, **kwargs)

where the name argument represents the string name of the command as listed in the last column of table from commands. For commands which do not require data to be sent name is the only argument to be passed. The returned value is on object which types depend on the name of the issued command.

The following example requests the device ID:

ipmi.send_message_with_name('GetDeviceId')

Note

The returned object in this case is different from the one shown for the native RMCP example shown above.

Closing the session

When you finish, close your session with session_close method.

ipmi.session.close()

As a beginner, you might find useful the debugging capabilities of this library. You can use the logging of the python-ipmi library by setting the following lines:

import logging
logging.basicConfig(filename='ipmi_debug.log', filemode='w', level=logging.DEBUG)

in which case debug, info and warning messages are all recorded in the ‘ipmi_debug.log’ file.

Note

It is assumed in all code examples that the instantiation of the pyipmi.Ipmi object is called ipmi, thus ipmi will preceed all the methods and attributes of the pyipmi.Ipmi object.