DCImanager 6
Documentation
/
DCImanager 6
/
Developer section
/
Handlers
/
Creating a PDU handler

Creating a PDU handler

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

Preparing the environment

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

You can create 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 ./

Project directories can be useful when creating a handler:

  • /common — common auxiliary classes and functions.
  • /pdu_common — auxiliary classes and functions for working with the PDU;
  • /pdu_common/handlers — PDU 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

Class for working with PDU

The PDU class is inherited from the class:

  • BaseSnmpPdu — for devices working via SNMP protocol;
  • BasePdu — for other devices.

The BaseSnmpPdu class contains methods of interacting with the PDU via SNMP:

  • snmp_get — execute a read request for a specific OID;
  • snmp_set — execute a modifying query for a certain OID;
  • snmp_walk — execute a request, the result of which is a list.
Example of class description
class ExampleHandlerSnmp(BaseSnmpPdu):
    """Example handler class."""

    def __init__(self, pdu_data: PduSnmpData):
        """__init__.

        Args:
            pdu_data (PduSnmpData): pdu connection data
        """
        super().__init__(pdu_data)

To get the data for connecting to the PDU, use the self.pdu_data method:

Example to get community
self.pdu_data.snmp_params[“community”]

Examples of SNMP requests to a PDU:

Getting the device name
result = self.snmp_get("1.3.6.1.2.1.1.5.0")
print(result.value)
Editing the device name
self.snmp_set("1.3.6.1.2.1.1.5.0", "test.pdu")
Obtaining device system data
for elem in self.snmp_walk("1.3.6.1.2.1.1"):
    print(elem.value)

Each handler file must contain the make_handler function. This function creates a handler object:

Example of function
def make_handler(pdu_data: pduSnmpData) -> BaseSnmpPdu:
    """Create pdu handler object.

    Args:
        pdu_data (PduSnmpData): pdu connection data
        for selected protocol.

    Returns:
        BasePdu: Initialized pdu handler object
    """
    return ExampleHandlerSnmp(pdu_data)

Methods for working with PDU

To allow DCImanager 6 to interact with the PDU, override the BasePdu class methods:

  • status — PDU polling;
  • port_up — enabling the port;
  • port_down — disabling the port;
  • statistic — gathering statistics.

For each method, there are argument types and return values that the platform expects. The equipment management service does not use raw json data when communicating with the PDU, but rather its object representation. For example, to enable a port using the port_up method, an object of the PduPortView class with the following properties is passed as a parameter:

  • identify — PDU port identifier;
  • power_status — PDU port status in DCImanager 6.

An object of the same class with the current port state in the power_status property is expected in the reply.

When overriding methods, specify the required format of queries and return values. All auxiliary views are described in the project file /pdu_common/helper.py.

Example of handler code

Example of code

Loading the handler into the platform

To load the handler into the platform:

  1. Create a directory with the following structure:

    handler_dir/
├── __init__.py
└── my_handler.py
    Comments

  2. Create a tar.gz archive with the following directory:

    tar -czvf custom_handler.tar.gz handler_dir
    Comments to the command

  3. Log in to DCImanager 6 with administrator permissions:

    curl -o- -k https://domain.com/api/auth/v4/public/token \
    -H "isp-box-instance: true" \
    -d '{
        "email": "<admin_email>",
        "password": "<admin_pass>"
    }'
    Comments to the command

    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.

  4. Create a description for the handler:

    curl -o- -k https://domain.com/api/eservice/v3/custom_equipment \
    -H "isp-box-instance: true" \
    -H "x-xsrf-token: <token>" \
    -d '{
        "device_type": "<device>",
        "handler": "<internal_handler_name>",
        "name": "<handler_name>",
        "protocol": ["<handler_protocol>"],
        "features": []
    }'
    Comments to the command

    The response will contain the id of the created handler. Save this value.

    {"id": 1}

  5. Load the archive with the handler into the platform:

    curl -o- -k https://domain.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
    Note
     You can also use this command to upload new handler versions to the platform.


Related topics