Device Discovery

NetBox Cloud NetBox Enterprise NetBox Community

The device discovery backend leverages NAPALM to connect to network devices and collect network information.

Configuration

The device_discovery backend does not require any special configuration, though overriding host and port values can be specified. The backend will use the diode settings specified in the common subsection to forward discovery results.

orb:
  backends:
    common:
      diode:
        target: grpc://192.168.0.100:8080/diode
        api_key: ${DIODE_API_KEY}
        agent_name: agent01
    device_discovery:
      host: 192.168.5.11 # default 0.0.0.0
      port: 8857 # default 8072

Policy

Device discovery policies are broken down into two subsections: config and scope.

Config

Config defines data for the whole scope and is optional overall.

Parameter	Type	Required	Description
schedule	cron format	no	If defined, it will execute scope following cron schedule time. If not defined, it will execute scope only once
defaults	map	no	key value pair that defines default values

Defaults

Current supported defaults:

Key	Description
site	NetBox Site Name

Scope

The scope defines a list of devices that can be accessed and pulled data.

Parameter	Type	Required	Description
hostname	string	yes	Device hostname
username	string	yes	Device username
password	string	yes	Device username's password
optional_args	map	no	NAPALM optional arguments defined here
driver	string	no	If defined, try to connect to device using the specified NAPALM driver. If not, it will try all the current installed drivers

Policy example

An example of the policy section, including all parameters supported by the device discovery backend:

orb:
  ...
  policies:
    device_discovery:
      discovery_1:
        config:
          schedule: "* * * * *"
          defaults:
            site: New York NY
        scope:
          - driver: ios
            hostname: 192.168.0.5
            username: admin
            password: ${PASS}
            optional_args:
               canonical_int: True
          - hostname: myhost.com
            username: remote
            password: 12345

Sample configuration

This sample configuration file demonstrates the device discovery backend connecting to a Cisco router at 192.168.0.5. It retrieves device, interface, and IP information, then sends the data to a diode server running at 192.168.0.100.

orb:
  config_manager: 
    active: local
  backends:
    device_discovery:
    common:
      diode:
        target: grpc://192.168.0.100:8080/diode
        api_key: ${DIODE_API_KEY}
        agent_name: agent01
  policies:
    device_discovery:
      discovery_1:
        config:
          schedule: "* * * * *"
          defaults:
            site: New York NY
        scope:
          - driver: ios
            hostname: 192.168.0.5
            username: admin
            password: ${PASS}

Run command:

 docker run -v /local/orb:/opt/orb/ \
 -e DIODE_API_KEY={YOUR_API_KEY} \
 -e PASS={DEVICE_PASSWORD} \
 netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

Custom device drivers

To specify community or custom NAPALM drivers, use the environment variable INSTALL_DRIVERS_PATH. Ensure that the required files are placed in the mounted volume (/opt/orb).

Mounted folder example:

/local/orb/
├── agent.yaml
├── drivers.txt
├── napalm-mos/
└── napalm-ros-0.3.2.tar.gz

Example drivers.txt:

napalm-sros==1.0.2 # try install from pypi
napalm-ros-0.3.2.tar.gz # try install from a tar.gz
./napalm-mos # try to install from a folder that contains project.toml

Run command:

 docker run -v /local/orb:/opt/orb/ \
 -e DIODE_API_KEY={YOUR_API_KEY} \
 -e PASS={DEVICE_PASSWORD} \
 -e INSTALL_DRIVERS_PATH=/opt/orb/drivers.txt \
 netboxlabs/orb-agent:latest run -c /opt/orb/agent.yaml

The relative path used by pip install should point to the directory containing the .txt file.