Home

NetDoc is an automatic network documentation plugin for NetBox 3.5. NetDoc aims to discover a partially known network populating netbox and drawing L2 and L3 diagrams.

NetDoc would be the industrialized, open-source tool available to the public to discover multi-vendor networks.

Compatibility:

• NetDoc 3.5.x requires NetBox 3.5.x
• NetDoc 0.10.x requires NetBox 3.4.x

Table of contents

1. Introduction
2. Device configuration
3. NetBox with NetDoc installation
4. Utilizing NetDoc
5. Developing NetDoc
6. Frequently Asked Questions and Errors

Use Cases

• Unknown networks discovery.
• Continuous known networks discovery.
• Device discovery and MAC address tracking.
• Network diagram drawing

Features

NetDoc is based on NetBox, Netmiko, nornir, and ntc-templates. The following NetBox features may be of interest in the context of FWAdmin:

• User roles.
• LDAP/Active Directory integration.
• API.

NetDoc features include:

• Discovers, via nornir + Netmiko, network devices fetching information (routing, adjacencies, configuration...).
• Populates NetBox (devices, cables, IP addresses and prefixes).
• Creates network diagrams exportable in Draw.io format.

The upcoming NetDoc releases will bring about significant changes to the way network engineers currently discover known and unknown networks. The objective is to help netowrk engineers to automatically build an IPAM database (based on NetBox, and change how they manage and track network related informations.

Supported devices

Currently, the following devices are supported:

• Allied Telesis AW+
• Cisco IOS (via SSH and telnet)
• Cisco NXOS (via SSH)
• Cisxo XR (via SSH)
• HPE Aruba OSCX (via SSH)
• HPE Comware (via SSH)
• HPE Procurve (via SSH and telnet)
• Huawei VRP (via SSH)
• Linux (via SSH)
• Palo Alto Netowrks PAN-OS (via XML API)
• VMware vSphere (via pyVmomi)

See the complete list of discoverers. Others can be added if they provide a CLI/API method to get device informations.

How to Use NetDoc

To use NetDoc, you need:

• A set of supported network devices.
• A NetBox installation with the NetDoc plugin.
• Proper configuration of NetDoc.

The following chapters explain the steps mentioned above.

Assumptions

Correlate data from different sources requires some assumptions:

• Device names are assumed unique and they are converted to uppercase.
• Interface labels are used to correlate interfaces from different sources/output (e.g. show interfaces, show cdp neighbors...). Labels are built from interface name or shortname using the normalize_interface_label function in utils.py file.
• Interface level VRFs have a local scope. Prefix and IP address level VRFs are used to globally track VRF. Because discovery scripts are not aware about global VRF, they set interface level VRF only. Discovery scripts do not modify IP address level VRF if IP address is already set. Users must manually update IP address and prefix level VRFs.
• NetBox don't have network objects. To draw L3 diagrams, NetDoc uses prefixes and IP addresses. Because there is no hard association between prefixes and IP addresses, mind that IP addresses are part of a specific prefix if they both have the same VRF.
• IP addresses of discoverable devices must be unique. They are used to correlate outputs and discoverables.
• A method to get the hostname of discoverable devices exists. This hostname is used to create NetBox devices associated to discoverables.
• Templates are used to parse hostnames and to select the right ingestor. If Netmiko can understand that show ip arp and show ip arp vrf red need the same template, ingestors must be aware of the specific VRF that can be found in the command line.
• L2 neighbors (LLDP/CDP) are used to guess L1 cabling. Interfaces with multiple netibhors raise an exception. NetDoc can be configured to skip that exception.
• Virtual machine name is the hostname used by the inner operating system.

A laboratory scenario

Presented below is a screenshot illustrating an EVE-NG topology:

The subsequent screenshot showcases the findings of NetDoc regarding the Layer 2 (L2) perspective:

Should an absence of a link between Switch4 and Switch5 be observed, the issue can be attributed to an anomaly within EVE-NG. Specifically, it appears that Cisco Discovery Protocol (CDP) fails to propagate information across the said link. Consequently, the veracity of NetDoc's findings remains intact.

Finally, the conclusive screenshot depicts the L3 perspective findings as uncovered by NetDoc:

Please note that the management and keep-alive Virtual Routing and Forwarding (VRF) entities have been deliberately excluded from the analysis.

The following are the L2 and L3 diagrams exported in Draw.io:

Request for Help

If you require assistance, please open an issue on GitHub and consider sponsoring the project.