Creating a VPU handler

If you are using the VPU (VLAN Per User) module, you can create your own VPU handler. A custom handler allows you to flexibly configure your VPU settings according to your network equipment settings.

To add a handler, create its code and upload it to the platform.

Preparing the environment

The VPU 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.
/vpu_common — auxiliary classes and functions for working with the VPU;
/vpu_common/handlers — VPU 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 VPU

The VPU class is inherited from the BaseVpu class.

Example of class description

class CustomVpuHandler(BaseVpu):
    """Custom vpu handler"""

    def __init__(self, vpu_data: BaseVpuData):
        """Init CustomVpuHandler object."""
        BaseVpu.__init__(self, vpu_data)

    def check_access(self) -> BaseReplyData:
        """Check router access."""
        logging.debug("custom_vpu: check_access")

        return BaseReplyData("Ok", "check_access")

    def tune_vpu(self) -> BaseReplyData:
        """Tune VPU settings."""
        logging.debug("custom_vpu: tune_vpu")

        return BaseReplyData("Ok", "tune_vpu")

    def create_net(self) -> BaseReplyData:
        """Create net."""
        logging.debug("custom_vpu: create_net")

        return BaseReplyData("Ok", "create_net")

    def delete_net(self) -> BaseReplyData:
        """Delete net."""
        logging.debug("custom_vpu: delete_net")

        return BaseReplyData("Ok", "delete_net")

To send requests to the switch or router of a VPU network via netconf protocol, inherit from the BaseNetconf auxiliary class:

Example of class description

class CustomVpuHandler(BaseNetconf, BaseVpu):
    """Custom vpu handler"""

    def __init__(self, vpu_data: BaseVpuData):
        """Init CustomVpuHandler object."""
        BaseNetconf.__init__(self,   vpu_data.router_info["router_info"]["netconf_params"])
        BaseVpu.__init__(self, vpu_data)

    def check_access(self) -> BaseReplyData:
        """Check router access."""
        logging.debug("custom_vpu: check_access")

        return BaseReplyData("Ok", "check_access")

    def tune_vpu(self) -> BaseReplyData:
        """Tune VPU settings."""
        logging.debug("custom_vpu: tune_vpu")

        return BaseReplyData("Ok", "tune_vpu")

    def create_net(self) -> BaseReplyData:
        """Create net."""
        logging.debug("custom_vpu: create_net")

        return BaseReplyData("Ok", "create_net")

    def delete_net(self) -> BaseReplyData:
        """Delete net."""
        logging.debug("custom_vpu: delete_net")

        return BaseReplyData("Ok", "delete_net")

The data for connecting to the VPU network switch is in "vpu_data.router_info["router_info"]["netconf_params"]".

All VPU data can be viewed in the self.vpu_info method. The parameters are described in the BaseVpuData class in the project file /vpu_common/vpu_helper.py.

For example, to get the parameters passed to the handler, use the self.handler_params method.

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

Example of function

def make_handler(vpu_data: BaseVpuData) -> BaseVpu:
    """Get object for VPU work.

    Args:
        vpu_data (BaseVpuData): VPU information

    Return:
        BaseVpu: Initialized vpu handler object
    """  

    return CustomVpuHandler(vpu_data)

Methods for working with VPU

To allow DCImanager 6 to interact with the VPU, override the BaseVpu class methods:

check_access — check access to router to work with VPU;
tune_vpu — preliminary configuration of the router when configuring the VPU module;
create_net — configure the VPU network on the router when creating this network in the DCImanager 6 interface;
delete_net — deletes VPU network on the router when deleting this network in the DCImanager 6 interface.

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

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://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.
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}
```
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.

Handler check

Upload the handler to the platform.
Configure the VPU (VLAN Per User) module.
Check how handler methods are executed. For example, create or delete a VPU network.