Using Housekeeper to Collect Device Data Howto

Sometimes it's required to collect and store additional data from equipment beyond those provided by basic functionality. We can store collected data in the custom fields or send notifications via any available channel, like email or telegram.

Solution

The Housekeeper comes to the resque. It executed in the very end of the box discovery process and allows to run the user function, wrapped in handler.

Though some known restrictions exists and should be kept in mind:

• The fatal error during box discovery will stop whole box process and the function will not be run.
• Housekeeper doesn't extend the data model and cannot introduce new fields in the data model by itself.

Implementing handler

# Python modules
import re

# NOC modules
from noc.core.mx import send_message, MessageType
from noc.sa.models.managedobject import ManagedObject
from noc.inv.models.subinterface import SubInterface

MGMT_VLAN_CAPS = "Management | VlanID"
IPv4 = "IPv4"


def handler_mgmt_vlan(object: ManagedObject) -> None:
    """
    Scan for an device management IP through the subinterfaces.
    If the sub is found look for `vlan_id` field. The VLAN found
    is considered as management vlan and stored in the
    `Management | VlanID` capability.
    """
    re_addr = re.compile(f"{object.address}.+")
    msub = SubInterface.objects.filter(
        ipv4_addresses=re_addr, managed_object=object, enabled_afi=IPv4, vlan_ids__exists=True
    ).first()
    if not msub or not msub.vlan_ids:
        return
    mgmt = object.get_caps(MGMT_VLAN_CAPS)
    if mgmt == msub.vlan_ids[0]:
        return
    object.set_caps(MGMT_VLAN_CAPS, msub.vlan_ids[0], source="manual")


def handler_vlans_script(object: ManagedObject) -> None:
    """
    Execute `get_vlans` script and sent the result as the message.
    """
    r = object.scripts.get_vlans()
    if not r:
        return
    # Add the label to use in condition
    send_message(
        r,
        message_type=MessageType.EVENT,
        headers=object.get_mx_message_headers(["custom_data"]),
    )


def hk_handler(job):
    """
    Housekeeper Entrypoint
    """
    mo: ManagedObject = job.object
    handler_mgmt_vlan(mo)
    handler_vlans_script(mo)

Place the resulting code into /opt/noc_custom/handlers/hks.py.

Registering the Handler

1. Go to Main > Setup > Handlers menu.
2. Press Add button.

3. Fill the fields:

   • Name - any human-readable name which will be seen to the user.
   • Handler - full path to the handler (noc.custom.handlers.hks.hk_handler).
   • Check Allow Housekeeping checkbox

Creating Capability

We will use capabilities to store the result.

1. Go to Inventory > Setup -> Capabilities menu.
2. Press Add button.

3. Fill the fields:

4. Name: Fill Management | VlanID. Name must match the MGMT_VLAN_CAPS value in the script.

5. Description: Let it be a Device management vlan
6. Type: Select Integer

Setting up Discovery

1. Go to Managed Object > Setup > Object Profiles
2. Select proper profile for your managed object
3. Select tab Box
4. Select our handler in the HouseKeeping combo box.
5. Press Save button.

Setting up a Notification Routing

1. Go to Main > Setup > Message Route menu
2. Press Add button.
3. Fill the form:
4. Name: any meaningful name for user.
5. Message Type: Notification
6. Match

Checking up

In the command line run

./noc discovery run -c hk box <name>

where <name> is the managed object's name or id.