Creating a storage equipment handler

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

Preparing the environment

The switch 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 location server via SSH. For more information about connecting via SSH, see Workstation setup.

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;
/dss_common — auxiliary classes and functions for working with the storage equipment;

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

Inheritance

The switch class is inherited from the class:

BaseSnmpDSS — for devices that work via SNMP protocol;
BaseHttpDSS — for devices that work via HTTP protocol;
BaseDSS — for other devices.

Inheritance example

class ExampleHandlerDss(BaseDss):
    """Example handler class for DSS."""

    def __init__(self, dss_data: DssData):
        """__init__.

        Args:
            dss_data (DssData): DSS connection data
        """
        super().__init__(dss_data)
        self.__logger = get_logger("example_handler_dss")

To get the data for connecting to the storage equipment unit, use the self.dss_data method:

handler = make_handler(dss_data, custom_params)
logger.info(handler.dss_data.snmp_params)
logger.info(handler.dss_data.device_type)

Methods for working with storage equipment

To allow DCImanager 6 to interact with and gather metrics from the storage equipment, override the get_metrics method:

class ExampleHandlerDss(BaseSnmpDss):

    def get_metrics(self) -> DssMetricsView:
        """Returns DSS metrics."""
        start_timestamp = int(datetime.datetime.now().timestamp() * 1_000)
        metrics = DssMetricsView(start_timestamp)
        
        # Code for gathering metrics
        
        return metrics

To allow DCImanager 6 to interact with and gather metrics from the storage equipment, use the methods from a base class for one of the poll types:

BaseSnmp:
- snmp_walk;
- snmp_bulkwalk;
- snmp_get;
- snmp_set;
- snmp_set_multiple.
BaseHttp:
- get;
- post.

Interfaces are described in the BaseSnmpDSS and BaseHtmlDSS base classes.

Handler creation function

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

def make_handler(dss_data: DssData) -> "ExampleHandlerDss":
    """Create DSS handler object.

    Args:
        dss_data (DssData): DSS connection data for selected protocol.

    Returns:
        BaseDss: Initialized DSS handler object
    """
    return ExampleHandlerDss(dss_data)

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": "<device>",
        "handler": "<internal_handler_name>",
        "name": "<handler_name>",
        "protocol": ["<handler_protocol>"],
        "features": []
    }'
```
Comments to the command
example.com — domain name of the server with DCImanager 6
<token> — authorization token
<device> — device type. Possible values:
- switch;
- pdu;
- vpu
<internal_handler_name> — unique internal name of the handler
<handler_name> — the name of the handler to be displayed in the platform interface
<handler_protocol> — protocol for working with the handler. For example, snmp
features — parameters for displaying information in the user interface. You can pass an empty array to leave the information display unaffected, or you can add:
- port_aggregation — if the handler supports receiving information about aggregated ports;
- collect_mac - if the handler supports obtaining a list of MAC addresses of devices that are behind the switch ports
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.

Useful tips