Creating a switch handler

You can add your own switch 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.

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

The switch class is inherited from the class:

• BaseSnmpSwitch — for devices working via SNMP protocol;
• BaseSwitch — for other devices.

The BaseSnmpSwitch class contains methods of interacting with the switch 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.

class ExampleHandlerSnmp(BaseSnmpSwitch):
    """Example handler class."""
 
    def __init__(self, switch_data: SwitchSnmpData):
        """__init__.
 
        Args:
            switch_data (SwitchSnmpData): Switch connection data
        """
        super().__init__(switch_data)

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

self.switch_data.snmp_params[“community”]

Examples of SNMP requests to a switch:

result = self.snmp_get("1.3.6.1.2.1.1.5.0")
print(result.value)

self.snmp_set("1.3.6.1.2.1.1.5.0", "test.switch")

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:

def make_handler(switch_data: SwitchSnmpData) -> BaseSnmpSwitch:
    """Create switch handler object.
 
    Args:
        switch_data (SwitchSnmpData): Switch connection data
        for selected protocol.
 
    Returns:
        BaseSwitch: Initialized switch handler object
    """
    return ExampleHandlerSnmp(switch_data)

Methods for working with switch

To allow DCImanager 6 to interact with the switch, override the BaseSwitch class methods:

• status — switch polling;
• port_up — enabling the port;
• port_down — disabling the port;
• port_speed — changing the port speed;
  
• port_duplex — changing the port duplex;
  

• port_edit — editing the port; 
  

  Note

  Use this method instead of port_speed and port_duplex for switches that do not allow you to change the speed and duplex separately. For example, Arista.
• get_statistic — gathering statistics;
  
• vlan_create — creating a VLAN;
• vlan_delete — delete VLAN;
• add_port_to_vlan — adding a port to the VLAN.

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 SwitchPortView class with the following properties is passed as a parameter:

• if_index — switch port identifier;
• power_status — switch port status in DCImanager 6.

An object of the same class with properties is expected in the response:

• admin_status — current status of the port;
• oper_status — connection status.

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

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

   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

2. 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

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

   domain.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.

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

   domain.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

   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

   domain.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

   Note

    You can also use this command to upload new handler versions to the platform.

Related topics

• Adding a switch
• Configuring a switch
• API guide
• Equipment service