Creating a BMC handler

You can add your own BMC handler to DCImanager 6. To do this, create the handler code and upload it to the platform.

Preparing the environment

The BMC handler must be written in Python. We recommend using Python version 3.9.

We recommend creating a handler based on an existing project. To copy a project, connect to the DCImanager 6 location server via SSH and run the command:

docker cp eservice_handler:/opt/ispsystem/equip_handler ./

The project directories may be useful when creating a handler:

/common – common helper classes and functions.
/ipmi_common – helper classes and functions for working with BMC.
/ipmi_common/handlers – BMC handlers.

You can see the required Python libraries and their versions in the project requirements.txt file. To install the required libraries, run the command:

pip3 install -r requirements.txt

To check the data types in the project, we recommend using the mypy analyzer.

Creating the handler

The platform uses handlers to interact with BMC via two protocols:

IPMI – uses the ipmitool utility.
Redfish – uses the REST API.

The handler must inherit from base classes:

From BaseIpmi — for IPMI.
Simultaneously from BaseRedfishIpmi and BaseIpmi — for Redfish.

BaseRedfishIpmi is a class that has get, put, post, patch, and delete methods for making corresponding HTTP requests to a BMC with a Redfish interface.

The IpmiData class is also used to create an instance of the BMC handler. It contains information about the BMC:

IP address;
username;
password;
other parameters.

The IpmiData class has attributes:

device – specifies the name of the custom handler, for example, "my_handler".
custom_params – can be used to pass any parameters required for the handler's operation.

The handler file must contain a function that returns a handler instance:

def make_handler(ipmi_data: IpmiData) -> BaseIpmi:
    """Make handler instance"""
    return MyHandler(ipmi_data)

If any handler function needs to remain unimplemented, you can:

write an exception. For example: NotImplementedError("Is not supported by this handler");
return a result with a message about the unsupported operation. For example: return {"result": "Operation is unsupported"}.

You can raise exceptions in handler methods if an error occurs during method execution.

Method Logging

We recommend logging method execution to help with handler debugging. To do this:

Add the following line to the handler file:
```
import logging
```
Use functions like logging.info, logging.debug, logging.warning, logging.error, etc., in the handler methods.

Loading the handler into the platform

To load the handler into the platform:

Create a directory with the following structure:
```
handler_dir/
├── __init__.py
└── my_handler.py
```
Comments

handler_dir — directory name. There should not be a handler directory with the same name in the platform
__init__.py — the initialization file. If there is no such file, create an empty file with that name
my_handler.py — the handler file
Create a tar.gz archive with the following directory:
```
tar -czvf custom_handler.tar.gz handler_dir
```
Comments to the command

custom_handler.tar.gz — archive name
handler_dir –- the name of the created directory with the handler
Log in to DCImanager 6 with administrator permissions:
```
curl -o- -k https://example.com/api/auth/v4/public/token \
    -H "isp-box-instance: true" \
    -d '{
        "email": "<admin_email>",
        "password": "<admin_pass>"
    }'
```
Comments to the command

example.com — domain name of the servier with DCImanager 6
<admin_email> — email of the DCImanager 6 administrator
<admin_pass> — password of the DCImanager 6 administrator

A response message in the format below will be received:
```
{"id":"24","token":"24-cee181d2-ccaa-4b64-a229-234aa7a25db6"}
```
Save the value of the token parameter from the received response.
Create a description for the handler:
```
curl -o- -k https://example.com/api/eservice/v3/custom_equipment \
    -H "isp-box-instance: true" \
    -H "x-xsrf-token: <token>" \
    -d '{
        "device_type": "ipmi",
        "handler": "<internal_handler_name>",
        "name": "<handler_name>",
        "protocol": ["<handler_protocol>"],
    }'
```
Comments to the command

example.com — domain name of the server with DCImanager 6
<token> — authorization token
<device_type> — device type. The value "ipmi" is used for BMC handlers.
<internal_handler_name> —unique internal handler name
<handler_name> — handler display name in the platform interface
<handler_protocol> — protocol for working with the handler. For BMC handlers, this can be "lan", "lanplus", or "redfish_v1"

The response will contain the id of the created handler. Save this value.
```
{"id": 1}
```
Load the archive with the handler into the platform:
```
curl -o- -k https://example.com/api/eservice/v3/custom_equipment/<handler_id>/content \
    -H "isp-box-instance: true" \
    -H "x-xsrf-token: <token>" \
    -F "data=@custom_handler.tar.gz" \
    -F "handler_import=<import_path>"
```
Comments to the command

example.com — domain name of the server with DCImanager 6
<handler id> — id of the created handler
<token> — authorization token
custom_handler.tar.gz — name of the archive with the handler
<import_path> - relative path for import. For example, if the handler file my_handler.py is in the handler_dir directory, the relative path would be handler_dir.my_handler

You can also use this command to upload new handler versions to the platform.
Set the device and custom_params fields for IPMI in dci_back:
```
curl -o- -k https://example.com/dci/v3/ipmi/{ipmi_id} \
    -H "isp-box-instance: true" \
    -H "x-xsrf-token: <token>" \
    -d '{"custom_params" : <custom_handler_params>, "device" : <custom_handler_name>}'
```
Click here to expand...

example.com — the domain name of the server with DCImanager 6
<handler_id> — handler ID
<token> — authorization token
custom_handler.tar.gz — name of the archive containing the handler
<ipmi_id> — ID of the BMC connection via Redfish or IPMI
<custom_handler_name> — handler name
<custom_handler_params> — custom parameters for the user-defined handler that will be passed to the handler instance during its creation in the init() method. You can pass any parameters that might be required for the handler's operation.

If the query is successful, you'll get a reply in the form of:
```
{"id": 1}
```

After that, you can use the custom handler to manage the BMC. To do this, start the BMC poll in the DCImanager graphical interface or execute the request:

curl 'https://example.com/dci/v3/ipmi/1/status' \
-H "isp-box-instance: true" \
-H "x-xsrf-token: <token>" \
-d '{}'

After this, a directory named handler_dir should appear in the container of the eservice_handler service, located at /opt/ispsystem/equip_handler/custom_handlers/ipmi. This directory will contain the files from the handler archive.